@atproto/lex-server 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @atproto/lex-server
 
+## 0.0.13
+
+### Patch Changes
+
+- Updated dependencies [[`5a2f884`](https://github.com/bluesky-social/atproto/commit/5a2f8847efd91252971fa243d21bd52ada7aa8f4), [`3dc3791`](https://github.com/bluesky-social/atproto/commit/3dc37915436dec7e18c7dc9dcf01b72cad53fdbe), [`3dc3791`](https://github.com/bluesky-social/atproto/commit/3dc37915436dec7e18c7dc9dcf01b72cad53fdbe), [`3dc3791`](https://github.com/bluesky-social/atproto/commit/3dc37915436dec7e18c7dc9dcf01b72cad53fdbe), [`3dc3791`](https://github.com/bluesky-social/atproto/commit/3dc37915436dec7e18c7dc9dcf01b72cad53fdbe), [`112b159`](https://github.com/bluesky-social/atproto/commit/112b159ec293a5c3fff41237474a3788fc47f9ca), [`3dc3791`](https://github.com/bluesky-social/atproto/commit/3dc37915436dec7e18c7dc9dcf01b72cad53fdbe), [`3dc3791`](https://github.com/bluesky-social/atproto/commit/3dc37915436dec7e18c7dc9dcf01b72cad53fdbe)]:
+  - @atproto/lex-client@0.0.16
+  - @atproto/lex-schema@0.0.15
+
+## 0.0.12
+
+### Patch Changes
+
+- [#4688](https://github.com/bluesky-social/atproto/pull/4688) [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add support for `/xrpc/_health` requests
+
+- [#4688](https://github.com/bluesky-social/atproto/pull/4688) [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Update error management to be more aligned with the way errors work in `@atproto/xrpc` and `@atproto/xrpc-server`
+
+- [#4688](https://github.com/bluesky-social/atproto/pull/4688) [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add `LexServerError` error class to encode errors destined to be returned as XRPC responses by an XRPC server
+
+- [#4688](https://github.com/bluesky-social/atproto/pull/4688) [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Allow defining a custom `fallback` handler for non XRPC HTTP calls
+
+- Updated dependencies [[`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`f7c2610`](https://github.com/bluesky-social/atproto/commit/f7c26103a6d4e24e5bedbb6fd908be140420e0dd), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7)]:
+  - @atproto/lex-schema@0.0.14
+  - @atproto/lex-data@0.0.13
+  - @atproto/lex-client@0.0.15
+  - @atproto/lex-cbor@0.0.14
+  - @atproto/lex-json@0.0.13
+
 ## 0.0.11
 
 ### Patch Changes

package/README.md

@@ -64,7 +64,7 @@ await serve(router, { port: 3000 })
   - [Custom Authentication](#custom-authentication)
   - [WWW-Authenticate Headers](#www-authenticate-headers)
 - [Error Handling](#error-handling)
-  - [LexError](#lexerror)
+  - [LexServerError](#lexservererror)
   - [LexServerAuthError](#lexserverautherror)
   - [Error Handler Callback](#error-handler-callback)
 - [Node.js Server](#nodejs-server)
@@ -100,7 +100,7 @@ lex build
 **3. Create a router and add handlers**
 
 ```typescript
-import { LexRouter, LexError } from '@atproto/lex-server'
+import { LexRouter, LexServerError } from '@atproto/lex-server'
 import { serve, upgradeWebSocket } from '@atproto/lex-server/nodejs'
 import * as app from './lexicons/app.js'
 
@@ -110,7 +110,10 @@ const router = new LexRouter({ upgradeWebSocket })
 router.add(app.bsky.actor.getProfile, async ({ params }) => {
   const profile = await db.getProfile(params.actor)
   if (!profile) {
-    throw new LexError('NotFound', 'Profile not found')
+    throw new LexServerError(404, {
+      error: 'NotFound',
+      message: 'Profile not found',
+    })
   }
   return { body: profile }
 })
@@ -134,7 +137,7 @@ const router = new LexRouter({
   // Required for WebSocket subscriptions (Node.js)
   upgradeWebSocket,
 
-  // Optional: Handle unexpected errors
+  // Optional: Add logging or error reporting for unexpected errors in handlers
   onHandlerError: ({ error, request, method }) => {
     console.error(`Error in ${method.nsid}:`, error)
   },
@@ -359,7 +362,7 @@ The auth function:
 
 1. Is called **before** parsing the request body
 2. Receives `params`, `request`, and `connection` info
-3. Should throw `LexError` or `LexServerAuthError` on failure
+3. Should throw `LexServerError` (or `LexServerAuthError`) on failure
 4. Returns credentials that are passed to the handler
 
 ### WWW-Authenticate Headers
@@ -391,19 +394,30 @@ throw new LexServerAuthError('AuthenticationRequired', 'Auth required', {
 
 ## Error Handling
 
-### LexError
+### LexServerError
 
-Throw `LexError` to return structured XRPC error responses:
+Throw `LexServerError` to return structured XRPC error responses:
 
 ```typescript
-import { LexError } from '@atproto/lex-server'
+import { LexServerError } from '@atproto/lex-server'
 
 router.add(app.bsky.actor.getProfile, async ({ params }) => {
-  const profile = await db.getProfile(params.actor)
-  if (!profile) {
-    throw new LexError('NotFound', 'Profile not found')
+  try {
+    const profile = await db.getProfile(params.actor)
+    return { body: profile }
+  } catch (cause) {
+    throw new LexServerError(
+      404,
+      {
+        error: 'NotFound',
+        message: 'Profile not found',
+      },
+      {
+        'cache-control': 'max-age=600',
+      },
+      { cause },
+    )
   }
-  return { body: profile }
 })
 ```
 
@@ -418,7 +432,7 @@ Error responses follow the XRPC format:
 
 ### LexServerAuthError
 
-`LexServerAuthError` extends `LexError` with `WWW-Authenticate` header support:
+`LexServerAuthError` extends `LexServerError` with `WWW-Authenticate` header support:
 
 ```typescript
 import { LexServerAuthError } from '@atproto/lex-server'
@@ -510,7 +524,7 @@ import { toRequestListener } from '@atproto/lex-server/nodejs'
 const app = express()
 
 // Mount the XRPC router
-app.use('/xrpc', toRequestListener(router.handle))
+app.use('/xrpc', toRequestListener(router.fetch))
 
 app.listen(3000)
 ```
@@ -530,7 +544,8 @@ const router = new LexRouter({ upgradeWebSocket })
 
 ### Custom Response Objects
 
-Return a `Response` object for full control over the response:
+Return a `Response` object for full control over the response (disables any kind
+of validation of the body):
 
 ```typescript
 router.add(schema, async ({ params }) => {
@@ -538,13 +553,15 @@ router.add(schema, async ({ params }) => {
     return Response.redirect('https://example.com', 302)
   }
 
-  return new Response(JSON.stringify({ custom: true }), {
-    status: 201,
-    headers: {
-      'Content-Type': 'application/json',
-      'X-Custom-Header': 'value',
+  return Response.json(
+    { custom: true },
+    {
+      status: 201,
+      headers: {
+        'X-Custom-Header': 'value',
+      },
     },
-  })
+  )
 })
 ```
 

package/dist/errors.d.ts

@@ -1,6 +1,21 @@
-import { LexError, LexErrorCode } from '@atproto/lex-data';
+import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data';
 import { WWWAuthenticate } from './lib/www-authenticate.js';
-export type { WWWAuthenticate };
+export { LexError };
+export type { LexErrorCode, LexErrorData, WWWAuthenticate };
+/**
+ * Base error class for representing errors that should be converted to XRPC
+ * error responses.
+ */
+export declare class LexServerError<N extends LexErrorCode = LexErrorCode> extends LexError<N> {
+    readonly status: number;
+    readonly body: LexErrorData<N>;
+    name: string;
+    readonly headers?: Headers;
+    constructor(status: number, body: LexErrorData<N>, headers?: HeadersInit, options?: ErrorOptions);
+    toJSON(): LexErrorData<N>;
+    toResponse(): Response;
+    static from(cause: unknown): LexServerError;
+}
 /**
  * Error class for authentication failures in XRPC server handlers.
  *
@@ -21,22 +36,8 @@ export type { WWWAuthenticate };
  *   { Bearer: { error: 'InvalidToken', realm: 'api.example.com' } }
  * )
  * ```
- *
- * @example Converting from a LexError
- * ```typescript
- * try {
- *   await validateToken(token)
- * } catch (error) {
- *   if (error instanceof LexError) {
- *     throw LexServerAuthError.from(error, {
- *       Bearer: { error: 'InvalidToken' }
- *     })
- *   }
- *   throw error
- * }
- * ```
  */
-export declare class LexServerAuthError<N extends LexErrorCode = LexErrorCode> extends LexError<N> {
+export declare class LexServerAuthError<N extends LexErrorCode = LexErrorCode> extends LexServerError<N> {
     readonly wwwAuthenticate: WWWAuthenticate;
     name: string;
     /**
@@ -48,42 +49,6 @@ export declare class LexServerAuthError<N extends LexErrorCode = LexErrorCode> e
      * @param options - Standard Error options including `cause`
      */
     constructor(error: N, message: string, wwwAuthenticate?: WWWAuthenticate, options?: ErrorOptions);
-    /**
-     * Gets the formatted WWW-Authenticate header value.
-     *
-     * @returns The formatted header string for the 401 response
-     *
-     * @example
-     * ```typescript
-     * const error = new LexServerAuthError('AuthenticationRequired', 'Token required', {
-     *   Bearer: { realm: 'api.example.com', error: 'MissingToken' }
-     * })
-     * console.log(error.wwwAuthenticateHeader)
-     * // Output: 'Bearer realm="api.example.com", error="MissingToken"'
-     * ```
-     */
-    get wwwAuthenticateHeader(): string;
-    /**
-     * Converts the error to a JSON representation suitable for response bodies.
-     *
-     * If the error was created from another LexError (via `from()`), returns
-     * the original error's JSON representation.
-     *
-     * @returns JSON object with error code and message
-     */
-    toJSON(): import("@atproto/lex-data").LexErrorData<any>;
-    /**
-     * Converts the error to an HTTP 401 Response with WWW-Authenticate header.
-     *
-     * The response includes:
-     * - Status code 401 (Unauthorized)
-     * - WWW-Authenticate header (if parameters were provided)
-     * - Access-Control-Expose-Headers for CORS compatibility
-     * - JSON body with error details
-     *
-     * @returns HTTP Response object ready to be sent to the client
-     */
-    toResponse(): Response;
     /**
      * Creates a LexServerAuthError from an existing LexError.
      *
@@ -96,12 +61,17 @@ export declare class LexServerAuthError<N extends LexErrorCode = LexErrorCode> e
      *
      * @example
      * ```typescript
-     * const lexError = new LexError('AuthenticationRequired', 'Token expired')
-     * const authError = LexServerAuthError.from(lexError, {
-     *   Bearer: { error: 'ExpiredToken' }
-     * })
+     * function authenticate(token: string): Promise<User> {
+     *   try {
+     *     return await validateToken(token)
+     *   } catch (cause) {
+     *     throw LexServerAuthError.from(cause, {
+     *       Bearer: { error: 'InvalidToken' }
+     *     })
+     *   }
+     * }
      * ```
      */
-    static from(cause: LexError, wwwAuthenticate?: WWWAuthenticate): LexServerAuthError;
+    static from(cause: unknown, wwwAuthenticate?: WWWAuthenticate): LexServerAuthError;
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EACL,eAAe,EAEhB,MAAM,2BAA2B,CAAA;AAElC,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,kBAAkB,CAC7B,CAAC,SAAS,YAAY,GAAG,YAAY,CACrC,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAcjB,QAAQ,CAAC,eAAe,EAAE,eAAe;IAb3C,IAAI,SAAuB;IAE3B;;;;;;;OAOG;gBAED,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,MAAM,EACN,eAAe,GAAE,eAAoB,EAC9C,OAAO,CAAC,EAAE,YAAY;IAKxB;;;;;;;;;;;;;OAaG;IACH,IAAI,qBAAqB,IAAI,MAAM,CAElC;IAED;;;;;;;OAOG;IACH,MAAM;IAKN;;;;;;;;;;OAUG;IACH,UAAU,IAAI,QAAQ;IAatB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,IAAI,CACT,KAAK,EAAE,QAAQ,EACf,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB;CAMtB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAExE,OAAO,EACL,eAAe,EAEhB,MAAM,2BAA2B,CAAA;AAElC,OAAO,EAAE,QAAQ,EAAE,CAAA;AACnB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,CAAA;AAE3D;;;GAGG;AACH,qBAAa,cAAc,CACzB,CAAC,SAAS,YAAY,GAAG,YAAY,CACrC,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAMjB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IANhC,IAAI,SAAmB;IAEvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;gBAGf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAC9B,OAAO,CAAC,EAAE,WAAW,EACrB,OAAO,CAAC,EAAE,YAAY;IAMf,MAAM,IAAI,YAAY,CAAC,CAAC,CAAC;IAI3B,UAAU,IAAI,QAAQ;IAM7B,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc;CAgC5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kBAAkB,CAC7B,CAAC,SAAS,YAAY,GAAG,YAAY,CACrC,SAAQ,cAAc,CAAC,CAAC,CAAC;IAcvB,QAAQ,CAAC,eAAe,EAAE,eAAe;IAb3C,IAAI,SAAuB;IAE3B;;;;;;;OAOG;gBAED,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,MAAM,EACN,eAAe,GAAE,eAAoB,EAC9C,OAAO,CAAC,EAAE,YAAY;IAWxB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,IAAI,CACT,KAAK,EAAE,OAAO,EACd,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB;CAqBtB"}

package/dist/errors.js

@@ -1,8 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LexServerAuthError = void 0;
+exports.LexServerAuthError = exports.LexServerError = exports.LexError = void 0;
+const lex_client_1 = require("@atproto/lex-client");
 const lex_data_1 = require("@atproto/lex-data");
+Object.defineProperty(exports, "LexError", { enumerable: true, get: function () { return lex_data_1.LexError; } });
+const lex_schema_1 = require("@atproto/lex-schema");
 const www_authenticate_js_1 = require("./lib/www-authenticate.js");
+/**
+ * Base error class for representing errors that should be converted to XRPC
+ * error responses.
+ */
+class LexServerError extends lex_data_1.LexError {
+    status;
+    body;
+    name = 'LexServerError';
+    headers;
+    constructor(status, body, headers, options) {
+        super(body.error, body.message, options);
+        this.status = status;
+        this.body = body;
+        this.headers = headers ? new Headers(headers) : undefined;
+    }
+    toJSON() {
+        return this.body;
+    }
+    toResponse() {
+        const { status, headers } = this;
+        // @NOTE using this.toJSON() instead of this.body to allow overrides in subclasses
+        return Response.json(this.toJSON(), { status, headers });
+    }
+    static from(cause) {
+        if (cause instanceof LexServerError) {
+            return cause;
+        }
+        // Convert @atproto/lex-client errors to downstream LexServerError
+        if (cause instanceof lex_client_1.XrpcError) {
+            const { status, body, headers } = cause.toDownstreamError();
+            return new LexServerError(status, body, headers, { cause });
+        }
+        // Convert @atproto/lex-schema validation errors to 400 Bad Request
+        if (cause instanceof lex_schema_1.LexValidationError) {
+            return new LexServerError(400, cause.toJSON(), undefined, {
+                cause,
+            });
+        }
+        // Any other error is treated as a generic 500 Internal Server Error
+        if (cause instanceof lex_data_1.LexError) {
+            return new LexServerError(500, cause.toJSON(), undefined, {
+                cause,
+            });
+        }
+        return new LexServerError(500, { error: 'InternalServerError', message: 'An internal error occurred' }, undefined, { cause });
+    }
+}
+exports.LexServerError = LexServerError;
 /**
  * Error class for authentication failures in XRPC server handlers.
  *
@@ -23,22 +74,8 @@ const www_authenticate_js_1 = require("./lib/www-authenticate.js");
  *   { Bearer: { error: 'InvalidToken', realm: 'api.example.com' } }
  * )
  * ```
- *
- * @example Converting from a LexError
- * ```typescript
- * try {
- *   await validateToken(token)
- * } catch (error) {
- *   if (error instanceof LexError) {
- *     throw LexServerAuthError.from(error, {
- *       Bearer: { error: 'InvalidToken' }
- *     })
- *   }
- *   throw error
- * }
- * ```
  */
-class LexServerAuthError extends lex_data_1.LexError {
+class LexServerAuthError extends LexServerError {
     wwwAuthenticate;
     name = 'LexServerAuthError';
     /**
@@ -50,58 +87,14 @@ class LexServerAuthError extends lex_data_1.LexError {
      * @param options - Standard Error options including `cause`
      */
     constructor(error, message, wwwAuthenticate = {}, options) {
-        super(error, message, options);
-        this.wwwAuthenticate = wwwAuthenticate;
-    }
-    /**
-     * Gets the formatted WWW-Authenticate header value.
-     *
-     * @returns The formatted header string for the 401 response
-     *
-     * @example
-     * ```typescript
-     * const error = new LexServerAuthError('AuthenticationRequired', 'Token required', {
-     *   Bearer: { realm: 'api.example.com', error: 'MissingToken' }
-     * })
-     * console.log(error.wwwAuthenticateHeader)
-     * // Output: 'Bearer realm="api.example.com", error="MissingToken"'
-     * ```
-     */
-    get wwwAuthenticateHeader() {
-        return (0, www_authenticate_js_1.formatWWWAuthenticateHeader)(this.wwwAuthenticate);
-    }
-    /**
-     * Converts the error to a JSON representation suitable for response bodies.
-     *
-     * If the error was created from another LexError (via `from()`), returns
-     * the original error's JSON representation.
-     *
-     * @returns JSON object with error code and message
-     */
-    toJSON() {
-        const { cause } = this;
-        return cause instanceof lex_data_1.LexError ? cause.toJSON() : super.toJSON();
-    }
-    /**
-     * Converts the error to an HTTP 401 Response with WWW-Authenticate header.
-     *
-     * The response includes:
-     * - Status code 401 (Unauthorized)
-     * - WWW-Authenticate header (if parameters were provided)
-     * - Access-Control-Expose-Headers for CORS compatibility
-     * - JSON body with error details
-     *
-     * @returns HTTP Response object ready to be sent to the client
-     */
-    toResponse() {
-        const { wwwAuthenticateHeader } = this;
-        const headers = wwwAuthenticateHeader
+        const headers = Object.keys(wwwAuthenticate).length
             ? new Headers({
-                'WWW-Authenticate': wwwAuthenticateHeader,
+                'WWW-Authenticate': (0, www_authenticate_js_1.formatWWWAuthenticateHeader)(wwwAuthenticate),
                 'Access-Control-Expose-Headers': 'WWW-Authenticate', // CORS
             })
             : undefined;
-        return Response.json(this.toJSON(), { status: 401, headers });
+        super(401, { error, message }, headers, options);
+        this.wwwAuthenticate = wwwAuthenticate;
     }
     /**
      * Creates a LexServerAuthError from an existing LexError.
@@ -115,18 +108,25 @@ class LexServerAuthError extends lex_data_1.LexError {
      *
      * @example
      * ```typescript
-     * const lexError = new LexError('AuthenticationRequired', 'Token expired')
-     * const authError = LexServerAuthError.from(lexError, {
-     *   Bearer: { error: 'ExpiredToken' }
-     * })
+     * function authenticate(token: string): Promise<User> {
+     *   try {
+     *     return await validateToken(token)
+     *   } catch (cause) {
+     *     throw LexServerAuthError.from(cause, {
+     *       Bearer: { error: 'InvalidToken' }
+     *     })
+     *   }
+     * }
      * ```
      */
     static from(cause, wwwAuthenticate) {
-        if (cause instanceof LexServerAuthError)
+        if (cause instanceof LexServerAuthError) {
             return cause;
-        return new LexServerAuthError(cause.error, cause.message, wwwAuthenticate, {
-            cause,
-        });
+        }
+        if (cause instanceof lex_data_1.LexError) {
+            return new LexServerAuthError(cause.error, cause.message, wwwAuthenticate, { cause });
+        }
+        return new LexServerAuthError('AuthenticationRequired', 'Authentication failed', wwwAuthenticate, { cause });
     }
 }
 exports.LexServerAuthError = LexServerAuthError;

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA,gDAA0D;AAC1D,mEAGkC;AAIlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAa,kBAEX,SAAQ,mBAAW;IAcR;IAbX,IAAI,GAAG,oBAAoB,CAAA;IAE3B;;;;;;;OAOG;IACH,YACE,KAAQ,EACR,OAAe,EACN,kBAAmC,EAAE,EAC9C,OAAsB;QAEtB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QAHrB,oBAAe,GAAf,eAAe,CAAsB;IAIhD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,qBAAqB;QACvB,OAAO,IAAA,iDAA2B,EAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAC1D,CAAC;IAED;;;;;;;OAOG;IACH,MAAM;QACJ,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;QACtB,OAAO,KAAK,YAAY,mBAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAA;IACpE,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU;QACR,MAAM,EAAE,qBAAqB,EAAE,GAAG,IAAI,CAAA;QAEtC,MAAM,OAAO,GAAG,qBAAqB;YACnC,CAAC,CAAC,IAAI,OAAO,CAAC;gBACV,kBAAkB,EAAE,qBAAqB;gBACzC,+BAA+B,EAAE,kBAAkB,EAAE,OAAO;aAC7D,CAAC;YACJ,CAAC,CAAC,SAAS,CAAA;QAEb,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,IAAI,CACT,KAAe,EACf,eAAiC;QAEjC,IAAI,KAAK,YAAY,kBAAkB;YAAE,OAAO,KAAK,CAAA;QACrD,OAAO,IAAI,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE;YACzE,KAAK;SACN,CAAC,CAAA;IACJ,CAAC;CACF;AAxGD,gDAwGC","sourcesContent":["import { LexError, LexErrorCode } from '@atproto/lex-data'\nimport {\n  WWWAuthenticate,\n  formatWWWAuthenticateHeader,\n} from './lib/www-authenticate.js'\n\nexport type { WWWAuthenticate }\n\n/**\n * Error class for authentication failures in XRPC server handlers.\n *\n * Extends {@link LexError} to include WWW-Authenticate header support,\n * which is required by HTTP authentication standards (RFC 7235).\n * The error automatically generates the appropriate 401 response with\n * the WWW-Authenticate header when converted to a Response.\n *\n * @typeParam N - The Lexicon error code type\n *\n * @example Throwing an auth error\n * ```typescript\n * import { LexServerAuthError } from '@atproto/lex-server'\n *\n * throw new LexServerAuthError(\n *   'AuthenticationRequired',\n *   'Invalid or expired token',\n *   { Bearer: { error: 'InvalidToken', realm: 'api.example.com' } }\n * )\n * ```\n *\n * @example Converting from a LexError\n * ```typescript\n * try {\n *   await validateToken(token)\n * } catch (error) {\n *   if (error instanceof LexError) {\n *     throw LexServerAuthError.from(error, {\n *       Bearer: { error: 'InvalidToken' }\n *     })\n *   }\n *   throw error\n * }\n * ```\n */\nexport class LexServerAuthError<\n  N extends LexErrorCode = LexErrorCode,\n> extends LexError<N> {\n  name = 'LexServerAuthError'\n\n  /**\n   * Creates a new authentication error.\n   *\n   * @param error - The Lexicon error code (e.g., 'AuthenticationRequired')\n   * @param message - Human-readable error message\n   * @param wwwAuthenticate - WWW-Authenticate header parameters\n   * @param options - Standard Error options including `cause`\n   */\n  constructor(\n    error: N,\n    message: string,\n    readonly wwwAuthenticate: WWWAuthenticate = {},\n    options?: ErrorOptions,\n  ) {\n    super(error, message, options)\n  }\n\n  /**\n   * Gets the formatted WWW-Authenticate header value.\n   *\n   * @returns The formatted header string for the 401 response\n   *\n   * @example\n   * ```typescript\n   * const error = new LexServerAuthError('AuthenticationRequired', 'Token required', {\n   *   Bearer: { realm: 'api.example.com', error: 'MissingToken' }\n   * })\n   * console.log(error.wwwAuthenticateHeader)\n   * // Output: 'Bearer realm=\"api.example.com\", error=\"MissingToken\"'\n   * ```\n   */\n  get wwwAuthenticateHeader(): string {\n    return formatWWWAuthenticateHeader(this.wwwAuthenticate)\n  }\n\n  /**\n   * Converts the error to a JSON representation suitable for response bodies.\n   *\n   * If the error was created from another LexError (via `from()`), returns\n   * the original error's JSON representation.\n   *\n   * @returns JSON object with error code and message\n   */\n  toJSON() {\n    const { cause } = this\n    return cause instanceof LexError ? cause.toJSON() : super.toJSON()\n  }\n\n  /**\n   * Converts the error to an HTTP 401 Response with WWW-Authenticate header.\n   *\n   * The response includes:\n   * - Status code 401 (Unauthorized)\n   * - WWW-Authenticate header (if parameters were provided)\n   * - Access-Control-Expose-Headers for CORS compatibility\n   * - JSON body with error details\n   *\n   * @returns HTTP Response object ready to be sent to the client\n   */\n  toResponse(): Response {\n    const { wwwAuthenticateHeader } = this\n\n    const headers = wwwAuthenticateHeader\n      ? new Headers({\n          'WWW-Authenticate': wwwAuthenticateHeader,\n          'Access-Control-Expose-Headers': 'WWW-Authenticate', // CORS\n        })\n      : undefined\n\n    return Response.json(this.toJSON(), { status: 401, headers })\n  }\n\n  /**\n   * Creates a LexServerAuthError from an existing LexError.\n   *\n   * If the input is already a LexServerAuthError, returns it unchanged.\n   * Otherwise, wraps the error with the provided WWW-Authenticate parameters.\n   *\n   * @param cause - The original LexError to wrap\n   * @param wwwAuthenticate - WWW-Authenticate header parameters\n   * @returns A LexServerAuthError instance\n   *\n   * @example\n   * ```typescript\n   * const lexError = new LexError('AuthenticationRequired', 'Token expired')\n   * const authError = LexServerAuthError.from(lexError, {\n   *   Bearer: { error: 'ExpiredToken' }\n   * })\n   * ```\n   */\n  static from(\n    cause: LexError,\n    wwwAuthenticate?: WWWAuthenticate,\n  ): LexServerAuthError {\n    if (cause instanceof LexServerAuthError) return cause\n    return new LexServerAuthError(cause.error, cause.message, wwwAuthenticate, {\n      cause,\n    })\n  }\n}\n"]}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import { XrpcError } from '@atproto/lex-client'\nimport { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'\nimport { LexValidationError } from '@atproto/lex-schema'\nimport {\n  WWWAuthenticate,\n  formatWWWAuthenticateHeader,\n} from './lib/www-authenticate.js'\n\nexport { LexError }\nexport type { LexErrorCode, LexErrorData, WWWAuthenticate }\n\n/**\n * Base error class for representing errors that should be converted to XRPC\n * error responses.\n */\nexport class LexServerError<\n  N extends LexErrorCode = LexErrorCode,\n> extends LexError<N> {\n  name = 'LexServerError'\n\n  readonly headers?: Headers\n\n  constructor(\n    readonly status: number,\n    readonly body: LexErrorData<N>,\n    headers?: HeadersInit,\n    options?: ErrorOptions,\n  ) {\n    super(body.error, body.message, options)\n    this.headers = headers ? new Headers(headers) : undefined\n  }\n\n  override toJSON(): LexErrorData<N> {\n    return this.body\n  }\n\n  public toResponse(): Response {\n    const { status, headers } = this\n    // @NOTE using this.toJSON() instead of this.body to allow overrides in subclasses\n    return Response.json(this.toJSON(), { status, headers })\n  }\n\n  static from(cause: unknown): LexServerError {\n    if (cause instanceof LexServerError) {\n      return cause\n    }\n\n    // Convert @atproto/lex-client errors to downstream LexServerError\n    if (cause instanceof XrpcError) {\n      const { status, body, headers } = cause.toDownstreamError()\n      return new LexServerError(status, body, headers, { cause })\n    }\n\n    // Convert @atproto/lex-schema validation errors to 400 Bad Request\n    if (cause instanceof LexValidationError) {\n      return new LexServerError(400, cause.toJSON(), undefined, {\n        cause,\n      })\n    }\n\n    // Any other error is treated as a generic 500 Internal Server Error\n    if (cause instanceof LexError) {\n      return new LexServerError(500, cause.toJSON(), undefined, {\n        cause,\n      })\n    }\n\n    return new LexServerError(\n      500,\n      { error: 'InternalServerError', message: 'An internal error occurred' },\n      undefined,\n      { cause },\n    )\n  }\n}\n\n/**\n * Error class for authentication failures in XRPC server handlers.\n *\n * Extends {@link LexError} to include WWW-Authenticate header support,\n * which is required by HTTP authentication standards (RFC 7235).\n * The error automatically generates the appropriate 401 response with\n * the WWW-Authenticate header when converted to a Response.\n *\n * @typeParam N - The Lexicon error code type\n *\n * @example Throwing an auth error\n * ```typescript\n * import { LexServerAuthError } from '@atproto/lex-server'\n *\n * throw new LexServerAuthError(\n *   'AuthenticationRequired',\n *   'Invalid or expired token',\n *   { Bearer: { error: 'InvalidToken', realm: 'api.example.com' } }\n * )\n * ```\n */\nexport class LexServerAuthError<\n  N extends LexErrorCode = LexErrorCode,\n> extends LexServerError<N> {\n  name = 'LexServerAuthError'\n\n  /**\n   * Creates a new authentication error.\n   *\n   * @param error - The Lexicon error code (e.g., 'AuthenticationRequired')\n   * @param message - Human-readable error message\n   * @param wwwAuthenticate - WWW-Authenticate header parameters\n   * @param options - Standard Error options including `cause`\n   */\n  constructor(\n    error: N,\n    message: string,\n    readonly wwwAuthenticate: WWWAuthenticate = {},\n    options?: ErrorOptions,\n  ) {\n    const headers = Object.keys(wwwAuthenticate).length\n      ? new Headers({\n          'WWW-Authenticate': formatWWWAuthenticateHeader(wwwAuthenticate),\n          'Access-Control-Expose-Headers': 'WWW-Authenticate', // CORS\n        })\n      : undefined\n    super(401, { error, message }, headers, options)\n  }\n\n  /**\n   * Creates a LexServerAuthError from an existing LexError.\n   *\n   * If the input is already a LexServerAuthError, returns it unchanged.\n   * Otherwise, wraps the error with the provided WWW-Authenticate parameters.\n   *\n   * @param cause - The original LexError to wrap\n   * @param wwwAuthenticate - WWW-Authenticate header parameters\n   * @returns A LexServerAuthError instance\n   *\n   * @example\n   * ```typescript\n   * function authenticate(token: string): Promise<User> {\n   *   try {\n   *     return await validateToken(token)\n   *   } catch (cause) {\n   *     throw LexServerAuthError.from(cause, {\n   *       Bearer: { error: 'InvalidToken' }\n   *     })\n   *   }\n   * }\n   * ```\n   */\n  static from(\n    cause: unknown,\n    wwwAuthenticate?: WWWAuthenticate,\n  ): LexServerAuthError {\n    if (cause instanceof LexServerAuthError) {\n      return cause\n    }\n\n    if (cause instanceof LexError) {\n      return new LexServerAuthError(\n        cause.error,\n        cause.message,\n        wwwAuthenticate,\n        { cause },\n      )\n    }\n\n    return new LexServerAuthError(\n      'AuthenticationRequired',\n      'Authentication failed',\n      wwwAuthenticate,\n      { cause },\n    )\n  }\n}\n"]}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { LexError, type LexErrorCode, type LexErrorData, } from '@atproto/lex-data';
 export * from './errors.js';
-export * from './lex-server.js';
+export * from './lex-router.js';
 export * from './service-auth.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAA;AAE1B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA"}

package/dist/index.js

@@ -1,10 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LexError = void 0;
 const tslib_1 = require("tslib");
-var lex_data_1 = require("@atproto/lex-data");
-Object.defineProperty(exports, "LexError", { enumerable: true, get: function () { return lex_data_1.LexError; } });
 tslib_1.__exportStar(require("./errors.js"), exports);
-tslib_1.__exportStar(require("./lex-server.js"), exports);
+tslib_1.__exportStar(require("./lex-router.js"), exports);
 tslib_1.__exportStar(require("./service-auth.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;AAAA,8CAI0B;AAHxB,oGAAA,QAAQ,OAAA;AAKV,sDAA2B;AAC3B,0DAA+B;AAC/B,4DAAiC","sourcesContent":["export {\n  LexError,\n  type LexErrorCode,\n  type LexErrorData,\n} from '@atproto/lex-data'\n\nexport * from './errors.js'\nexport * from './lex-server.js'\nexport * from './service-auth.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,sDAA2B;AAC3B,0DAA+B;AAC/B,4DAAiC","sourcesContent":["export * from './errors.js'\nexport * from './lex-router.js'\nexport * from './service-auth.js'\n"]}