@atproto/lex-client 0.0.16 → 0.0.18

package/src/response.ts

@@ -1,23 +1,120 @@
-import { lexParse } from '@atproto/lex-json'
+import { LexParseOptions, lexParse } from '@atproto/lex-json'
 import {
   InferMethodOutputEncoding,
+  InferOutput,
+  LexValue,
+  Payload,
   Procedure,
   Query,
   ResultSuccess,
+  Validator,
 } from '@atproto/lex-schema'
 import {
   XrpcAuthenticationError,
   XrpcInvalidResponseError,
   XrpcResponseError,
-  XrpcUpstreamError,
-  isXrpcErrorPayload,
+  XrpcResponseValidationError,
 } from './errors.js'
-import { XrpcResponseBody, XrpcResponsePayload } from './util.js'
+import {
+  EncodingString,
+  XrpcUnknownResponsePayload,
+  isEncodingString,
+} from './types.js'
 
 const CONTENT_TYPE_BINARY = 'application/octet-stream'
 const CONTENT_TYPE_JSON = 'application/json'
 
-export type { XrpcResponseBody, XrpcResponsePayload }
+// @NOTE the output schema is used in "parse" mode (safeParse), which means that
+// defaults will be applied and coercions will be performed, so we need to use
+// InferOutput here to get the final parsed type, not Infer/InferInput. For this
+// reason, we cannot use InferMethodOutputBody and InferMethodOutput from
+// lex-schema here.
+
+type InferEncodingType<TEncoding extends string> = TEncoding extends '*/*'
+  ? EncodingString
+  : TEncoding extends `${infer T extends string}/*`
+    ? `${T}/${string}`
+    : TEncoding
+
+type InferBodyType<
+  TEncoding extends string,
+  TSchema,
+> = TSchema extends Validator
+  ? InferOutput<TSchema>
+  : TEncoding extends `application/json`
+    ? LexValue
+    : Uint8Array
+
+/**
+ * The body type of an XRPC response, inferred from the method's output schema.
+ *
+ * For JSON responses, this is the parsed LexValue. For binary responses,
+ * this is a Uint8Array.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ */
+export type XrpcResponseBody<M extends Procedure | Query> =
+  M['output'] extends Payload<infer TEncoding, infer TSchema>
+    ? TEncoding extends string
+      ? InferBodyType<TEncoding, TSchema>
+      : undefined | LexValue | Uint8Array
+    : never
+
+/**
+ * The full payload type of an XRPC response, including body and encoding.
+ *
+ * Returns `null` for methods that have no output.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ */
+export type XrpcResponsePayload<M extends Procedure | Query> =
+  M['output'] extends Payload<infer TEncoding, infer TSchema>
+    ? TEncoding extends string
+      ? {
+          encoding: InferEncodingType<TEncoding>
+          body: InferBodyType<TEncoding, TSchema>
+        }
+      : // If the schema does not specify an output encoding, anything could be
+        // returned, including no payload at all (undefined).
+        undefined | { body: LexValue | Uint8Array; encoding: string }
+    : never
+
+export type XrpcResponseOptions = {
+  /**
+   * Whether to validate the response against the method's output schema.
+   * Disabling this can improve performance but may lead to runtime errors if
+   * the response does not conform to the expected schema. Only set this to
+   * `false` if you are certain that the upstream service will always return
+   * valid responses.
+   *
+   * @default true
+   */
+  validateResponse?: boolean
+
+  /**
+   * Whether to strictly process response payloads according to Lex encoding
+   * rules. By default, the client will reject responses with invalid Lex data
+   * (floats and invalid $bytes / $link objects).
+   *
+   * Setting this option to `false` will allow the client to accept such
+   * responses in a non-strict mode, where invalid Lex data will be returned
+   * as-is (e.g., floats will not be rejected, and invalid $bytes / $link
+   * objects will not be converted to Uint8Array / Cid). When in non-strict
+   * mode, the validation will also be relaxed when validating the response
+   * against the method's output schema, allowing values that do not strictly
+   * conform to the schema (e.g. datetime strings that are not valid RFC3339
+   * format, blobs that are not of the right size/mime-type, etc.) to be
+   * accepted as long as their basic structure is correct.
+   *
+   * When validation is enabled (the default), the values defined through the
+   * method schema will be enforced, ensuring that the client can still process
+   * the response even if the server returns invalid Lex data.
+   *
+   * @default true
+   * @see {@link LexParseOptions.strict}
+   */
+  strictResponseProcessing?: boolean
+}
 
 /**
  * Small container for XRPC response data.
@@ -74,102 +171,101 @@ export class XrpcResponse<M extends Procedure | Query>
    * {@link XrpcResponseError.matchesSchemaErrors} to narrow the error type based on
    * the method's declared error schema. This can be narrowed further as a
    * {@link XrpcAuthenticationError} if the error is an authentication error.
-   * @throws {XrpcUpstreamError} when the response is not a valid XRPC
+   * @throws {XrpcInvalidResponseError} when the response is not a valid XRPC
    * response, or if the response does not conform to the method's schema.
    */
   static async fromFetchResponse<const M extends Procedure | Query>(
     method: M,
     response: Response,
-    options?: { validateResponse?: boolean },
+    options?: XrpcResponseOptions,
   ): Promise<XrpcResponse<M>> {
     // @NOTE The body MUST either be read or canceled to avoid resource leaks.
     // Since nothing should cause an exception before "readPayload" is
     // called, we can safely not use a try/finally here.
 
-    // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
-    if (response.status < 200 || response.status >= 300) {
-      // Always parse json for error responses
-      const payload = await readPayload(response, { parse: true }).catch(
-        (cause) => {
-          throw new XrpcUpstreamError(
-            method,
-            response,
-            null,
-            'Unable to parse response payload',
-            { cause },
-          )
-        },
-      )
+    // Always turn 4xx/5xx responses into XrpcResponseError
+    if (response.status >= 400) {
+      const payload = await readPayload(method, response, {
+        // Always parse errors in non-strict mode
+        parse: { strict: false },
+      })
 
-      // Properly formatted XRPC error response ?
-      if (response.status >= 400 && isXrpcErrorPayload(payload)) {
-        throw response.status === 401
-          ? new XrpcAuthenticationError<M>(method, response, payload)
-          : new XrpcResponseError<M>(method, response, payload)
+      if (response.status === 401) {
+        throw new XrpcAuthenticationError<M>(method, response, payload)
       }
 
-      // Invalid XRPC response (we probably did not hit an XRPC implementation)
-      throw new XrpcUpstreamError(
+      throw new XrpcResponseError<M>(method, response, payload)
+    }
+
+    // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
+    if (response.status < 200 || response.status >= 300) {
+      await response.body?.cancel()
+
+      throw new XrpcInvalidResponseError(
         method,
         response,
-        payload,
-        response.status >= 500
-          ? 'Upstream server encountered an error'
-          : response.status >= 400
-            ? 'Invalid response payload'
-            : 'Invalid response status code',
+        undefined,
+        `Unexpected status code ${response.status}`,
       )
     }
 
-    // Only parse json if the schema expects it
-    const payload = await readPayload(response, {
-      parse: method.output.encoding === CONTENT_TYPE_JSON,
-    }).catch((cause) => {
-      throw new XrpcUpstreamError(
+    const payload = await readPayload(method, response, {
+      // Parse response if there is a schema, or if the encoding is
+      // "application/json"
+      parse:
+        method.output.schema || method.output.encoding === CONTENT_TYPE_JSON
+          ? { strict: options?.strictResponseProcessing ?? true }
+          : // If there is no declared output encoding, we'll parse the output (in loose mode)
+            method.output.encoding == null
+            ? { strict: false }
+            : false,
+    })
+
+    if (!method.output.matchesEncoding(payload?.encoding)) {
+      throw new XrpcInvalidResponseError(
         method,
         response,
-        null,
-        'Unable to parse response payload',
-        { cause },
+        payload,
+        `Expected ${stringifyEncoding(method.output.encoding)} response (got ${stringifyEncoding(payload?.encoding)})`,
       )
-    })
+    }
 
     // Response is successful (2xx). Validate payload (data and encoding) against schema.
-    if (method.output.encoding == null) {
-      // Schema expects no payload
-      if (payload) {
-        throw new XrpcUpstreamError(
-          method,
-          response,
-          payload,
-          `Expected response with no body, got ${payload.encoding}`,
-        )
-      }
-    } else {
-      // Schema expects a payload
-      if (!payload || !method.output.matchesEncoding(payload.encoding)) {
-        throw new XrpcUpstreamError(
-          method,
-          response,
-          payload,
-          payload
-            ? `Expected ${method.output.encoding} response, got ${payload.encoding}`
-            : `Expected non-empty response with content-type ${method.output.encoding}`,
-        )
-      }
+    if (method.output.encoding != null) {
+      // If the schema specifies an output, verify that the response properly
+      // matches the expected format (encoding and schema, if present). If no
+      // output is specified, any payload could be returned.
+
+      // Needed for type safety. Should never happen since matchesEncoding()
+      // should return not succeed if there is a schema encoding but no payload.
+      if (!payload) throw new Error('Expected payload')
 
       // Assert valid response body.
       if (method.output.schema && options?.validateResponse !== false) {
-        const result = method.output.schema.safeParse(payload.body)
+        const result = method.output.schema.safeParse(payload.body, {
+          strict: options?.strictResponseProcessing ?? true,
+        })
 
         if (!result.success) {
-          throw new XrpcInvalidResponseError(
+          throw new XrpcResponseValidationError(
             method,
             response,
             payload,
             result.reason,
           )
         }
+
+        const parsedPayload = {
+          body: result.value,
+          encoding: payload.encoding,
+        } as XrpcResponsePayload<M>
+
+        return new XrpcResponse<M>(
+          method,
+          response.status,
+          response.headers,
+          parsedPayload,
+        )
       }
     }
 
@@ -182,50 +278,81 @@ export class XrpcResponse<M extends Procedure | Query>
   }
 }
 
+type ReadPayloadOptions = {
+  /**
+   * Whether to parse the response body as JSON and convert it to LexValue.
+   *
+   * @default false
+   */
+  parse?: false | LexParseOptions
+}
+
 /**
  * @note this function always consumes the response body
  */
 async function readPayload(
+  method: Query | Procedure,
   response: Response,
-  options?: { parse?: boolean },
-): Promise<XrpcResponsePayload> {
-  // @TODO Should we limit the maximum response size here (this could also be
-  // done by the FetchHandler)?
-
-  const encoding = response.headers
-    .get('content-type')
-    ?.split(';')[0]
-    .trim()
-    .toLowerCase()
-
-  // Response content-type is undefined
-  if (!encoding) {
-    // If the body is empty, return undefined (= no payload)
-    const body = await response.arrayBuffer()
-    if (body.byteLength === 0) return undefined
-
-    // If we got data despite no content-type, treat it as binary
-    return {
-      encoding: CONTENT_TYPE_BINARY,
-      body: new Uint8Array(body),
+  options?: ReadPayloadOptions,
+): Promise<undefined | XrpcUnknownResponsePayload> {
+  try {
+    // @TODO Should we limit the maximum response size here (this could also be
+    // done by the FetchHandler)?
+
+    const encoding = response.headers
+      .get('content-type')
+      ?.split(';')[0]
+      .trim()
+      .toLowerCase()
+
+    // Response content-type is undefined
+    if (!encoding) {
+      // If the body is empty, return undefined (= no payload)
+      const arrayBuffer = await response.arrayBuffer()
+      if (arrayBuffer.byteLength === 0) return undefined
+
+      // If we got data despite no content-type, treat it as binary
+      return {
+        encoding: CONTENT_TYPE_BINARY,
+        body: new Uint8Array(arrayBuffer),
+      }
     }
-  }
 
-  if (options?.parse && encoding === CONTENT_TYPE_JSON) {
-    // @NOTE It might be worth returning the raw bytes here (Uint8Array) and
-    // perform the lex parsing using cborg/json, allowing to do
-    // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.
-    // This would require adding encode/decode utilities to lex-json (similar
-    // to @ipld/dag-json)
-    const text = await response.text()
+    if (!isEncodingString(encoding)) {
+      throw new TypeError(`Invalid content-type "${encoding}" in response`)
+    }
+
+    if (options?.parse && encoding === CONTENT_TYPE_JSON) {
+      // @NOTE It might be worth returning the raw bytes here (Uint8Array) and
+      // perform the lex parsing using cborg/json, allowing to do
+      // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.
+      // This would require adding encode/decode utilities to lex-json (similar
+      // to @ipld/dag-json)
+      const text = await response.text()
+
+      // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
+      // using a reviver function during JSON.parse should be faster than
+      // parsing to JSON then converting to Lex (?)
 
-    // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
-    // using a reviver function during JSON.parse should be faster than
-    // parsing to JSON then converting to Lex (?)
+      // @TODO verify statement above
+      return { encoding, body: lexParse(text, options.parse) }
+    }
 
-    // @TODO verify statement above
-    return { encoding, body: lexParse(text) }
+    const arrayBuffer = await response.arrayBuffer()
+    return { encoding, body: new Uint8Array(arrayBuffer) }
+  } catch (cause) {
+    const message = 'Unable to parse response payload'
+    const messageDetail = cause instanceof TypeError ? cause.message : undefined
+    throw new XrpcInvalidResponseError(
+      method,
+      response,
+      undefined,
+      messageDetail ? `${message}: ${messageDetail}` : message,
+      { cause },
+    )
   }
+}
 
-  return { encoding, body: new Uint8Array(await response.arrayBuffer()) }
+function stringifyEncoding(encoding: string | undefined) {
+  return encoding ? `"${encoding}"` : 'no payload'
 }

package/src/types.ts

@@ -1,6 +1,6 @@
-import { DidString, UnknownString } from '@atproto/lex-schema'
+import { DidString, LexValue, UnknownString } from '@atproto/lex-schema'
 
-export type { DidString, UnknownString }
+export type { DidString, LexValue, UnknownString }
 
 /**
  * Service identifier fragment for DID service endpoints.
@@ -22,44 +22,6 @@ export type DidServiceIdentifier = 'atproto_labeler' | UnknownString
  */
 export type Service = `${DidString}#${DidServiceIdentifier}`
 
-/**
- * Common options available for all XRPC calls.
- *
- * These options can be passed to any method that makes XRPC requests,
- * including `xrpc()`, `call()`, and record operations.
- */
-export type CallOptions = {
-  /** Labeler DIDs to request labels from for content moderation. */
-  labelers?: Iterable<DidString>
-  /** AbortSignal to cancel the request. */
-  signal?: AbortSignal
-  /** Additional HTTP headers to include in the request. */
-  headers?: HeadersInit
-  /** Service proxy identifier for routing requests through a specific service. */
-  service?: Service
-
-  /**
-   * Whether to validate the request against the method's input schema. Enabling
-   * this can help catch errors early but may have a performance cost. This
-   * would typically only be set to `true` in development or debugging
-   * scenarios.
-   *
-   * @default false
-   */
-  validateRequest?: boolean
-
-  /**
-   * Whether to validate the response against the method's output schema.
-   * Disabling this can improve performance but may lead to runtime errors if
-   * the response does not conform to the expected schema. Only set this to
-   * `false` if you are certain that the upstream service will always return
-   * valid responses.
-   *
-   * @default true
-   */
-  validateResponse?: boolean
-}
-
 /**
  * Valid input types for binary request bodies.
  *
@@ -92,3 +54,18 @@ export type BinaryBodyInit =
   | ReadableStream<Uint8Array>
   | AsyncIterable<Uint8Array>
   | string
+
+export type EncodingString = `${string}/${string}`
+
+export function isEncodingString(
+  contentType: string,
+): contentType is EncodingString {
+  return contentType.includes('/')
+}
+
+export type XrpcUnknownResponsePayload<
+  TBinary extends BinaryBodyInit = Uint8Array,
+> = {
+  encoding: EncodingString
+  body: LexValue | TBinary
+}

package/src/util.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
-  buildAtprotoHeaders,
+  buildXrpcRequestHeaders,
   isAsyncIterable,
   isBlobLike,
   toReadableStream,
@@ -111,24 +111,24 @@ describe(isAsyncIterable, () => {
 })
 
 // ============================================================================
-// buildAtprotoHeaders
+// buildXrpcRequestHeaders
 // ============================================================================
 
-describe(buildAtprotoHeaders, () => {
+describe(buildXrpcRequestHeaders, () => {
   it('returns empty headers when no options are set', () => {
-    const headers = buildAtprotoHeaders({})
+    const headers = buildXrpcRequestHeaders({})
     expect([...headers.entries()]).toEqual([])
   })
 
   it('sets atproto-proxy header from service option', () => {
-    const headers = buildAtprotoHeaders({
+    const headers = buildXrpcRequestHeaders({
       service: 'did:plc:1234#atproto_labeler',
     })
     expect(headers.get('atproto-proxy')).toBe('did:plc:1234#atproto_labeler')
   })
 
   it('does not override existing atproto-proxy header', () => {
-    const headers = buildAtprotoHeaders({
+    const headers = buildXrpcRequestHeaders({
       headers: { 'atproto-proxy': 'did:plc:existing#service' },
       service: 'did:plc:new#service',
     })
@@ -136,7 +136,7 @@ describe(buildAtprotoHeaders, () => {
   })
 
   it('sets atproto-accept-labelers from labelers option', () => {
-    const headers = buildAtprotoHeaders({
+    const headers = buildXrpcRequestHeaders({
       labelers: ['did:plc:labeler1', 'did:plc:labeler2'] as const,
     })
     expect(headers.get('atproto-accept-labelers')).toBe(
@@ -145,7 +145,7 @@ describe(buildAtprotoHeaders, () => {
   })
 
   it('appends to existing atproto-accept-labelers header', () => {
-    const headers = buildAtprotoHeaders({
+    const headers = buildXrpcRequestHeaders({
       headers: { 'atproto-accept-labelers': 'did:plc:existing' },
       labelers: ['did:plc:new'] as const,
     })
@@ -155,7 +155,7 @@ describe(buildAtprotoHeaders, () => {
   })
 
   it('passes through base headers', () => {
-    const headers = buildAtprotoHeaders({
+    const headers = buildXrpcRequestHeaders({
       headers: { Authorization: 'Bearer token123' },
     })
     expect(headers.get('Authorization')).toBe('Bearer token123')
@@ -163,12 +163,12 @@ describe(buildAtprotoHeaders, () => {
 
   it('accepts Headers instance as base headers', () => {
     const base = new Headers({ 'X-Custom': 'value' })
-    const headers = buildAtprotoHeaders({ headers: base })
+    const headers = buildXrpcRequestHeaders({ headers: base })
     expect(headers.get('X-Custom')).toBe('value')
   })
 
   it('sets empty header for empty labelers iterable', () => {
-    const headers = buildAtprotoHeaders({ labelers: [] })
+    const headers = buildXrpcRequestHeaders({ labelers: [] })
     // An empty array still sets the header (to empty string), distinguishing
     // "no labelers requested" from "labelers option not provided"
     expect(headers.has('atproto-accept-labelers')).toBe(true)

package/src/util.ts

@@ -1,32 +1,23 @@
-import {
-  DidString,
-  InferMethodOutput,
-  InferMethodOutputBody,
-  Procedure,
-  Query,
-} from '@atproto/lex-schema'
+import type { DidString, Service } from './types.js'
 
-/**
- * The body type of an XRPC response, inferred from the method's output schema.
- *
- * For JSON responses, this is the parsed LexValue. For binary responses,
- * this is a Uint8Array.
- *
- * @typeParam M - The XRPC method type (Procedure or Query)
- */
-export type XrpcResponseBody<M extends Procedure | Query = Procedure | Query> =
-  InferMethodOutputBody<M, Uint8Array>
+export function applyDefaults<
+  TDefaults extends Record<string, unknown>,
+  TOptions extends {
+    [K in keyof TDefaults]?: TDefaults[K]
+  },
+>(options: TOptions, defaults: TDefaults): TOptions & TDefaults {
+  const combined: Partial<TDefaults> = { ...options }
 
-/**
- * The full payload type of an XRPC response, including body and encoding.
- *
- * Returns `null` for methods that have no output.
- *
- * @typeParam M - The XRPC method type (Procedure or Query)
- */
-export type XrpcResponsePayload<
-  M extends Procedure | Query = Procedure | Query,
-> = InferMethodOutput<M, Uint8Array>
+  // @NOTE We make sure that options with an explicit `undefined` value get the
+  // default, since spreading doesn't override with `undefined`.
+  for (const key of Object.keys(defaults) as (keyof typeof defaults)[]) {
+    if (options[key] === undefined) {
+      combined[key] = defaults[key]
+    }
+  }
+
+  return combined as TOptions & TDefaults
+}
 
 /**
  * Type guard to check if a value is {@link Blob}-like.
@@ -64,6 +55,17 @@ export function isAsyncIterable<T>(
   )
 }
 
+export type XrpcRequestHeadersOptions = {
+  /** Additional HTTP headers to include in the request. */
+  headers?: HeadersInit
+
+  /** Labeler DIDs to request labels from for content moderation. */
+  labelers?: Iterable<DidString>
+
+  /** Service proxy identifier for routing requests through a specific service. */
+  service?: Service
+}
+
 /**
  * Builds HTTP headers for AT Protocol requests.
  *
@@ -71,17 +73,12 @@ export function isAsyncIterable<T>(
  * - `atproto-proxy`: Service routing header (if service is specified)
  * - `atproto-accept-labelers`: Comma-separated list of labeler DIDs
  *
- * @param options - Header building options
- * @param options.headers - Base headers to include
- * @param options.service - Service proxy identifier
- * @param options.labelers - Labeler DIDs to request labels from
+ * @see {@link XrpcRequestHeadersOptions}
  * @returns A new Headers object with AT Protocol headers added
  */
-export function buildAtprotoHeaders(options: {
-  headers?: HeadersInit
-  service?: `${DidString}#${string}`
-  labelers?: Iterable<DidString>
-}): Headers {
+export function buildXrpcRequestHeaders(
+  options: XrpcRequestHeadersOptions,
+): Headers {
   const headers = new Headers(options?.headers)
 
   if (options.service && !headers.has('atproto-proxy')) {