lex-client

Call AT Protocol XRPC services with the typed Client from @atproto/lex.

9.6k|915|Updated Dec 17, 2021
One-click install
npx skills add https://github.com/bluesky-social/atproto --skill lex-client
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: lex-client
Source: https://github.com/bluesky-social/atproto/tree/main/.agents/skills/lex-client
Command: npx skills add https://github.com/bluesky-social/atproto --skill lex-client

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @atproto/lex, @atproto/lex-password-session, @atproto/oauth-client-node.

What problem does it solve?

Making authenticated or unauthenticated HTTP calls to AT Protocol XRPC services requires juggling sessions, headers, service proxying, retries, and schema validation by hand. This Skill provides the patterns for using the Client from @atproto/lex so those concerns are handled consistently and type-safely.

Core Features & Use Cases

  • Session-based requests: Construct a client from an OAuth session, an app-password PasswordSession, a static service credential, or a custom agent, then call any Lexicon-defined query or procedure.
  • Repository operations: Create, read, update, delete, list, and batch-write records, plus upload and fetch blobs, with typed results and optimistic-concurrency options.
  • Resilience and control: Configure retries, request/response validation, labelers, service proxying, and handle typed XRPC errors via throwing or discriminated-result APIs.
  • Use Case: A bot logs in with an app password, pages through a user's posts with listAll, and atomically deletes stale records with applyWrites, all with automatic retries and schema-checked responses.

Quick Start

Ask the AI to write a TypeScript script that logs into Bluesky with an app password using PasswordSession and creates a feed post via the @atproto/lex Client.

Frequently Asked Questions about lex-client

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I call an XRPC endpoint in TypeScript with @atproto/lex?

Create a Client with a service URL or session, then use client.call(schema, input) to get the response body, client.xrpc for the full response, or client.xrpcSafe for a discriminated result. The standalone xrpc() export handles one-off session-less calls.

How do I log in to Bluesky with an app password in a script?

Use PasswordSession.login from @atproto/lex-password-session with a credentials URL, then pass the session to new Client(session). Prefer await using so the session is deleted server-side on scope exit, and catch LexAuthFactorError for 2FA accounts.

What is the difference between AtpAgent and the @atproto/lex Client?

Client from @atproto/lex is the newer type-safe client generated from Lexicon schemas, replacing AtpAgent and XrpcClient. New code should prefer @atproto/lex; the lexification-client skill covers migrating off the legacy stack.

Does the @atproto/lex Client retry failed requests automatically?

Yes, call, xrpc, and xrpcSafe retry internally when maxRetries is set, covering 408, 425, 429, 5xx statuses and network errors. Backoff is tunable via minRetryTimeout, maxRetryTimeout, and retryTimeoutFactor, so manual retry loops are unnecessary.

Why does client.assertAuthenticated() cause TypeScript error TS2775?

assertAuthenticated is an assertion function, so the receiver needs an explicit type annotation. Write const client: Client = new Client(...) instead of relying on inference, or annotate the function parameter.

How do I send requests to the user's PDS instead of the AppView?

Pass service: null and labelers: null on the individual request to override the client's proxy defaults. The record helpers like create, get, and list already default to direct PDS access since repo operations belong there.