magicbell-js 1.5.0 → 1.6.0

package/src/user-client/http/handlers/request-validation-handler.ts

@@ -4,9 +4,21 @@ import { ValidationError } from '../errors/validation-error.js';
 import { Request } from '../transport/request.js';
 import { ContentType, HttpResponse, RequestHandler } from '../types.js';
 
+/**
+ * Request handler that validates and serializes request bodies based on content type.
+ * Supports JSON, XML, text, binary, form data, and multipart form data.
+ */
 export class RequestValidationHandler implements RequestHandler {
+  /** Next handler in the chain */
   next?: RequestHandler;
 
+  /**
+   * Handles a standard HTTP request with validation.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to validate
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no next handler is set
+   */
   async handle<T>(request: Request): Promise<HttpResponse<T>> {
     if (!this.next) {
       throw new Error('No next handler set in ContentTypeHandler.');
@@ -17,6 +29,13 @@ export class RequestValidationHandler implements RequestHandler {
     return this.next.handle<T>(request);
   }
 
+  /**
+   * Handles a streaming HTTP request with validation.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to validate
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no next handler is set
+   */
   async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
     if (!this.next) {
       throw new Error('No next handler set in ContentTypeHandler.');
@@ -27,6 +46,11 @@ export class RequestValidationHandler implements RequestHandler {
     yield* this.next.stream<T>(request);
   }
 
+  /**
+   * Validates and serializes the request body based on its content type.
+   * @param request - The HTTP request to validate
+   * @throws ValidationError if Zod schema validation fails
+   */
   validateRequest(request: Request): void {
     if (request.requestContentType === ContentType.Json) {
       try {
@@ -54,6 +78,11 @@ export class RequestValidationHandler implements RequestHandler {
     }
   }
 
+  /**
+   * Converts request body to URL-encoded form data format.
+   * @param request - The HTTP request with body to convert
+   * @returns URL-encoded string representation of the body
+   */
   toFormUrlEncoded(request: Request): string {
     if (request.body === undefined) {
       return '';
@@ -92,6 +121,14 @@ export class RequestValidationHandler implements RequestHandler {
     return '';
   }
 
+  /**
+   * Converts request body to multipart form data format.
+   * Handles files (ArrayBuffer), arrays, and regular values.
+   * @param body - The request body object
+   * @param filename - Optional filename for single file uploads
+   * @param filenames - Optional filenames array for array of file uploads
+   * @returns FormData object with serialized body
+   */
   toFormData(body: Record<string, any>, filename?: string, filenames?: string[]): FormData {
     const formData = new FormData();
 

package/src/user-client/http/handlers/response-validation-handler.ts

@@ -5,15 +5,33 @@ import { ResponseDefinition } from '../transport/types.js';
 import { ContentType, HttpResponse, RequestHandler } from '../types.js';
 import { ResponseMatcher } from '../utils/response-matcher.js';
 
+/**
+ * Request handler that validates and decodes HTTP response bodies.
+ * Supports multiple content types including JSON, XML, binary, form data, and event streams.
+ */
 export class ResponseValidationHandler implements RequestHandler {
+  /** Next handler in the chain */
   next?: RequestHandler;
 
+  /**
+   * Handles a standard HTTP request and validates its response.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the validated HTTP response
+   */
   async handle<T>(request: Request): Promise<HttpResponse<T>> {
     const response = await this.next!.handle<T>(request);
 
     return this.decodeBody<T>(request, response);
   }
 
+  /**
+   * Handles a streaming HTTP request and validates response chunks.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields validated HTTP responses
+   * @throws Error if response headers are enabled (streaming not supported with headers)
+   */
   async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
     const stream = this.next!.stream<T>(request);
 
@@ -151,6 +169,14 @@ export class ResponseValidationHandler implements RequestHandler {
     };
   }
 
+  /**
+   * Validates response data against the expected schema if validation is enabled.
+   * @template T - The expected data type
+   * @param request - The HTTP request containing validation settings
+   * @param response - The response definition with schema
+   * @param data - The data to validate
+   * @returns The validated data (parsed if validation enabled, raw otherwise)
+   */
   private validate<T>(request: Request, response: ResponseDefinition, data: any): T {
     if (request.validation?.responseValidation) {
       return response.schema.parse(data);
@@ -158,6 +184,13 @@ export class ResponseValidationHandler implements RequestHandler {
     return data;
   }
 
+  /**
+   * Checks if a response should contain data based on its schema and status.
+   * @template T - The response data type
+   * @param responseDefinition - The response definition
+   * @param response - The HTTP response
+   * @returns True if the response should have content, false otherwise
+   */
   private hasContent<T>(responseDefinition: ResponseDefinition, response: HttpResponse<T>): boolean {
     return (
       !!responseDefinition.schema &&
@@ -166,6 +199,11 @@ export class ResponseValidationHandler implements RequestHandler {
     );
   }
 
+  /**
+   * Parses URL-encoded data into an object.
+   * @param urlEncodedData - The URL-encoded string
+   * @returns An object with decoded key-value pairs
+   */
   private fromUrlEncoded(urlEncodedData: string): object {
     const pairs = urlEncodedData.split('&');
     const result: Record<string, string> = {};
@@ -180,6 +218,11 @@ export class ResponseValidationHandler implements RequestHandler {
     return result;
   }
 
+  /**
+   * Parses multipart form data into an object.
+   * @param arrayBuffer - The raw form data as ArrayBuffer
+   * @returns An object with form field names and values
+   */
   private fromFormData(arrayBuffer: ArrayBuffer): Record<string, string> {
     const decoder = new TextDecoder();
     const text = decoder.decode(arrayBuffer);

package/src/user-client/http/handlers/retry-handler.ts

@@ -2,9 +2,22 @@ import { HttpError } from '../error.js';
 import { Request } from '../transport/request.js';
 import { HttpResponse, RequestHandler } from '../types.js';
 
+/**
+ * Request handler that automatically retries failed requests.
+ * Retries are triggered for server errors (5xx), timeouts (408), and rate limits (429).
+ */
 export class RetryHandler implements RequestHandler {
+  /** Next handler in the chain */
   next?: RequestHandler;
 
+  /**
+   * Handles a standard HTTP request with retry logic.
+   * Retries failed requests based on the configured retry settings.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no next handler is set, or if all retry attempts fail
+   */
   async handle<T>(request: Request): Promise<HttpResponse<T>> {
     if (!this.next) {
       throw new Error('No next handler set in retry handler.');
@@ -24,6 +37,13 @@ export class RetryHandler implements RequestHandler {
     throw new Error('Error retrying request.');
   }
 
+  /**
+   * Handles a streaming HTTP request with retry logic.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no next handler is set, or if all retry attempts fail
+   */
   async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
     if (!this.next) {
       throw new Error('No next handler set in retry handler.');
@@ -44,6 +64,12 @@ export class RetryHandler implements RequestHandler {
     throw new Error('Error retrying request.');
   }
 
+  /**
+   * Determines if an error should trigger a retry.
+   * Retries server errors (5xx), request timeouts (408), and rate limits (429).
+   * @param error - The error to check
+   * @returns True if the request should be retried, false otherwise
+   */
   private shouldRetry(error: Error): boolean {
     return (
       error instanceof HttpError &&
@@ -51,6 +77,11 @@ export class RetryHandler implements RequestHandler {
     );
   }
 
+  /**
+   * Delays execution for a specified duration before retrying.
+   * @param delayMs - The delay in milliseconds (optional)
+   * @returns A promise that resolves after the delay
+   */
   private delay(delayMs: number | undefined): Promise<void> {
     if (!delayMs) {
       return Promise.resolve();

package/src/user-client/http/handlers/terminating-handler.ts

@@ -3,11 +3,27 @@ import { Request } from '../transport/request.js';
 import { RequestFetchAdapter } from '../transport/request-fetch-adapter.js';
 import { HttpResponse, RequestHandler } from '../types.js';
 
+/**
+ * Final handler in the request chain that executes the actual HTTP request.
+ * Uses the configured HTTP client adapter (Fetch or Axios) to send the request.
+ */
 export class TerminatingHandler implements RequestHandler {
+  /**
+   * Executes the actual HTTP request using the configured client adapter.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to execute
+   * @returns A promise that resolves to the HTTP response
+   */
   async handle<T>(request: Request): Promise<HttpResponse<T>> {
     return new RequestFetchAdapter<T>(request).send();
   }
 
+  /**
+   * Executes a streaming HTTP request using the configured client adapter.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to execute
+   * @returns An async generator that yields HTTP responses
+   */
   async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
     yield* new RequestFetchAdapter<T>(request).stream();
   }

package/src/user-client/http/hooks/custom-hook.ts

@@ -2,11 +2,30 @@ import { HttpError } from '../error.js';
 import { HttpMetadata } from '../types.js';
 import { Hook, HttpRequest, HttpResponse } from './hook.js';
 
+/**
+ * Default implementation of the Hook interface that provides pass-through behavior.
+ * This hook can be extended to add custom logic for request/response interception.
+ */
 export class CustomHook implements Hook {
+  /**
+   * Called before an HTTP request is sent.
+   * Default implementation returns the request unchanged.
+   * @param request - The HTTP request to be sent
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to the unmodified request
+   */
   public async beforeRequest(request: HttpRequest, params: Map<string, string>): Promise<HttpRequest> {
     return request;
   }
 
+  /**
+   * Called after a successful HTTP response is received.
+   * Default implementation returns the response unchanged.
+   * @param request - The original HTTP request
+   * @param response - The HTTP response received
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to the unmodified response
+   */
   public async afterResponse(
     request: HttpRequest,
     response: HttpResponse<any>,
@@ -15,6 +34,14 @@ export class CustomHook implements Hook {
     return response;
   }
 
+  /**
+   * Called when an HTTP request results in an error.
+   * Default implementation wraps the error response in an HttpError object.
+   * @param request - The original HTTP request
+   * @param response - The error response received
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to an HttpError object
+   */
   public async onError(
     request: HttpRequest,
     response: HttpResponse<any>,

package/src/user-client/http/hooks/hook.ts

@@ -1,41 +1,100 @@
+/**
+ * Standard HTTP methods supported by the SDK.
+ */
 type HttpMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'PUT' | 'TRACE';
 
+/**
+ * Represents an HTTP request with all its components.
+ */
 export interface HttpRequest {
+  /** Base URL of the API endpoint */
   baseUrl: string;
+  /** HTTP method for the request */
   method: HttpMethod;
+  /** Request path (relative to base URL) */
   path: string;
+  /** Request headers as key-value pairs */
   headers: Map<string, unknown>;
+  /** Request body payload (optional) */
   body?: BodyInit;
+  /** Signal to abort the request (optional) */
   abortSignal?: AbortSignal;
+  /** Query string parameters */
   queryParams: Map<string, unknown>;
+  /** Path parameters for URL templating */
   pathParams: Map<string, unknown>;
 }
 
+/**
+ * Metadata about an HTTP response.
+ */
 interface HttpMetadata {
+  /** HTTP status code */
   status: number;
+  /** HTTP status text message */
   statusText: string;
+  /** Response headers as key-value pairs */
   headers: Record<string, string>;
 }
 
+/**
+ * Represents an HTTP response with typed data.
+ * @template T - The type of the response data
+ */
 export interface HttpResponse<T> {
+  /** Parsed response data (optional) */
   data?: T;
+  /** Response metadata (status, headers, etc.) */
   metadata: HttpMetadata;
+  /** Raw response object from the HTTP client */
   raw: ArrayBuffer;
 }
 
+/**
+ * Represents an HTTP error response.
+ */
 export interface HttpError {
+  /** Error message or description */
   error: string;
+  /** Response metadata (status, headers, etc.) */
   metadata: HttpMetadata;
 }
 
+/**
+ * Hook interface for intercepting and modifying HTTP requests and responses.
+ * Allows custom logic to be executed at different stages of the request lifecycle.
+ */
 export interface Hook {
+  /**
+   * Called before an HTTP request is sent.
+   * Allows modification of the request before execution.
+   * @param request - The HTTP request to be sent
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to the potentially modified request
+   */
   beforeRequest(request: HttpRequest, params: Map<string, string>): Promise<HttpRequest>;
 
+  /**
+   * Called after a successful HTTP response is received.
+   * Allows processing or modification of the response.
+   * @param request - The original HTTP request
+   * @param response - The HTTP response received
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to the potentially modified response
+   */
   afterResponse(
     request: HttpRequest,
     response: HttpResponse<any>,
     params: Map<string, string>,
   ): Promise<HttpResponse<any>>;
 
+  /**
+   * Called when an HTTP request results in an error.
+   * Allows custom error handling and transformation.
+   * @param request - The original HTTP request
+   * @param response - The error response received
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to an error object
+   */
   onError(request: HttpRequest, response: HttpResponse<any>, params: Map<string, string>): Promise<HttpError>;
 }

package/src/user-client/http/serialization/base-serializer.ts

@@ -1,23 +1,50 @@
 import { RequestParameter } from '../transport/types.js';
 
+/**
+ * Options for parameter serialization.
+ */
 export type SerializationOptions = {
+  /** Whether to use exploded parameter format */
   explode: boolean;
+  /** The serialization style to use */
   style: SerializationStyle;
+  /** Whether to URL-encode the parameter */
   encode: boolean;
 };
 
+/**
+ * OpenAPI parameter serialization styles.
+ * Defines how parameters should be formatted in the request.
+ */
 export enum SerializationStyle {
+  /** Simple comma-separated values (e.g., "3,4,5") */
   SIMPLE = 'simple',
+  /** Label prefix with dot notation (e.g., ".3.4.5") */
   LABEL = 'label',
+  /** Matrix semicolon-prefixed (e.g., ";id=3;id=4") */
   MATRIX = 'matrix',
+  /** Form-style ampersand-separated (e.g., "id=3&id=4") */
   FORM = 'form',
+  /** Space-delimited values (e.g., "id=3 4 5") */
   SPACE_DELIMITED = 'space_delimited',
+  /** Pipe-delimited values (e.g., "id=3|4|5") */
   PIPE_DELIMITED = 'pipe_delimited',
+  /** Deep object notation (e.g., "id[role]=admin") */
   DEEP_OBJECT = 'deep_object',
+  /** No specific style applied */
   NONE = 'none',
 }
 
+/**
+ * Base serializer class for converting request parameters to string format.
+ * Supports multiple OpenAPI serialization styles for primitives, arrays, and objects.
+ */
 export class Serializer {
+  /**
+   * Serializes a parameter value based on its type and serialization style.
+   * @param param - The request parameter to serialize
+   * @returns The serialized string representation
+   */
   protected serializeValue(param: RequestParameter): string {
     if (Array.isArray(param.value)) {
       return this.serializeArray(param.value, param);
@@ -30,6 +57,11 @@ export class Serializer {
     return this.serializePrimitive(param);
   }
 
+  /**
+   * Serializes a primitive value (string, number, boolean).
+   * @param param - The request parameter containing the primitive value
+   * @returns The serialized primitive string
+   */
   private serializePrimitive(param: RequestParameter): string {
     if (param.style === SerializationStyle.LABEL) {
       return `.${param.value}`;
@@ -42,6 +74,12 @@ export class Serializer {
     return `${param.value}`;
   }
 
+  /**
+   * Serializes an array value according to the specified style.
+   * @param value - The array to serialize
+   * @param param - The request parameter configuration
+   * @returns The serialized array string
+   */
   private serializeArray(value: unknown[], param: RequestParameter): string {
     if (param.explode) {
       this.serializeArrayExploded(value, param);
@@ -65,6 +103,12 @@ export class Serializer {
     return `${value.join(',')}`;
   }
 
+  /**
+   * Serializes an array in exploded format where each value is a separate parameter.
+   * @param value - The array to serialize
+   * @param param - The request parameter configuration
+   * @returns The serialized exploded array string
+   */
   private serializeArrayExploded(value: unknown[], param: RequestParameter): string {
     if (param.style === SerializationStyle.SIMPLE) {
       return value.map((val) => `${val}`).join(',');
@@ -83,6 +127,12 @@ export class Serializer {
     return `${value.join(',')}`;
   }
 
+  /**
+   * Serializes an object value according to the specified style.
+   * @param obj - The object to serialize
+   * @param param - The request parameter configuration
+   * @returns The serialized object string
+   */
   private serializeObject(obj: object, param: RequestParameter): string {
     if (param.explode) {
       if (param.style === SerializationStyle.SIMPLE) {
@@ -133,6 +183,11 @@ export class Serializer {
       .join('&');
   }
 
+  /**
+   * Type guard to check if a value is a non-null object.
+   * @param value - The value to check
+   * @returns True if the value is an object and not null
+   */
   private isNonNullObject(value: unknown): value is object {
     return typeof value === 'object' && value !== null;
   }

package/src/user-client/http/serialization/cookie-serializer.ts

@@ -0,0 +1,93 @@
+import { RequestParameter } from '../transport/types.js';
+import { SerializationStyle } from './base-serializer.js';
+
+/**
+ * Serializer for HTTP cookies.
+ * Converts cookie parameters into a cookie object for requests.
+ */
+export class CookieSerializer {
+  /**
+   * Serializes cookie parameters into a cookie object.
+   * @param cookieParams - Map of cookie names to their parameter values
+   * @returns A record of cookie names to serialized values, or undefined if no cookies
+   */
+  public serialize(cookieParams: Map<string, RequestParameter> | undefined): Record<string, string> | undefined {
+    if (!cookieParams || !cookieParams.size) {
+      return undefined;
+    }
+
+    const cookies: Record<string, string> = {};
+    cookieParams.forEach((param) => {
+      if (!param.key || param.value === undefined) {
+        return;
+      }
+      cookies[param.key] = this.serializeCookieValue(param);
+    });
+    return cookies;
+  }
+
+  /**
+   * Serializes a single cookie value based on its type.
+   * @param param - The cookie parameter to serialize
+   * @returns The serialized cookie value string
+   */
+  private serializeCookieValue(param: RequestParameter): string {
+    if (Array.isArray(param.value)) {
+      return this.serializeArray(param.value, param);
+    }
+
+    if (this.isNonNullObject(param.value)) {
+      return this.serializeObject(param.value, param);
+    }
+
+    return this.serializePrimitive(param.value);
+  }
+
+  /**
+   * Serializes a primitive cookie value.
+   * @param value - The primitive value to serialize
+   * @returns The string representation of the value
+   */
+  private serializePrimitive(value: unknown): string {
+    return `${value}`;
+  }
+
+  /**
+   * Serializes an array cookie value.
+   * @param value - The array to serialize
+   * @param param - The cookie parameter configuration
+   * @returns The serialized array string
+   */
+  private serializeArray(value: unknown[], param: RequestParameter): string {
+    if (param.explode) {
+      if (value.length === 0) return '';
+      const first = value[0];
+      const rest = value
+        .slice(1)
+        .map((v) => `${param.key}=${v}`)
+        .join('; ');
+      return rest ? `${first}; ${rest}` : `${first}`;
+    }
+
+    return value.join(',');
+  }
+
+  /**
+   * Serializes an object cookie value as JSON.
+   * @param obj - The object to serialize
+   * @param param - The cookie parameter configuration
+   * @returns The JSON string representation of the object
+   */
+  private serializeObject(obj: object, param: RequestParameter): string {
+    return JSON.stringify(obj);
+  }
+
+  /**
+   * Type guard to check if a value is a non-null object.
+   * @param value - The value to check
+   * @returns True if the value is an object and not null
+   */
+  private isNonNullObject(value: unknown): value is object {
+    return typeof value === 'object' && value !== null;
+  }
+}

package/src/user-client/http/serialization/header-serializer.ts

@@ -1,7 +1,16 @@
 import { RequestParameter } from '../transport/types.js';
 import { Serializer } from './base-serializer.js';
 
+/**
+ * Serializer for HTTP request headers.
+ * Converts header parameters into a HeadersInit object.
+ */
 export class HeaderSerializer extends Serializer {
+  /**
+   * Serializes header parameters into a headers object.
+   * @param headerParams - Map of header names to their parameter values
+   * @returns A HeadersInit object with serialized header values, or undefined if no headers
+   */
   public serialize(headerParams: Map<string, RequestParameter> | undefined): HeadersInit | undefined {
     if (!headerParams || !headerParams.size) {
       return undefined;

package/src/user-client/http/serialization/path-serializer.ts

@@ -1,7 +1,19 @@
 import { RequestParameter } from '../transport/types.js';
 import { Serializer } from './base-serializer.js';
 
+/**
+ * Serializer for path parameters in URL templates.
+ * Replaces path template placeholders with serialized parameter values.
+ */
 export class PathSerializer extends Serializer {
+  /**
+   * Serializes path parameters into a URL path by replacing template placeholders.
+   * @param pathPattern - The URL path pattern with {placeholders}
+   * @param pathArguments - Map of parameter names to their values
+   * @returns The path with placeholders replaced by serialized values
+   * @example
+   * serialize("/users/{id}", Map([["id", {key: "id", value: 123}]])) returns "/users/123"
+   */
   public serialize(pathPattern: string, pathArguments: Map<string, RequestParameter>): string {
     let serializedPath = pathPattern;
     pathArguments.forEach((param: RequestParameter) => {

package/src/user-client/http/serialization/query-serializer.ts

@@ -1,7 +1,18 @@
 import { RequestParameter } from '../transport/types.js';
 import { SerializationOptions, Serializer } from './base-serializer.js';
 
+/**
+ * Serializer for URL query string parameters.
+ * Converts query parameters into a URL query string.
+ */
 export class QuerySerializer extends Serializer {
+  /**
+   * Serializes query parameters into a URL query string.
+   * @param queryParams - Map of query parameter names to their values
+   * @returns A query string starting with "?" if parameters exist, empty string otherwise
+   * @example
+   * serialize(Map([["name", {...}], ["age", {...}]])) returns "?name=John&age=30"
+   */
   public serialize(queryParams: Map<string, RequestParameter>): string {
     if (!queryParams || !queryParams.size) {
       return '';