@atproto/lex-client 0.2.0 → 0.2.1

package/package.json

@@ -1,9 +1,6 @@
 {
   "name": "@atproto/lex-client",
-  "version": "0.2.0",
-  "engines": {
-    "node": ">=22"
-  },
+  "version": "0.2.1",
   "license": "MIT",
   "description": "HTTP client for interacting with Lexicon based APIs",
   "keywords": [
@@ -19,10 +16,6 @@
     "directory": "packages/lex/lex-client"
   },
   "files": [
-    "./src",
-    "./tsconfig.build.json",
-    "./tsconfig.tests.json",
-    "./tsconfig.json",
     "./dist",
     "./CHANGELOG.md"
   ],
@@ -34,19 +27,23 @@
       "default": "./dist/index.js"
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-data": "^0.1.3",
-    "@atproto/lex-json": "^0.1.2",
-    "@atproto/lex-schema": "^0.1.5"
+    "@atproto/lex-data": "^0.1.4",
+    "@atproto/lex-schema": "^0.1.6",
+    "@atproto/lex-json": "^0.1.3"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-cbor": "^0.1.2",
-    "@atproto/lex-builder": "^0.1.4"
+    "@atproto/lex-cbor": "^0.1.3",
+    "@atproto/lex-builder": "^0.1.5"
   },
   "scripts": {
-    "prebuild": "node ./scripts/lex-build.mjs",
+    "codegen:lex": "node ./scripts/lex-build.mjs",
+    "prebuild": "pnpm run '/^(codegen:.+)$/'",
     "build": "tsgo --build tsconfig.build.json",
     "test": "vitest run"
   }

package/src/agent.test.ts

@@ -1,216 +0,0 @@
-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

@@ -1,186 +0,0 @@
-import { DidString } from '@atproto/lex-schema'
-
-/**
- * A function that performs HTTP requests towards a service endpoint.
- *
- * The handler is responsible for adding the origin (protocol, hostname, and
- * port) to the provided path, typically based on authentication or service
- * configuration. The handler can also be responsible for adding any necessary
- * headers, such as authorization tokens.
- *
- * @param path - The URL path (pathname + query parameters) without the origin
- * @param init - Standard fetch RequestInit options
- * @returns A Promise resolving to the HTTP Response
- */
-export type FetchHandler = (
-  /**
-   * The URL (pathname + query parameters) to make the request to, without the
-   * origin. The origin (protocol, hostname, and port) must be added by this
-   * {@link FetchHandler}, typically based on authentication or other factors.
-   */
-  path: `/${string}`,
-  init: RequestInit,
-) => Promise<Response>
-
-/**
- * Core interface for making XRPC requests towards a specific service.
- *
- * An {@link Agent} encapsulates an identity and request handling for AT
- * Protocol operations. Agents will typically handle authentication, service URL
- * resolution, and other request configuration, allowing client code to make
- * requests without needing to manage these details directly. The key component
- * of an Agent is the {@link FetchHandler}, which is responsible for
- * constructing the full request URL and adding any necessary headers or
- * authentication tokens. The Agent's `did` property represents the
- * authenticated user's DID, if available, and can be used for operations that
- * require knowledge of the user's identity (such as creating AT Protocol
- * records).
- *
- * @see {@link buildAgent} for creating (simple) Agent instances.
- *
- * @example
- * ```typescript
- * const agent: Agent = {
- *   did: 'did:plc:example123',
- *   fetchHandler: async (path, init) => {
- *     const url = new URL(path, 'https://bsky.social')
- *     return fetch(url, init)
- *   }
- * }
- * ```
- */
-export interface Agent {
-  /** The DID of the authenticated user, or `undefined` if unauthenticated. */
-  readonly did?: DidString
-  /** The fetch handler used to make HTTP requests. */
-  fetchHandler: FetchHandler
-}
-
-export function isAgent(value: unknown): value is Agent {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'fetchHandler' in value &&
-    typeof value.fetchHandler === 'function' &&
-    (!('did' in value) ||
-      value.did === undefined ||
-      typeof value.did === 'string')
-  )
-}
-
-export type AgentConfig = {
-  /**
-   * The identifier (DID) of the user represented by this agent.
-   */
-  did?: DidString
-
-  /**
-   * The service URL to make requests to. This can be a string, URL, or a
-   * function that returns a string or URL. This is useful for dynamic URLs,
-   * such as a service URL that changes based on authentication.
-   */
-  service: string | URL
-
-  /**
-   * Optional headers to include with every request made by this agent, unless
-   * overridden by the request-specific headers provided to the fetch handler.
-   */
-  headers?: HeadersInit
-
-  /**
-   * Bring your own fetch implementation. Typically useful for testing, logging,
-   * mocking, or adding retries, session management, signatures, proof of
-   * possession (DPoP), SSRF protection, etc. Defaults to the global `fetch`
-   * function.
-   */
-  fetch?: typeof globalThis.fetch
-}
-
-/**
- * Options for creating an Agent.
- *
- * Can be a full {@link AgentConfig} object, or a simple service URL string/{@link URL}.
- */
-export type AgentOptions = AgentConfig | FetchHandler | string | URL
-
-/**
- * Creates an {@link Agent} from various input types.
- *
- * This factory function accepts an existing Agent (returned as-is), a service
- * URL, or a full configuration object. It handles the common case of creating
- * an unauthenticated agent from just a service URL.
- *
- * @param options - Agent instance, configuration object, or service URL
- * @returns A configured Agent ready for making requests
- * @throws {TypeError} If fetch() is not available in the environment
- *
- * @example // From URL string
- * ```typescript
- * const agent = buildAgent('https://public.api.bsky.app')
- * ```
- *
- * @example // From configuration
- * ```typescript
- * const agent = buildAgent({
- *   did: 'did:plc:example',
- *   service: 'https://bsky.social',
- *   headers: { 'Authorization': 'Bearer ...' }
- * })
- * ```
- */
-export function buildAgent<O extends Agent | AgentOptions>(
-  options: O,
-): O extends Agent ? O : Agent
-export function buildAgent(options: Agent | AgentOptions): Agent {
-  const config: Agent | AgentConfig =
-    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
-
-  if (typeof fetch !== 'function') {
-    throw new TypeError('fetch() is not available in this environment')
-  }
-
-  return {
-    get did() {
-      return config.did
-    },
-
-    async fetchHandler(path, init) {
-      const headers =
-        config.headers != null && init.headers != null
-          ? mergeHeaders(config.headers, init.headers)
-          : config.headers || init.headers
-
-      return fetch(
-        new URL(path, service),
-        headers !== init.headers ? { ...init, headers } : init,
-      )
-    },
-  }
-}
-
-function mergeHeaders(
-  defaultHeaders: HeadersInit,
-  requestHeaders: HeadersInit,
-): Headers {
-  // We don't want to alter the original Headers objects, so we create a new one
-  const result = new Headers(defaultHeaders)
-
-  const overrides =
-    requestHeaders instanceof Headers
-      ? requestHeaders
-      : new Headers(requestHeaders)
-
-  for (const [key, value] of overrides.entries()) {
-    result.set(key, value)
-  }
-
-  return result
-}