@atcute/client

lightweight and cute API client for AT Protocol.

• small, the bare minimum is ~1 kB gzipped with the full package at ~2.4 kB gzipped.
• no runtime validation, type definitions match actual HTTP responses, the server is assumed to be trusted in returning valid responses.

1import { Client, CredentialManager, ok, simpleFetchHandler } from '@atcute/client';
2
3// import lexicons
4import type {} from '@atcute/bluesky';
5
6// basic usage
7{
8	const handler = simpleFetchHandler({ service: 'https://public.api.bsky.app' });
9	const rpc = new Client({ handler });
10
11	// explicit response handling
12	{
13		const { ok, data } = await rpc.get('app.bsky.actor.getProfile', {
14			params: {
15				actor: 'bsky.app',
16			},
17		});
18
19		if (!ok) {
20			switch (data.error) {
21				case 'InvalidRequest': {
22					// Account doesn't exist
23					break;
24				}
25				case 'AccountTakedown': {
26					// Account taken down
27					break;
28				}
29				case 'AccountDeactivated': {
30					// Account deactivated
31					break;
32				}
33			}
34		}
35
36		if (ok) {
37			console.log(data.displayName);
38			// -> "Bluesky"
39		}
40	}
41
42	// optimistic response handling
43	{
44		const data = await ok(
45			rpc.get('app.bsky.actor.getProfile', {
46				params: {
47					actor: 'bsky.app',
48				},
49			}),
50		);
51
52		console.log(data.displayName);
53		// -> "Bluesky"
54	}
55}
56
57// performing authenticated requests
58{
59	const manager = new CredentialManager({ service: 'https://bsky.social' });
60	const rpc = new Client({ handler: manager });
61
62	await manager.login({ identifier: 'example.com', password: 'ofki-yrwl-hmcc-cvau' });
63
64	console.log(manager.session);
65	// -> { refreshJwt: 'eyJhb...', ... }
66
67	const data = await ok(
68		rpc.get('com.atproto.identity.resolveHandle', {
69			params: {
70				handle: 'pfrazee.com',
71			},
72		}),
73	);
74
75	console.log(data.did);
76	// -> 'did:plc:ragtjsm2j2vknwkz3zp4oxrd'
77}

by default, the API client ships with no queries or procedures. you can extend the client by installing one of these definition packages.

• @atcute/atproto: com.atproto.* schema definitions
• @atcute/bluemoji: blue.moji.* schema definitions
• @atcute/bluesky: app.bsky.* and chat.bsky.* schema definitions
• @atcute/frontpage: fyi.unravel.frontpage.* schema definitions
• @atcute/ozone: tools.ozone.* schema definitions
• @atcute/tangled: sh.tangled.* schema definitions
• @atcute/whitewind: com.whtwnd.* schema definitions