@atproto/lex-client 0.0.15 → 0.0.17

package/src/agent.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  type Agent,
+  type AgentConfig,
+  type FetchHandler,
+  buildAgent,
+  isAgent,
+} from './agent.js'
+
+// ============================================================================
+// isAgent
+// ============================================================================
+
+describe(isAgent, () => {
+  it('returns true for a valid agent with did', () => {
+    const agent: Agent = {
+      did: 'did:plc:example',
+      fetchHandler: async () => new Response(),
+    }
+    expect(isAgent(agent)).toBe(true)
+  })
+
+  it('returns true for an agent without did', () => {
+    const agent = { fetchHandler: async () => new Response() }
+    expect(isAgent(agent)).toBe(true)
+  })
+
+  it('returns true when did is undefined', () => {
+    const agent = { did: undefined, fetchHandler: async () => new Response() }
+    expect(isAgent(agent)).toBe(true)
+  })
+
+  it('returns false for null', () => {
+    expect(isAgent(null)).toBe(false)
+  })
+
+  it('returns false for non-objects', () => {
+    expect(isAgent('string')).toBe(false)
+    expect(isAgent(42)).toBe(false)
+    expect(isAgent(undefined)).toBe(false)
+  })
+
+  it('returns false when fetchHandler is not a function', () => {
+    expect(isAgent({ fetchHandler: 'not-a-function' })).toBe(false)
+  })
+
+  it('returns false when did is not a string', () => {
+    expect(isAgent({ did: 42, fetchHandler: async () => new Response() })).toBe(
+      false,
+    )
+  })
+})
+
+// ============================================================================
+// buildAgent
+// ============================================================================
+
+describe(buildAgent, () => {
+  describe('from Agent', () => {
+    it('returns the same agent instance', () => {
+      const agent: Agent = {
+        did: 'did:plc:example',
+        fetchHandler: async () => new Response(),
+      }
+      expect(buildAgent(agent)).toBe(agent)
+    })
+  })
+
+  describe('from FetchHandler', () => {
+    it('wraps a function as an agent', () => {
+      const handler: FetchHandler = async () => new Response()
+      const agent = buildAgent(handler)
+
+      expect(agent.did).toBeUndefined()
+      expect(typeof agent.fetchHandler).toBe('function')
+    })
+  })
+
+  describe('from string URL', () => {
+    it('creates an agent that prepends the service URL', async () => {
+      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
+        Response.json({ ok: true }),
+      )
+      const agent = buildAgent({
+        service: 'https://example.com',
+        fetch: fetchFn,
+      })
+
+      await agent.fetchHandler('/xrpc/io.example.test', { method: 'GET' })
+
+      expect(fetchFn).toHaveBeenCalledOnce()
+      const [url, init] = fetchFn.mock.calls[0]
+      expect(url).toEqual(
+        new URL('/xrpc/io.example.test', 'https://example.com'),
+      )
+      expect(init?.method).toBe('GET')
+    })
+
+    it('has undefined did', () => {
+      const agent = buildAgent('https://example.com')
+      expect(agent.did).toBeUndefined()
+    })
+  })
+
+  describe('from URL instance', () => {
+    it('creates an agent with the URL as service', async () => {
+      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
+        Response.json({ ok: true }),
+      )
+      const agent = buildAgent({
+        service: new URL('https://example.com'),
+        fetch: fetchFn,
+      })
+
+      await agent.fetchHandler('/xrpc/io.example.test', { method: 'GET' })
+
+      expect(fetchFn).toHaveBeenCalledOnce()
+      const [url] = fetchFn.mock.calls[0]
+      expect(url).toEqual(
+        new URL('/xrpc/io.example.test', 'https://example.com'),
+      )
+    })
+  })
+
+  describe('from AgentConfig', () => {
+    it('exposes did from config', () => {
+      const agent = buildAgent({
+        did: 'did:plc:test123',
+        service: 'https://example.com',
+      })
+      expect(agent.did).toBe('did:plc:test123')
+    })
+
+    it('reflects did changes on the config object', () => {
+      const config: AgentConfig = {
+        did: 'did:plc:original',
+        service: 'https://example.com',
+      }
+      const agent = buildAgent(config)
+      expect(agent.did).toBe('did:plc:original')
+
+      config.did = 'did:plc:updated'
+      expect(agent.did).toBe('did:plc:updated')
+    })
+
+    it('throws TypeError when fetch is not available', () => {
+      const originalFetch = globalThis.fetch
+      try {
+        // @ts-expect-error removing fetch to simulate missing environment
+        globalThis.fetch = undefined
+        expect(() => buildAgent({ service: 'https://example.com' })).toThrow(
+          TypeError,
+        )
+      } finally {
+        globalThis.fetch = originalFetch
+      }
+    })
+  })
+
+  describe('headers', () => {
+    it('sends config headers when no request headers', async () => {
+      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
+        Response.json({}),
+      )
+      const agent = buildAgent({
+        service: 'https://example.com',
+        headers: { Authorization: 'Bearer token123' },
+        fetch: fetchFn,
+      })
+
+      await agent.fetchHandler('/xrpc/test', { method: 'GET' })
+
+      const [, init] = fetchFn.mock.calls[0]
+      expect(init?.headers).toEqual({ Authorization: 'Bearer token123' })
+    })
+
+    it('sends request headers when no config headers', async () => {
+      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
+        Response.json({}),
+      )
+      const agent = buildAgent({
+        service: 'https://example.com',
+        fetch: fetchFn,
+      })
+
+      await agent.fetchHandler('/xrpc/test', {
+        method: 'GET',
+        headers: { 'X-Custom': 'value' },
+      })
+
+      const [, init] = fetchFn.mock.calls[0]
+      expect(init?.headers).toEqual({ 'X-Custom': 'value' })
+    })
+
+    it('merges config and request headers, with request taking priority', async () => {
+      const fetchFn = vi.fn<typeof globalThis.fetch>(async () =>
+        Response.json({}),
+      )
+      const agent = buildAgent({
+        service: 'https://example.com',
+        headers: { Authorization: 'Bearer default', 'X-Default': 'yes' },
+        fetch: fetchFn,
+      })
+
+      await agent.fetchHandler('/xrpc/test', {
+        method: 'GET',
+        headers: { Authorization: 'Bearer override' },
+      })
+
+      const [, init] = fetchFn.mock.calls[0]
+      const headers = new Headers(init?.headers)
+      expect(headers.get('Authorization')).toBe('Bearer override')
+      expect(headers.get('X-Default')).toBe('yes')
+    })
+  })
+})

package/src/agent.ts

@@ -101,7 +101,7 @@ export type AgentConfig = {
  *
  * Can be a full {@link AgentConfig} object, or a simple service URL string/{@link URL}.
  */
-export type AgentOptions = AgentConfig | string | URL
+export type AgentOptions = AgentConfig | FetchHandler | string | URL
 
 /**
  * Creates an {@link Agent} from various input types.
@@ -132,12 +132,14 @@ export function buildAgent<O extends Agent | AgentOptions>(
   options: O,
 ): O extends Agent ? O : Agent
 export function buildAgent(options: Agent | AgentOptions): Agent {
-  if (isAgent(options)) return options
-
   const config: Agent | AgentConfig =
-    typeof options === 'string' || options instanceof URL
-      ? { did: undefined, service: options }
-      : options
+    typeof options === 'function'
+      ? { did: undefined, fetchHandler: options }
+      : typeof options === 'string' || options instanceof URL
+        ? { did: undefined, service: options }
+        : options
+
+  if (isAgent(config)) return config
 
   const { service, fetch = globalThis.fetch } = config
 

package/src/client.ts

@@ -20,10 +20,24 @@ import {
 import { Agent, AgentOptions, buildAgent } from './agent.js'
 import { XrpcFailure } from './errors.js'
 import { com } from './lexicons/index.js'
-import { XrpcResponse, XrpcResponseBody } from './response.js'
-import { BinaryBodyInit, CallOptions, Service } from './types.js'
-import { buildAtprotoHeaders } from './util.js'
-import { XrpcOptions, XrpcRequestParams, xrpc, xrpcSafe } from './xrpc.js'
+import {
+  XrpcResponse,
+  XrpcResponseBody,
+  XrpcResponseOptions,
+} from './response.js'
+import { BinaryBodyInit, Service } from './types.js'
+import {
+  XrpcRequestHeadersOptions,
+  applyDefaults,
+  buildXrpcRequestHeaders,
+} from './util.js'
+import {
+  XrpcOptions,
+  XrpcRequestParams,
+  XrpcRequestProcessingOptions,
+  xrpc,
+  xrpcSafe,
+} from './xrpc.js'
 
 export type {
   AtIdentifierString,
@@ -58,13 +72,13 @@ export type {
  * }
  * ```
  */
-export type ClientOptions = {
-  /** Labeler DIDs to include in requests for content moderation. */
-  labelers?: Iterable<DidString>
-  /** Custom headers to include in all requests made by this client. */
-  headers?: HeadersInit
-  /** Service proxy identifier for routing requests through a specific service. */
-  service?: Service
+export type ClientOptions = XrpcRequestHeadersOptions &
+  Pick<XrpcRequestProcessingOptions, 'validateRequest'> &
+  XrpcResponseOptions
+
+export type ActionOptions = {
+  /** AbortSignal to cancel the request. */
+  signal?: AbortSignal
 }
 
 /**
@@ -87,7 +101,7 @@ export type ClientOptions = {
 export type Action<I = any, O = any> = (
   client: Client,
   input: I,
-  options: CallOptions,
+  options: ActionOptions,
 ) => O | Promise<O>
 
 /**
@@ -109,7 +123,10 @@ export type InferActionOutput<A extends Action> =
  *
  * @see {@link Client.createRecord}
  */
-export type CreateRecordOptions = CallOptions & {
+export type CreateRecordOptions = Omit<
+  XrpcOptions<typeof com.atproto.repo.createRecord.main>,
+  'body'
+> & {
   /** Repository identifier (DID or handle). Defaults to authenticated user's DID. */
   repo?: AtIdentifierString
   /** Compare-and-swap on the repo commit. If specified, must match current commit. */
@@ -123,7 +140,10 @@ export type CreateRecordOptions = CallOptions & {
  *
  * @see {@link Client.deleteRecord}
  */
-export type DeleteRecordOptions = CallOptions & {
+export type DeleteRecordOptions = Omit<
+  XrpcOptions<typeof com.atproto.repo.deleteRecord.main>,
+  'params'
+> & {
   /** Repository identifier (DID or handle). Defaults to authenticated user's DID. */
   repo?: AtIdentifierString
   /** Compare-and-swap on the repo commit. If specified, must match current commit. */
@@ -137,7 +157,10 @@ export type DeleteRecordOptions = CallOptions & {
  *
  * @see {@link Client.getRecord}
  */
-export type GetRecordOptions = CallOptions & {
+export type GetRecordOptions = Omit<
+  XrpcOptions<typeof com.atproto.repo.getRecord.main>,
+  'params'
+> & {
   /** Repository identifier (DID or handle). Defaults to authenticated user's DID. */
   repo?: AtIdentifierString
 }
@@ -147,7 +170,10 @@ export type GetRecordOptions = CallOptions & {
  *
  * @see {@link Client.putRecord}
  */
-export type PutRecordOptions = CallOptions & {
+export type PutRecordOptions = Omit<
+  XrpcOptions<typeof com.atproto.repo.putRecord.main>,
+  'body'
+> & {
   /** Repository identifier (DID or handle). Defaults to authenticated user's DID. */
   repo?: AtIdentifierString
   /** Compare-and-swap on the repo commit. If specified, must match current commit. */
@@ -163,7 +189,10 @@ export type PutRecordOptions = CallOptions & {
  *
  * @see {@link Client.listRecords}
  */
-export type ListRecordsOptions = CallOptions & {
+export type ListRecordsOptions = Omit<
+  XrpcOptions<typeof com.atproto.repo.listRecords.main>,
+  'params'
+> & {
   /** Repository identifier (DID or handle). Defaults to authenticated user's DID. */
   repo?: AtIdentifierString
   /** Maximum number of records to return. */
@@ -174,6 +203,16 @@ export type ListRecordsOptions = CallOptions & {
   reverse?: boolean
 }
 
+export type UploadBlobOptions = Omit<
+  XrpcOptions<typeof com.atproto.repo.uploadBlob.main>,
+  'body'
+>
+
+export type GetBlobOptions = Omit<
+  XrpcOptions<typeof com.atproto.sync.getBlob.main>,
+  'params'
+>
+
 export type RecordKeyOptions<
   T extends RecordSchema,
   AlsoOptionalWhenRecordKeyIs extends LexiconRecordKey = never,
@@ -315,11 +354,22 @@ export class Client implements Agent {
   /** Set of labeler DIDs specific to this client instance. */
   public readonly labelers: Set<DidString>
 
+  public readonly xrpcDefaults: {
+    readonly validateRequest: boolean
+    readonly validateResponse: boolean
+    readonly strictResponseProcessing: boolean
+  }
+
   constructor(agent: Agent | AgentOptions, options: ClientOptions = {}) {
     this.agent = buildAgent(agent)
     this.service = options.service
     this.labelers = new Set(options.labelers)
     this.headers = new Headers(options.headers)
+    this.xrpcDefaults = Object.freeze({
+      validateRequest: options.validateRequest ?? false,
+      validateResponse: options.validateResponse ?? true,
+      strictResponseProcessing: options.strictResponseProcessing ?? true,
+    })
   }
 
   /**
@@ -392,7 +442,7 @@ export class Client implements Agent {
     path: `/${string}`,
     init: RequestInit,
   ): Promise<Response> {
-    const headers = buildAtprotoHeaders({
+    const headers = buildXrpcRequestHeaders({
       headers: init.headers,
       service: this.service,
       labelers: [
@@ -454,7 +504,7 @@ export class Client implements Agent {
     ns: Main<M>,
     options: XrpcOptions<M> = {} as XrpcOptions<M>,
   ): Promise<XrpcResponse<M>> {
-    return xrpc(this, ns, options)
+    return xrpc(this, ns, applyDefaults(options, this.xrpcDefaults))
   }
 
   /**
@@ -493,7 +543,7 @@ export class Client implements Agent {
     ns: Main<M>,
     options: XrpcOptions<M> = {} as XrpcOptions<M>,
   ): Promise<XrpcResponse<M> | XrpcFailure<M>> {
-    return xrpcSafe(this, ns, options)
+    return xrpcSafe(this, ns, applyDefaults(options, this.xrpcDefaults))
   }
 
   /**
@@ -649,14 +699,8 @@ export class Client implements Agent {
    * console.log(response.body.blob) // Use this ref in records
    * ```
    */
-  async uploadBlob(
-    body: BinaryBodyInit,
-    options?: CallOptions & { encoding?: `${string}/${string}` },
-  ) {
-    return this.xrpc(com.atproto.repo.uploadBlob.main, {
-      ...options,
-      body,
-    })
+  async uploadBlob(body: BinaryBodyInit, options?: UploadBlobOptions) {
+    return this.xrpc(com.atproto.repo.uploadBlob.main, { ...options, body })
   }
 
   /**
@@ -666,7 +710,7 @@ export class Client implements Agent {
    * @param cid - The CID of the blob
    * @param options - Call options
    */
-  async getBlob(did: DidString, cid: CidString, options?: CallOptions) {
+  async getBlob(did: DidString, cid: CidString, options?: GetBlobOptions) {
     return this.xrpc(com.atproto.sync.getBlob.main, {
       ...options,
       params: { did, cid },
@@ -723,7 +767,13 @@ export class Client implements Agent {
         : T extends Query
           ? XrpcRequestParams<T>
           : never,
-    options?: CallOptions,
+    options?: T extends Action
+      ? ActionOptions
+      : T extends Procedure
+        ? Omit<XrpcOptions<T>, 'body'>
+        : T extends Query
+          ? Omit<XrpcOptions<T>, 'params'>
+          : never,
   ): Promise<
     T extends Action
       ? InferActionOutput<T>
@@ -736,7 +786,7 @@ export class Client implements Agent {
   public async call(
     ns: Main<Action> | Main<Procedure> | Main<Query>,
     arg?: LexValue | Params,
-    options: CallOptions = {},
+    options: ActionOptions = {},
   ): Promise<unknown> {
     const method = getMain(ns)
 

package/src/errors.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { IssueInvalidType, LexValidationError, l } from '@atproto/lex-schema'
 import {
   XrpcAuthenticationError,
+  XrpcFetchError,
   XrpcInternalError,
   XrpcInvalidResponseError,
   XrpcResponseError,
@@ -13,14 +14,14 @@ import {
 const testQuery = l.query(
   'io.example.test',
   l.params(),
-  l.payload('application/json', l.object({ value: l.string() })),
+  l.jsonPayload({ value: l.string() }),
   ['TestError', 'AnotherError'],
 )
 
 const testQueryNoErrors = l.query(
   'io.example.noErrors',
   l.params(),
-  l.payload('application/json', l.object({ value: l.string() })),
+  l.jsonPayload({ value: l.string() }),
 )
 
 // ============================================================================
@@ -42,6 +43,7 @@ describe(XrpcResponseError, () => {
 
   it('exposes status from the response', () => {
     const err = createResponseError(404, 'NotFound')
+    expect(err.reason).toBe(err)
     expect(err.status).toBe(404)
   })
 
@@ -54,6 +56,7 @@ describe(XrpcResponseError, () => {
       encoding: 'application/json',
       body: { error: 'TestError' },
     })
+    expect(err.reason).toBe(err)
     expect(err.headers.get('X-Test')).toBe('value')
   })
 
@@ -63,7 +66,7 @@ describe(XrpcResponseError, () => {
   })
 
   describe('toDownstreamError', () => {
-    it('returns 502 for 5xx upstream errors', () => {
+    it('returns 502 for upstream 500 errors', () => {
       const err = createResponseError(
         500,
         'InternalServerError',
@@ -78,6 +81,17 @@ describe(XrpcResponseError, () => {
       })
     })
 
+    it('preserves original status for non-500 5xx errors', () => {
+      const err = createResponseError(503, 'ServiceUnavailable', 'Try later')
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.status).toBe(503)
+      expect(downstream.body).toEqual({
+        error: 'ServiceUnavailable',
+        message: 'Try later',
+      })
+    })
+
     it('preserves original status for 4xx errors', () => {
       const err = createResponseError(404, 'NotFound', 'Record not found')
       const downstream = err.toDownstreamError()
@@ -159,6 +173,7 @@ describe(XrpcAuthenticationError, () => {
       encoding: 'application/json',
       body: { error: 'AuthenticationRequired' },
     })
+    expect(err.reason).toBe(err)
     expect(err.wwwAuthenticate).toHaveProperty('Bearer')
   })
 
@@ -195,6 +210,7 @@ describe(XrpcUpstreamError, () => {
   it('has error code UpstreamFailure', () => {
     const response = new Response(null, { status: 200 })
     const err = new XrpcUpstreamError(testQuery, response)
+    expect(err.reason).toBe(err)
     expect(err.error).toBe('UpstreamFailure')
   })
 
@@ -236,6 +252,7 @@ describe(XrpcInvalidResponseError, () => {
     )
 
     expect(err).toBeInstanceOf(XrpcUpstreamError)
+    expect(err.reason).toBe(err)
     expect(err.error).toBe('UpstreamFailure')
     expect(err.cause).toBe(validationError)
   })
@@ -277,14 +294,10 @@ describe(XrpcInvalidResponseError, () => {
 describe(XrpcInternalError, () => {
   it('has error code InternalServerError', () => {
     const err = new XrpcInternalError(testQuery)
+    expect(err.reason).toBe(err)
     expect(err.error).toBe('InternalServerError')
   })
 
-  it('is always retryable', () => {
-    const err = new XrpcInternalError(testQuery)
-    expect(err.shouldRetry()).toBe(true)
-  })
-
   it('toJSON does not expose internal details', () => {
     const err = new XrpcInternalError(
       testQuery,
@@ -305,6 +318,62 @@ describe(XrpcInternalError, () => {
     expect(downstream.body.error).toBe('InternalServerError')
     expect(downstream.body.message).toBe('Internal Server Error')
   })
+
+  it('is not retryable', () => {
+    const err = new XrpcInternalError(testQuery, 'something broke')
+    expect(err.shouldRetry()).toBe(false)
+  })
+})
+
+// ============================================================================
+// XrpcFetchError
+// ============================================================================
+
+describe(XrpcFetchError, () => {
+  it('extends XrpcInternalError', () => {
+    const err = new XrpcFetchError(testQuery, new TypeError('fetch failed'))
+    expect(err).toBeInstanceOf(XrpcInternalError)
+    expect(err.error).toBe('InternalServerError')
+  })
+
+  it('uses cause message when cause is an Error', () => {
+    const cause = new TypeError('Failed to fetch')
+    const err = new XrpcFetchError(testQuery, cause)
+    expect(err.message).toBe('Unexpected fetchHandler() error: Failed to fetch')
+    expect(err.cause).toBe(cause)
+  })
+
+  it('uses fallback message when cause is not an Error', () => {
+    const err = new XrpcFetchError(testQuery, 'string cause')
+    expect(err.message).toBe('Unexpected fetchHandler() error: string cause')
+    expect(err.cause).toBe('string cause')
+  })
+
+  it('is retryable', () => {
+    const err = new XrpcFetchError(testQuery, new Error('network timeout'))
+    expect(err.shouldRetry()).toBe(true)
+  })
+
+  it('toJSON does not expose internal details', () => {
+    const err = new XrpcFetchError(
+      testQuery,
+      new Error('ECONNREFUSED 10.0.0.1:443'),
+    )
+    const json = err.toJSON()
+
+    expect(json.error).toBe('InternalServerError')
+    expect(json.message).toBe('Failed to perform upstream request')
+    expect(json.message).not.toContain('ECONNREFUSED')
+  })
+
+  it('toDownstreamError returns 502', () => {
+    const err = new XrpcFetchError(testQuery, new Error('DNS lookup failed'))
+    const downstream = err.toDownstreamError()
+
+    expect(downstream.status).toBe(502)
+    expect(downstream.body.error).toBe('InternalServerError')
+    expect(downstream.body.message).toBe('Failed to perform upstream request')
+  })
 })
 
 // ============================================================================