@atproto/lex-client 0.0.14 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-client",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "license": "MIT",
   "description": "HTTP client for interacting with Lexicon based APIs",
   "keywords": [
@@ -37,14 +37,14 @@
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-data": "^0.0.12",
-    "@atproto/lex-json": "^0.0.12",
-    "@atproto/lex-schema": "^0.0.13"
+    "@atproto/lex-data": "^0.0.13",
+    "@atproto/lex-json": "^0.0.13",
+    "@atproto/lex-schema": "^0.0.15"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-cbor": "^0.0.13",
-    "@atproto/lex-builder": "^0.0.16"
+    "@atproto/lex-cbor": "^0.0.14",
+    "@atproto/lex-builder": "^0.0.18"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

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

@@ -1,4 +1,4 @@
-import { LexError, LexMap, LexValue, TypedLexMap } from '@atproto/lex-data'
+import { LexMap, LexValue, TypedLexMap } from '@atproto/lex-data'
 import {
   AtIdentifierString,
   CidString,
@@ -331,7 +331,7 @@ export class Client implements Agent {
 
   /**
    * The DID of the authenticated user.
-   * @throws {LexError} with code 'AuthenticationRequired' if not authenticated
+   * @throws {Error} if not authenticated
    */
   get assertDid(): DidString {
     this.assertAuthenticated()
@@ -342,7 +342,7 @@ export class Client implements Agent {
    * Asserts that the client is authenticated.
    * Use as a type guard when you need to ensure authentication.
    *
-   * @throws {LexError} with code 'AuthenticationRequired' if not authenticated
+   * @throws {Error} if not authenticated
    *
    * @example
    * ```typescript
@@ -352,7 +352,7 @@ export class Client implements Agent {
    * ```
    */
   public assertAuthenticated(): asserts this is { did: DidString } {
-    if (!this.did) throw new LexError('AuthenticationRequired')
+    if (!this.did) throw new Error('Client is not authenticated')
   }
 
   /**