@atproto/lex-client 0.0.4 → 0.0.6

package/src/client.ts

@@ -1,14 +1,15 @@
-import { LexMap, LexValue } from '@atproto/lex-data'
+import { LexError, LexMap, LexValue } from '@atproto/lex-data'
 import {
   AtIdentifierString,
+  CidString,
   DidString,
   Infer,
-  InferProcedureInputBody,
-  InferProcedureOutputBody,
-  InferQueryOutputBody,
-  InferQueryParameters,
+  InferMethodInputBody,
+  InferMethodOutputBody,
+  InferMethodParams,
   InferRecordKey,
   LexiconRecordKey,
+  Main,
   NsidString,
   Params,
   Procedure,
@@ -16,18 +17,34 @@ import {
   RecordSchema,
   Restricted,
   Schema,
+  getMain,
 } from '@atproto/lex-schema'
 import { Agent, AgentOptions, buildAgent } from './agent.js'
-import {
-  KnownError,
-  XrpcError,
-  XrpcRequestFailure,
-  asXrpcRequestFailureFor,
-} from './error.js'
-import * as com from './lexicons/com.js'
-import { XrpcResponse, XrpcResponseBody } from './response.js'
-import { CallOptions, Namespace, Service, getMain } from './types.js'
-import { XrpcOptions, xrpc, xrpcRequestHeaders } from './xrpc.js'
+import { com } from './lexicons.js'
+import { LexRpcResponse, LexRpcResponseBody } from './response.js'
+import { BinaryBodyInit, CallOptions, Service } from './types.js'
+import { buildAtprotoHeaders } from './util.js'
+import { LexRpcFailure, LexRpcOptions, xrpc, xrpcSafe } from './xrpc.js'
+
+export type {
+  AtIdentifierString,
+  CidString,
+  DidString,
+  InferMethodInputBody,
+  InferMethodOutputBody,
+  InferMethodParams,
+  InferRecordKey,
+  LexMap,
+  LexValue,
+  LexiconRecordKey,
+  NsidString,
+  Params,
+  Procedure,
+  Query,
+  RecordSchema,
+  Restricted,
+  Schema,
+}
 
 export type ClientOptions = {
   labelers?: Iterable<DidString>
@@ -84,29 +101,35 @@ export type RecordKeyOptions<
 
 export type CreateOptions<T extends RecordSchema> = CreateRecordOptions &
   RecordKeyOptions<T, 'tid'>
-export type CreateOutput = XrpcResponseBody<
-  typeof com.atproto.repo.createRecord.main
+export type CreateOutput = InferMethodOutputBody<
+  typeof com.atproto.repo.createRecord.main,
+  Uint8Array
 >
 
 export type DeleteOptions<T extends RecordSchema> = DeleteRecordOptions &
   RecordKeyOptions<T>
-export type DeleteOutput = XrpcResponseBody<
-  typeof com.atproto.repo.deleteRecord.main
+export type DeleteOutput = InferMethodOutputBody<
+  typeof com.atproto.repo.deleteRecord.main,
+  Uint8Array
 >
 export type GetOptions<T extends RecordSchema> = GetRecordOptions &
   RecordKeyOptions<T>
 export type GetOutput<T extends RecordSchema> = Omit<
-  XrpcResponseBody<typeof com.atproto.repo.getRecord.main>,
+  InferMethodOutputBody<typeof com.atproto.repo.getRecord.main, Uint8Array>,
   'value'
 > & { value: Infer<T> }
 
 export type PutOptions<T extends RecordSchema> = PutRecordOptions &
   RecordKeyOptions<T>
-export type PutOutput = XrpcResponseBody<typeof com.atproto.repo.putRecord.main>
+export type PutOutput = InferMethodOutputBody<
+  typeof com.atproto.repo.putRecord.main,
+  Uint8Array
+>
 
 export type ListOptions = ListRecordsOptions
-export type ListOutput<T extends RecordSchema> = XrpcResponseBody<
-  typeof com.atproto.repo.listRecords.main
+export type ListOutput<T extends RecordSchema> = InferMethodOutputBody<
+  typeof com.atproto.repo.listRecords.main,
+  Uint8Array
 > & {
   records: ListRecord<T>[]
   // @NOTE Because the schema uses "type": "unknown" instead of an open union,
@@ -134,10 +157,7 @@ export class Client implements Agent {
   public readonly labelers: Set<DidString>
 
   constructor(agent: Agent | AgentOptions, options: ClientOptions = {}) {
-    this.agent =
-      typeof agent === 'object' && 'fetchHandler' in agent
-        ? agent
-        : buildAgent(agent)
+    this.agent = buildAgent(agent)
     this.service = options.service
     this.labelers = new Set(options.labelers)
     this.headers = new Headers(options.headers)
@@ -153,7 +173,7 @@ export class Client implements Agent {
   }
 
   public assertAuthenticated(): asserts this is { did: DidString } {
-    if (!this.did) throw new XrpcError(KnownError.AuthenticationRequired)
+    if (!this.did) throw new LexError('AuthenticationRequired')
   }
 
   public setLabelers(labelers: Iterable<DidString> = []) {
@@ -170,7 +190,7 @@ export class Client implements Agent {
   }
 
   public fetchHandler(path: string, init: RequestInit): Promise<Response> {
-    const headers = xrpcRequestHeaders({
+    const headers = buildAtprotoHeaders({
       headers: init.headers,
       service: this.service,
       labelers: [
@@ -186,40 +206,43 @@ export class Client implements Agent {
       if (!headers.has(key)) headers.set(key, value)
     }
 
+    // @NOTE The agent here could be another Client instance.
     return this.agent.fetchHandler(path, { ...init, headers })
   }
 
+  /**
+   * @throws {LexRpcFailure<M>} when the request fails or the response is an error
+   */
   async xrpc<const M extends Query | Procedure>(
-    ns: NonNullable<unknown> extends XrpcOptions<M>
-      ? Namespace<M>
+    ns: NonNullable<unknown> extends LexRpcOptions<M>
+      ? Main<M>
       : Restricted<'This XRPC method requires an "options" argument'>,
-  ): Promise<XrpcResponse<M>>
+  ): Promise<LexRpcResponse<M>>
   async xrpc<const M extends Query | Procedure>(
-    ns: Namespace<M>,
-    options: XrpcOptions<M>,
-  ): Promise<XrpcResponse<M>>
+    ns: Main<M>,
+    options: LexRpcOptions<M>,
+  ): Promise<LexRpcResponse<M>>
   async xrpc<const M extends Query | Procedure>(
-    ns: Namespace<M>,
-    options: XrpcOptions<M> = {} as XrpcOptions<M>,
-  ): Promise<XrpcResponse<M>> {
+    ns: Main<M>,
+    options: LexRpcOptions<M> = {} as LexRpcOptions<M>,
+  ): Promise<LexRpcResponse<M>> {
     return xrpc(this, ns, options)
   }
 
   async xrpcSafe<const M extends Query | Procedure>(
-    ns: NonNullable<unknown> extends XrpcOptions<M>
-      ? Namespace<M>
+    ns: NonNullable<unknown> extends LexRpcOptions<M>
+      ? Main<M>
       : Restricted<'This XRPC method requires an "options" argument'>,
-  ): Promise<XrpcResponse<M> | XrpcRequestFailure<M>>
+  ): Promise<LexRpcResponse<M> | LexRpcFailure<M>>
   async xrpcSafe<const M extends Query | Procedure>(
-    ns: Namespace<M>,
-    options: XrpcOptions<M>,
-  ): Promise<XrpcResponse<M> | XrpcRequestFailure<M>>
+    ns: Main<M>,
+    options: LexRpcOptions<M>,
+  ): Promise<LexRpcResponse<M> | LexRpcFailure<M>>
   async xrpcSafe<const M extends Query | Procedure>(
-    ns: Namespace<M>,
-    options: XrpcOptions<M> = {} as XrpcOptions<M>,
-  ): Promise<unknown> {
-    const schema = getMain(ns)
-    return this.xrpc(schema, options).catch(asXrpcRequestFailureFor(schema))
+    ns: Main<M>,
+    options: LexRpcOptions<M> = {} as LexRpcOptions<M>,
+  ): Promise<LexRpcResponse<M> | LexRpcFailure<M>> {
+    return xrpcSafe(this, ns, options)
   }
 
   /**
@@ -243,12 +266,6 @@ export class Client implements Agent {
     })
   }
 
-  async createRecordsSafe(...args: Parameters<Client['createRecord']>) {
-    return this.createRecord(...args).catch(
-      asXrpcRequestFailureFor(com.atproto.repo.createRecord.main),
-    )
-  }
-
   async deleteRecord(
     collection: NsidString,
     rkey: string,
@@ -266,12 +283,6 @@ export class Client implements Agent {
     })
   }
 
-  async deleteRecordsSafe(...args: Parameters<Client['deleteRecord']>) {
-    return this.deleteRecord(...args).catch(
-      asXrpcRequestFailureFor(com.atproto.repo.deleteRecord.main),
-    )
-  }
-
   public async getRecord(
     collection: NsidString,
     rkey: string,
@@ -287,12 +298,6 @@ export class Client implements Agent {
     })
   }
 
-  async getRecordsSafe(...args: Parameters<Client['getRecord']>) {
-    return this.getRecord(...args).catch(
-      asXrpcRequestFailureFor(com.atproto.repo.getRecord.main),
-    )
-  }
-
   async putRecord(
     record: { $type: NsidString } & LexMap,
     rkey: string,
@@ -312,12 +317,6 @@ export class Client implements Agent {
     })
   }
 
-  async putRecordsSafe(...args: Parameters<Client['putRecord']>) {
-    return this.putRecord(...args).catch(
-      asXrpcRequestFailureFor(com.atproto.repo.putRecord.main),
-    )
-  }
-
   async listRecords(nsid: NsidString, options?: ListRecordsOptions) {
     return this.xrpc(com.atproto.repo.listRecords.main, {
       ...options,
@@ -331,30 +330,54 @@ export class Client implements Agent {
     })
   }
 
-  public async call<const T extends Action>(
-    ns: Namespace<T>,
-    input: InferActionInput<T>,
-    options?: CallOptions,
-  ): Promise<InferActionOutput<T>>
-  public async call<const T extends Procedure>(
-    ns: Namespace<T>,
-    body: InferProcedureInputBody<T>,
-    options?: CallOptions,
-  ): Promise<InferProcedureOutputBody<T>>
+  async uploadBlob(
+    body: BinaryBodyInit,
+    options?: CallOptions & { encoding?: `${string}/${string}` },
+  ) {
+    return this.xrpc(com.atproto.repo.uploadBlob.main, {
+      ...options,
+      body,
+    })
+  }
+
+  async getBlob(did: DidString, cid: CidString, options?: CallOptions) {
+    return this.xrpc(com.atproto.sync.getBlob.main, {
+      ...options,
+      params: { did, cid },
+    })
+  }
+
   public async call<const T extends Query>(
-    ns: NonNullable<unknown> extends InferQueryParameters<T>
-      ? Namespace<T>
+    ns: NonNullable<unknown> extends InferMethodParams<T>
+      ? Main<T>
       : Restricted<'This query type requires a "params" argument'>,
-  ): Promise<InferQueryOutputBody<T>>
-  public async call<const T extends Query>(
-    ns: Namespace<T>,
-    params: NonNullable<unknown> extends InferQueryParameters<T>
-      ? InferQueryParameters<T> | undefined
-      : InferQueryParameters<T>,
+  ): Promise<LexRpcResponseBody<T>>
+  public async call<const T extends Action>(
+    ns: void extends InferActionInput<T>
+      ? Main<T>
+      : Restricted<'This action type requires an "input" argument'>,
+  ): Promise<InferActionOutput<T>>
+  public async call<const T extends Action | Procedure | Query>(
+    ns: Main<T>,
+    arg: T extends Action
+      ? InferActionInput<T>
+      : T extends Procedure
+        ? InferMethodInputBody<T, Uint8Array>
+        : T extends Query
+          ? InferMethodParams<T>
+          : never,
     options?: CallOptions,
-  ): Promise<InferQueryOutputBody<T>>
+  ): Promise<
+    T extends Action
+      ? InferActionOutput<T>
+      : T extends Procedure
+        ? LexRpcResponseBody<T>
+        : T extends Query
+          ? LexRpcResponseBody<T>
+          : never
+  >
   public async call(
-    ns: Namespace<Action> | Namespace<Procedure> | Namespace<Query>,
+    ns: Main<Action> | Main<Procedure> | Main<Query>,
     arg?: LexValue | Params,
     options: CallOptions = {},
   ): Promise<unknown> {
@@ -365,12 +388,10 @@ export class Client implements Agent {
     }
 
     if (method instanceof Procedure) {
-      const body = arg as LexValue | undefined
-      const result = await this.xrpc(method, { ...options, body })
+      const result = await this.xrpc(method, { ...options, body: arg as any })
       return result.body
     } else if (method instanceof Query) {
-      const params = arg as Params | undefined
-      const result = await this.xrpc(method, { ...options, params })
+      const result = await this.xrpc(method, { ...options, params: arg as any })
       return result.body
     } else {
       throw new TypeError('Invalid lexicon')
@@ -379,24 +400,23 @@ export class Client implements Agent {
 
   public async create<const T extends RecordSchema>(
     ns: NonNullable<unknown> extends CreateOptions<T>
-      ? Namespace<T>
+      ? Main<T>
       : Restricted<'This record type requires an "options" argument'>,
     input: Omit<Infer<T>, '$type'>,
   ): Promise<CreateOutput>
   public async create<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     input: Omit<Infer<T>, '$type'>,
     options: CreateOptions<T>,
   ): Promise<CreateOutput>
   public async create<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     input: Omit<Infer<T>, '$type'>,
     options: CreateOptions<T> = {} as CreateOptions<T>,
   ): Promise<CreateOutput> {
     const schema: T = getMain(ns)
-    const record = options.validate
-      ? schema.parse(schema.build(input))
-      : schema.build(input)
+    const record = schema.build(input)
+    if (options.validateRequest) schema.assert(record)
     const rkey = options.rkey ?? getDefaultRecordKey(schema)
     if (rkey !== undefined) schema.keySchema.assert(rkey)
     const response = await this.createRecord(record, rkey, options)
@@ -405,15 +425,15 @@ export class Client implements Agent {
 
   public async delete<const T extends RecordSchema>(
     ns: NonNullable<unknown> extends DeleteOptions<T>
-      ? Namespace<T>
+      ? Main<T>
       : Restricted<'This record type requires an "options" argument'>,
   ): Promise<DeleteOutput>
   public async delete<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     options?: DeleteOptions<T>,
   ): Promise<DeleteOutput>
   public async delete<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     options: DeleteOptions<T> = {} as DeleteOptions<T>,
   ): Promise<DeleteOutput> {
     const schema = getMain(ns)
@@ -426,15 +446,15 @@ export class Client implements Agent {
 
   public async get<const T extends RecordSchema>(
     ns: T['key'] extends `literal:${string}`
-      ? Namespace<T>
+      ? Main<T>
       : Restricted<'This record type requires an "options" argument'>,
   ): Promise<GetOutput<T>>
   public async get<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     options?: GetOptions<T>,
   ): Promise<GetOutput<T>>
   public async get<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     options: GetOptions<T> = {} as GetOptions<T>,
   ): Promise<GetOutput<T>> {
     const schema = getMain(ns)
@@ -448,29 +468,30 @@ export class Client implements Agent {
 
   public async put<const T extends RecordSchema>(
     ns: NonNullable<unknown> extends PutOptions<T>
-      ? Namespace<T>
+      ? Main<T>
       : Restricted<'This record type requires an "options" argument'>,
     input: Omit<Infer<T>, '$type'>,
   ): Promise<PutOutput>
   public async put<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     input: Omit<Infer<T>, '$type'>,
     options: PutOptions<T>,
   ): Promise<PutOutput>
   public async put<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     input: Omit<Infer<T>, '$type'>,
     options: PutOptions<T> = {} as PutOptions<T>,
   ): Promise<PutOutput> {
-    const schema = getMain(ns)
+    const schema: T = getMain(ns)
     const record = schema.build(input)
+    if (options.validateRequest) schema.assert(record)
     const rkey = options.rkey ?? getLiteralRecordKey(schema)
     const response = await this.putRecord(record, rkey, options)
     return response.body
   }
 
   async list<const T extends RecordSchema>(
-    ns: Namespace<T>,
+    ns: Main<T>,
     options?: ListOptions,
   ): Promise<ListOutput<T>> {
     const schema = getMain(ns)

package/src/errors.ts

@@ -0,0 +1,206 @@
+import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'
+import { l } from '@atproto/lex-schema'
+import { Payload } from './util.js'
+
+export type LexRpcErrorPayload<N extends LexErrorCode = LexErrorCode> = Payload<
+  LexErrorData<N>,
+  'application/json'
+>
+
+export class LexRpcError<
+  N extends LexErrorCode = LexErrorCode,
+> extends LexError<N> {
+  name = 'LexRpcError'
+
+  constructor(
+    error: N,
+    message: string = `${error} Lexicon RPC error`,
+    options?: ErrorOptions,
+  ) {
+    super(error, message, options)
+  }
+}
+
+/**
+ * All unsuccessful responses should follow a standard error response
+ * schema. The Content-Type should be application/json, and the payload
+ * should be a JSON object with the following fields:
+ *
+ * - `error` (string, required): type name of the error (generic ASCII
+ *   constant, no whitespace)
+ * - `message` (string, optional): description of the error, appropriate for
+ *   display to humans
+ *
+ * This function checks whether a given payload matches this schema.
+ */
+export function isLexRpcErrorPayload(
+  payload: Payload | null,
+): payload is LexRpcErrorPayload {
+  return (
+    payload !== null &&
+    payload.encoding === 'application/json' &&
+    l.lexErrorData.matches(payload.body)
+  )
+}
+
+/**
+ * Interface representing a failed XRPC request result.
+ */
+type LexRpcFailureResult<N extends LexErrorCode, E> = l.ResultFailure<E> & {
+  readonly error: N
+  shouldRetry(): boolean
+  matchesSchema(): boolean
+}
+
+/**
+ * Class used to represent an HTTP request that resulted in an XRPC method error
+ * That is, a non-2xx response with a valid XRPC error payload.
+ */
+export class LexRpcResponseError<
+    M extends l.Procedure | l.Query = l.Procedure | l.Query,
+    N extends LexErrorCode = LexErrorCode,
+  >
+  extends LexRpcError<N>
+  implements LexRpcFailureResult<N, LexRpcResponseError<M, N>>
+{
+  name = 'LexRpcResponseError'
+
+  constructor(
+    readonly method: M,
+    readonly status: number,
+    readonly headers: Headers,
+    readonly payload: LexRpcErrorPayload<N>,
+    options?: ErrorOptions,
+  ) {
+    const { error, message } = payload.body
+    super(error, message, options)
+  }
+
+  readonly success = false
+
+  get reason(): this {
+    return this as this
+  }
+
+  get body(): LexErrorData {
+    return this.payload.body
+  }
+
+  matchesSchema(): this is M extends {
+    errors: readonly (infer E extends string)[]
+  }
+    ? LexRpcResponseError<M, E>
+    : never {
+    return this.method.errors?.includes(this.error) ?? false
+  }
+
+  shouldRetry(): boolean {
+    // Do not retry client errors
+    if (this.status < 500) return false
+
+    return true
+  }
+
+  toJSON() {
+    return this.payload.body
+  }
+
+  toResponse(): Response {
+    const { status, headers } = this
+    return Response.json(this.toJSON(), { status, headers })
+  }
+}
+
+/**
+ * This class represents an invalid XRPC response from the server.
+ */
+export class LexRpcUpstreamError<
+    N extends 'InvalidResponse' | 'UpstreamFailure' =
+      | 'InvalidResponse'
+      | 'UpstreamFailure',
+  >
+  extends LexRpcError<N>
+  implements LexRpcFailureResult<N, LexRpcUpstreamError<N>>
+{
+  name = 'LexRpcUpstreamError' as const
+
+  // For debugging purposes, we keep the response details here
+  readonly response: {
+    status: number
+    headers: Headers
+    payload: Payload | null
+  }
+
+  constructor(
+    error: N,
+    message: string,
+    response: { status: number; headers: Headers },
+    payload: Payload | null,
+    options?: ErrorOptions,
+  ) {
+    super(error, message, { cause: options?.cause })
+    this.response = {
+      status: response.status,
+      headers: response.headers,
+      payload,
+    }
+  }
+
+  readonly success = false as const
+
+  get reason(): this {
+    return this
+  }
+
+  matchesSchema(): false {
+    return false
+  }
+
+  shouldRetry(): boolean {
+    // Do not retry client errors
+    return this.response.status >= 500
+  }
+
+  toResponse(): Response {
+    return Response.json(this.toJSON(), { status: 502 })
+  }
+}
+
+export class LexRpcUnexpectedError
+  extends LexRpcError<'InternalServerError'>
+  implements LexRpcFailureResult<'InternalServerError', unknown>
+{
+  name = 'LexRpcUnexpectedError' as const
+
+  protected constructor(message: string, options: Required<ErrorOptions>) {
+    super('InternalServerError', message, options)
+  }
+
+  readonly success = false
+
+  get reason() {
+    return this.cause
+  }
+
+  matchesSchema(): false {
+    return false
+  }
+
+  shouldRetry(): boolean {
+    return true
+  }
+
+  toResponse(): Response {
+    return Response.json(this.toJSON(), { status: 500 })
+  }
+
+  static from(
+    cause: unknown,
+    message: string = cause instanceof LexError
+      ? cause.message
+      : 'XRPC request failed',
+  ): LexRpcUnexpectedError {
+    if (cause instanceof LexRpcUnexpectedError) return cause
+    return new LexRpcUnexpectedError(message, { cause })
+  }
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from './agent.js'
 export * from './client.js'
-export * from './error.js'
+export * from './errors.js'
 export * from './response.js'
 export * from './types.js'
 export * from './xrpc.js'