@atproto/lex-client 0.0.15 → 0.0.17

package/src/xrpc.ts

@@ -14,20 +14,17 @@ import {
   getMain,
 } from '@atproto/lex-schema'
 import { Agent, AgentOptions, buildAgent } from './agent.js'
-import { XrpcFailure, asXrpcFailure } from './errors.js'
-import { XrpcResponse } from './response.js'
-import { BinaryBodyInit, CallOptions } from './types.js'
+import { XrpcFailure, XrpcFetchError, asXrpcFailure } from './errors.js'
+import { XrpcResponse, XrpcResponseOptions } from './response.js'
+import { BinaryBodyInit } from './types.js'
 import {
-  buildAtprotoHeaders,
+  XrpcRequestHeadersOptions,
+  buildXrpcRequestHeaders,
   isAsyncIterable,
   isBlobLike,
   toReadableStream,
 } from './util.js'
 
-// If all params are optional, allow omitting the params object
-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.
  *
@@ -36,25 +33,43 @@ type XrpcParamsOptions<P extends Params> =
 export type XrpcRequestParams<M extends Procedure | Query | Subscription> =
   InferInput<M['parameters']>
 
+// If all params are optional, allow omitting the params object
+type XrpcRequestParamsOptions<P extends Params> =
+  NonNullable<unknown> extends P ? { params?: P } : { params: P }
+
 type XrpcRequestPayload<M extends Procedure | Query> = M extends Procedure
   ? InferPayload<M['input'], BinaryBodyInit>
   : undefined
 
-type XrpcInputOptions<In> = In extends { body: infer B; encoding: infer E }
-  ? // encoding will be inferred from the schema at runtime if not provided
-    { body: B; encoding?: E }
+type XrpcRequestPayloadOptions<TPayload> = TPayload extends {
+  body: infer B
+  encoding: infer E
+}
+  ? {
+      body: B
+
+      /**
+       * mime type hint for binary bodies
+       *
+       * Only needed for endpoints that accept binary input (e.g. file uploads)
+       * when the body is a Blob-like object without a type (e.g. fetch-blob's
+       * Blob). If the body is a Blob-like object with a type, that type will be
+       * used as the content-type header instead of this option.
+       *
+       * @default "application/octet-stream"
+       */
+      encoding?: E
+    }
   : { body?: undefined; encoding?: undefined }
 
 /**
- * Options for making an XRPC request.
+ * Options for making an XRPC request, based on the method schema.
  *
- * Combines {@link CallOptions} with method-specific params and body requirements.
- * The type system ensures required params/body are provided based on the method schema.
+ * Combines {@link XrpcRequestOptions} and {@link XrpcResponseOptions} 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
@@ -71,9 +86,31 @@ type XrpcInputOptions<In> = In extends { body: infer B; encoding: infer E }
  * ```
  */
 export type XrpcOptions<M extends Procedure | Query = Procedure | Query> =
-  CallOptions &
-    XrpcInputOptions<XrpcRequestPayload<M>> &
-    XrpcParamsOptions<XrpcRequestParams<M>>
+  XrpcRequestOptions<M> & XrpcResponseOptions
+
+export type XrpcRequestOptions<
+  M extends Procedure | Query = Procedure | Query,
+> = XrpcRequestProcessingOptions &
+  XrpcRequestHeadersOptions &
+  XrpcRequestPayloadOptions<XrpcRequestPayload<M>> &
+  XrpcRequestParamsOptions<XrpcRequestParams<M>>
+
+export type XrpcRequestProcessingOptions = {
+  /**
+   * AbortSignal to cancel the request.
+   */
+  signal?: AbortSignal
+
+  /**
+   * 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
+}
 
 /**
  * Makes an XRPC request and throws on failure.
@@ -181,7 +218,9 @@ export async function xrpcSafe<const M extends Query | Procedure>(
     const agent = buildAgent(agentOpts)
     const url = xrpcRequestUrl(method, options)
     const request = xrpcRequestInit(method, options)
-    const response = await agent.fetchHandler(url, request)
+    const response = await agent.fetchHandler(url, request).catch((cause) => {
+      throw new XrpcFetchError(method, cause)
+    })
     return await XrpcResponse.fromFetchResponse<M>(method, response, options)
   } catch (cause) {
     return asXrpcFailure(method, cause)
@@ -190,10 +229,13 @@ export async function xrpcSafe<const M extends Query | Procedure>(
 
 function xrpcRequestUrl<M extends Procedure | Query | Subscription>(
   method: M,
-  options: CallOptions & { params?: Params },
+  options: { params?: Params },
 ): `/xrpc/${NsidString}${'' | `?${string}`}` {
   const path = `/xrpc/${method.nsid}` as const
 
+  // @NOTE param.toURLSearchParams() will always validate the params in order to
+  // apply default values, so we can't disable it with options.validateRequest
+
   const queryString = method.parameters
     ?.toURLSearchParams(options.params ?? {})
     .toString()
@@ -203,12 +245,13 @@ function xrpcRequestUrl<M extends Procedure | Query | Subscription>(
 
 function xrpcRequestInit<T extends Procedure | Query>(
   schema: T,
-  options: CallOptions & {
-    body?: LexValue | BinaryBodyInit
-    encoding?: string
-  },
+  options: XrpcRequestProcessingOptions &
+    XrpcRequestHeadersOptions &
+    XrpcProcedureInputOptions & {
+      encoding?: string
+    },
 ): RequestInit & { duplex?: 'half' } {
-  const headers = buildAtprotoHeaders(options)
+  const headers = buildXrpcRequestHeaders(options)
 
   // Tell the server what type of response we're expecting
   if (schema.output.encoding) {
@@ -256,9 +299,14 @@ function xrpcRequestInit<T extends Procedure | Query>(
   }
 }
 
+type XrpcProcedureInputOptions = {
+  body?: LexValue | BinaryBodyInit
+  validateRequest?: boolean
+}
+
 function xrpcProcedureInput(
   method: Procedure,
-  options: CallOptions & { body?: LexValue | BinaryBodyInit },
+  options: XrpcProcedureInputOptions,
   encodingHint?: string,
 ): null | { body: BodyInit; encoding: string } {
   const { input } = method