@spec block(session(), String.t()) :: {:ok, map()} | {:error, term()}

Blocks an actor.

Examples

{:ok, block} = Bsky.block(session, "spammer.bsky.social")
{:ok, block} = Bsky.block(session, "did:plc:xyz123")

@spec delete_post(session(), String.t()) :: :ok | {:error, term()}

Deletes a post by its AT-URI.

Examples

:ok = Bsky.delete_post(session, post.uri)

@spec follow(session(), String.t()) :: {:ok, map()} | {:error, term()}

Follows an actor.

Examples

{:ok, follow} = Bsky.follow(session, "alice.bsky.social")
{:ok, follow} = Bsky.follow(session, "did:plc:abc123")

@spec get_post_thread(session(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Gets a post thread with context.

Options

• :depth - How many levels of replies to fetch (default: 6)
• :parent_height - How many levels of parent posts to fetch (default: 80)

Examples

{:ok, thread} = Bsky.get_post_thread(session, post_uri)

@spec get_posts(session(), [String.t()]) :: {:ok, map()} | {:error, term()}

Gets multiple posts by their AT-URIs.

Examples

uris = ["at://did:plc:xyz/app.bsky.feed.post/123", "at://..."]
{:ok, posts} = Bsky.get_posts(session, uris)

@spec get_profile(session(), String.t()) :: {:ok, map()} | {:error, term()}

Gets an actor's profile.

Examples

{:ok, profile} = Bsky.get_profile(session, "alice.bsky.social")

@spec get_profiles(session(), [String.t()]) :: {:ok, map()} | {:error, term()}

Gets multiple actor profiles.

Examples

{:ok, profiles} = Bsky.get_profiles(session, ["alice.bsky.social", "bob.bsky.social"])

@spec get_timeline(
  session(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Gets the authenticated user's timeline.

Options

• :limit - Number of posts (default: 50, max: 100)
• :cursor - Pagination cursor

Examples

{:ok, %{feed: posts, cursor: cursor}} = Bsky.get_timeline(session)
{:ok, %{feed: more}} = Bsky.get_timeline(session, cursor: cursor)

@spec get_unread_count(session()) :: {:ok, map()} | {:error, term()}

Gets the count of unread notifications.

Examples

{:ok, %{count: unread}} = Bsky.get_unread_count(session)

@spec like(session(), String.t(), String.t()) :: {:ok, map()} | {:error, term()}

Likes a post.

Examples

{:ok, like} = Bsky.like(session, post.uri, post.cid)

@spec list_notifications(
  session(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Lists notifications for the authenticated user.

Options

• :limit - Number of notifications (default: 50)
• :cursor - Pagination cursor
• :seen_at - Only return notifications after this timestamp

Examples

{:ok, %{notifications: notifs, cursor: cursor}} = Bsky.list_notifications(session)

@spec mute(session(), String.t()) :: {:ok, map()} | {:error, term()}

Mutes an actor (client-side muting via XRPC).

Examples

{:ok, _} = Bsky.mute(session, "noisy.bsky.social")

@spec post(session(), String.t() | map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Posts a text message to Bluesky.

Supports both plain text strings and RichText structs with facets.

Options

• :langs - List of language codes (default: ["en"])
• :reply_to - AT-URI of post to reply to
• :created_at - Timestamp (default: now)

Examples

# Simple text post
{:ok, post} = Bsky.post(session, "Hello Bluesky!")

# Reply to a post
{:ok, reply} = Bsky.post(session, "Great point!",
  reply_to: "at://did:plc:xyz/app.bsky.feed.post/3k..."
)

# Rich text with mentions and links
alias ProtoRune.RichText

{:ok, rt} =
  RichText.new()
  |> RichText.text("Hello ")
  |> RichText.mention("alice.bsky.social")
  |> RichText.text("!")
  |> RichText.build()

{:ok, post} = Bsky.post(session, rt)

@spec repost(session(), String.t(), String.t()) :: {:ok, map()} | {:error, term()}

Reposts a post.

Examples

{:ok, repost} = Bsky.repost(session, post.uri, post.cid)

@spec search_actors(session(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Searches for actors (profiles) matching a query.

Options

• :limit - Number of actors (default: 25, max: 100)
• :cursor - Pagination cursor

Examples

{:ok, %{actors: actors}} = Bsky.search_actors(session, "alice")

@spec search_posts(session(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Searches for posts matching a query.

Options

• :sort - :top or :latest
• :since - Only posts after this Date
• :until - Only posts before this Date
• :author - Restrict to posts by this actor (handle or DID)
• :lang - Restrict to this language code
• :domain - Restrict to posts linking to this domain
• :url - Restrict to posts linking to this URL
• :mentions - Restrict to posts mentioning these actors
• :tag - Restrict to posts with these hashtags
• :limit - Number of posts (default: 25, max: 100)
• :cursor - Pagination cursor

Examples

{:ok, %{posts: posts}} = Bsky.search_posts(session, "elixir lang")
{:ok, %{posts: latest}} = Bsky.search_posts(session, "elixir", sort: :latest)

@spec unblock(session(), String.t()) :: :ok | {:error, term()}

Unblocks an actor by deleting the block record.

Examples

:ok = Bsky.unblock(session, block.uri)

@spec unfollow(session(), String.t()) :: :ok | {:error, term()}

Unfollows an actor by deleting the follow record.

Examples

:ok = Bsky.unfollow(session, follow.uri)

@spec unlike(session(), String.t()) :: :ok | {:error, term()}

Unlikes a post by deleting the like record.

Examples

:ok = Bsky.unlike(session, like.uri)

@spec unmute(session(), String.t()) :: {:ok, map()} | {:error, term()}

Unmutes an actor.

Examples

{:ok, _} = Bsky.unmute(session, "noisy.bsky.social")

@spec unrepost(session(), String.t()) :: :ok | {:error, term()}

Unrepost by deleting the repost record.

Examples

:ok = Bsky.unrepost(session, repost.uri)

@spec update_profile(
  session(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Updates the authenticated user's profile.

Fetches the current app.bsky.actor.profile record, merges the given changes, and writes it back, so fields not mentioned are preserved.

Options

• :display_name - New display name
• :description - New profile description (bio)
• :avatar - {data, content_type} tuple with the raw image bytes and its MIME type. The data is uploaded as a blob and linked in the record.

Examples

{:ok, _} = Bsky.update_profile(session, display_name: "Alice")

{:ok, _} =
  Bsky.update_profile(session,
    display_name: "Alice",
    description: "Posting about Elixir",
    avatar: {File.read!("avatar.png"), "image/png"}
  )

@spec update_seen(session(), DateTime.t()) :: {:ok, map()} | {:error, term()}

Marks notifications as seen up to a given timestamp.

Examples

:ok = Bsky.update_seen(session, DateTime.utc_now())