a collection of lightweight TypeScript packages for AT Protocol, the protocol powering Bluesky
mary.my.id
atproto
bluesky
typescript
npm
1# atcute
2
3lightweight TypeScript packages for [AT Protocol](https://atproto.com), the protocol powering
4Bluesky.
5
6## quick start
7
8```sh
9npm install @atcute/client @atcute/bluesky
10```
11
12```ts
13import { Client, simpleFetchHandler } from '@atcute/client';
14import type {} from '@atcute/bluesky';
15
16const client = new Client({
17 handler: simpleFetchHandler({ service: 'https://public.api.bsky.app' }),
18});
19
20const { data } = await client.get('app.bsky.actor.getProfile', {
21 params: { actor: 'bsky.app' },
22});
23
24console.log(data.displayName);
25// -> Bluesky
26```
27
28for authenticated requests, see the [client docs](./packages/clients/client) or use the
29[OAuth browser client](./packages/oauth/browser-client) for web apps.
30
31## packages
32
33| Packages |
34| ----------------------------------------------------------------------------------------------------------- |
35| **Client packages** |
36| [`client`](./packages/clients/client): XRPC HTTP client |
37| [`firehose`](./packages/clients/firehose): XRPC subscription client |
38| [`jetstream`](./packages/clients/jetstream): Jetstream WebSocket client |
39| [`tap`](./packages/clients/tap): Tap WebSocket client |
40| [`cache`](./packages/clients/cache): normalized cache store |
41| **Server packages** |
42| [`xrpc-server`](./packages/servers/xrpc-server): XRPC web framework |
43| [`xrpc-server-bun`](./packages/servers/xrpc-server-bun): Bun WebSocket adapter |
44| [`xrpc-server-cloudflare`](./packages/servers/xrpc-server-cloudflare): Cloudflare Workers WebSocket adapter |
45| [`xrpc-server-deno`](./packages/servers/xrpc-server-deno): Deno WebSocket adapter |
46| [`xrpc-server-node`](./packages/servers/xrpc-server-node): Node.js WebSocket adapter |
47| **OAuth packages** |
48| [`oauth-browser-client`](./packages/oauth/browser-client): minimal OAuth client for SPAs |
49| [`oauth-node-client`](./packages/oauth/node-client): OAuth client for Node.js |
50| **Lexicon packages** |
51| [`lex-cli`](./packages/lexicons/lex-cli): generate TypeScript from lexicon schemas |
52| [`lexicon-doc`](./packages/lexicons/lexicon-doc): parse and author lexicon documents |
53| [`lexicon-resolver`](./packages/lexicons/lexicon-resolver): resolve lexicons from the network |
54| [`lexicons`](./packages/lexicons/lexicons): core types and schema validation |
55| **Lexicon definition packages** |
56| [`atproto`](./packages/definitions/atproto): `com.atproto.*` definitions |
57| [`bluemoji`](./packages/definitions/bluemoji): `blue.moji.*` definitions |
58| [`bluesky`](./packages/definitions/bluesky): `app.bsky.*`, `chat.bsky.*` definitions |
59| [`frontpage`](./packages/definitions/frontpage): `fyi.unravel.frontpage.*` definitions |
60| [`leaflet`](./packages/definitions/leaflet): `pub.leaflet.*` definitions |
61| [`lexicon-community`](./packages/definitions/lexicon-community): `community.lexicon.*` definitions |
62| [`microcosm`](./packages/definitions/microcosm): `blue.microcosm.*`, `com.bad-example.*` definitions |
63| [`ozone`](./packages/definitions/ozone): `tools.ozone.*` definitions |
64| [`pckt`](./packages/definitions/pckt): `blog.pckt.*` definitions |
65| [`tangled`](./packages/definitions/tangled): `sh.tangled.*` definitions |
66| [`whitewind`](./packages/definitions/whitewind): `com.whtwnd.*` definitions |
67| **Identity packages** |
68| [`identity`](./packages/identity/identity): handle, DID and DID document types |
69| [`identity-resolver`](./packages/identity/identity-resolver): handle and DID document resolution |
70| [`identity-resolver-node`](./packages/identity/identity-resolver-node): Node.js DNS-based handle resolver |
71| [`did-plc`](./packages/identity/did-plc): did:plc operation validation |
72| **Utility packages** |
73| [`car`](./packages/utilities/car): CAR archive codec |
74| [`cbor`](./packages/utilities/cbor): deterministic CBOR codec |
75| [`cid`](./packages/utilities/cid): content identifier codec |
76| [`crypto`](./packages/utilities/crypto): signing and verification |
77| [`mst`](./packages/utilities/mst): merkle search tree utilities |
78| [`multibase`](./packages/utilities/multibase): base32/base64 encoding |
79| [`repo`](./packages/utilities/repo): repository export reader |
80| [`tid`](./packages/utilities/tid): timestamp identifier codec |
81| [`varint`](./packages/utilities/varint): LEB128 varint codec |
82| **Bluesky-specific packages** |
83| [`bluesky-moderation`](./packages/bluesky/moderation): content moderation interpretation |
84| [`bluesky-richtext-builder`](./packages/bluesky/richtext-builder): rich text facet builder |
85| [`bluesky-richtext-parser`](./packages/bluesky/richtext-parser): parse rich text syntax |
86| [`bluesky-richtext-segmenter`](./packages/bluesky/richtext-segmenter): segment text by facets |
87| [`bluesky-search-parser`](./packages/bluesky/search-parser): search query tokenizer |
88| [`bluesky-threading`](./packages/bluesky/threading): atomic thread publishing |
89
90## contributing
91
92this monorepo uses [mise](https://mise.jdx.dev) for runtime versioning and pnpm for package
93management.
94
95```sh
96# install runtimes
97mise install
98
99# build all packages
100pnpm run -r build
101
102# pull latest lexicons and regenerate definitions
103pnpm run -r pull
104pnpm run -r generate
105```
106
107### package size reporting
108
109check bundle sizes with the `pkg-size-report` tool:
110
111> [!WARNING]
112> run `pnpm run -r build` first, otherwise measurements may be inaccurate.
113
114```sh
115pnpm pkg-size-report # show sizes (and diff if previously saved)
116pnpm pkg-size-report --save # save current sizes for comparison
117pnpm pkg-size-report --compare # show only changed packages
118```