atproto

README

atproto

A pure-Go, dependency-free read client for Bluesky and the AT Protocol, talking to the XRPC HTTP API.

• CGO-free (CGO_ENABLED=0) and zero third-party dependencies — standard library only.
• Targets the public Bluesky AppView at https://public.api.bsky.app, which serves read methods without authentication.
• Optional Login exchanges credentials for an access token to use authenticated methods (such as the home timeline).

Install

go get github.com/go-atproto/atproto

Usage

Fetch an author's feed anonymously against the public AppView — no credentials required:

package main

import (
	"context"
	"fmt"

	"github.com/go-atproto/atproto"
)

func main() {
	c := atproto.New() // defaults to https://public.api.bsky.app

	feed, err := c.AuthorFeed(context.Background(), "bsky.app", 25, "")
	if err != nil {
		panic(err)
	}

	for _, p := range feed.Posts {
		fmt.Printf("@%s (%d likes): %s\n", p.Author.Handle, p.LikeCount, p.Text)
		for _, img := range p.Images {
			fmt.Printf("    image: %s (%s)\n", img.Fullsize, img.Alt)
		}
	}

	if feed.Cursor != "" {
		// Pass feed.Cursor back to AuthorFeed to fetch the next page.
	}
}

Searching posts

feed, err := c.SearchPosts(context.Background(), "golang", 25, "")

Authenticated timeline

Timeline requires a token. Point the client at a PDS (for example https://bsky.social) and call Login first:

c := atproto.New(atproto.WithService("https://bsky.social"))
if err := c.Login(context.Background(), "you.bsky.social", "app-password"); err != nil {
	panic(err)
}
feed, err := c.Timeline(context.Background(), 25, "")

Configuration

Option	Purpose
WithService(url)	Override the XRPC base URL / PDS.
WithHTTPClient(client)	Supply a custom *http.Client (timeouts, etc).
WithUserAgent(ua)	Set the User-Agent header.

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package atproto is a pure-Go, dependency-free read client for Bluesky and the AT Protocol, talking to the XRPC HTTP API.

By default the client targets the public Bluesky AppView at https://public.api.bsky.app, which serves read methods without authentication. Optionally, Login exchanges credentials for an access token so that authenticated methods such as Timeline can be used.

Index

• Constants
• type Actor
• type ActorPage
• type Author
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) AuthorFeed(ctx context.Context, actor string, limit int, cursor string) (*Feed, error)
  • func (c *Client) Login(ctx context.Context, identifier, password string) error
  • func (c *Client) SearchActors(ctx context.Context, q string, limit int, cursor string) (*ActorPage, error)
  • func (c *Client) SearchPosts(ctx context.Context, q string, limit int, cursor string) (*Feed, error)
  • func (c *Client) Timeline(ctx context.Context, limit int, cursor string) (*Feed, error)
• type Feed
• type Image
• type Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithService(u string) Option
  • func WithUserAgent(ua string) Option
• type Post

Constants

const DefaultService = "https://public.api.bsky.app"

DefaultService is the public Bluesky AppView, which serves read XRPC methods without authentication.

Types

type Actor

type Actor struct {
	DID         string
	Handle      string // e.g. "alice.bsky.social" (follow as @<Handle>)
	DisplayName string
	Description string
	Avatar      string
}

Actor is a Bluesky account profile returned by an actor search.

type ActorPage

type ActorPage struct {
	Actors []Actor
	Cursor string
}

ActorPage is a page of actors with an optional pagination cursor.

type Author

type Author struct {
	DID         string
	Handle      string
	DisplayName string
	Avatar      string
}

Author is the profile of a post's author.

type Client

type Client struct {
	// Service is the base URL of the XRPC service (default DefaultService).
	Service string
	// HTTPClient is the underlying HTTP client (default http.DefaultClient).
	HTTPClient *http.Client
	// UserAgent is sent as the User-Agent header on every request.
	UserAgent string
	// contains filtered or unexported fields
}

Client is an AT Protocol / Bluesky XRPC read client.

func New

func New(opts ...Option) *Client

New returns a Client configured with the given options.

func (*Client) AuthorFeed

func (c *Client) AuthorFeed(ctx context.Context, actor string, limit int, cursor string) (*Feed, error)

AuthorFeed returns the feed of posts authored by actor (a handle or DID) via app.bsky.feed.getAuthorFeed.

func (*Client) Login

func (c *Client) Login(ctx context.Context, identifier, password string) error

Login exchanges credentials for an access token via com.atproto.server.createSession and stores it for subsequent authenticated calls. Note that the default public AppView does not host createSession; set a PDS URL (e.g. https://bsky.social) with WithService to authenticate.

func (*Client) SearchActors

func (c *Client) SearchActors(ctx context.Context, q string, limit int, cursor string) (*ActorPage, error)

SearchActors returns the accounts matching q via app.bsky.actor.searchActors, a public (unauthenticated) read on the default AppView — used to discover accounts to follow. limit caps the page (0 = server default); cursor pages.

func (*Client) SearchPosts

func (c *Client) SearchPosts(ctx context.Context, q string, limit int, cursor string) (*Feed, error)

SearchPosts returns posts matching the query q via app.bsky.feed.searchPosts.

func (*Client) Timeline

func (c *Client) Timeline(ctx context.Context, limit int, cursor string) (*Feed, error)

Timeline returns the authenticated user's home timeline via app.bsky.feed.getTimeline. It requires a prior successful Login.

type Feed

type Feed struct {
	Posts  []Post
	Cursor string
}

Feed is a page of posts with an optional pagination cursor.

type Image

type Image struct {
	Thumb    string
	Fullsize string
	Alt      string
}

Image is a single image embedded in a post.

type Option

type Option func(*Client)

Option configures a Client.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the underlying HTTP client.

func WithService

func WithService(u string) Option

WithService sets the base URL of the XRPC service.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header sent on every request.

type Post

type Post struct {
	URI         string
	CID         string
	Author      Author
	Text        string
	CreatedAt   time.Time
	LikeCount   int
	RepostCount int
	ReplyCount  int
	Images      []Image
}

Post is a single Bluesky post.