magicbell-js 1.5.0 → 1.6.0

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

@@ -3,8 +3,15 @@ import { ZodType } from 'zod';
 import { Environment } from './environment.js';
 import { Request } from './transport/request.js';
 
+/**
+ * Standard HTTP methods supported by the SDK.
+ */
 export type HttpMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'PUT' | 'TRACE';
 
+/**
+ * SDK configuration interface.
+ * Contains all settings required to initialize and configure the SDK.
+ */
 export interface SdkConfig {
   baseUrl?: string;
   environment?: Environment;
@@ -14,44 +21,102 @@ export interface SdkConfig {
   validation?: ValidationOptions;
 }
 
+/**
+ * Metadata about an HTTP response.
+ * Contains status information and headers from the server response.
+ */
 export interface HttpMetadata {
+  /** HTTP status code (e.g., 200, 404, 500) */
   status: number;
+  /** HTTP status text message (e.g., "OK", "Not Found") */
   statusText: string;
+  /** Response headers as key-value pairs */
   headers: Record<string, string>;
 }
 
+/**
+ * Standard HTTP response with typed data.
+ * @template T - The type of the response data
+ */
 export interface HttpResponse<T = unknown> {
+  /** Parsed response data (optional) */
   data?: T;
+  /** Response metadata (status, headers, etc.) */
   metadata: HttpMetadata;
+  /** Raw response object from the HTTP client */
   raw: ArrayBuffer;
 }
 
+/**
+ * HTTP response for paginated API endpoints.
+ * Marker interface extending HttpResponse for type safety with pagination.
+ * @template T - The type of a single page of data
+ */
 export interface PaginatedHttpResponse<T = unknown> extends HttpResponse<T> {
   // Marker interface for pagination responses
 }
 
+/**
+ * HTTP response for cursor-paginated API endpoints.
+ * Includes a cursor for fetching the next page of results.
+ * @template T - The type of a single page of data
+ */
 export interface CursorPaginatedHttpResponse<T = unknown> extends HttpResponse<T> {
+  /** Cursor string for fetching the next page, null if no more pages, undefined if not applicable */
   nextCursor?: string | null;
 }
 
+/**
+ * Interface for request handlers in the chain of responsibility pattern.
+ * Handlers process requests sequentially, each performing specific operations.
+ */
 export interface RequestHandler {
+  /** Reference to the next handler in the chain */
   next?: RequestHandler;
 
+  /**
+   * Handles a standard HTTP request.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the HTTP response
+   */
   handle<T>(request: Request): Promise<HttpResponse<T>>;
+
+  /**
+   * Handles a streaming HTTP request.
+   * @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
+   */
   stream<T>(request: Request): AsyncGenerator<HttpResponse<T>>;
 }
 
+/**
+ * Supported content types for HTTP requests and responses.
+ * Determines how the SDK serializes requests and parses responses.
+ */
 export enum ContentType {
+  /** JSON format (application/json) */
   Json = 'json',
+  /** XML format (application/xml, text/xml) */
   Xml = 'xml',
+  /** PDF document (application/pdf) */
   Pdf = 'pdf',
+  /** Image file (image/*) */
   Image = 'image',
+  /** Generic file */
   File = 'file',
+  /** Binary data (application/octet-stream) */
   Binary = 'binary',
+  /** URL-encoded form data (application/x-www-form-urlencoded) */
   FormUrlEncoded = 'form',
+  /** Plain text (text/plain) */
   Text = 'text',
+  /** Multipart form data for file uploads (multipart/form-data) */
   MultipartFormData = 'multipartFormData',
+  /** Server-sent events stream (text/event-stream) */
   EventStream = 'eventStream',
+  /** No content (HTTP 204) */
   NoContent = 'noContent',
 }
 

package/src/project-client/http/utils/content-type.ts

@@ -1,5 +1,12 @@
 import { ContentType } from '../types.js';
 
+/**
+ * Determines the ContentType enum value from a MIME type string.
+ * Maps HTTP Content-Type header values to the SDK's ContentType enum.
+ * Handles special cases like text/json (parsed as JSON), image/svg+xml (text), and wildcards.
+ * @param contentType - The Content-Type header value (e.g., "application/json", "text/plain")
+ * @returns The corresponding ContentType enum value
+ */
 export function getContentTypeDefinition(contentType: string): ContentType {
   const ct = contentType.toLowerCase();
 

package/src/project-client/http/utils/line-decoder.ts

@@ -1,3 +1,8 @@
+/**
+ * Utility for splitting streaming data into line-based chunks.
+ * Buffers incomplete lines between chunks and handles newline characters correctly.
+ * Useful for processing server-sent events or other line-based streaming protocols.
+ */
 export class LineDecoder {
   private lineBuffer = '';
   private decoder = new TextDecoder();
@@ -6,6 +11,9 @@ export class LineDecoder {
   /**
    * Splits the given chunk into lines.
    * Stores incomplete lines in a buffer and returns them when the next chunk arrives.
+   *
+   * @param chunk - The data chunk to split into lines
+   * @returns An array of complete lines as Uint8Array
    */
   public splitLines(chunk: Uint8Array): Uint8Array[] {
     this.lineBuffer += this.decoder.decode(chunk);
@@ -23,7 +31,12 @@ export class LineDecoder {
     return lines;
   }
 
-  /** Returns the remaining lines in the buffer. */
+  /**
+   * Returns the remaining lines in the buffer.
+   * Call this after the stream ends to get any incomplete final line.
+   *
+   * @returns An array containing the buffered line, or empty if buffer is empty
+   */
   public flush(): Uint8Array[] {
     if (this.lineBuffer.length === 0) {
       return [];

package/src/project-client/http/utils/response-matcher.ts

@@ -2,9 +2,23 @@ import { ResponseDefinition } from '../transport/types.js';
 import { ContentType, HttpResponse } from '../types.js';
 import { getContentTypeDefinition } from './content-type.js';
 
+/**
+ * Matches HTTP responses to their expected response definitions.
+ * Determines which response schema to use based on status code and content type.
+ */
 export class ResponseMatcher {
+  /**
+   * Creates a new response matcher.
+   * @param responses - Array of possible response definitions for an endpoint
+   */
   constructor(private responses: ResponseDefinition[]) {}
 
+  /**
+   * Finds the matching response definition for an HTTP response.
+   * Matches based on status code and content type from the response headers.
+   * @param response - The HTTP response to match
+   * @returns The matching response definition, or undefined if no match found
+   */
   public getResponseDefinition(response: HttpResponse): ResponseDefinition | undefined {
     const rawContentType = response.metadata.headers['content-type']?.toLocaleLowerCase() || '';
     const contentType = getContentTypeDefinition(rawContentType);

package/src/project-client/services/base-service.ts

@@ -2,7 +2,12 @@ import { HttpClient } from '../http/client.js';
 import { Environment } from '../http/environment.js';
 import { SdkConfig } from '../http/types.js';
 
+/**
+ * Base service class that all API service classes extend.
+ * Provides common functionality including HTTP client management and configuration.
+ */
 export class BaseService {
+  /** The HTTP client instance used to make API requests */
   public client: HttpClient;
 
   constructor(public config: SdkConfig) {

package/src/project-client/services/broadcasts/broadcasts-service.ts

@@ -10,12 +10,17 @@ import { Broadcast, broadcastRequest, broadcastResponse } from './models/broadca
 import { BroadcastCollection, broadcastCollectionResponse } from './models/broadcast-collection.js';
 import { ListBroadcastsParams } from './request-params.js';
 
+/**
+ * Service class for BroadcastsService operations.
+ * Provides methods to interact with BroadcastsService-related API endpoints.
+ * All methods return promises and handle request/response serialization automatically.
+ */
 export class BroadcastsService extends BaseService {
   /**
    * Retrieves a paginated list of broadcasts for the project. Returns basic information about each broadcast including its creation time and status.
-   * @param {number} [params.limit] -
-   * @param {string} [params.startingAfter] -
-   * @param {string} [params.endingBefore] -
+   * @param {number} [params.limit] - defines the maximum number of items to return per page (default: 50)
+   * @param {string} [params.startingAfter] - a cursor for use in pagination, points to the last ID in previous page
+   * @param {string} [params.endingBefore] - a cursor for use in pagination, points to the first ID in next page
    * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
    * @returns {Promise<HttpResponse<BroadcastCollection>>} - OK
    */

package/src/project-client/services/broadcasts/models/broadcast-collection.ts

@@ -4,7 +4,9 @@ import { Links, links, linksRequest, linksResponse } from '../../common/links.js
 import { Broadcast, broadcast, broadcastRequest, broadcastResponse } from './broadcast.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the BroadcastCollection model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const broadcastCollection = z.lazy(() => {
   return z.object({
@@ -22,8 +24,9 @@ export const broadcastCollection = z.lazy(() => {
 export type BroadcastCollection = z.infer<typeof broadcastCollection>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the BroadcastCollection application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const broadcastCollectionResponse = z.lazy(() => {
   return z
@@ -38,8 +41,9 @@ export const broadcastCollectionResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the BroadcastCollection application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const broadcastCollectionRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/broadcast-status.ts

@@ -4,7 +4,9 @@ import { Errors, errors, errorsRequest, errorsResponse } from './errors.js';
 import { Summary, summary, summaryRequest, summaryResponse } from './summary.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the BroadcastStatus model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const broadcastStatus = z.lazy(() => {
   return z.object({
@@ -15,17 +17,18 @@ export const broadcastStatus = z.lazy(() => {
 });
 
 /**
- *
- * @typedef  {BroadcastStatus} broadcastStatus
- * @property {Errors[]}
- * @property {StatusStatus}
- * @property {Summary}
+ * The runtime state of the broadcast execution.
+ * @typedef  {BroadcastStatus} broadcastStatus - The runtime state of the broadcast execution. - The runtime state of the broadcast execution.
+ * @property {Errors[]} - A list of errors encountered while processing the broadcast.
+ * @property {StatusStatus} - The overall processing status of the broadcast.
+ * @property {Summary} - The summary counts for total recipients and failures.
  */
 export type BroadcastStatus = z.infer<typeof broadcastStatus>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the BroadcastStatus application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const broadcastStatusResponse = z.lazy(() => {
   return z
@@ -42,8 +45,9 @@ export const broadcastStatusResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the BroadcastStatus application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const broadcastStatusRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/broadcast.ts

@@ -10,7 +10,9 @@ import {
 import { Overrides, overrides, overridesRequest, overridesResponse } from './overrides.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the Broadcast model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const broadcast = z.lazy(() => {
   return z.object({
@@ -41,23 +43,24 @@ export const broadcast = z.lazy(() => {
 /**
  *
  * @typedef  {Broadcast} broadcast
- * @property {string}
- * @property {string}
- * @property {string}
+ * @property {string} - The URL recipients will be directed to when interacting with the broadcast.
+ * @property {string} - The label used to group broadcasts.
+ * @property {string} - The body content delivered with the broadcast.
  * @property {string} - The timestamp when the broadcast was created.
- * @property {any}
+ * @property {any} - Arbitrary custom data associated with the broadcast.
  * @property {string} - The unique id for this broadcast.
- * @property {Overrides}
- * @property {User[]}
- * @property {BroadcastStatus}
- * @property {string}
- * @property {string}
+ * @property {Overrides} - Channel- or provider-specific values that override the defaults.
+ * @property {User[]} - A collection of users or filters that determine who receives the broadcast.
+ * @property {BroadcastStatus} - The runtime state of the broadcast execution.
+ * @property {string} - The subject or headline that will be shown to recipients.
+ * @property {string} - The topic that further classifies the broadcast.
  */
 export type Broadcast = z.infer<typeof broadcast>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the Broadcast application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const broadcastResponse = z.lazy(() => {
   return z
@@ -100,8 +103,9 @@ export const broadcastResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the Broadcast application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const broadcastRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/email.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the Email model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const email = z.lazy(() => {
   return z.object({
@@ -12,17 +14,18 @@ export const email = z.lazy(() => {
 });
 
 /**
- *
- * @typedef  {Email} email
- * @property {string}
- * @property {string}
- * @property {string}
+ * Overrides for email notifications.
+ * @typedef  {Email} email - Overrides for email notifications. - Overrides for email notifications.
+ * @property {string} - The link associated with the channel-specific notification.
+ * @property {string} - The channel-specific content.
+ * @property {string} - The channel-specific title.
  */
 export type Email = z.infer<typeof email>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the Email application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const emailResponse = z.lazy(() => {
   return z
@@ -39,8 +42,9 @@ export const emailResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the Email application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const emailRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/errors.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the Errors model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const errors = z.lazy(() => {
   return z.object({
@@ -12,13 +14,14 @@ export const errors = z.lazy(() => {
 /**
  *
  * @typedef  {Errors} errors
- * @property {string}
+ * @property {string} - The details about the processing error.
  */
 export type Errors = z.infer<typeof errors>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the Errors application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const errorsResponse = z.lazy(() => {
   return z
@@ -31,8 +34,9 @@ export const errorsResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the Errors application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const errorsRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/in-app.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the InApp model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const inApp = z.lazy(() => {
   return z.object({
@@ -12,17 +14,18 @@ export const inApp = z.lazy(() => {
 });
 
 /**
- *
- * @typedef  {InApp} inApp
- * @property {string}
- * @property {string}
- * @property {string}
+ * Overrides for in-app notifications.
+ * @typedef  {InApp} inApp - Overrides for in-app notifications. - Overrides for in-app notifications.
+ * @property {string} - The link associated with the channel-specific notification.
+ * @property {string} - The channel-specific content.
+ * @property {string} - The channel-specific title.
  */
 export type InApp = z.infer<typeof inApp>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the InApp application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const inAppResponse = z.lazy(() => {
   return z
@@ -39,8 +42,9 @@ export const inAppResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the InApp application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const inAppRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/mobile-push.ts

@@ -1,7 +1,9 @@
 import { z } from 'zod';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the MobilePush model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const mobilePush = z.lazy(() => {
   return z.object({
@@ -12,17 +14,18 @@ export const mobilePush = z.lazy(() => {
 });
 
 /**
- *
- * @typedef  {MobilePush} mobilePush
- * @property {string}
- * @property {string}
- * @property {string}
+ * Overrides for mobile push notifications.
+ * @typedef  {MobilePush} mobilePush - Overrides for mobile push notifications. - Overrides for mobile push notifications.
+ * @property {string} - The link associated with the channel-specific notification.
+ * @property {string} - The channel-specific content.
+ * @property {string} - The channel-specific title.
  */
 export type MobilePush = z.infer<typeof mobilePush>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the MobilePush application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const mobilePushResponse = z.lazy(() => {
   return z
@@ -39,8 +42,9 @@ export const mobilePushResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the MobilePush application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const mobilePushRequest = z.lazy(() => {
   return z

package/src/project-client/services/broadcasts/models/overrides-channels.ts

@@ -6,7 +6,9 @@ import { MobilePush, mobilePush, mobilePushRequest, mobilePushResponse } from '.
 import { Sms, sms, smsRequest, smsResponse } from './sms.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the OverridesChannels model.
+ * Defines the structure and validation rules for this data type.
+ * This is the shape used in application code - what developers interact with.
  */
 export const overridesChannels = z.lazy(() => {
   return z.object({
@@ -18,18 +20,19 @@ export const overridesChannels = z.lazy(() => {
 });
 
 /**
- *
- * @typedef  {OverridesChannels} overridesChannels
- * @property {Email}
- * @property {InApp}
- * @property {MobilePush}
- * @property {Sms}
+ * Overrides that are scoped to individual delivery channels.
+ * @typedef  {OverridesChannels} overridesChannels - Overrides that are scoped to individual delivery channels. - Overrides that are scoped to individual delivery channels.
+ * @property {Email} - Overrides for email notifications.
+ * @property {InApp} - Overrides for in-app notifications.
+ * @property {MobilePush} - Overrides for mobile push notifications.
+ * @property {Sms} - Overrides for SMS notifications.
  */
 export type OverridesChannels = z.infer<typeof overridesChannels>;
 
 /**
- * The shape of the model mapping from the api schema into the application shape.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping API responses to the OverridesChannels application shape.
+ * Handles any property name transformations from the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const overridesChannelsResponse = z.lazy(() => {
   return z
@@ -48,8 +51,9 @@ export const overridesChannelsResponse = z.lazy(() => {
 });
 
 /**
- * The shape of the model mapping from the application shape into the api schema.
- * Is equal to application shape if all property names match the api schema
+ * Zod schema for mapping the OverridesChannels application shape to API requests.
+ * Handles any property name transformations required by the API schema.
+ * If property names match the API schema exactly, this is identical to the application shape.
  */
 export const overridesChannelsRequest = z.lazy(() => {
   return z