Documentation
¶
Overview ¶
Package client provides a high-level interface to interact with the Bluesky social network. It handles authentication, rate limiting, and provides methods for common operations like posting, retrieving posts, and managing the firehose subscription.
Index ¶
- type BskyClient
- func (c *BskyClient) CloseFirehose() error
- func (c *BskyClient) Connect(ctx context.Context) error
- func (c *BskyClient) DownloadBlob(ctx context.Context, cid string, did string) ([]byte, string, error)
- func (c *BskyClient) Follow(ctx context.Context, did string) error
- func (c *BskyClient) GetAccessToken() string
- func (c *BskyClient) GetConfig() *config.Config
- func (c *BskyClient) GetDIDForHandle(ctx context.Context, handle string) (string, error)
- func (c *BskyClient) GetFirehoseURL() string
- func (c *BskyClient) GetHandleForDID(ctx context.Context, did string) (string, error)
- func (c *BskyClient) GetPost(ctx context.Context, uri string) (*post.Post, error)
- func (c *BskyClient) GetPosts(ctx context.Context, uris ...string) ([]*post.Post, error)
- func (c *BskyClient) GetProfile(ctx context.Context, handle string) (*appbsky.ActorDefs_ProfileViewDetailed, error)
- func (c *BskyClient) GetTimeout() time.Duration
- func (c *BskyClient) NewPostBuilder(opts ...post.BuilderOption) *post.Builder
- func (c *BskyClient) PostToFeed(ctx context.Context, post appbsky.FeedPost) (string, string, error)
- func (c *BskyClient) RefreshSession(ctx context.Context) error
- func (c *BskyClient) ResolveDID(ctx context.Context, did string) (*identity.Identity, error)
- func (c *BskyClient) ResolveHandle(ctx context.Context, handle string) (*identity.Identity, error)
- func (c *BskyClient) SubscribeToFirehose(ctx context.Context, callbacks *firehose.EnhancedFirehoseCallbacks) error
- func (c *BskyClient) Unfollow(ctx context.Context, did string) error
- func (c *BskyClient) UploadImage(ctx context.Context, image models.Image) (*models.UploadedImage, error)
- func (c *BskyClient) UploadImageFromFile(ctx context.Context, title string, filePath string) (*models.UploadedImage, error)
- func (c *BskyClient) UploadImageFromURL(ctx context.Context, title string, imageURL string) (*models.UploadedImage, error)
- func (c *BskyClient) UploadImages(ctx context.Context, images ...models.Image) ([]*models.UploadedImage, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BskyClient ¶
type BskyClient struct {
// contains filtered or unexported fields
}
BskyClient implements the main interface for interacting with Bluesky. It handles authentication, rate limiting, and provides methods for all supported Bluesky operations.
func NewClient ¶
func NewClient(cfg *config.Config) (*BskyClient, error)
NewClient creates a new Bluesky client with the given configuration. The configuration must include at minimum a Handle and APIKey. If no configuration is provided, default values will be used.
Example:
cfg := &config.Config{
Handle: "user.bsky.social",
APIKey: "your-api-key",
ServerURL: "https://bsky.social",
}
client, err := NewClient(cfg)
func (*BskyClient) CloseFirehose ¶
func (c *BskyClient) CloseFirehose() error
CloseFirehose stops the firehose subscription and cleans up resources. It's important to call this when you're done with the firehose to prevent resource leaks.
func (*BskyClient) Connect ¶
func (c *BskyClient) Connect(ctx context.Context) error
Connect establishes a connection to the Bluesky network and authenticates the user. This must be called before using any other methods that require authentication. The context can be used to cancel the connection attempt.
Example:
ctx := context.Background()
if err := client.Connect(ctx); err != nil {
log.Fatal("Failed to connect:", err)
}
func (*BskyClient) DownloadBlob ¶
func (c *BskyClient) DownloadBlob(ctx context.Context, cid string, did string) ([]byte, string, error)
DownloadBlob downloads a blob (like an image) from the Bluesky network using its CID and owner's DID. The CID (Content Identifier) can be found in several places:
- post.Embed.Images[].Ref for direct image embeds
- post.Embed.RecordWithMedia.Media.Images[].Ref for images in quoted posts
- post.Embed.External.ThumbRef for external link thumbnails
The DID (Decentralized Identifier) can be found in:
- post.Repo for the post author's DID
- post.Record.Uri for quoted/embedded post DIDs
It returns the raw blob data, the detected content type (e.g., "image/jpeg"), and any error that occurred during download.
Example:
data, contentType, err := client.DownloadBlob(ctx, img.Ref, post.Repo)
if err != nil {
return fmt.Errorf("failed to download: %w", err)
}
func (*BskyClient) Follow ¶
func (c *BskyClient) Follow(ctx context.Context, did string) error
Follow follows a user by their DID
func (*BskyClient) GetAccessToken ¶
func (c *BskyClient) GetAccessToken() string
GetAccessToken returns the current access token
func (*BskyClient) GetConfig ¶
func (c *BskyClient) GetConfig() *config.Config
GetConfig returns the client's configuration
func (*BskyClient) GetDIDForHandle ¶
GetDIDForHandle resolves a handle (e.g., "user.bsky.social") to its DID (Decentralized Identifier). The result is cached to improve performance of future lookups.
Example:
did, err := client.GetDIDForHandle(ctx, "user.bsky.social") // did will be something like "did:plc:xyz123..."
func (*BskyClient) GetFirehoseURL ¶
func (c *BskyClient) GetFirehoseURL() string
GetFirehoseURL returns the configured firehose URL
func (*BskyClient) GetHandleForDID ¶
GetHandleForDID resolves a DID to its current handle. The result is cached to improve performance of future lookups.
Example:
handle, err := client.GetHandleForDID(ctx, "did:plc:xyz123...") // handle will be something like "user.bsky.social"
func (*BskyClient) GetPost ¶
GetPost retrieves a single post by its URI. The URI should be in the format "at://did:plc:xyz/app.bsky.feed.post/timestamp".
Example:
post, err := client.GetPost(ctx, "at://did:plc:xyz/app.bsky.feed.post/123")
func (*BskyClient) GetPosts ¶
GetPosts retrieves multiple posts by their URIs. This is more efficient than making multiple GetPost calls when you need to fetch several posts at once.
Example:
posts, err := client.GetPosts(ctx,
"at://did:plc:xyz/app.bsky.feed.post/123",
"at://did:plc:xyz/app.bsky.feed.post/456",
)
func (*BskyClient) GetProfile ¶
func (c *BskyClient) GetProfile(ctx context.Context, handle string) (*appbsky.ActorDefs_ProfileViewDetailed, error)
GetProfile fetches a user's profile
func (*BskyClient) GetTimeout ¶
func (c *BskyClient) GetTimeout() time.Duration
GetTimeout returns the configured timeout duration for API requests. This is used internally by the firehose and other long-running operations.
func (*BskyClient) NewPostBuilder ¶
func (c *BskyClient) NewPostBuilder(opts ...post.BuilderOption) *post.Builder
NewPostBuilder creates a new post builder with the specified options
func (*BskyClient) PostToFeed ¶
PostToFeed creates a new post in the user's feed. The post parameter should be a fully constructed FeedPost object, which you can create using the post.Builder.
Returns the CID (Content Identifier) and URI of the created post.
Example:
post, _ := post.NewBuilder().
AddText("Hello, Bluesky!").
WithImages([]models.UploadedImage{*uploadedImage}).
Build()
cid, uri, err := client.PostToFeed(ctx, post)
func (*BskyClient) RefreshSession ¶
func (c *BskyClient) RefreshSession(ctx context.Context) error
RefreshSession refreshes the access token using the refresh token. This is called automatically by ensureValidSession when needed, but you can call it manually if you want to force a refresh.
Returns an error if the refresh fails or if there is no valid refresh token.
func (*BskyClient) ResolveDID ¶
ResolveDID resolves a DID to an identity, using a cache to avoid repeated lookups
func (*BskyClient) ResolveHandle ¶
ResolveHandle resolves a handle to an identity, using a cache to avoid repeated lookups
func (*BskyClient) SubscribeToFirehose ¶
func (c *BskyClient) SubscribeToFirehose(ctx context.Context, callbacks *firehose.EnhancedFirehoseCallbacks) error
SubscribeToFirehose connects to the Bluesky firehose and starts processing events using the provided callbacks. The firehose provides a real-time stream of all public activities on the network.
The callbacks parameter should define handlers for the types of events you're interested in (posts, likes, follows, etc.).
Example:
callbacks := &firehose.EnhancedFirehoseCallbacks{
PostHandlers: []*firehose.OnPostHandler{
{
Filters: []firehose.PostFilter{
func(post *post.Post) bool {
return len(post.Embed.Images) > 0
},
},
Handler: func(post *post.Post) error {
fmt.Printf("New post with images: %s\n", post.Url())
return nil
},
},
},
}
err := client.SubscribeToFirehose(ctx, callbacks)
func (*BskyClient) Unfollow ¶
func (c *BskyClient) Unfollow(ctx context.Context, did string) error
Unfollow unfollows a user by their DID
func (*BskyClient) UploadImage ¶
func (c *BskyClient) UploadImage(ctx context.Context, image models.Image) (*models.UploadedImage, error)
UploadImage uploads an image to Bluesky. The image data should be provided in the Image struct, which includes the raw bytes and metadata like title.
The returned UploadedImage contains the blob reference needed for including the image in posts.
Example:
img := models.Image{
Title: "My Photo",
Data: imageBytes,
}
uploaded, err := client.UploadImage(ctx, img)
func (*BskyClient) UploadImageFromFile ¶
func (c *BskyClient) UploadImageFromFile(ctx context.Context, title string, filePath string) (*models.UploadedImage, error)
UploadImageFromFile reads an image from the local filesystem and uploads it to Bluesky. This is a convenience method that handles both reading and uploading.
The title parameter will be used as the alt text for the image.
Example:
uploaded, err := client.UploadImageFromFile(ctx, "My Photo", "/path/to/photo.jpg")
func (*BskyClient) UploadImageFromURL ¶
func (c *BskyClient) UploadImageFromURL(ctx context.Context, title string, imageURL string) (*models.UploadedImage, error)
UploadImageFromURL downloads an image from the given URL and uploads it to Bluesky. This is a convenience method that handles both downloading and uploading.
The title parameter will be used as the alt text for the image.
Example:
uploaded, err := client.UploadImageFromURL(ctx, "My Photo", "https://example.com/photo.jpg")
func (*BskyClient) UploadImages ¶
func (c *BskyClient) UploadImages(ctx context.Context, images ...models.Image) ([]*models.UploadedImage, error)
UploadImages uploads multiple images to Bluesky
Source Files