@atproto/lex-client 0.0.10 → 0.0.12

package/src/www-authenticate.ts

@@ -0,0 +1,101 @@
+type WWWAuthenticateParams = { [authParam in string]: string }
+
+/**
+ * Parsed representation of a WWW-Authenticate HTTP header.
+ *
+ * Maps authentication scheme names to either:
+ * - A token68 string (compact authentication data)
+ * - A params object with key-value pairs
+ *
+ * @example Bearer with realm
+ * ```typescript
+ * // WWW-Authenticate: Bearer realm="example"
+ * const parsed: WWWAuthenticate = {
+ *   Bearer: { realm: 'example' }
+ * }
+ * ```
+ *
+ * @example DPoP with error
+ * ```typescript
+ * // WWW-Authenticate: DPoP error="use_dpop_nonce", error_description="..."
+ * const parsed: WWWAuthenticate = {
+ *   DPoP: { error: 'use_dpop_nonce', error_description: '...' }
+ * }
+ * ```
+ */
+export type WWWAuthenticate = {
+  [authScheme in string]:
+    | string // token68
+    | WWWAuthenticateParams
+}
+
+/**
+ * Returns `undefined` if the header is malformed.
+ */
+export function parseWWWAuthenticateHeader(
+  header?: unknown,
+): undefined | WWWAuthenticate {
+  if (typeof header !== 'string') return undefined
+
+  const wwwAuthenticate: WWWAuthenticate = {}
+
+  // Split over commas, not within quoted strings
+  const trimmedHeader = header.trim()
+  if (!trimmedHeader) return wwwAuthenticate
+
+  const parts = trimmedHeader.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/)
+
+  let currentParams: WWWAuthenticateParams | null = null
+
+  for (let part of parts) {
+    // Check if the part starts with an auth scheme
+    const schemeMatch = part.trim().match(/^([^"=\s]+)(\s+.*)?$/)
+    if (schemeMatch) {
+      const scheme = schemeMatch[1]
+
+      // Duplicate scheme
+      if (Object.hasOwn(wwwAuthenticate, scheme)) return undefined
+
+      const rest = schemeMatch[2]?.trim()
+      if (!rest) {
+        // Scheme only (no params or token68)
+        currentParams = null
+        wwwAuthenticate[scheme] = Object.create(null)
+        continue
+      }
+
+      if (!rest.includes('=')) {
+        // Scheme with token68
+        currentParams = null
+        wwwAuthenticate[scheme] = rest
+        continue
+      }
+
+      // Scheme with params
+
+      currentParams = Object.create(null) as WWWAuthenticateParams
+      wwwAuthenticate[scheme] = currentParams
+
+      // Fall through to parse params
+      part = rest
+    }
+
+    // Invalid header
+    if (!currentParams) return undefined
+
+    const param = part.match(
+      /^\s*([^"\s=]+)=(?:("[^"\\]*(?:\\.[^"\\]*)*")|([^\s,"]*))\s*$/,
+    )
+
+    // invalid param
+    if (!param) return undefined
+
+    const paramName = param[1]
+    const paramValue =
+      param[3] ?? param[2]!.slice(1, -1).replaceAll(/\\(.)/g, '$1')
+
+    currentParams[paramName] = paramValue
+  }
+
+  return wwwAuthenticate
+}

package/src/xrpc.ts

@@ -13,15 +13,10 @@ import {
   getMain,
 } from '@atproto/lex-schema'
 import { Agent } from './agent.js'
-import {
-  XrpcResponseError,
-  XrpcUnexpectedError,
-  XrpcUpstreamError,
-} from './errors.js'
+import { XrpcFailure, asXrpcFailure } from './errors.js'
 import { XrpcResponse } from './response.js'
 import { BinaryBodyInit, CallOptions } from './types.js'
 import {
-  XrpcPayload,
   buildAtprotoHeaders,
   isAsyncIterable,
   isBlobLike,
@@ -32,6 +27,11 @@ import {
 type XrpcParamsOptions<P extends Params> =
   NonNullable<unknown> extends P ? { params?: P } : { params: P }
 
+/**
+ * The query/path parameters type for an XRPC method, inferred from its schema.
+ *
+ * @typeParam M - The XRPC method type (Procedure, Query, or Subscription)
+ */
 export type XrpcRequestParams<M extends Procedure | Query | Subscription> =
   InferInput<M['parameters']>
 
@@ -44,39 +44,54 @@ type XrpcInputOptions<In> = In extends { body: infer B; encoding: infer E }
     { body: B; encoding?: E }
   : { body?: undefined; encoding?: undefined }
 
+/**
+ * Options for making an XRPC request.
+ *
+ * Combines {@link CallOptions} with method-specific params and body requirements.
+ * The type system ensures required params/body are provided based on the method schema.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ * @see {@link CallOptions} for general request options like signal and validateRequest
+ * @see {@link XrpcParamsOptions} for method-specific query parameters
+ * @see {@link XrpcInputOptions} for method-specific body and encoding requirements
+ *
+ * @example Query with params
+ * ```typescript
+ * const options: XrpcOptions<typeof app.bsky.feed.getTimeline.main> = {
+ *   params: { limit: 50 }
+ * }
+ * ```
+ *
+ * @example Procedure with body
+ * ```typescript
+ * const options: XrpcOptions<typeof com.atproto.repo.createRecord.main> = {
+ *   body: { repo: did, collection: 'app.bsky.feed.post', record: { ... } }
+ * }
+ * ```
+ */
 export type XrpcOptions<M extends Procedure | Query = Procedure | Query> =
   CallOptions &
     XrpcInputOptions<XrpcRequestPayload<M>> &
     XrpcParamsOptions<XrpcRequestParams<M>>
 
-export type XrpcFailure<M extends Procedure | Query> =
-  // The server returned a valid XRPC error response
-  | XrpcResponseError<M>
-  // The response was not a valid XRPC response, or it does not match the schema
-  | XrpcUpstreamError
-  // Something went wrong (network error, etc.)
-  | XrpcUnexpectedError
-
-export type XrpcResult<M extends Procedure | Query> =
-  | XrpcResponse<M>
-  | XrpcFailure<M>
-
-/**
- * Utility method to type cast the error thrown by {@link xrpc} to an
- * {@link XrpcFailure} matching the provided method. Only use this function
- * inside a catch block right after calling {@link xrpc}, and use the same
- * method type parameter as used in the {@link xrpc} call.
- */
-export function asXrpcFailure<M extends Procedure | Query = Procedure | Query>(
-  err: unknown,
-): XrpcFailure<M> {
-  if (err instanceof XrpcResponseError) return err
-  if (err instanceof XrpcUpstreamError) return err
-  return XrpcUnexpectedError.from(err)
-}
-
 /**
- * @throws XrpcFailure<M>
+ * Makes an XRPC request and throws on failure.
+ *
+ * This is the low-level function for making XRPC calls. For most use cases,
+ * prefer using {@link Client.xrpc} which provides a more ergonomic API.
+ *
+ * @param agent - The {@link Agent} to use for making the request
+ * @param ns - The lexicon method definition
+ * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)
+ * @returns The successful {@link XrpcResponse}
+ * @throws {XrpcFailure} When the request fails
+ *
+ * @example
+ * ```typescript
+ * const response = await xrpc(agent, app.bsky.feed.getTimeline.main, {
+ *   params: { limit: 50 }
+ * })
+ * ```
  */
 export async function xrpc<const M extends Query | Procedure>(
   agent: Agent,
@@ -94,13 +109,49 @@ export async function xrpc<const M extends Query | Procedure>(
   ns: Main<M>,
   options: XrpcOptions<M> = {} as XrpcOptions<M>,
 ): Promise<XrpcResponse<M>> {
-  try {
-    return await lexRpcRequest<M>(agent, ns, options)
-  } catch (err) {
-    throw asXrpcFailure<M>(err)
-  }
+  const response = await xrpcSafe<M>(agent, ns, options)
+  if (response.success) return response
+  else throw response
 }
 
+/**
+ * Union type representing either a successful response or a failure.
+ *
+ * Both {@link XrpcResponse} and {@link XrpcFailure} have a `success` property
+ * that can be used to discriminate between them.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export type XrpcResult<M extends Procedure | Query> =
+  | XrpcResponse<M>
+  | XrpcFailure<M>
+
+/**
+ * Makes an XRPC request without throwing on failure.
+ *
+ * Returns a discriminated union that can be checked via the `success` property.
+ * This is useful for handling errors without try/catch blocks. This also allow
+ * failure results to be typed with the method schema, which can provide better
+ * type safety when handling errors (e.g. checking for specific error codes).
+ *
+ * @param agent - The {@link Agent} to use for making the request
+ * @param ns - The lexicon method definition
+ * @param options - Request {@link XrpcOptions options} (params, body, headers, etc.)
+ * @returns Either a successful {@link XrpcResponse} or an {@link XrpcFailure}
+ *
+ * @example
+ * ```typescript
+ * const result = await xrpcSafe(agent, app.bsky.actor.getProfile.main, {
+ *   params: { actor: 'alice.bsky.social' }
+ * })
+ *
+ * if (result.success) {
+ *   console.log(result.body.displayName)
+ * } else {
+ *   console.error('Request failed:', result.error)
+ * }
+ * ```
+ */
 export async function xrpcSafe<const M extends Query | Procedure>(
   agent: Agent,
   ns: NonNullable<unknown> extends XrpcOptions<M>
@@ -117,20 +168,16 @@ export async function xrpcSafe<const M extends Query | Procedure>(
   ns: Main<M>,
   options: XrpcOptions<M> = {} as XrpcOptions<M>,
 ): Promise<XrpcResult<M>> {
-  return lexRpcRequest<M>(agent, ns, options).catch(asXrpcFailure<M>)
-}
-
-async function lexRpcRequest<const M extends Query | Procedure>(
-  agent: Agent,
-  ns: Main<M>,
-  options: XrpcOptions<M> = {} as XrpcOptions<M>,
-): Promise<XrpcResponse<M>> {
-  const method = getMain(ns)
   options.signal?.throwIfAborted()
-  const url = xrpcRequestUrl(method, options)
-  const request = xrpcRequestInit(method, options)
-  const response = await agent.fetchHandler(url, request)
-  return XrpcResponse.fromFetchResponse<M>(method, response, options)
+  const method: M = getMain(ns)
+  try {
+    const url = xrpcRequestUrl(method, options)
+    const request = xrpcRequestInit(method, options)
+    const response = await agent.fetchHandler(url, request)
+    return await XrpcResponse.fromFetchResponse<M>(method, response, options)
+  } catch (cause) {
+    return asXrpcFailure(method, cause)
+  }
 }
 
 function xrpcRequestUrl<M extends Procedure | Query | Subscription>(
@@ -205,7 +252,7 @@ function xrpcProcedureInput(
   method: Procedure,
   options: CallOptions & { body?: LexValue | BinaryBodyInit },
   encodingHint?: string,
-): null | XrpcPayload<BodyInit> {
+): null | { body: BodyInit; encoding: string } {
   const { input } = method
   const { body } = options
 
@@ -254,7 +301,7 @@ function buildPayload(
   schema: Payload,
   body: undefined | BodyInit,
   encodingHint?: string,
-): null | XrpcPayload<BodyInit> {
+): null | { body: BodyInit; encoding: string } {
   if (schema.encoding === undefined) {
     if (body !== undefined) {
       throw new TypeError(