Bluesky plugin¶

The bluesky entry point publishes through the AT Protocol PDS APIs and exposes both low-level post/blob actions and the shared Telegram mirror workflow.

Configuration¶

Use either an already-issued access token plus repository DID, or an account identifier and an app password. service_url defaults to https://bsky.social; set it to the account's PDS when the account is hosted elsewhere.

plugins:
  - module: cb_social_plugin.bluesky
    config:
      identifier: "publisher.example"
      app_password: "${BLUESKY_APP_PASSWORD}"
      service_url: "https://bsky.social"
      state_db_path: "/srv/data/social-publications.db"
      media_group_wait_seconds: 2

For long-running deployments, keep credentials in the normal Call Baxter environment/secret boundary. Do not put app passwords or access tokens in committed rule files.

Actions¶

Action	Purpose
`bluesky.create_post`	Create an `app.bsky.feed.post` record.
`bluesky.update_post`	Upsert a post at a known record key with `putRecord`.
`bluesky.delete_post`	Delete a post record by record key.
`bluesky.upload_blob`	Upload raw bytes to the authenticated PDS.
`bluesky.mirror_telegram_message`	Mirror one Telegram message/update.
`bluesky.flush_due_media_groups`	Publish staged Telegram albums that are due.

bluesky.create_post accepts text plus optional created_at, langs, embed, and rkey. bluesky.update_post requires rkey and text and accepts the same record fields.

Telegram mirroring¶

The mirror derives a deterministic record key from the Telegram source key and writes with com.atproto.repo.putRecord. A Telegram edit therefore targets the same remote record rather than creating another post. When state_db_path is configured, Call Baxter also records the source version, remote URI/CID/rkey, and creation timestamp so stale or duplicate Telegram events can be suppressed locally.

actions:
  - kind: bluesky.mirror_telegram_message
    args:
      update: "{{ event.attrs.raw_update }}"
      required_hashtag: "#social"

URLs in mirrored text receive link facets with UTF-8 byte offsets. The original Telegram creation time is retained when an edit updates the record.

Images¶

The alpha mirror supports Telegram photos and image documents. It embeds at most four images and rejects individual images larger than 1,000,000 bytes before upload, matching the Bluesky image embed limit. media_required: true makes a missing/failed image fatal; otherwise omissions are returned in media_errors.

Video, animation, alt-text extraction, mentions, replies, quotes, and external-card generation are not synthesized by this first mirror slice.

Idempotency and failure boundary¶

The deterministic record key gives the mirror a stable remote target even if local publication state is lost. Native create/delete/blob actions remain classified as external mutations and are not considered generally replay-safe by Call Baxter.

Use dry_run: true to inspect the Telegram publication key, text, media count, and edit detection without authenticating to or mutating Bluesky.