@atproto/lex-client 0.0.20 → 0.1.0-next.0

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@atproto/lex-client",
-  "version": "0.0.20",
+  "version": "0.1.0-next.0",
+  "engines": {
+    "node": ">=22"
+  },
   "license": "MIT",
   "description": "HTTP client for interacting with Lexicon based APIs",
   "keywords": [
@@ -24,27 +27,23 @@
     "./CHANGELOG.md"
   ],
   "sideEffects": false,
-  "type": "commonjs",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "browser": "./dist/index.js",
-      "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-data": "^0.0.15",
-    "@atproto/lex-json": "^0.0.16",
-    "@atproto/lex-schema": "^0.0.19"
+    "@atproto/lex-data": "^0.1.0-next.0",
+    "@atproto/lex-schema": "^0.1.0-next.0",
+    "@atproto/lex-json": "^0.1.0-next.0"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-cbor": "^0.0.16",
-    "@atproto/lex-builder": "^0.0.22"
+    "@atproto/lex-builder": "^0.1.0-next.0",
+    "@atproto/lex-cbor": "^0.1.0-next.0"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

package/src/client.ts

@@ -63,12 +63,26 @@ export type {
 /**
  * Configuration options for creating a {@link Client}.
  *
+ * @property {@link ClientOptions.labelers} - An iterable of labeler DIDs to include in requests. These will be combined with any global app labelers configured via {@link Client.configure}.
+ * @property {@link ClientOptions.service} - An optional service identifier (DID or URL) for routing requests with service proxying.
+ * @property {@link ClientOptions.headers} - Custom headers to include in all requests made by this client instance.
+ * @property {@link ClientOptions.validateRequest} - If true, validates request bodies against their lexicon schemas before sending. Defaults to false for performance.
+ * @property {@link ClientOptions.validateResponse} - If false, skips validation of response bodies against their lexicon schemas. Defaults to true to catch errors, but can be disabled for performance if you trust the server responses. Note that defaults will not be applied if validation is disabled, which can cause typing inconsistencies, so use with caution.
+ * @property {@link ClientOptions.strictResponseProcessing} - If false, relaxes certain validation rules during response processing (e.g., allowing floats, deeper nesting, etc.). Defaults to true for strict compliance with {@link https://atproto.com/specs/data-model lexicon data model}, but can be disabled to handle non-compliant responses.
+ *
+ * @see {@link XrpcRequestHeadersOptions}
+ * @see {@link XrpcRequestProcessingOptions}
+ * @see {@link XrpcResponseOptions}
+ *
  * @example
  * ```typescript
  * const options: ClientOptions = {
  *   labelers: ['did:plc:labeler1'],
  *   service: 'did:web:api.bsky.app#bsky_appview',
- *   headers: { 'X-Custom-Header': 'value' }
+ *   headers: { 'X-Custom-Header': 'value' },
+ *   validateRequest: false,
+ *   validateResponse: true,
+ *   strictResponseProcessing: false,
  * }
  * ```
  */
@@ -223,6 +237,7 @@ export type RecordKeyOptions<
 /**
  * Type-safe options for {@link Client.create}, combining record options with key requirements.
  * @typeParam T - The record schema type
+ * @see {@link CreateRecordOptions}
  */
 export type CreateOptions<T extends RecordSchema> = CreateRecordOptions &
   RecordKeyOptions<T, 'tid' | 'any'>
@@ -321,9 +336,10 @@ export type ListRecord<Value extends LexMap> =
  * services. It provides type-safe methods for XRPC calls, record operations,
  * and blob handling.
  *
- * @example // Basic usage
+ * @example
  * ```typescript
  * import { Client } from '@atproto/lex'
+ * import { app } from '#/lexicons
  *
  * const client = new Client(oauthSession)
  *

package/src/response.ts

@@ -117,9 +117,26 @@ export type XrpcResponseOptions = {
 }
 
 /**
- * Small container for XRPC response data.
+ * Small container for XRPC response.
  *
  * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { app } from '#/lexicons'
+ * import { XrpcResponse } from '@atproto/lex-client'
+ *
+ * const fetchResponse = await fetch('https://example.com/xrpc/app.bsky.feed.getTimeline')
+ *
+ * const response = await XrpcResponse.fromFetchResponse(
+ *   app.bsky.feed.getTimeline.main,
+ *   fetchResponse,
+ * )
+ *
+ * // Fully typed (validated) response body, according to the method's output schema
+ * const { cursor, feed } = response.body
+ * ```
  */
 export class XrpcResponse<M extends Procedure | Query>
   implements ResultSuccess<XrpcResponse<M>>

package/src/types.ts

@@ -46,13 +46,17 @@ export type Service = `${DidString}#${DidServiceIdentifier}`
  * const file: BinaryBodyInit = fileInput.files[0]
  * await client.xrpc(uploadMethod, { body: file })
  * ```
+ *
+ * @note Uint8Array is parameterized with ArrayBuffer (not ArrayBufferLike)
+ * because fetch's BodyInit requires ArrayBuffer-backed views —
+ * SharedArrayBuffer is not supported for network I/O.
  */
 export type BinaryBodyInit =
-  | Uint8Array
+  | Uint8Array<ArrayBuffer>
   | ArrayBuffer
   | Blob
-  | ReadableStream<Uint8Array>
-  | AsyncIterable<Uint8Array>
+  | ReadableStream<Uint8Array<ArrayBuffer>>
+  | AsyncIterable<Uint8Array<ArrayBuffer>>
   | string
 
 export type EncodingString = `${string}/${string}`
@@ -64,7 +68,7 @@ export function isEncodingString(
 }
 
 export type XrpcUnknownResponsePayload<
-  TBinary extends BinaryBodyInit = Uint8Array,
+  TBinary extends BinaryBodyInit = Uint8Array<ArrayBuffer>,
 > = {
   encoding: EncodingString
   body: LexValue | TBinary

package/src/xrpc.ts

@@ -335,8 +335,13 @@ function xrpcProcedureInput(
       return buildPayload(input, body, encodingHint)
     case 'object': {
       if (body === null) break
-      if (
-        ArrayBuffer.isView(body) ||
+      if (ArrayBuffer.isView(body)) {
+        return buildPayload(
+          input,
+          body as Uint8Array<ArrayBuffer>,
+          encodingHint,
+        )
+      } else if (
         body instanceof ArrayBuffer ||
         body instanceof ReadableStream
       ) {