@atproto/lex-client 0.0.10 → 0.0.12

package/src/response.ts

@@ -1,32 +1,29 @@
 import { lexParse } from '@atproto/lex-json'
 import {
-  InferMethodOutputBody,
   InferMethodOutputEncoding,
   Procedure,
   Query,
   ResultSuccess,
 } from '@atproto/lex-schema'
 import {
+  XrpcAuthenticationError,
   XrpcResponseError,
   XrpcUpstreamError,
   isXrpcErrorPayload,
 } from './errors.js'
-import { XrpcPayload } from './util.js'
+import { XrpcResponseBody, XrpcResponsePayload } from './util.js'
 
-export type XrpcResponseBody<M extends Procedure | Query> =
-  InferMethodOutputBody<M, Uint8Array>
+const CONTENT_TYPE_BINARY = 'application/octet-stream'
+const CONTENT_TYPE_JSON = 'application/json'
 
-export type XrpcResponsePayload<M extends Procedure | Query> =
-  InferMethodOutputEncoding<M> extends infer E extends string
-    ? XrpcPayload<XrpcResponseBody<M>, E>
-    : null
+export type { XrpcResponseBody, XrpcResponsePayload }
 
 /**
  * Small container for XRPC response data.
  *
  * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.
  */
-export class XrpcResponse<const M extends Procedure | Query>
+export class XrpcResponse<M extends Procedure | Query>
   implements ResultSuccess<XrpcResponse<M>>
 {
   /** @see {@link ResultSuccess.success} */
@@ -49,13 +46,24 @@ export class XrpcResponse<const M extends Procedure | Query>
    * in binary form {@link Uint8Array} (`false`).
    */
   get isParsed() {
-    return this.encoding === 'application/json' && shouldParse(this.method)
+    return this.method.output.encoding === CONTENT_TYPE_JSON
   }
 
+  /**
+   * The Content-Type encoding of the response (e.g., 'application/json').
+   * Returns `undefined` if the response has no body.
+   */
   get encoding() {
     return this.payload?.encoding as InferMethodOutputEncoding<M>
   }
 
+  /**
+   * The parsed response body.
+   *
+   * For 'application/json' responses, this is the parsed and validated LexValue.
+   * For binary responses, this is a Uint8Array.
+   * Returns `undefined` if the response has no body.
+   */
   get body() {
     return this.payload?.body as XrpcResponseBody<M>
   }
@@ -63,7 +71,8 @@ export class XrpcResponse<const M extends Procedure | Query>
   /**
    * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use
    * {@link XrpcResponseError.matchesSchema} to narrow the error type based on
-   * the method's declared error schema.
+   * 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
    * response, or if the response does not conform to the method's schema.
    */
@@ -79,39 +88,49 @@ export class XrpcResponse<const M extends Procedure | Query>
     // @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 })
+      const payload = await readPayload(response, { parse: true }).catch(
+        (cause) => {
+          throw new XrpcUpstreamError(
+            method,
+            response,
+            null,
+            'Unable to parse response payload',
+            { cause },
+          )
+        },
+      )
 
+      // Properly formatted XRPC error response ?
       if (response.status >= 400 && isXrpcErrorPayload(payload)) {
-        throw new XrpcResponseError(
-          method,
-          response.status,
-          response.headers,
-          payload,
-        )
-      }
-
-      if (response.status >= 500) {
-        throw new XrpcUpstreamError(
-          'UpstreamFailure',
-          `Upstream server encountered an error`,
-          response,
-          payload,
-        )
+        throw response.status === 401
+          ? new XrpcAuthenticationError<M>(method, response, payload)
+          : new XrpcResponseError<M>(method, response, payload)
       }
 
+      // Invalid XRPC response (we probably did not hit an XRPC implementation)
       throw new XrpcUpstreamError(
-        'InvalidResponse',
-        response.status >= 400
-          ? `Upstream server returned an invalid response payload`
-          : `Upstream server returned an invalid status code`,
+        method,
         response,
         payload,
+        response.status >= 500
+          ? 'Upstream server encountered an error'
+          : response.status >= 400
+            ? 'Invalid response payload'
+            : 'Invalid response status code',
       )
     }
 
     // Only parse json if the schema expects it
     const payload = await readPayload(response, {
-      parse: shouldParse(method),
+      parse: method.output.encoding === CONTENT_TYPE_JSON,
+    }).catch((cause) => {
+      throw new XrpcUpstreamError(
+        method,
+        response,
+        null,
+        'Unable to parse response payload',
+        { cause },
+      )
     })
 
     // Response is successful (2xx). Validate payload (data and encoding) against schema.
@@ -119,22 +138,22 @@ export class XrpcResponse<const M extends Procedure | Query>
       // Schema expects no payload
       if (payload) {
         throw new XrpcUpstreamError(
-          'InvalidResponse',
-          `Expected response with no body, got ${payload.encoding}`,
+          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(
-          'InvalidResponse',
+          method,
+          response,
+          payload,
           payload
             ? `Expected ${method.output.encoding} response, got ${payload.encoding}`
             : `Expected non-empty response with content-type ${method.output.encoding}`,
-          response,
-          payload,
         )
       }
 
@@ -144,10 +163,10 @@ export class XrpcResponse<const M extends Procedure | Query>
 
         if (!result.success) {
           throw new XrpcUpstreamError(
-            'InvalidResponse',
-            `Response validation failed: ${result.reason.message}`,
+            method,
             response,
             payload,
+            `Response validation failed: ${result.reason.message}`,
             { cause: result.reason },
           )
         }
@@ -163,17 +182,13 @@ export class XrpcResponse<const M extends Procedure | Query>
   }
 }
 
-function shouldParse(method: Procedure | Query) {
-  return method.output.encoding === 'application/json'
-}
-
 /**
  * @note this function always consumes the response body
  */
 async function readPayload(
   response: Response,
   options?: { parse?: boolean },
-): Promise<XrpcPayload | null> {
+): Promise<XrpcResponsePayload> {
   // @TODO Should we limit the maximum response size here (this could also be
   // done by the FetchHandler)?
 
@@ -185,18 +200,18 @@ async function readPayload(
 
   // Response content-type is undefined
   if (!encoding) {
-    // If the body is empty, return null (= no payload)
+    // If the body is empty, return undefined (= no payload)
     const body = await response.arrayBuffer()
-    if (body.byteLength === 0) return null
+    if (body.byteLength === 0) return undefined
 
     // If we got data despite no content-type, treat it as binary
     return {
-      encoding: 'application/octet-stream',
+      encoding: CONTENT_TYPE_BINARY,
       body: new Uint8Array(body),
     }
   }
 
-  if (options?.parse && encoding === 'application/json') {
+  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.
@@ -204,22 +219,12 @@ async function readPayload(
     // to @ipld/dag-json)
     const text = await response.text()
 
-    try {
-      // @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) }
-    } catch (cause) {
-      throw new XrpcUpstreamError(
-        'InvalidResponse',
-        'Invalid JSON response body',
-        response,
-        null,
-        { cause },
-      )
-    }
+    // @TODO verify statement above
+    return { encoding, body: lexParse(text) }
   }
 
   return { encoding, body: new Uint8Array(await response.arrayBuffer()) }

package/src/types.ts

@@ -2,13 +2,40 @@ import { DidString, UnknownString } from '@atproto/lex-schema'
 
 export type { DidString, UnknownString }
 
+/**
+ * Service identifier fragment for DID service endpoints.
+ *
+ * Common values include 'atproto_labeler' for labeling services,
+ * or custom service identifiers.
+ */
 export type DidServiceIdentifier = 'atproto_labeler' | UnknownString
+
+/**
+ * A full service proxy identifier combining a DID with a service fragment.
+ *
+ * Used to route requests through a specific service endpoint.
+ *
+ * @example
+ * ```typescript
+ * const service: Service = 'did:web:api.bsky.app#bsky_appview'
+ * ```
+ */
 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
 
   /**
@@ -33,6 +60,31 @@ export type CallOptions = {
   validateResponse?: boolean
 }
 
+/**
+ * Valid input types for binary request bodies.
+ *
+ * These types can be used as the body for procedures that expect
+ * non-JSON content (e.g., blob uploads, binary data).
+ *
+ * @example Uploading a blob
+ * ```typescript
+ * const imageData: BinaryBodyInit = new Uint8Array(buffer)
+ * await client.uploadBlob(imageData, { encoding: 'image/png' })
+ * ```
+ *
+ * @example Streaming upload
+ * ```typescript
+ * const stream: BinaryBodyInit = someReadableStream
+ * await client.xrpc(uploadMethod, { body: stream })
+ * ```
+ *
+ * @example File upload in browser
+ * ```typescript
+ * const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement
+ * const file: BinaryBodyInit = fileInput.files[0]
+ * await client.xrpc(uploadMethod, { body: file })
+ * ```
+ */
 export type BinaryBodyInit =
   | Uint8Array
   | ArrayBuffer

package/src/util.ts

@@ -1,10 +1,42 @@
-import { DidString } from '@atproto/lex-schema'
+import {
+  DidString,
+  InferMethodOutput,
+  InferMethodOutputBody,
+  Procedure,
+  Query,
+} from '@atproto/lex-schema'
 
-export type XrpcPayload<B = unknown, E extends string = string> = {
-  body: B
-  encoding: E
-}
+/**
+ * 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>
+
+/**
+ * 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>
 
+/**
+ * Type guard to check if a value is {@link Blob}-like.
+ *
+ * Handles both native Blobs and polyfilled Blob implementations
+ * (e.g., fetch-blob from node-fetch).
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a Blob or Blob-like object
+ */
 export function isBlobLike(value: unknown): value is Blob {
   if (value == null) return false
   if (typeof value !== 'object') return false
@@ -32,6 +64,19 @@ export function isAsyncIterable<T>(
   )
 }
 
+/**
+ * Builds HTTP headers for AT Protocol requests.
+ *
+ * Adds the following headers when applicable:
+ * - `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
+ * @returns A new Headers object with AT Protocol headers added
+ */
 export function buildAtprotoHeaders(options: {
   headers?: HeadersInit
   service?: `${DidString}#${string}`

package/src/www-authenticate.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from 'vitest'
+import { parseWWWAuthenticateHeader } from './www-authenticate.js'
+
+describe(parseWWWAuthenticateHeader, () => {
+  describe('auth-params', () => {
+    it('parses single unquoted auth param', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm=example.com')).toEqual({
+        Bearer: { realm: 'example.com' },
+      })
+    })
+
+    it('parses single quoted auth param', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm="example.com"')).toEqual({
+        Bearer: { realm: 'example.com' },
+      })
+    })
+
+    it('parses quoted values with spaces', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm="my realm"')).toEqual({
+        Bearer: { realm: 'my realm' },
+      })
+    })
+
+    it('parses quoted values with escaped double quotes', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="example\\"quoted\\""'),
+      ).toEqual({
+        Bearer: { realm: 'example"quoted"' },
+      })
+    })
+
+    it('parses quoted values with escaped backslash', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="path\\\\to\\\\file"'),
+      ).toEqual({
+        Bearer: { realm: 'path\\to\\file' },
+      })
+    })
+
+    it('parses param names with hyphens', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer error-uri="https://example.com"'),
+      ).toEqual({
+        Bearer: { 'error-uri': 'https://example.com' },
+      })
+    })
+
+    it('parses param names with underscores', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer error_description="test"'),
+      ).toEqual({
+        Bearer: { error_description: 'test' },
+      })
+    })
+
+    it('parses param with numeric value', () => {
+      expect(parseWWWAuthenticateHeader('Bearer max-age=3600')).toEqual({
+        Bearer: { 'max-age': '3600' },
+      })
+    })
+
+    it('parses empty quoted value', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm=""')).toEqual({
+        Bearer: { realm: '' },
+      })
+    })
+
+    it('parses Basic auth challenge', () => {
+      expect(
+        parseWWWAuthenticateHeader('Basic realm="Access to staging site"'),
+      ).toEqual({
+        Basic: { realm: 'Access to staging site' },
+      })
+    })
+
+    it('parses Bearer with realm', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="https://auth.example.com"'),
+      ).toEqual({
+        Bearer: { realm: 'https://auth.example.com' },
+      })
+    })
+
+    it('parses DPoP with algs param', () => {
+      expect(parseWWWAuthenticateHeader('DPoP algs="ES256 RS256"')).toEqual({
+        DPoP: { algs: 'ES256 RS256' },
+      })
+    })
+
+    it('parses Digest auth challenge', () => {
+      const result = parseWWWAuthenticateHeader(
+        'Digest realm="digest-realm", nonce="abc123"',
+      )
+      expect(result).toEqual({
+        Digest: { realm: 'digest-realm', nonce: 'abc123' },
+      })
+    })
+
+    it('handle empty unquoted params', () => {
+      const result = parseWWWAuthenticateHeader('Bearer realm=')
+      expect(result).toEqual({ Bearer: { realm: '' } })
+    })
+
+    it('handle empty params', () => {
+      const result = parseWWWAuthenticateHeader('Bearer realm=""')
+      expect(result).toEqual({ Bearer: { realm: '' } })
+    })
+
+    it('treats scheme-only header as scheme with itself as token68', () => {
+      const result = parseWWWAuthenticateHeader('Basic')
+      expect(result).toEqual({ Basic: {} })
+    })
+
+    it('parses multiple challenges with commas and escaped quotes', () => {
+      const result = parseWWWAuthenticateHeader(
+        `Newauth realm="apps", type=1,\n\t    title="Login to \\"apps\\"", Basic realm="simple"`,
+      )
+      expect(result).toEqual({
+        Newauth: {
+          realm: 'apps',
+          type: '1',
+          title: 'Login to "apps"',
+        },
+        Basic: { realm: 'simple' },
+      })
+    })
+
+    it('parses first challenge before comma', () => {
+      const result = parseWWWAuthenticateHeader(
+        'Basic realm="foo", Bearer realm="bar"',
+      )
+      expect(result).toEqual({
+        Basic: { realm: 'foo' },
+        Bearer: { realm: 'bar' },
+      })
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles empty string', () => {
+      expect(parseWWWAuthenticateHeader('')).toEqual({})
+    })
+
+    it('handles whitespace-only string', () => {
+      expect(parseWWWAuthenticateHeader('   ')).toEqual({})
+    })
+
+    it('trims whitespace from header', () => {
+      expect(parseWWWAuthenticateHeader('  Bearer realm="test"  ')).toEqual({
+        Bearer: { realm: 'test' },
+      })
+    })
+
+    it('handles commas as quoted param value', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="example, with, commas"'),
+      ).toEqual({ Bearer: { realm: 'example, with, commas' } })
+    })
+
+    it('handles multiple challenges with varying whitespace', () => {
+      expect(
+        parseWWWAuthenticateHeader(
+          '  Bearer realm="test"  ,    Basic    rr=               ',
+        ),
+      ).toEqual({
+        Bearer: { realm: 'test' },
+        Basic: { rr: '' },
+      })
+    })
+  })
+
+  describe('invalid challenges', () => {
+    it('parses single challenge with no comma correctly', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="oauth" error="invalid"'),
+      ).toEqual(undefined)
+    })
+
+    it('ignores invalid challenges', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm="unclosed')).toEqual(
+        undefined,
+      )
+    })
+
+    it('handles random text without equals sign as token68', () => {
+      expect(parseWWWAuthenticateHeader('Bearer sometoken')).toEqual({
+        Bearer: 'sometoken',
+      })
+    })
+
+    it('ignores trailing whitespace after scheme', () => {
+      expect(parseWWWAuthenticateHeader('Bearer   ')).toEqual({ Bearer: {} })
+    })
+
+    it('handles duplicate params (last wins)', () => {
+      expect(
+        parseWWWAuthenticateHeader('Bearer realm="first", realm="second"'),
+      ).toEqual({ Bearer: { realm: 'second' } })
+    })
+
+    it('extracts valid param after invalid characters', () => {
+      expect(parseWWWAuthenticateHeader('Bearer realm@foo="bar"')).toEqual({
+        Bearer: { 'realm@foo': 'bar' },
+      })
+    })
+
+    it('ignores param with empty name', () => {
+      expect(parseWWWAuthenticateHeader('Bearer ="value"')).toEqual(undefined)
+    })
+
+    it('handles completely malformed input gracefully', () => {
+      expect(parseWWWAuthenticateHeader('!@#$%')).toEqual({ '!@#$%': {} })
+    })
+
+    it('handles duplicate schemes as invalid', () => {
+      expect(
+        parseWWWAuthenticateHeader('Basic realm="first", Basic realm="second"'),
+      ).toEqual(undefined)
+    })
+
+    it('handles params without scheme as invalid', () => {
+      expect(parseWWWAuthenticateHeader('Bearer, realm="foo"')).toEqual(
+        undefined,
+      )
+    })
+  })
+})