magicbell-js 1.5.0 → 1.6.0

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;

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

@@ -2,6 +2,7 @@ import { ZodType } from 'zod';
 
 import { HttpRequest } from '../hooks/hook.js';
 import { SerializationStyle } from '../serialization/base-serializer.js';
+import { CookieSerializer } from '../serialization/cookie-serializer.js';
 import { HeaderSerializer } from '../serialization/header-serializer.js';
 import { PathSerializer } from '../serialization/path-serializer.js';
 import { QuerySerializer } from '../serialization/query-serializer.js';
@@ -16,6 +17,13 @@ import {
   ResponseDefinition,
 } from './types.js';
 
+/**
+ * Represents an HTTP request with all necessary configuration and parameters.
+ * Handles path/query/header/cookie serialization, pagination, validation, and retry logic.
+ * This is the core request object passed through the handler chain for execution.
+ *
+ * @template PageSchema - The type of paginated data returned by this request
+ */
 export class Request<PageSchema = unknown[]> {
   public baseUrl = '';
 
@@ -25,6 +33,8 @@ export class Request<PageSchema = unknown[]> {
 
   public pathParams: Map<string, RequestParameter> = new Map();
 
+  public cookies: Map<string, RequestParameter> = new Map();
+
   public body?: any;
 
   public method: HttpMethod;
@@ -63,6 +73,7 @@ export class Request<PageSchema = unknown[]> {
     this.pathParams = params.pathParams;
     this.headers = params.headers;
     this.queryParams = params.queryParams;
+    this.cookies = params.cookies;
     this.responses = params.responses;
     this.errors = params.errors;
     this.requestSchema = params.requestSchema;
@@ -74,6 +85,12 @@ export class Request<PageSchema = unknown[]> {
     this.filenames = params.filenames;
   }
 
+  /**
+   * Adds a header parameter to the request with OpenAPI serialization rules.
+   *
+   * @param key - The header name
+   * @param param - The parameter configuration including value, style, and encoding options
+   */
   addHeaderParam(key: string, param: RequestParameter): void {
     if (param.value === undefined) {
       return;
@@ -94,6 +111,12 @@ export class Request<PageSchema = unknown[]> {
     this.headers.set(key, param);
   }
 
+  /**
+   * Adds a query parameter to the request with OpenAPI serialization rules.
+   *
+   * @param key - The query parameter name
+   * @param param - The parameter configuration including value, style, and encoding options
+   */
   addQueryParam(key: string, param: RequestParameter): void {
     if (param.value === undefined) {
       return;
@@ -114,6 +137,12 @@ export class Request<PageSchema = unknown[]> {
     this.queryParams.set(key, param);
   }
 
+  /**
+   * Adds a path parameter to the request with OpenAPI serialization rules.
+   *
+   * @param key - The path parameter name (matches template variable in path pattern)
+   * @param param - The parameter configuration including value, style, and encoding options
+   */
   addPathParam(key: string, param: RequestParameter): void {
     if (param.value === undefined) {
       return;
@@ -134,6 +163,11 @@ export class Request<PageSchema = unknown[]> {
     this.pathParams.set(key, param);
   }
 
+  /**
+   * Sets the request body if the value is defined.
+   *
+   * @param body - The request body to send
+   */
   addBody(body: any): void {
     if (body === undefined) {
       return;
@@ -142,6 +176,12 @@ export class Request<PageSchema = unknown[]> {
     this.body = body;
   }
 
+  /**
+   * Updates this request from a modified hook request.
+   * Used after hooks modify the request to sync changes back to the internal Request object.
+   *
+   * @param hookRequest - The modified request from hook processing
+   */
   public updateFromHookRequest(hookRequest: HttpRequest): void {
     this.baseUrl = hookRequest.baseUrl;
     this.method = hookRequest.method;
@@ -149,6 +189,12 @@ export class Request<PageSchema = unknown[]> {
     this.body = hookRequest.body;
   }
 
+  /**
+   * Constructs the complete URL by combining base URL, path with substituted parameters,
+   * and serialized query string.
+   *
+   * @returns The fully constructed URL ready for HTTP execution
+   */
   public constructFullUrl(): string {
     const queryString = new QuerySerializer().serialize(this.queryParams);
     const path = this.constructPath();
@@ -157,6 +203,13 @@ export class Request<PageSchema = unknown[]> {
     return `${baseUrl}${path}${queryString}`;
   }
 
+  /**
+   * Creates a copy of this request with optional parameter overrides.
+   * Useful for pagination where you need to modify parameters while keeping the rest intact.
+   *
+   * @param overrides - Optional parameters to override in the copied request
+   * @returns A new Request instance with the specified overrides
+   */
   public copy(overrides?: Partial<CreateRequestParameters>) {
     const createRequestParams: CreateRequestParameters = {
       baseUrl: overrides?.baseUrl ?? this.baseUrl,
@@ -168,6 +221,7 @@ export class Request<PageSchema = unknown[]> {
       pathParams: overrides?.pathParams ?? this.pathParams,
       queryParams: overrides?.queryParams ?? this.queryParams,
       headers: overrides?.headers ?? this.headers,
+      cookies: overrides?.cookies ?? this.cookies,
       responses: overrides?.responses ?? this.responses,
       requestSchema: overrides?.requestSchema ?? this.requestSchema,
       requestContentType: overrides?.requestContentType ?? this.requestContentType,
@@ -182,6 +236,11 @@ export class Request<PageSchema = unknown[]> {
     });
   }
 
+  /**
+   * Serializes headers to a format suitable for HTTP execution.
+   *
+   * @returns Serialized headers as HeadersInit, or undefined if no headers
+   */
   public getHeaders(): HeadersInit | undefined {
     if (!this.headers || !this.headers.size) {
       return undefined;
@@ -190,6 +249,25 @@ export class Request<PageSchema = unknown[]> {
     return new HeaderSerializer().serialize(this.headers);
   }
 
+  /**
+   * Serializes cookies to a format suitable for HTTP execution.
+   *
+   * @returns Serialized cookies as a record, or undefined if no cookies
+   */
+  public getCookies(): Record<string, string> | undefined {
+    if (!this.cookies || !this.cookies.size) {
+      return undefined;
+    }
+
+    return new CookieSerializer().serialize(this.cookies);
+  }
+
+  /**
+   * Advances pagination parameters to fetch the next page.
+   * Handles both cursor-based and limit-offset pagination strategies.
+   *
+   * @param cursor - The cursor value for cursor-based pagination (optional for limit-offset)
+   */
   public nextPage(cursor?: string): void {
     if (!this.pagination) {
       return;
@@ -243,6 +321,10 @@ export class Request<PageSchema = unknown[]> {
       allParams.push(val);
     });
 
+    this.cookies.forEach((val, _) => {
+      allParams.push(val);
+    });
+
     return allParams;
   }
 }

package/src/project-client/http/transport/transport-hook-adapter.ts

@@ -5,9 +5,24 @@ import { HttpResponse } from '../types.js';
 import { Request } from './request.js';
 import { RequestParameter } from './types.js';
 
+/**
+ * Adapter that bridges between the internal Request representation and the Hook interface.
+ * Converts Request objects to HttpRequest format for hook processing, then converts
+ * modified HttpRequest objects back to Request format.
+ *
+ * @template T - The expected response type
+ */
 export class TransportHookAdapter<T> {
   private hook: CustomHook = new CustomHook();
 
+  /**
+   * Invokes the custom hook before sending the request.
+   * Converts the Request to HttpRequest format, calls the hook, then converts back.
+   *
+   * @param request - The internal Request object
+   * @param params - Additional parameters to pass to the hook
+   * @returns The modified Request after hook processing
+   */
   public async beforeRequest(request: Request, params: Map<string, string>): Promise<Request> {
     const hookRequest = this.requestToHookRequest(request);
 
@@ -26,6 +41,15 @@ export class TransportHookAdapter<T> {
     return newTransportRequest;
   }
 
+  /**
+   * Invokes the custom hook after receiving a response.
+   * Converts the Request to HttpRequest format and calls the hook with the response.
+   *
+   * @param request - The internal Request object
+   * @param response - The HTTP response received
+   * @param params - Additional parameters to pass to the hook
+   * @returns The potentially modified response after hook processing
+   */
   public async afterResponse(
     request: Request,
     response: HttpResponse<T>,
@@ -35,11 +59,27 @@ export class TransportHookAdapter<T> {
     return this.hook.afterResponse(hookRequest, response, params);
   }
 
+  /**
+   * Invokes the custom hook when an error occurs.
+   * Converts the Request to HttpRequest format and calls the error hook.
+   *
+   * @param request - The internal Request object
+   * @param response - The HTTP response that triggered the error
+   * @param params - Additional parameters to pass to the hook
+   * @returns The HttpError from the hook
+   */
   public async onError(request: Request, response: HttpResponse<T>, params: Map<string, string>): Promise<HttpError> {
     const hookRequest = this.requestToHookRequest(request);
     return this.hook.onError(hookRequest, response, params);
   }
 
+  /**
+   * Converts the internal Request representation to the hook's HttpRequest format.
+   * Extracts parameter values from RequestParameter wrappers.
+   *
+   * @param request - The internal Request object
+   * @returns An HttpRequest object for hook processing
+   */
   private requestToHookRequest(request: Request): HttpRequest {
     const hookHeaders: Map<string, unknown> = new Map();
     request.headers.forEach((header, key) => {
@@ -68,6 +108,16 @@ export class TransportHookAdapter<T> {
     return hookRequest;
   }
 
+  /**
+   * Converts hook parameter maps back to RequestParameter format.
+   * Preserves serialization metadata from the original parameters.
+   *
+   * @template T - The parameter value type
+   * @param hookParams - The parameter map from hook processing
+   * @param originalTransportParams - The original RequestParameter map for metadata
+   * @param encode - Whether to encode the parameters
+   * @returns A map of RequestParameter objects for transport
+   */
   private hookParamsToTransportParams<T>(
     hookParams: Map<string, unknown>,
     originalTransportParams: Map<string, RequestParameter>,

package/src/project-client/http/transport/types.ts

@@ -4,18 +4,38 @@ import { ThrowableError } from '../errors/throwable-error.js';
 import { SerializationStyle } from '../serialization/base-serializer.js';
 import { ContentType, HttpMethod, RetryOptions, SdkConfig, ValidationOptions } from '../types.js';
 
+/**
+ * Defines an expected response format with schema validation.
+ * Used to match and validate responses based on content type and status code.
+ */
 export interface ResponseDefinition {
+  /** Zod schema for validating the response body */
   schema: ZodType;
+  /** The content type of this response (e.g., 'application/json') */
   contentType: ContentType;
+  /** The HTTP status code this definition applies to */
   status: number;
 }
 
+/**
+ * Defines an error response format with custom error class.
+ * Used to throw typed errors based on content type and status code.
+ */
 export interface ErrorDefinition {
+  /** Constructor for the error class to instantiate */
   error: new (...args: any[]) => ThrowableError;
+  /** The content type of this error response */
   contentType: ContentType;
+  /** The HTTP status code this error applies to */
   status: number;
 }
 
+/**
+ * Parameters required to create a Request instance.
+ * Contains all configuration needed for HTTP execution, validation, and error handling.
+ *
+ * @template Page - The type of paginated data items
+ */
 export interface CreateRequestParameters<Page = unknown[]> {
   baseUrl: string;
   method: HttpMethod;
@@ -23,6 +43,7 @@ export interface CreateRequestParameters<Page = unknown[]> {
   headers: Map<string, RequestParameter>;
   queryParams: Map<string, RequestParameter>;
   pathParams: Map<string, RequestParameter>;
+  cookies: Map<string, RequestParameter>;
   path: string;
   config: SdkConfig;
   responses: ResponseDefinition[];
@@ -36,30 +57,68 @@ export interface CreateRequestParameters<Page = unknown[]> {
   filenames?: string[];
 }
 
+/**
+ * Represents a request parameter with serialization metadata.
+ * Wraps a value with OpenAPI serialization instructions for proper encoding.
+ */
 export interface RequestParameter {
+  /** The parameter name (may be undefined for path substitution) */
   key: string | undefined;
+  /** The actual parameter value */
   value: unknown;
+  /** Whether to explode arrays/objects into multiple parameters */
   explode: boolean;
+  /** Whether to URL-encode the value */
   encode: boolean;
+  /** The OpenAPI serialization style (e.g., SIMPLE, FORM, MATRIX) */
   style: SerializationStyle;
+  /** Whether this parameter is a pagination limit */
   isLimit: boolean;
+  /** Whether this parameter is a pagination offset */
   isOffset: boolean;
+  /** Whether this parameter is a pagination cursor */
   isCursor: boolean;
 }
 
+/**
+ * Configuration for limit-offset pagination.
+ * Used for traditional page-based pagination with size and offset.
+ *
+ * @template Page - The type of page data
+ */
 export interface RequestPagination<Page> {
+  /** The number of items per page */
   pageSize?: number;
+  /** JSON path to extract page data from response */
   pagePath: string[];
+  /** Zod schema for validating page data */
   pageSchema?: ZodType<Page, any, any>;
 }
 
+/**
+ * Configuration for cursor-based pagination.
+ * Used for stateless pagination with cursor tokens.
+ *
+ * @template Page - The type of page data
+ */
 export interface RequestCursorPagination<Page> {
+  /** JSON path to extract page data from response */
   pagePath: string[];
+  /** Zod schema for validating page data */
   pageSchema?: ZodType<Page, any, any>;
+  /** JSON path to extract next cursor from response */
   cursorPath: string[];
+  /** Zod schema for validating cursor value */
   cursorSchema?: ZodType<string | null | undefined>;
 }
 
+/**
+ * Type guard to determine if pagination configuration is cursor-based.
+ *
+ * @template Page - The type of page data
+ * @param pagination - The pagination configuration to check
+ * @returns true if cursor-based pagination, false otherwise
+ */
 export function isRequestCursorPagination<Page>(
   pagination: RequestPagination<Page> | RequestCursorPagination<Page> | undefined,
 ): pagination is RequestCursorPagination<Page> {