Index of every page on this site: llms.txt
All skills
bluesky-social avatar

/lex-client

@d9cdc54
by bluesky-socialbluesky-social/atproto9.7k stars
941
Run it yourself

Call AT Protocol XRPC services with the `Client` from `@atproto/lex`. Use when making an authenticated or unauthenticated HTTP request to an XRPC service, wiring one service to call another, logging in with OAuth or an app password, reading or writing repository records, uploading or fetching blobs, configuring headers, labelers, service proxying, retries, or request/response validation, handling XRPC errors, composing reusable client actions, or consuming an XRPC subscription (WebSocket event stream, firehose, `subscribeRepos`, `subscribeLabels`). Also use when replacing `AtpAgent`, `XrpcClient`, `@atproto/xrpc-server`'s `Subscription`, or a hand-rolled `fetch` call to an `/xrpc/` endpoint. For a full migration off the legacy client stack, use the lexification-client skill.

  • 1 file
  • 19.1 KB
  • Updated 3 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/bluesky-social/atproto/lex-client

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈199 tokens for metadata: the name and description. ≈4.7k when used: this file.

Description uses 10.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈798 characters, or 10.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

high-level XRPC client

Client wraps an authenticated (or anonymous) session with helpers for AT Proto repo operations (create, get, put, delete, list, listAll, applyWrites, uploadBlob, getBlob) plus the low-level call/xrpc/xrpcSafe request methods. Reach for it whenever there is a session to carry, or per-service config (headers, labelers, proxy target) worth encapsulating.

The standalone xrpc() / xrpcSafe() exports exist for one-off, session-less calls. Their first argument is an Agent | AgentOptions — a URL string, URL, AgentConfig object, or bare FetchHandler — and they otherwise share the same options, responses, and errors as the client methods.

import { xrpc } from '@atproto/lex-client'

await xrpc(hostUrl, com.atproto.sync.requestCrawl, { body: { hostname } })

Constructing

The constructor takes an Agent (anything with fetchHandler, optionally did) or AgentOptions (a URL string/URL, or an AgentConfig).

import { Client } from '@atproto/lex-client'

// Unauthenticated
const client = new Client('https://public.api.bsky.app')

// OAuth — OAuthSession implements Agent
import { type OAuthSession } from '@atproto/oauth-client-node'
const session: OAuthSession = await oauthClient.restore(userDid)
const client = new Client(session)

App password sessions (CLI / scripts / bots)

PasswordSession also implements Agent, plus AsyncDisposable — prefer await using so the session is deleted server-side on scope exit.

import {
  LexAuthFactorError,
  PasswordSession,
} from '@atproto/lex-password-session'

// Credentials as a single URL: https://<handle>:<app-password>@<pds-host>
await using session = await PasswordSession.login(
  process.env.APP_PASSWORD_CREDENTIALS,
)
const client = new Client(session)

Long-lived apps should persist session data via onUpdated and use PasswordSession.resume(data, options) on the next run rather than re-sending credentials. Other statics: createAccount(body, { service, ... }) and delete(data) (revoke stored session data without resuming it). login throws LexAuthFactorError when the account requires 2FA — catch it, prompt, and retry with authFactorToken.

Server-side calls with a static credential

No session needed — put the credential in the constructor headers. Internal services typically also relax response processing:

const client = new Client(
  {
    service: config.serviceUrl,
    headers: { authorization: `Bearer ${config.serviceApiKey}` },
  },
  // Trust internal services to send well-formed responses
  { strictResponseProcessing: false, validateResponse: config.devMode },
)

If the credential or URL must be resolved per-request, supply a custom agent:

const agent: Agent = {
  get did() {
    return undefined
  },
  async fetchHandler(path, init) {
    const { serviceUrl, serviceApiKey } = await getConfig()
    const headers = new Headers(init?.headers)
    headers.set('authorization', `Bearer ${serviceApiKey}`)
    return fetch(new URL(path, serviceUrl), { ...init, headers })
  },
}

const client = new Client(agent)

AgentConfig and fetchHandler are mutually exclusive — passing both throws a TypeError.

Service proxying, and one client for several services

service and labelers set the atproto-proxy / atproto-accept-labelers headers. Both are defaults and are overridable per request, so a single AppView-configured client can still reach the user's PDS directly — pass null to suppress the header for that request.

const client = new Client(session, {
  service: 'did:web:api.bsky.app#bsky_appview',
  labelers: ['did:plc:labeler1', 'did:plc:labeler2'],
})

// Proxied to the AppView (client default)
await client.call(app.bsky.feed.getTimeline)

// Straight to the user's PDS
await client.xrpc(com.atproto.repo.getRecord, {
  service: null,
  labelers: null,
  appLabelers: null,
  params: { repo: client.assertDid, collection, rkey: 'self' },
})

The record helpers (create, get, put, delete, list, listAll, *Record, applyWrites, uploadBlob, getBlob) already default to service: null / labelers: null, since repo operations belong on the PDS. Set them explicitly to proxy one.

Validation options

const client = new Client(session, {
  // Validate request bodies against the input schema before sending. Worth
  // enabling in dev/test to catch schema mistakes at the source.
  validateRequest: true, // default: false

  // Validate response bodies against the output schema.
  validateResponse: false, // default: true

  // Strict Lex decoding. `false` accepts legacy blobs, datetimes without
  // timezones, etc. — see the lex-schema skill.
  strictResponseProcessing: false, // default: true
})

All three are overridable per-call on call / xrpc / xrpcSafe.

Authentication accessors

client.did // DidString | undefined
client.assertAuthenticated() // throws if unauthenticated; narrows client.did
client.assertDid // DidString (throws if unauthenticated)

assertAuthenticated() is an assertion function, so TypeScript requires the receiver to have an explicit type annotation. const client = new Client(...) (inferred) will fail with TS2775 — write const client: Client = new Client(...) or annotate the parameter.

Requests

client.call() — returns the body, throws on failure

import { app } from './lexicons/index.js'

const profile = await client.call(app.bsky.actor.getProfile, {
  actor: 'pfrazee.com',
})

await client.call(app.bsky.feed.sendInteractions, { interactions })

const timeline = await client.call(
  app.bsky.feed.getTimeline,
  { limit: 50 },
  { signal, maxRetries: 3, headers: { 'custom-header': 'value' } },
)

The input argument is positional and distinct from the options: for a query it is the params, for a procedure the body, for an action the input. Methods that take neither can be called with the schema alone, but the options must never occupy the input slot — client.call(schema, options) sends options as query parameters and fails validation. Use client.call(schema, {}, options), or client.xrpc(schema, options).

client.xrpc() — full response

const response = await client.xrpc(app.bsky.feed.getTimeline, {
  params: { limit: 50 },
  signal,
  headers: { 'custom-header': 'value' },
})
response.status
response.headers.get('content-language')
response.body

Unlike call, xrpc takes a single options object with params / body as named fields, so options-only calls are unambiguous.

client.xrpcSafe() — discriminated result

Same request as xrpc(), but returns the failure instead of throwing:

const result = await client.xrpcSafe(com.atproto.identity.resolveHandle, {
  params: { handle: 'alice.bsky.social' },
})
if (result.success) {
  result.body
} else if (result.matchesSchemaErrors()) {
  result.error // narrowed to the errors declared by the schema
} else {
  throw result.reason
}

Errors

All failures extend XrpcError (error, message, matchesSchemaErrors(), shouldRetry()). The three concrete branches of XrpcFailure:

Class Meaning
XrpcResponseError Server returned a non-2xx status
XrpcInvalidResponseError Response is non-compliant — unexpected status, wrong encoding, bad data
XrpcInternalError Failed before a usable response existed (network, client)

Subclasses worth narrowing on: XrpcAuthenticationError (401, exposes wwwAuthenticate), XrpcResponseValidationError (response failed schema validation), and XrpcFetchError (the underlying fetch threw — the retryable internal error).

Only XrpcResponseError carries HTTP data. status, headers, and body do not exist on the XrpcFailure union, so narrow first:

if (!result.success && result instanceof XrpcResponseError) {
  result.status
  result.headers.get('retry-after')
}

Retries

call, xrpc, xrpcSafe, and the standalone functions all retry internally. Set maxRetries (default 0); tune with minRetryTimeout (500ms), maxRetryTimeout (30s), retryTimeoutFactor (2), retryHeaders (honour Retry-After / RateLimit-Reset, default true), or replace the predicate with retry(failure, { counter }). The defaults already cover the retryable status codes (408, 425, 429, 5xx) and network errors, so do not wrap calls in a manual retry loop.

Subscriptions

xrpcSubscribe(agent, ns, options) returns an async generator of validated messages ($type restored) that spans reconnects. Use it instead of @atproto/xrpc-server's Subscription or a raw WebSocket, and don't wrap it in a reconnect loop.

  • Import it from @atproto/lex, or from the @atproto/lex-rpc/subscription entrypoint when depending on the runtime packages. Only that entrypoint loads ws-client: keep it out of the main entrypoints of lex-rpc and lex-client (which aren't always bundled), so that code without subscriptions doesn't load it. Client has no subscription method.
  • Its first argument is a service URL, an AgentConfig or an Agent. A URL or config connects through defaultWebsocket (a WebSocketFactory, the WebSocket counterpart of fetch, over ws-client) unless the config sets its own websocket, with the config's headers merged into the subscription's (Node.js only: ws-client throws on headers in browsers). An Agent without a websocketHandler throws a TypeError; buildAgent() and the Client constructor build one from a config with a websocket (pass client.agent).
  • Connection behavior (backoff, heartbeat, hooks, shouldReconnect) belongs to the websocket factory: for other options, use createWebSocketFactory(options) (ws-client's websocket() options, minus signal and headers) rather than wrapping ws-client by hand. xrpcSubscribe() only takes params, signal, headers, validateResponse, strictResponseProcessing and onMessageError.
  • Frames failing to decode or validate, error frames included, are handed back to the stream with throw() as XrpcSubscriptionErrors, which ws-client's defaultShouldReconnect() never retries. createWebSocketFactory() defaults to defaultSubscriptionShouldReconnect(), which also accepts isRetryableSubscriptionError(err): build a custom shouldReconnect on it, or transient error frames end the stream. Retrying e.g. ConsumerTooSlow is an explicit extra condition.
  • Resume from a cursor with a function: params: () => ({ cursor }) is re-invoked on every connection, so update cursor from each message's seq (or once it is processed).
  • The loop rejects with an XrpcSubscriptionError, except an abort reason, which passes through unchanged. A handler error with a shouldRetry() method is wrapped in XrpcSubscriptionConnectionError, and an error thrown by a params function (or invalid params) in XrpcSubscriptionParamsError, both as cause and retried when it is transient (so a params function looking up a cursor over XRPC is invoked again on the reconnect). ws-client hooks see connection failures unwrapped.
  • A message failing validation ends the connection with an XrpcSubscriptionMessageError, not retryable (a resume from the last cursor would receive it again). To skip them, pass an onMessageError that returns instead of throwing, or pass validateResponse: false and validate each message yourself.

Records

create / get / put / delete

import { currentDatetimeString } from '@atproto/lex-schema'

const { uri, cid } = await client.create(app.bsky.feed.post, {
  text: 'Hello, world!',
  createdAt: currentDatetimeString(),
})

// Literal-key records (profile is rkey 'self') need no rkey
const profile = await client.get(app.bsky.actor.profile)
profile.value.displayName

const post = await client.get(app.bsky.feed.post, { rkey: '3jxf7z2k3q2' })

await client.put(app.bsky.actor.profile, { displayName: 'New Name' })
await client.delete(app.bsky.feed.post, { rkey: '3jxf7z2k3q2' })

rkey is optional for literal: and auto-generated (tid) keys and required otherwise; the type system enforces this, so a missing rkey shows up as a compile error rather than a runtime one. Shared options: validate (ask the PDS to validate), validateRequest (validate locally before sending), swapCommit (optimistic concurrency on the commit CID), and for put/delete also swapRecord (on the record's own CID).

list / listAll — paginating a collection

Listed records are a discriminated union on valid: entries that fail schema validation still come back, with value widened to LexMap. Check valid before touching typed fields.

const page = await client.list(app.bsky.feed.post, { limit: 50, reverse: true })
for (const record of page.records) {
  if (record.valid) console.log(record.uri, record.value.text)
}
if (page.cursor) {
  await client.list(app.bsky.feed.post, { cursor: page.cursor, limit: 50 })
}

listAll() is the auto-paginating async generator — prefer it over hand-rolling a cursor loop. It defaults to maxRetries: 3 since a long walk is far more likely to hit a transient failure:

for await (const record of client.listAll(app.bsky.feed.post)) {
  if (record.valid) console.log(record.value.text)
}

applyWrites — atomic batch writes

All ops succeed or fail together. Options: repo (defaults to client.did), validate, swapCommit.

const response = await client.applyWrites((op) => [
  op.create(app.bsky.feed.post, {
    text: 'Hello!',
    createdAt: currentDatetimeString(),
  }),
  op.update(app.bsky.actor.profile, { displayName: 'Alice' }),
  op.delete(app.bsky.feed.post, { rkey: '3jxf7z2k3q2' }),
])

response.body.results is optional, and is a union in which deleteResult has no uri or cid. Narrow before reading them:

for (const result of response.body.results ?? []) {
  if (com.atproto.repo.applyWrites.createResult.$isTypeOf(result)) {
    console.log(result.uri, result.cid)
  }
}

The callback may also be a generator, which reads better for dynamic batches:

await client.applyWrites(function* (op) {
  for (const rkey of staleRkeys) yield op.delete(app.bsky.feed.post, { rkey })
})

Blobs

const { body } = await client.uploadBlob(bytes, { encoding: 'image/png' })
body.blob // BlobRef — store this in a record

const image = await client.getBlob(did, cid)

// Large payloads: get the unread ReadableStream instead of a Uint8Array
await using response = await client.getBlobStream(did, cid)

xrpcStream() / xrpcStreamSafe() / getBlobStream() return an XrpcStreamResponse (binary outputs only). The caller owns the stream: consume it, cancel() it, or dispose of the response. Buffered responses are not disposable.

Labelers

// Process-global defaults, always sent with `;redact`
Client.configure({ appLabelers: ['did:plc:labeler1'] })

// Per-client, and mutable at runtime
const client = new Client(session, { labelers: ['did:plc:labeler3'] })
client.addLabelers(['did:plc:labeler4'])
client.setLabelers(['did:plc:labeler5'])
client.clearLabelers()

Pass appLabelers: null on a request to drop the process-global ones. The usual post-login flow reads the user's preference:

const { preferences } = await client.call(app.bsky.actor.getPreferences)
const pref = preferences.findLast(app.bsky.actor.defs.labelersPref.$isTypeOf)
client.setLabelers(pref?.labelers.map((l) => l.did) ?? [])

Actions — composable client operations

An Action<Input, Output> is (client, input, options) => Output | Promise<Output>. client.call() accepts one anywhere a schema fits, so an action is interchangeable with a lexicon method at the call site.

import { type Action, Client } from '@atproto/lex-client'
import { currentDatetimeString } from '@atproto/lex-schema'
import { app } from './lexicons/index.js'

type LikeInput = { uri: AtUriString; cid: CidString }

export const likePost: Action<LikeInput, CreateOutput> = async (
  client: Client, // explicit — required by assertAuthenticated() below
  { uri, cid },
  options,
) => {
  client.assertAuthenticated()
  return client.create(
    app.bsky.feed.like,
    { subject: { uri, cid }, createdAt: currentDatetimeString() },
    options,
  )
}

await client.call(likePost, { uri, cid })

Actions compose — thread options through so cancellation propagates:

const upsertPreference: Action<Preference, Preference[]> = async (
  client,
  pref,
  options,
) => {
  const { preferences } = await client.call(
    app.bsky.actor.getPreferences,
    {},
    options,
  )
  options?.signal?.throwIfAborted()
  const updated = [...preferences.filter((p) => p.$type !== pref.$type), pref]
  await client.call(
    app.bsky.actor.putPreferences,
    { preferences: updated },
    options,
  )
  return updated
}

Export actions individually rather than as one object, so consumers tree-shake what they don't call:

// actions.ts
export const post: Action</* ... */> = async (c, i, o) => {/* ... */}
export const follow: Action</* ... */> = async (c, i, o) => {/* ... */}

// usage
import * as actions from './actions.js'
await client.call(actions.post, { text: 'Hello!' })

Guidelines: annotate as Action<Input, Output> (it contextually types the parameters); call client.assertAuthenticated() when auth is required; options?.signal?.throwIfAborted() between long steps; and handle swap-error retries here rather than pushing optimistic-concurrency handling onto callers.

Related skills

  • lex-schema — the generated schemas passed to every client method, and $isTypeOf / $build / $type.
  • lex-data — blobs, CIDs, branded strings, and datetimes at the call boundary.
  • lexification-client — migrating from AtpAgent / XrpcClient.
  • xrpc-server — the other half, when the service also serves XRPC routes.
  • lex-setup — installing lexicons and configuring the codegen that produces ./lexicons/index.js.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at d9cdc54. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
disable-model-invocation
false

README badge

README badge for bluesky-social/atproto/lex-client