magicbell-js 1.4.0 → 1.6.0

package/src/project-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/project-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/project-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/project-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/project-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/project-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/project-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/project-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/project-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 '';

package/src/project-client/http/transport/request-builder.ts

@@ -13,9 +13,19 @@ import {
   ResponseDefinition,
 } from './types.js';
 
+/**
+ * Builder pattern implementation for constructing HTTP requests.
+ * Provides a fluent interface for configuring all aspects of an API request.
+ * @template Page - The type for paginated response pages
+ */
 export class RequestBuilder<Page extends unknown[] = unknown[]> {
+  /** Internal request parameters being built */
   private params: CreateRequestParameters<Page>;
 
+  /**
+   * Creates a new request builder with default configuration.
+   * Initializes retry settings, validation options, and empty parameter collections.
+   */
   constructor() {
     this.params = {
       baseUrl: Environment.DEFAULT,
@@ -36,6 +46,7 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       pathParams: new Map(),
       queryParams: new Map(),
       headers: new Map(),
+      cookies: new Map(),
     };
   }
 
@@ -254,10 +265,40 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
     return this;
   }
 
+  addCookieParam(param: Partial<RequestParameter>): RequestBuilder<Page> {
+    if (param.value === undefined || param.key === undefined) {
+      return this;
+    }
+
+    this.params.cookies.set(param.key, {
+      key: param.key,
+      value: param.value,
+      explode: param.explode ?? true,
+      style: param.style ?? SerializationStyle.FORM,
+      encode: param.encode ?? false,
+      isLimit: !!param.isLimit,
+      isOffset: !!param.isOffset,
+      isCursor: !!param.isCursor,
+    });
+
+    return this;
+  }
+
+  /**
+   * Builds and returns the configured Request object.
+   * Call this method after configuring all request parameters.
+   * @returns A new Request instance with all configured parameters
+   */
   public build(): Request<Page> {
     return new Request<Page>(this.params);
   }
 
+  /**
+   * Converts a string to Base64 encoding.
+   * Works in both Node.js and browser environments.
+   * @param str - The string to encode
+   * @returns The Base64-encoded string
+   */
   private toBase64(str: string): string {
     if (typeof window === 'undefined') {
       return Buffer.from(str, 'utf-8').toString('base64');

package/src/project-client/http/transport/request-fetch-adapter.ts

@@ -3,21 +3,39 @@ import { HttpMetadata, HttpMethod, HttpResponse } from '../types.js';
 import { LineDecoder } from '../utils/line-decoder.js';
 import { Request } from './request.js';
 
+/**
+ * Interface for HTTP client adapters.
+ * Defines the contract for sending HTTP requests and streaming responses.
+ */
 interface HttpAdapter {
   send(): Promise<HttpResponse>;
   stream(): AsyncGenerator<HttpResponse>;
 }
 
+/**
+ * Fetch API-based HTTP adapter for executing requests.
+ * Uses the native Fetch API to provide a consistent interface for both regular and streaming requests.
+ * Handles headers, cookies, timeouts with AbortSignal, and error responses.
+ *
+ * @template T - The expected response type
+ */
 export class RequestFetchAdapter<T> implements HttpAdapter {
   private requestInit: RequestInit = {};
 
   constructor(private request: Request) {
     this.setMethod(request.method);
     this.setHeaders(request.getHeaders());
+    this.setCookies(request.getCookies());
     this.setBody(request.body);
     this.setTimeout(request.config.timeoutMs);
   }
 
+  /**
+   * Executes the HTTP request and returns the response.
+   * Fetches the full response body as an ArrayBuffer.
+   *
+   * @returns A promise resolving to the HTTP response with metadata and body
+   */
   public async send(): Promise<HttpResponse<T>> {
     const response = await fetch(this.request.constructFullUrl(), this.requestInit);
 
@@ -33,6 +51,13 @@ export class RequestFetchAdapter<T> implements HttpAdapter {
     };
   }
 
+  /**
+   * Executes the HTTP request as a stream, yielding chunks as they arrive.
+   * Uses the Fetch API's ReadableStream and LineDecoder to split into lines.
+   *
+   * @returns An async generator yielding HTTP response chunks
+   * @throws Error if responseHeaders is enabled (streaming not supported with responseHeaders)
+   */
   public async *stream(): AsyncGenerator<HttpResponse<T>> {
     const response = await fetch(this.request.constructFullUrl(), this.requestInit);
 
@@ -109,6 +134,25 @@ export class RequestFetchAdapter<T> implements HttpAdapter {
     };
   }
 
+  private setCookies(cookies: Record<string, string> | undefined): void {
+    if (!cookies || Object.keys(cookies).length === 0) {
+      return;
+    }
+
+    // Serialize cookies as a Cookie header
+    const cookieString = Object.entries(cookies)
+      .map(([key, value]) => `${key}=${value}`)
+      .join('; ');
+
+    this.requestInit = {
+      ...this.requestInit,
+      headers: {
+        ...this.requestInit.headers,
+        Cookie: cookieString,
+      },
+    };
+  }
+
   private setTimeout(timeoutMs: number | undefined): void {
     if (!timeoutMs) {
       return;