---
name: lexification-client
description: >-
  Migrate AT Protocol client and consumer code off the legacy `@atproto/api`, `@atproto/lexicon`, and `@atproto/xrpc` stack onto `@atproto/lex`. Use whenever code that *calls out* to an XRPC service is being modernized — replacing an `AtpAgent` with `Client`, `result.data` / `result.headers[…]` response handling, `XRPCError` try/catch, `jsonStringToLex` / `stringifyLex`, `BlobRef` `instanceof` checks, `CID` from `multiformats`, `new Date().toISOString()` on AT Proto datetimes, bare `string` DIDs and handles, or legacy `isX()` type guards — including when the request is phrased as "clean this up" or "modernize this file" rather than "migrate". For code that *defines* routes, use the lexification-server skill.
disable-model-invocation: false
title: lexification-client
canonical_url: https://skilld.dev/gh/bluesky-social/atproto/lexification-client
last_updated: 2026-11-14T06:30:25.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install bluesky-social/atproto/lexification-client`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/lexification-client`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/bluesky-social/atproto/lexification-client) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/lexification-client`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/lexification-client --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/lexification-client --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Lexification: migrating client / consumer code

Scope: **calls out**. Anything that used `AtpAgent` or the `@atproto/lexicon` /
`@atproto/xrpc` runtime to talk to an AT Proto service, plus the data types
that flow across that boundary.

Route _definitions_ (`server.add`, handler signatures, codegen removal) are the
[lexification-server skill](../lexification-server/SKILL.md). A service package
almost always needs both: it defines routes **and** calls other services. If
you're mid-migration on a service and reach an `agent.api.…` call, you're in
the right file.

## What changes

| Old                                               | New                                                                    |
| ------------------------------------------------- | ---------------------------------------------------------------------- |
| `AtpAgent` from `@atproto/api`                    | `Client` from `@atproto/lex-client`                                    |
| `agent.api.<ns>.<method>(params, { headers })`    | `client.call(<schema>, params, opts)` or `client.xrpc(<schema>, opts)` |
| `result.data`                                     | `result.body`                                                          |
| `result.headers['content-language']`              | `result.headers.get('content-language')` (standard `Headers`)          |
| `XRPCError` from `@atproto/xrpc`                  | `XrpcError` from `@atproto/lex-client`                                 |
| try/catch + `instanceof XRPCError`                | `xrpcSafe()` / `client.xrpcSafe()` discriminated result                |
| `HeadersMap` from `@atproto/xrpc`                 | `Headers as HeadersMap` from `@atproto/xrpc-server`                    |
| `jsonStringToLex` / `stringifyLex`                | `lexParse` / `lexStringify`                                            |
| `BlobRef` class from `@atproto/lexicon`           | `BlobRef` interface from `@atproto/lex-data`                           |
| `CID` from `multiformats/cid`                     | `Cid` / `parseCid` from `@atproto/lex-data`                            |
| `new Date().toISOString()` for AT Proto datetimes | `currentDatetimeString()` / `toDatetimeString()`                       |
| `isX(v)` from `src/lexicon/types/…`               | `<ns>.<def>.$matches(v)` / `.$isTypeOf(v)`                             |

## XRPC calls

Three shapes, in rough order of preference — pick the least machinery that
covers what the call site actually uses.

### `call()` — you only want the body

Errors propagate as exceptions. Params (query) or body (procedure) go in the
second argument; everything else in the third.

```ts
return ctx.suggestionsClient.call(
  app.bsky.unspecced.getSuggestedUsersSkeleton,
  { limit: params.limit, viewer: params.hydrateCtx.viewer ?? undefined },
  { headers: params.headers },
)
```

### `xrpc()` — you need status or headers too

```diff
- const res = await ctx.suggestionsAgent.api.app.bsky.unspecced.getSuggestionsSkeleton(
-   { viewer: params.hydrateCtx.viewer, relativeToDid },
-   { headers: params.headers },
- )
- return {
-   suggestedDids: res.data.actors.map((a) => a.did),
-   resHeaders: res.headers,
- }
+ const res = await ctx.suggestionsClient.xrpc(
+   app.bsky.unspecced.getSuggestionsSkeleton,
+   {
+     params: { viewer: params.hydrateCtx.viewer, relativeToDid },
+     headers: params.headers,
+   },
+ )
+ const contentLang = res.headers.get('content-language')
+ return {
+   suggestedDids: res.body.actors.map((a) => a.did),
+   resHeaders: contentLang ? { 'content-language': contentLang } : undefined,
+ }
```

Everything is one options object: query params under `params`, procedure
bodies under `body` (not `input`), plus `headers`, `signal`, `service`,
`labelers`, `maxRetries`, and the validation flags.

Response headers are a standard `Headers` instance. If the value flows into
something typed `HeadersMap` (`Record<string, string>`), pull the specific
headers out with `.get()` as above; if the consumer takes `Headers`, pass it
through unchanged.

### `xrpcSafe()` — errors are part of the contract

Returns a discriminated result instead of throwing, and the failure is typed
against the method schema. Use it where the call site already had a `catch`
that inspected the error rather than just rethrowing.

Narrow on the concrete failure class when the branches map to different
downstream responses (see `packages/bsky/src/api/app/bsky/feed/getFeed.ts`):

```ts
import {
  XrpcInvalidResponseError,
  XrpcResponseError,
  xrpcSafe,
} from '@atproto/lex-client'

const result = await xrpcSafe(fgEndpoint, app.bsky.feed.getFeedSkeleton, {
  strictResponseProcessing: false,
  signal: AbortSignal.timeout(10_000),
  headers,
  params: { feed, limit, cursor },
})

if (!result.success) {
  const cause = result.reason

  // Structurally valid XRPC error (4xx/5xx) — pass it through
  if (cause instanceof XrpcResponseError) {
    const { status, body } = cause.toDownstreamError()
    throw new XRPCError(status, body.message, body.error, { cause })
  }

  // Response didn't match the schema
  if (cause instanceof XrpcInvalidResponseError) {
    throw new UpstreamFailureError(
      'feed provided an invalid response',
      'InvalidFeedResponse',
      { cause },
    )
  }

  // Typically a network error
  throw new UpstreamFailureError('feed unavailable', undefined, { cause })
}

const { feed: feedSkele, cursor } = result.body // typed
```

`toDownstreamError()` is what replaces hand-mapping upstream status codes: it
remaps 500 → 502 and strips hop-by-hop headers. It does **not** redact — when
the upstream payload is a structurally valid XRPC error, its `error` / `message`
are passed through verbatim for transparency. Sanitize them yourself before
re-throwing if the upstream may leak internal detail.

When you only care about one schema-declared error code, skip the class checks:

```ts
const res = await xrpcSafe(pds, com.atproto.sync.getLatestCommit, {
  params: { did },
})
if (res.success) return true
if (res.error === 'RepoNotFound') return false
throw res.reason
```

`result.matchesSchemaErrors()` narrows `result.error` to the codes the method
declares, for when you want the compiler to check the code strings.

The old `ResponseType` enum comparisons have no replacement and don't need one:
`XrpcInvalidResponseError` covers `ResponseType.InvalidResponse`, and
`XrpcInternalError` / `XrpcFetchError` cover `ResponseType.Unknown`.

Retries are built in (`maxRetries`, default `0`), so delete any hand-rolled
retry loop wrapped around the call. See [lex-client](../lex-client/SKILL.md)
for the full error hierarchy and client API.

## Agent → Client

```diff
- import { AtpAgent } from '@atproto/api'
+ import { Client } from '@atproto/lex-client'

- searchAgent: AtpAgent | undefined
+ searchClient: Client | undefined
```

`Client` takes **two** arguments: the agent (a service URL, an `AgentConfig`,
or a session), then per-client options. Static headers belong in the agent
config rather than an imperative `setHeader` after construction — one frozen
config then describes the whole client (see `packages/bsky/src/index.ts`):

```diff
- const myServiceAgent = config.serviceUrl
-   ? new AtpAgent({ service: config.serviceUrl })
-   : undefined
- if (myServiceAgent && config.serviceApiKey) {
-   myServiceAgent.api.setHeader('authorization', `Bearer ${config.serviceApiKey}`)
- }
+ const myServiceClient = config.serviceUrl
+   ? new Client(
+       {
+         service: config.serviceUrl,
+         headers: config.serviceApiKey
+           ? { authorization: `Bearer ${config.serviceApiKey}` }
+           : undefined,
+       },
+       {
+         // Trust internal services to send us well-formed responses
+         strictResponseProcessing: false,
+         validateResponse: config.debugMode,
+       },
+     )
+   : undefined
```

That second argument is worth setting for internal service-to-service clients:
`Client` validates responses by default, which is stricter than `AtpAgent` was,
so a migrated call can start failing on data the old code happily accepted.

## Errors

```diff
- import { XRPCError } from '@atproto/xrpc'
+ import { XrpcError } from '@atproto/lex-client'
```

`@atproto/xrpc-server` keeps its own `XRPCError` for **throwing** errors out of
handlers — that one is unrelated and stays. A file can legitimately import
both (getFeed.ts above does): `XrpcError` describes a failed call out,
`XRPCError` produces the response going back down.

## Headers map type

```diff
- import { HeadersMap } from '@atproto/xrpc'
+ import type { Headers as HeadersMap } from '@atproto/xrpc-server'
```

Alias it — the unaliased `Headers` shadows the global `Headers` type, which the
same file usually also needs.

## Data utilities

### JSON ↔ Lex

```diff
- import { jsonStringToLex } from '@atproto/lexicon'
+ import { lexParse } from '@atproto/lex-json'

- const parsed = jsonStringToLex(payload.toString('utf8')) as SubjectActivitySubscription
+ const parsed = lexParse<app.bsky.notification.defs.SubjectActivitySubscription>(
+   payload.toString('utf8'),
+ )
```

`lexParse` takes a type parameter, so the `as` cast goes away. `stringifyLex` →
`lexStringify`. See [lex-data](../lex-data/SKILL.md) for `jsonToLex`,
`lexToJson`, `lexParseJsonBytes`, `parseLexLink`, `parseLexBytes`.

### Datetime strings

```diff
- createdAt: new Date().toISOString(),
+ createdAt: currentDatetimeString(),

- indexedAt: someDate.toISOString(),
+ indexedAt: toDatetimeString(someDate),
```

Both come from `@atproto/lex-schema` and return the branded `DatetimeString`, so
a value that reaches a lexicon field is checked at the type level rather than at
validation time.

### CIDs

```diff
- import { CID } from 'multiformats/cid'
+ import { type Cid, parseCid } from '@atproto/lex-data'
```

`Cid` is an interface. Drop `multiformats` from the package's dependencies once
no imports remain.

### BlobRef

`BlobRef` is now an interface (a union of `TypedBlobRef` and `LegacyBlobRef`),
so `instanceof` no longer works — and the hand-written fallbacks that used to
paper over the two JSON shapes are exactly what the helpers replace:

```diff
- import { BlobRef } from '@atproto/lexicon'
+ import { type BlobRef, getBlobCidString } from '@atproto/lex-data'

- export const cidFromBlobJson = (json: BlobRef) => {
-   if (json instanceof BlobRef) return json.ref.toString()
-   if (json['$type'] === 'blob') return (json['ref']?.['$link'] ?? '') as string
-   return (json['cid'] ?? '') as string
- }
+ export const cidFromBlobJson = (json: BlobRef): string => getBlobCidString(json)
```

```diff
- if (value instanceof BlobRef) { ... }
+ if (isBlobRef(value)) { ... }
```

`isBlobRef` validates the CID strictly by default; pass `{ strict: false }` for
legacy data. See [lex-data](../lex-data/SKILL.md) for the
`TypedBlobRef` / `LegacyBlobRef` split.

## Branded types at boundaries

Apply `DidString`, `HandleString`, `AtUriString`, `DatetimeString`, `Cid` at
signatures, interface fields, and DB schema types — that's where they stop bad
values propagating. Prefer importing them from `@atproto/lex-schema` (`Cid`
from `@atproto/lex-data`) over `@atproto/syntax`.

```diff
- did: string
+ did: DidString

- iss: string
+ iss: DidString | `${DidString}#${string}`
```

Prefix checks become guards:

```diff
- if (typeof iss !== 'string' || !iss.startsWith('did:')) {
+ if (typeof iss !== 'string' || !isDidString(iss)) {
```

Data arriving from protobuf, the data plane, or Kysely is plain `string`. Cast
once at that entry point rather than asserting at every later use:

```diff
- suggestedDids: dids,
+ suggestedDids: dids as DidString[],
```

## Type guards

```diff
- import { isRepoRef } from '../../../../lexicon/types/com/atproto/admin/defs'
- if (isRepoRef(subject)) { ... }
+ if (com.atproto.admin.defs.repoRef.$isTypeOf(subject)) { ... }
```

`$isTypeOf` is the behavioral equivalent of a legacy `isX()` guard, so it is the
default when replacing one — this is what the repo migrated to (see
`packages/pds/src/api/com/atproto/admin/updateSubjectStatus.ts`). It checks only
the `$type` tag, which is all that matters on an already-validated union, and it
doubles as a predicate:

```diff
- const pref = prefs.find((p) => p.$type === 'app.bsky.actor.defs#personalDetailsPref')
+ const pref = prefs.find(app.bsky.actor.defs.personalDetailsPref.$isTypeOf)
```

Reach for `$matches` instead only where the data is genuinely untrusted and a
`$type` tag alone isn't enough of a guarantee — it validates the whole value, so
it costs more. Treat that as a deliberate upgrade at an entry point, not the
default swap for an `isX()` call.

See [lex-schema](../lex-schema/SKILL.md) for the full `$`-accessor cheat sheet.

## Tests

Test migration is partial and lags the source migration. The `pds`, `bsky` and
`ozone` suites mostly still drive `AtpAgent` from `@atproto/api`, and `dev-env`
exposes both `getAgent(): AtpAgent` and `getClient(): Client` for exactly that
reason.

A suite still on `AtpAgent` hydrates blobs into **legacy `BlobRef` class
instances**, which only `@atproto/lexicon`'s `lexToJson` knows how to flatten.
Swapping a test helper to `@atproto/lex`'s `lexToJson` leaves those instances
untouched and leaks their internal `original` field into snapshots — which reads
like a wire-format regression in the service under test. Keep the legacy
converter until the suite itself moves to `Client`.

Default to leaving passing tests alone: during a source migration their value
is being an unchanged runtime regression check. Two things force a change:

- **A test imports a legacy path you deleted** (`src/lexicon/…`). Point it at
  the `@atproto/api` equivalent (`ComAtprotoAdminDefs`, `ids`, `$Typed`) — the
  smallest edit that keeps the test running.
- **You are deliberately migrating that test file.** Then it moves wholesale:
  `network.pds.getClient()`, schemas from `src/lexicons/index.js`, `res.body`,
  and helpers like `getBlobCidString` from `@atproto/lex-data`.
  `packages/pds/tests/file-uploads.test.ts` is a migrated example.

Avoid half-migrating a file — a suite mixing `agent.api.…` and `client.call(…)`
for the same operation is harder to read than either end state.

## Import source summary

| Before                                            | After                                                             |
| ------------------------------------------------- | ----------------------------------------------------------------- |
| `@atproto/api` (`AtpAgent`)                       | `@atproto/lex-client` (`Client`)                                  |
| `@atproto/lexicon` (`jsonStringToLex`, `BlobRef`) | `@atproto/lex-json` (`lexParse`), `@atproto/lex-data` (`BlobRef`) |
| `@atproto/lexicon` (`stringifyLex`)               | `@atproto/lex-json` (`lexStringify`)                              |
| `@atproto/xrpc` (`XRPCError`)                     | `@atproto/lex-client` (`XrpcError`, `xrpcSafe`)                   |
| `@atproto/xrpc` (`HeadersMap`)                    | `@atproto/xrpc-server` (`Headers as HeadersMap`)                  |
| `multiformats/cid` (`CID`)                        | `@atproto/lex-data` (`Cid`, `parseCid`)                           |
| `@atproto/syntax` (`DidString`, etc.)             | `@atproto/lex-schema` (prefer this)                               |

Dropped imports usually mean dropped `package.json` dependencies
(`multiformats`, `@atproto/lexicon`, `@atproto/xrpc`), and every package
touched needs a changeset entry.

## Related skills

[lex-client](../lex-client/SKILL.md) for the full `Client` API you're migrating
onto, [lex-setup](../lex-setup/SKILL.md) for codegen and dependency wiring, and
[lexification-server](../lexification-server/SKILL.md) for the route-definition
half — service packages need both.
