|
| 1 | +--- |
| 2 | +name: lex-sdk |
| 3 | +description: > |
| 4 | + Use this skill whenever code interacts with the `@atproto/lex` SDK family. |
| 5 | + This family covers `@atproto/lex` and its companion packages: |
| 6 | + `@atproto/lex-client`, `@atproto/lex-data`, `@atproto/lex-json`, and |
| 7 | + `@atproto/lex-schema` (all re-exported by `@atproto/lex`), plus |
| 8 | + `@atproto/lex-cbor` and `@atproto/xrpc-server` (related companion packages |
| 9 | + that must be imported directly — they are NOT re-exported by `@atproto/lex`). |
| 10 | + Trigger on ANY of the following (OR logic — match any one): |
| 11 | + (1) XRPC calls with `Client`, `xrpc`, or `xrpcSafe`; |
| 12 | + (2) defining XRPC server routes (`createServer`, `server.add`); |
| 13 | + (3) validating lexicon-derived data (`$build`, `$matches`, `$isTypeOf`, |
| 14 | + `$parse`, `$safeParse`, `$validate`); |
| 15 | + (4) processing AT Protocol data: JSON ↔ Lex with `lexParse` / `lexStringify` / |
| 16 | + `jsonToLex` / `lexToJson`, or CBOR via the separate `@atproto/lex-cbor` package; |
| 17 | + (5) installing or building lexicons (`lex install`, `lex build`); |
| 18 | + (6) working with branded strings (`DidString`, `HandleString`, `AtUriString`, |
| 19 | + `Cid`, `DatetimeString`); |
| 20 | + (7) handling blobs (`BlobRef`, `TypedBlobRef`, `LegacyBlobRef`); |
| 21 | + (8) migrating a package from the legacy `@atproto/api` / `@atproto/lexicon` / |
| 22 | + `@atproto/xrpc` / `@atproto/lex-cli` stack to `@atproto/lex` ("lexification"). |
| 23 | + (9) replacement for zod/joi/ajv validation libraries, in projects that already |
| 24 | + require `@atproto/lex`. |
| 25 | + When a task matches multiple triggers, consult all corresponding references |
| 26 | + in the routing table below before responding. |
| 27 | +disable-model-invocation: false |
| 28 | +--- |
| 29 | + |
| 30 | +# `@atproto/lex` SDK |
| 31 | + |
| 32 | +`@atproto/lex` is the type-safe Lexicon SDK for AT Protocol. It generates |
| 33 | +TypeScript schemas from Lexicon JSON, validates and builds data at runtime, |
| 34 | +and provides an XRPC client + helpers for building services. |
| 35 | + |
| 36 | +This skill is split into focused references. Read the ones relevant to the |
| 37 | +current task — they are self-contained. If the task involves more than one |
| 38 | +concern (e.g., migrating a client that also uses CBOR, or both server routes |
| 39 | +and data validation), read **all** references whose Task column matches; when |
| 40 | +in doubt, prefer reading more references over fewer. If a referenced `.md` |
| 41 | +file is unavailable or cannot be read, state which file is missing and respond |
| 42 | +using only the information in this SKILL.md and general AT Protocol knowledge, |
| 43 | +noting the limitation explicitly. |
| 44 | + |
| 45 | +## When to read which reference |
| 46 | + |
| 47 | +| Reference | Task | |
| 48 | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 49 | +| [references/setup.md](./references/setup.md) | Install lexicons, configure `lex build`, set up scripts/gitignore | |
| 50 | +| [references/schemas.md](./references/schemas.md) | Use generated schemas: `$build`, `$matches`, `$isTypeOf`, `$parse`, `$safeParse`, `$validate`, `$type`, `$lxm`, `$Params`, `$Output`. Create custom schemas with the `l` builder. | |
| 51 | +| [references/data-model.md](./references/data-model.md) | Work with AT Proto data: `LexValue`, `Cid`, `BlobRef`, JSON ↔ Lex, CBOR, datetime, branded strings (`DidString`, `HandleString`, `AtUriString`, …), `graphemeLen`/`utf8Len` | |
| 52 | +| [references/xrpc.md](./references/xrpc.md) | Make low-level XRPC calls with `xrpc()` / `xrpcSafe()`, handle `XrpcResponseError` / `XrpcInvalidResponseError` / `XrpcInternalError` | |
| 53 | +| [references/client.md](./references/client.md) | Use the `Client` class: auth, `call`/`create`/`get`/`put`/`delete`/`list`/`applyWrites`, labelers, Actions, service proxy | |
| 54 | +| [references/server.md](./references/server.md) | Define XRPC server routes with `@atproto/xrpc-server` (`createServer`, `server.add`, handler shape) | |
| 55 | +| [references/lexification-server.md](./references/lexification-server.md) | Migrate **service / server** code from the legacy stack (old `src/lexicon/`, `ids.*`, `Server` from generated code, `server.app.bsky.…()` chains) | |
| 56 | +| [references/lexification-client.md](./references/lexification-client.md) | Migrate **client / consumer** code from the legacy stack (`AtpAgent` → `Client`, `.data` → `.body`, `XRPCError` → `XrpcError`, `jsonStringToLex` → `lexParse`, etc.) | |
| 57 | + |
| 58 | +## Top-level package layout |
| 59 | + |
| 60 | +The `@atproto/lex` SDK family is split into two groups: |
| 61 | + |
| 62 | +- **Re-exported sub-packages**: `@atproto/lex-client`, `@atproto/lex-schema`, |
| 63 | + `@atproto/lex-data`, `@atproto/lex-json`. Importing from either |
| 64 | + `@atproto/lex` or the sub-package path works. |
| 65 | +- **Companion packages (NOT re-exported)**: `@atproto/lex-cbor` and |
| 66 | + `@atproto/xrpc-server`. These are part of the SDK family and trigger this |
| 67 | + skill, but they must be imported directly from their own package paths — |
| 68 | + never from `@atproto/lex`. |
| 69 | + |
| 70 | +| Sub-package | Provides | |
| 71 | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 72 | +| `@atproto/lex-client` | `Client`, `xrpc`, `xrpcSafe`, `XrpcResponseError`, `XrpcInvalidResponseError`, `XrpcInternalError`, `XrpcResponseValidationError` | |
| 73 | +| `@atproto/lex-schema` | The `l` schema-builder namespace, `Schema` types, validation primitives | |
| 74 | +| `@atproto/lex-data` | `LexValue`, `LexMap`, `Cid`, `parseCid`, `BlobRef`, `TypedBlobRef`, `LegacyBlobRef`, branded strings (`DidString`, `HandleString`, `AtUriString`, `DatetimeString`, …), `graphemeLen`, `utf8Len`, `isLanguageString` | |
| 75 | +| `@atproto/lex-json` | `lexParse`, `lexStringify`, `jsonToLex`, `lexToJson`, `parseLexLink`, `encodeLexLink`, `parseLexBytes`, `encodeLexBytes` | |
| 76 | +| `@atproto/lex-cbor` | CBOR `encode` / `decode` (separate package, not re-exported by `@atproto/lex`) | |
| 77 | +| `@atproto/xrpc-server` | `createServer`, `Server` type, `Headers` (used to define server routes — not re-exported by `@atproto/lex`) | |
| 78 | + |
| 79 | +## Generated code conventions |
| 80 | + |
| 81 | +- Lexicon JSON lives in `./lexicons/`, manifest in `lexicons.json` (or |
| 82 | + `manifest.json` — both are committed). |
| 83 | +- Generated TS lives in `./src/lexicons/` (plural — gitignored, regenerated |
| 84 | + by `lex build`). |
| 85 | +- Import the namespace tree from the index: `import { app, com, chat } from './lexicons/index.js'`. |
| 86 | +- Schemas are accessed by NSID dot-path: `app.bsky.feed.post`, |
| 87 | + `com.atproto.repo.getRecord`, `app.bsky.feed.defs.postView`. |
| 88 | + |
| 89 | +## Related skills |
| 90 | + |
| 91 | +When writing or migrating tests for code that uses `@atproto/lex`, also see the [testing skill](../testing/SKILL.md) — it covers runner choice (vitest vs jest), test file location, and tsconfig setup. |
0 commit comments