@externdefs/bluesky-client

@mary/bluesky-client

Lightweight API client for Bluesky/AT Protocol (atproto).

[!IMPORTANT]
This is an ESM-only library, you need to configure your TypeScript correctly in order to correctly pick up the type declarations.

Why?

The official @atproto/api library is massive, weighing in at 662 KB minified. (v0.12.22)

• The library relies on automatically generated classes and functions for representing the nature of RPC and namespaces, which can't be treeshaken at all if you only request to one or two endpoints.
• The library depends on zod and graphemer, and as the library is shipped in CJS format it is unlikely that the treeshaking will be able to get them all off, resulting in a code bloat that's especially noticeable if you don't also rely on said functionality or dependencies.

Which leads to this alternative library, where it makes the following tradeoffs for its size:

• The client does not attempt to validate if the responses are valid, or provide the means to check if what you're sending is correct during runtime. Proceed at your own risk.
• IPLD and blob types are represented as-is.
  • CID links are not converted to a CID instance, and you'd need to rely on @mary/atproto-cid or multiformats if you need to parse them.
  • bytes are typed as Uint8Array, but please be aware that these only exists on subscriptions, which we don't actually cover here as it's a WebSocket connection.
  • Blobs are not turned into a BlobRef instance.
• Additional APIs for handling rich text or moderation are not included, but there are some alternatives provided as examples in the repository.

The result is a very small API client that you can extend easily:

• BskyXRPC alone: 1,725 b (918 b gzipped)
• BskyXRPC and BskyAuth: 4,440 b (1,986 b gzipped)

Usage

Fiddling with AT Protocol lexicons...

Type declarations can be accessed via the ./lexicons module.

import type { AppBskyRichtextFacet, Brand } from '@mary/bluesky-client/lexicons';

type Facet = AppBskyRichtextFacet.Main;
type MentionFeature = Brand.Union<AppBskyRichtextFacet.Mention>;

const mention: MentionFeature = {
	$type: 'app.bsky.richtext.facet#mention',
	did: 'did:plc:ragtjsm2j2vknwkz3zp4oxrd',
};

const facet: Facet = {
	index: {
		byteStart: 7,
		byteEnd: 12,
	},
	features: [mention],
};

Unions in AT Protocol are done by discriminating the object's $type field, where the field only needs to exist if it's under a union. To make this possible, objects are branded with a (nonexistent) unique symbol. Note that object typings are slightly stricter than usual because of this (can't pass AppBskyActorDefs.ProfileView in functions that expects ProfileViewBasic).

Doing an unauthenticated request...

const rpc = new BskyXRPC({ service: 'https://public.api.bsky.app' });

const profile = await rpc.get('app.bsky.actor.getProfile', {
	params: {
		actor: 'did:plc:ragtjsm2j2vknwkz3zp4oxrd',
	},
});

console.log(profile.data); // -> { handle: 'pfrazee.com', ... }

Doing an authenticated request...

const rpc = new BskyXRPC({ service: 'https://bsky.social' });
const auth = new BskyAuth(rpc);

await auth.login({ identifier: '...', password: '...' });

const likes = await rpc.get('app.bsky.feed.getActorLikes', {
	params: {
		actor: auth.session.did,
		limit: 5,
	},
});

console.log(likes.data); // -> Array(5) [...]

Creating a post...

const record: AppBskyFeedPost.Record = {
	createdAt: new Date().toISOString(),
	text: `Hello world!`,
};

await rpc.call('com.atproto.repo.createRecord', {
	data: {
		repo: agent.session.did,
		collection: 'app.bsky.feed.post',
		record: record,
	},
});