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.bodyUnlike 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/subscriptionentrypoint when depending on the runtime packages. Only that entrypoint loadsws-client: keep it out of the main entrypoints oflex-rpcandlex-client(which aren't always bundled), so that code without subscriptions doesn't load it.Clienthas no subscription method. - Its first argument is a service URL, an
AgentConfigor anAgent. A URL or config connects throughdefaultWebsocket(aWebSocketFactory, the WebSocket counterpart offetch, overws-client) unless the config sets its ownwebsocket, with the config'sheadersmerged into the subscription's (Node.js only:ws-clientthrows on headers in browsers). AnAgentwithout awebsocketHandlerthrows aTypeError;buildAgent()and theClientconstructor build one from a config with awebsocket(passclient.agent). - Connection behavior (backoff, heartbeat, hooks,
shouldReconnect) belongs to thewebsocketfactory: for other options, usecreateWebSocketFactory(options)(ws-client'swebsocket()options, minussignalandheaders) rather than wrappingws-clientby hand.xrpcSubscribe()only takesparams,signal,headers,validateResponse,strictResponseProcessingandonMessageError. - Frames failing to decode or validate, error frames included, are handed back
to the stream with
throw()asXrpcSubscriptionErrors, whichws-client'sdefaultShouldReconnect()never retries.createWebSocketFactory()defaults todefaultSubscriptionShouldReconnect(), which also acceptsisRetryableSubscriptionError(err): build a customshouldReconnecton it, or transient error frames end the stream. Retrying e.g.ConsumerTooSlowis an explicit extra condition. - Resume from a cursor with a function:
params: () => ({ cursor })is re-invoked on every connection, so updatecursorfrom each message'sseq(or once it is processed). - The loop rejects with an
XrpcSubscriptionError, except an abort reason, which passes through unchanged. A handler error with ashouldRetry()method is wrapped inXrpcSubscriptionConnectionError, and an error thrown by aparamsfunction (or invalid params) inXrpcSubscriptionParamsError, both ascauseand retried when it is transient (so aparamsfunction looking up a cursor over XRPC is invoked again on the reconnect).ws-clienthooks 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 anonMessageErrorthat returns instead of throwing, or passvalidateResponse: falseand 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.