@atproto/lex-client 0.0.15 → 0.0.16

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/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')
+  })
 })
 
 // ============================================================================

package/src/errors.ts

@@ -7,6 +7,8 @@ import {
   ResultFailure,
   lexErrorDataSchema,
 } from '@atproto/lex-schema'
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Agent } from './agent.js'
 import { XrpcResponsePayload } from './util.js'
 import {
   WWWAuthenticate,
@@ -347,17 +349,11 @@ export class XrpcInvalidResponseError<
 }
 
 /**
- * Error class for internal/client-side errors during XRPC requests.
+ * Error class for unexpected internal/client-side errors during XRPC requests.
  *
- * This represents errors that occur before or during the request that are not
- * server responses, such as:
- * - Network errors (connection refused, DNS failure)
- * - Request timeouts
- * - Request aborted via AbortSignal
- * - Invalid request construction
- *
- * The error code is always 'InternalServerError' and these errors are
- * optimistically considered retryable.
+ * The error code is always 'InternalServerError' and these errors not
+ * considered retryable as they stem from unforeseen issues in the
+ * implementation.
  *
  * @typeParam M - The XRPC method type
  */
@@ -379,15 +375,11 @@ export class XrpcInternalError<
     return this
   }
 
-  override shouldRetry(): true {
-    // Ideally, we would inspect the reason to determine if it's retryable
-    // (by detecting network errors, timeouts, etc.). Since these cases are
-    // highly platform-dependent, we optimistically assume all internal
-    // errors are retryable.
-    return true
+  override shouldRetry(): boolean {
+    return false
   }
 
-  override toJSON(): LexErrorData<'InternalServerError'> {
+  override toJSON(): LexErrorData {
     // @NOTE Do not expose internal error details to downstream clients
     return { error: this.error, message: 'Internal Server Error' }
   }
@@ -397,6 +389,49 @@ export class XrpcInternalError<
   }
 }
 
+/**
+ * Special case of XrpcInternalError that specifically represents errors thrown
+ * by {@link Agent.fetchHandler} during the XRPC request. This includes:
+ * - Network errors (connection refused, DNS failure)
+ * - Request timeouts
+ * - Request aborted via AbortSignal
+ *
+ * These errors are optimistically considered retryable, as many fetch errors
+ * are transient and may succeed on retry.
+ */
+export class XrpcFetchError<
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcInternalError<M> {
+  name = 'XrpcFetchError'
+
+  constructor(method: M, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    super(method, `Unexpected fetchHandler() error: ${message}`, { cause })
+  }
+
+  override shouldRetry(): boolean {
+    // Ideally, we would inspect the reason to determine if it's retryable (by
+    // detecting network errors, timeouts, etc.). Since these cases are highly
+    // platform-dependent, we optimistically assume all fetch errors are
+    // transient and retryable.
+    return true
+  }
+
+  override toJSON(): LexErrorData {
+    // @NOTE Do not expose internal error details to downstream clients
+    return { error: this.error, message: 'Failed to perform upstream request' }
+  }
+
+  override toDownstreamError(): DownstreamError {
+    // While it might technically be a 500 error, we use 502 Bad Gateway here to
+    // indicate that the error occurred while communicating with the upstream
+    // server, allowing downstream clients to distinguish between errors in our
+    // internal processing (500) and errors in the upstream server or network
+    // (502).
+    return { status: 502, body: this.toJSON() }
+  }
+}
+
 /**
  * Union type of all possible XRPC failure types.
  *