@atproto/lex-server 0.0.7 → 0.0.9

package/src/errors.ts

@@ -6,11 +6,54 @@ import {
 
 export type { WWWAuthenticate }
 
+/**
+ * Error class for authentication failures in XRPC server handlers.
+ *
+ * Extends {@link LexError} to include WWW-Authenticate header support,
+ * which is required by HTTP authentication standards (RFC 7235).
+ * The error automatically generates the appropriate 401 response with
+ * the WWW-Authenticate header when converted to a Response.
+ *
+ * @typeParam N - The Lexicon error code type
+ *
+ * @example Throwing an auth error
+ * ```typescript
+ * import { LexServerAuthError } from '@atproto/lex-server'
+ *
+ * throw new LexServerAuthError(
+ *   'AuthenticationRequired',
+ *   'Invalid or expired token',
+ *   { 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 class LexServerAuthError<
   N extends LexErrorCode = LexErrorCode,
 > extends LexError<N> {
   name = 'LexServerAuthError'
 
+  /**
+   * Creates a new authentication error.
+   *
+   * @param error - The Lexicon error code (e.g., 'AuthenticationRequired')
+   * @param message - Human-readable error message
+   * @param wwwAuthenticate - WWW-Authenticate header parameters
+   * @param options - Standard Error options including `cause`
+   */
   constructor(
     error: N,
     message: string,
@@ -20,15 +63,48 @@ export class LexServerAuthError<
     super(error, message, options)
   }
 
+  /**
+   * 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 {
     return 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 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(): Response {
     const { wwwAuthenticateHeader } = this
 
@@ -42,6 +118,24 @@ export class LexServerAuthError<
     return Response.json(this.toJSON(), { status: 401, headers })
   }
 
+  /**
+   * Creates a LexServerAuthError from an existing LexError.
+   *
+   * If the input is already a LexServerAuthError, returns it unchanged.
+   * Otherwise, wraps the error with the provided WWW-Authenticate parameters.
+   *
+   * @param cause - The original LexError to wrap
+   * @param wwwAuthenticate - WWW-Authenticate header parameters
+   * @returns A LexServerAuthError instance
+   *
+   * @example
+   * ```typescript
+   * const lexError = new LexError('AuthenticationRequired', 'Token expired')
+   * const authError = LexServerAuthError.from(lexError, {
+   *   Bearer: { error: 'ExpiredToken' }
+   * })
+   * ```
+   */
   static from(
     cause: LexError,
     wwwAuthenticate?: WWWAuthenticate,

package/src/lex-server.test.ts

@@ -1509,6 +1509,7 @@ describe('Subscription', () => {
 
   it('handles subscriptions with cleanup', async () => {
     let sentCount = 0
+    const maxMessages = 10
 
     const { resolve, promise: finallyPromise } = timeoutDeferred(5000)
 
@@ -1516,7 +1517,7 @@ describe('Subscription', () => {
       io.example.subscribe,
       async function* ({ params: { message }, signal }) {
         try {
-          for (; sentCount < 10; ) {
+          for (; sentCount < maxMessages; ) {
             await scheduler.wait(5, { signal })
             yield { message, count: ++sentCount }
           }
@@ -1558,7 +1559,7 @@ describe('Subscription', () => {
     ])
 
     expect(sentCount).toBeGreaterThanOrEqual(3)
-    expect(sentCount).toBeLessThan(5)
+    expect(sentCount).toBeLessThan(maxMessages)
   })
 
   it('returns 405 for non-GET request', async () => {