Mastodon provider¶

Configuration¶

- module: cb_social_plugin.mastodon
  config:
    base_url: "https://social.example"
    access_token: "${MASTODON_ACCESS_TOKEN}"
    state_db_path: "/srv/data/social-publications.db"
    visibility: "unlisted"

base_url and a user access_token are required. visibility, sensitive, spoiler_text, and language can be defaults in plugin configuration and overridden by action arguments where the action contract allows them.

Actions and API contracts¶

Action	Remote operation
`mastodon.create_post`	`POST /api/v1/statuses`
`mastodon.update_post`	`PUT /api/v1/statuses/{id}`
`mastodon.delete_post`	`DELETE /api/v1/statuses/{id}`
`mastodon.upload_media`	`POST /api/v2/media`
`mastodon.mirror_telegram_message`	create or edit the mapped status

Native creates can receive an explicit idempotency_key. Mirror creates derive one deterministically from the provider and Telegram publication key.

Idempotency retention¶

The mirror sends Mastodon's Idempotency-Key header for creates, which protects retries while the target server retains that key. Retention is an implementation/server boundary; Call Baxter does not assume it is permanent. Once a local mapping exists, Telegram edits use the mapped status id.

Images are uploaded before status creation/update and passed as media_ids[].

Limitations¶

The shared mirror path handles images only.
Instance-specific limits (text size, media size/count, idempotency retention) are not normalized by this package.
HTTP/provider errors, including 429 rate limits, propagate to the Call Baxter action boundary.