@atproto/xrpc 0.4.3 → 0.5.1-rc.0

package/dist/xrpc-client.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XrpcClient = void 0;
+const lexicon_1 = require("@atproto/lexicon");
+const fetch_handler_1 = require("./fetch-handler");
+const types_1 = require("./types");
+const util_1 = require("./util");
+class XrpcClient {
+    constructor(fetchHandlerOpts, 
+    // "Lexicons" is redundant here (because that class implements
+    // "Iterable<LexiconDoc>") but we keep it for explicitness:
+    lex) {
+        Object.defineProperty(this, "fetchHandler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "lex", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.fetchHandler = (0, fetch_handler_1.buildFetchHandler)(fetchHandlerOpts);
+        this.lex = lex instanceof lexicon_1.Lexicons ? lex : new lexicon_1.Lexicons(lex);
+    }
+    async call(methodNsid, params, data, opts) {
+        const def = this.lex.getDefOrThrow(methodNsid);
+        if (!def || (def.type !== 'query' && def.type !== 'procedure')) {
+            throw new TypeError(`Invalid lexicon: ${methodNsid}. Must be a query or procedure.`);
+        }
+        // @TODO: should we validate the params and data here?
+        // this.lex.assertValidXrpcParams(methodNsid, params)
+        // if (data !== undefined) {
+        //   this.lex.assertValidXrpcInput(methodNsid, data)
+        // }
+        const reqUrl = (0, util_1.constructMethodCallUrl)(methodNsid, def, params);
+        const reqMethod = (0, util_1.getMethodSchemaHTTPMethod)(def);
+        const reqHeaders = (0, util_1.constructMethodCallHeaders)(def, data, opts);
+        const reqBody = (0, util_1.encodeMethodCallBody)(reqHeaders, data);
+        // The duplex field is required for streaming bodies, but not yet reflected
+        // anywhere in docs or types. See whatwg/fetch#1438, nodejs/node#46221.
+        const init = {
+            method: reqMethod,
+            headers: reqHeaders,
+            body: reqBody,
+            duplex: 'half',
+            signal: opts?.signal,
+        };
+        try {
+            const response = await this.fetchHandler.call(undefined, reqUrl, init);
+            const resStatus = response.status;
+            const resHeaders = Object.fromEntries(response.headers.entries());
+            const resBodyBytes = await response.arrayBuffer();
+            const resBody = (0, util_1.httpResponseBodyParse)(response.headers.get('content-type'), resBodyBytes);
+            const resCode = (0, types_1.httpResponseCodeToEnum)(resStatus);
+            if (resCode !== types_1.ResponseType.Success) {
+                const { error = undefined, message = undefined } = resBody && (0, util_1.isErrorResponseBody)(resBody) ? resBody : {};
+                throw new types_1.XRPCError(resCode, error, message, resHeaders);
+            }
+            try {
+                this.lex.assertValidXrpcOutput(methodNsid, resBody);
+            }
+            catch (e) {
+                if (e instanceof lexicon_1.ValidationError) {
+                    throw new types_1.XRPCInvalidResponseError(methodNsid, e, resBody);
+                }
+                throw e;
+            }
+            return new types_1.XRPCResponse(resBody, resHeaders);
+        }
+        catch (err) {
+            throw types_1.XRPCError.from(err);
+        }
+    }
+}
+exports.XrpcClient = XrpcClient;
+//# sourceMappingURL=xrpc-client.js.map

package/dist/xrpc-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xrpc-client.js","sourceRoot":"","sources":["../src/xrpc-client.ts"],"names":[],"mappings":";;;AAAA,8CAAwE;AACxE,mDAIwB;AACxB,mCAQgB;AAChB,iCAOe;AAEf,MAAa,UAAU;IAIrB,YACE,gBAAoD;IACpD,8DAA8D;IAC9D,2DAA2D;IAC3D,GAAoC;QAP7B;;;;;WAA0B;QAC1B;;;;;WAAa;QAQpB,IAAI,CAAC,YAAY,GAAG,IAAA,iCAAiB,EAAC,gBAAgB,CAAC,CAAA;QAEvD,IAAI,CAAC,GAAG,GAAG,GAAG,YAAY,kBAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,kBAAQ,CAAC,GAAG,CAAC,CAAA;IAC9D,CAAC;IAED,KAAK,CAAC,IAAI,CACR,UAAkB,EAClB,MAAoB,EACpB,IAAc,EACd,IAAkB;QAElB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,CAAA;QAC9C,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,SAAS,CACjB,oBAAoB,UAAU,iCAAiC,CAChE,CAAA;QACH,CAAC;QAED,sDAAsD;QACtD,qDAAqD;QACrD,4BAA4B;QAC5B,oDAAoD;QACpD,IAAI;QAEJ,MAAM,MAAM,GAAG,IAAA,6BAAsB,EAAC,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;QAC9D,MAAM,SAAS,GAAG,IAAA,gCAAyB,EAAC,GAAG,CAAC,CAAA;QAChD,MAAM,UAAU,GAAG,IAAA,iCAA0B,EAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QAC9D,MAAM,OAAO,GAAG,IAAA,2BAAoB,EAAC,UAAU,EAAE,IAAI,CAAC,CAAA;QAEtD,2EAA2E;QAC3E,uEAAuE;QACvE,MAAM,IAAI,GAAqC;YAC7C,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,UAAU;YACnB,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAA;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;YAEtE,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAA;YACjC,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;YACjE,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAA;YACjD,MAAM,OAAO,GAAG,IAAA,4BAAqB,EACnC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EACpC,YAAY,CACb,CAAA;YAED,MAAM,OAAO,GAAG,IAAA,8BAAsB,EAAC,SAAS,CAAC,CAAA;YACjD,IAAI,OAAO,KAAK,oBAAY,CAAC,OAAO,EAAE,CAAC;gBACrC,MAAM,EAAE,KAAK,GAAG,SAAS,EAAE,OAAO,GAAG,SAAS,EAAE,GAC9C,OAAO,IAAI,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;gBACxD,MAAM,IAAI,iBAAS,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;YAC1D,CAAC;YAED,IAAI,CAAC;gBACH,IAAI,CAAC,GAAG,CAAC,qBAAqB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;YACrD,CAAC;YAAC,OAAO,CAAU,EAAE,CAAC;gBACpB,IAAI,CAAC,YAAY,yBAAe,EAAE,CAAC;oBACjC,MAAM,IAAI,gCAAwB,CAAC,UAAU,EAAE,CAAC,EAAE,OAAO,CAAC,CAAA;gBAC5D,CAAC;gBAED,MAAM,CAAC,CAAA;YACT,CAAC;YAED,OAAO,IAAI,oBAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,iBAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC3B,CAAC;IACH,CAAC;CACF;AAlFD,gCAkFC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/xrpc",
-  "version": "0.4.3",
+  "version": "0.5.1-rc.0",
   "license": "MIT",
   "description": "atproto HTTP API (XRPC) client library",
   "keywords": [
@@ -14,14 +14,15 @@
     "directory": "packages/xrpc"
   },
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "dependencies": {
-    "zod": "^3.21.4",
-    "@atproto/lexicon": "^0.3.3"
+    "zod": "^3.23.8",
+    "@atproto/lexicon": "^0.4.0"
   },
-  "scripts": {
-    "build": "node ./build.js",
-    "postbuild": "tsc --build tsconfig.build.json",
-    "update-main-to-dist": "node ../../update-main-to-dist.js packages/xrpc"
+  "devDependencies": {
+    "typescript": "^5.3.3"
   },
-  "types": "dist/index.d.ts"
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json"
+  }
 }

package/src/client.ts

@@ -1,29 +1,24 @@
-import { LexiconDoc, Lexicons, ValidationError } from '@atproto/lexicon'
-import {
-  getMethodSchemaHTTPMethod,
-  constructMethodCallUri,
-  constructMethodCallHeaders,
-  encodeMethodCallBody,
-  httpResponseCodeToEnum,
-  httpResponseBodyParse,
-  normalizeHeaders,
-} from './util'
-import {
-  FetchHandler,
-  FetchHandlerResponse,
-  Headers,
-  CallOptions,
-  QueryParams,
-  ResponseType,
-  errorResponseBody,
-  ErrorResponseBody,
-  XRPCResponse,
-  XRPCError,
-  XRPCInvalidResponseError,
-} from './types'
+import { LexiconDoc, Lexicons } from '@atproto/lexicon'
+import { CallOptions, QueryParams } from './types'
+import { XrpcClient } from './xrpc-client'
+import { combineHeaders } from './util'
 
+/** @deprecated Use {@link XrpcClient} instead */
 export class Client {
-  fetch: FetchHandler = defaultFetchHandler
+  /** @deprecated */
+  get fetch(): never {
+    throw new Error(
+      'Client.fetch is no longer supported. Use an XrpcClient instead.',
+    )
+  }
+
+  /** @deprecated */
+  set fetch(_: never) {
+    throw new Error(
+      'Client.fetch is no longer supported. Use an XrpcClient instead.',
+    )
+  }
+
   lex = new Lexicons()
 
   // method calls
@@ -33,7 +28,7 @@ export class Client {
     serviceUri: string | URL,
     methodNsid: string,
     params?: QueryParams,
-    data?: unknown,
+    data?: BodyInit | null,
     opts?: CallOptions,
   ) {
     return this.service(serviceUri).call(methodNsid, params, data, opts)
@@ -61,13 +56,19 @@ export class Client {
   }
 }
 
-export class ServiceClient {
-  baseClient: Client
+/** @deprecated Use {@link XrpcClient} instead */
+export class ServiceClient extends XrpcClient {
   uri: URL
   headers: Record<string, string> = {}
 
-  constructor(baseClient: Client, serviceUri: string | URL) {
-    this.baseClient = baseClient
+  constructor(
+    public baseClient: Client,
+    serviceUri: string | URL,
+  ) {
+    super(async (input, init) => {
+      const headers = combineHeaders(init.headers, Object.entries(this.headers))
+      return fetch(new URL(input, this.uri), { ...init, headers })
+    }, baseClient.lex)
     this.uri = typeof serviceUri === 'string' ? new URL(serviceUri) : serviceUri
   }
 
@@ -78,92 +79,4 @@ export class ServiceClient {
   unsetHeader(key: string): void {
     delete this.headers[key]
   }
-
-  async call(
-    methodNsid: string,
-    params?: QueryParams,
-    data?: unknown,
-    opts?: CallOptions,
-  ) {
-    const def = this.baseClient.lex.getDefOrThrow(methodNsid)
-    if (!def || (def.type !== 'query' && def.type !== 'procedure')) {
-      throw new Error(
-        `Invalid lexicon: ${methodNsid}. Must be a query or procedure.`,
-      )
-    }
-
-    const httpMethod = getMethodSchemaHTTPMethod(def)
-    const httpUri = constructMethodCallUri(methodNsid, def, this.uri, params)
-    const httpHeaders = constructMethodCallHeaders(def, data, {
-      headers: {
-        ...this.headers,
-        ...opts?.headers,
-      },
-      encoding: opts?.encoding,
-    })
-
-    const res = await this.baseClient.fetch(
-      httpUri,
-      httpMethod,
-      httpHeaders,
-      data,
-    )
-
-    const resCode = httpResponseCodeToEnum(res.status)
-    if (resCode === ResponseType.Success) {
-      try {
-        this.baseClient.lex.assertValidXrpcOutput(methodNsid, res.body)
-      } catch (e: any) {
-        if (e instanceof ValidationError) {
-          throw new XRPCInvalidResponseError(methodNsid, e, res.body)
-        } else {
-          throw e
-        }
-      }
-      return new XRPCResponse(res.body, res.headers)
-    } else {
-      if (res.body && isErrorResponseBody(res.body)) {
-        throw new XRPCError(
-          resCode,
-          res.body.error,
-          res.body.message,
-          res.headers,
-        )
-      } else {
-        throw new XRPCError(resCode)
-      }
-    }
-  }
-}
-
-export async function defaultFetchHandler(
-  httpUri: string,
-  httpMethod: string,
-  httpHeaders: Headers,
-  httpReqBody: unknown,
-): Promise<FetchHandlerResponse> {
-  try {
-    // The duplex field is now required for streaming bodies, but not yet reflected
-    // anywhere in docs or types. See whatwg/fetch#1438, nodejs/node#46221.
-    const headers = normalizeHeaders(httpHeaders)
-    const reqInit: RequestInit & { duplex: string } = {
-      method: httpMethod,
-      headers,
-      body: encodeMethodCallBody(headers, httpReqBody),
-      duplex: 'half',
-    }
-    const res = await fetch(httpUri, reqInit)
-    const resBody = await res.arrayBuffer()
-    return {
-      status: res.status,
-      headers: Object.fromEntries(res.headers.entries()),
-      body: httpResponseBodyParse(res.headers.get('content-type'), resBody),
-    }
-  } catch (e) {
-    throw new XRPCError(ResponseType.Unknown, String(e))
-  }
-}
-
-function isErrorResponseBody(v: unknown): v is ErrorResponseBody {
-  return errorResponseBody.safeParse(v).success
 }

package/src/fetch-handler.ts

@@ -0,0 +1,73 @@
+import { Gettable } from './types'
+import { combineHeaders } from './util'
+
+export type FetchHandler = (
+  this: void,
+  /**
+   * 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.
+   */
+  url: string,
+  init: RequestInit,
+) => Promise<Response>
+
+export type FetchHandlerOptions = BuildFetchHandlerOptions | string | URL
+
+export type BuildFetchHandlerOptions = {
+  /**
+   * 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: Gettable<string | URL>
+
+  /**
+   * Headers to be added to every request. If a function is provided, it will be
+   * called on each request to get the headers. This is useful for dynamic
+   * headers, such as authentication tokens that may expire.
+   */
+  headers?: {
+    [_ in string]?: Gettable<null | string>
+  }
+
+  /**
+   * Bring your own fetch implementation. Typically useful for testing, logging,
+   * mocking, or adding retries, session management, signatures, proof of
+   * possession (DPoP), etc. Defaults to the global `fetch` function.
+   */
+  fetch?: typeof globalThis.fetch
+}
+
+export function buildFetchHandler(
+  options: FetchHandler | FetchHandlerOptions,
+): FetchHandler {
+  // Already a fetch handler (allowed for convenience)
+  if (typeof options === 'function') return options
+
+  const {
+    service,
+    headers: defaultHeaders = undefined,
+    fetch = globalThis.fetch,
+  } = typeof options === 'string' || options instanceof URL
+    ? { service: options }
+    : options
+
+  if (typeof fetch !== 'function') {
+    throw new TypeError(
+      'XrpcDispatcher requires fetch() to be available in your environment.',
+    )
+  }
+
+  const defaultHeadersEntries =
+    defaultHeaders != null ? Object.entries(defaultHeaders) : undefined
+
+  return async function (url, init) {
+    const base = typeof service === 'function' ? service() : service
+    const fullUrl = new URL(url, base)
+
+    const headers = combineHeaders(init.headers, defaultHeadersEntries)
+
+    return fetch(fullUrl, { ...init, headers })
+  }
+}

package/src/index.ts

@@ -1,6 +1,10 @@
-export * from './types'
 export * from './client'
+export * from './fetch-handler'
+export * from './types'
+export * from './util'
+export * from './xrpc-client'
 
 import { Client } from './client'
+/** @deprecated create a local {@link XrpcClient} instance instead */
 const defaultInst = new Client()
 export default defaultInst

package/src/types.ts

@@ -2,26 +2,19 @@ import { z } from 'zod'
 import { ValidationError } from '@atproto/lexicon'
 
 export type QueryParams = Record<string, any>
-export type Headers = Record<string, string>
+export type HeadersMap = Record<string, string>
+
+/** @deprecated not to be confused with the WHATWG Headers constructor */
+export type Headers = HeadersMap
+
+export type Gettable<T> = T | (() => T)
 
 export interface CallOptions {
   encoding?: string
-  headers?: Headers
-}
-
-export interface FetchHandlerResponse {
-  status: number
-  headers: Headers
-  body: ArrayBuffer | undefined
+  signal?: AbortSignal
+  headers?: HeadersMap
 }
 
-export type FetchHandler = (
-  httpUri: string,
-  httpMethod: string,
-  httpHeaders: Headers,
-  httpReqBody: any,
-) => Promise<FetchHandlerResponse>
-
 export const errorResponseBody = z.object({
   error: z.string().optional(),
   message: z.string().optional(),
@@ -45,7 +38,24 @@ export enum ResponseType {
   UpstreamTimeout = 504,
 }
 
+export function httpResponseCodeToEnum(status: number): ResponseType {
+  if (status in ResponseType) {
+    return status
+  } else if (status >= 100 && status < 200) {
+    return ResponseType.XRPCNotSupported
+  } else if (status >= 200 && status < 300) {
+    return ResponseType.Success
+  } else if (status >= 300 && status < 400) {
+    return ResponseType.XRPCNotSupported
+  } else if (status >= 400 && status < 500) {
+    return ResponseType.InvalidRequest
+  } else {
+    return ResponseType.InternalServerError
+  }
+}
+
 export const ResponseTypeNames = {
+  [ResponseType.Unknown]: 'Unknown',
   [ResponseType.InvalidResponse]: 'InvalidResponse',
   [ResponseType.Success]: 'Success',
   [ResponseType.InvalidRequest]: 'InvalidRequest',
@@ -61,7 +71,12 @@ export const ResponseTypeNames = {
   [ResponseType.UpstreamTimeout]: 'UpstreamTimeout',
 }
 
+export function httpResponseCodeToName(status: number): string {
+  return ResponseTypeNames[httpResponseCodeToEnum(status)]
+}
+
 export const ResponseTypeStrings = {
+  [ResponseType.Unknown]: 'Unknown',
   [ResponseType.InvalidResponse]: 'Invalid Response',
   [ResponseType.Success]: 'Success',
   [ResponseType.InvalidRequest]: 'Invalid Request',
@@ -77,27 +92,63 @@ export const ResponseTypeStrings = {
   [ResponseType.UpstreamTimeout]: 'Upstream Timeout',
 }
 
+export function httpResponseCodeToString(status: number): string {
+  return ResponseTypeStrings[httpResponseCodeToEnum(status)]
+}
+
 export class XRPCResponse {
   success = true
 
-  constructor(public data: any, public headers: Headers) {}
+  constructor(
+    public data: any,
+    public headers: Headers,
+  ) {}
 }
 
 export class XRPCError extends Error {
   success = false
-  headers?: Headers
+
+  public status: ResponseType
 
   constructor(
-    public status: ResponseType,
-    public error?: string,
+    statusCode: number,
+    public error: string = httpResponseCodeToName(statusCode),
     message?: string,
-    headers?: Headers,
+    public headers?: Headers,
+    options?: ErrorOptions,
   ) {
-    super(message || error || ResponseTypeStrings[status])
-    if (!this.error) {
-      this.error = ResponseTypeNames[status]
+    super(message || error || httpResponseCodeToString(statusCode), options)
+
+    this.status = httpResponseCodeToEnum(statusCode)
+
+    // Pre 2022 runtimes won't handle the "options" constructor argument
+    const cause = options?.cause
+    if (this.cause === undefined && cause !== undefined) {
+      this.cause = cause
     }
-    this.headers = headers
+  }
+
+  static from(cause: unknown, fallbackStatus?: ResponseType): XRPCError {
+    if (cause instanceof XRPCError) {
+      return cause
+    }
+
+    // Extract status code from "http-errors" like errors
+    const statusCode: unknown =
+      cause instanceof Error
+        ? ('statusCode' in cause ? cause.statusCode : undefined) ??
+          ('status' in cause ? cause.status : undefined)
+        : undefined
+
+    const status: ResponseType =
+      typeof statusCode === 'number'
+        ? httpResponseCodeToEnum(statusCode)
+        : fallbackStatus ?? ResponseType.Unknown
+
+    const error = ResponseTypeNames[status]
+    const message = cause instanceof Error ? cause.message : String(cause)
+
+    return new XRPCError(status, error, message, undefined, { cause })
   }
 }
 
@@ -111,6 +162,8 @@ export class XRPCInvalidResponseError extends XRPCError {
       ResponseType.InvalidResponse,
       ResponseTypeStrings[ResponseType.InvalidResponse],
       `The server gave an invalid response and may be out of date.`,
+      undefined,
+      { cause: validationError },
     )
   }
 }