magicbell-js 1.5.0 → 1.7.0

package/src/user-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/user-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/user-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/user-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/user-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/user-client/services/channels/channels-service.ts

@@ -55,12 +55,17 @@ import {
   ListWebPushTokensParams,
 } from './request-params.js';
 
+/**
+ * Service class for ChannelsService operations.
+ * Provides methods to interact with ChannelsService-related API endpoints.
+ * All methods return promises and handle request/response serialization automatically.
+ */
 export class ChannelsService extends BaseService {
   /**
    * Lists all Inbox tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<InboxTokenResponseCollection>>} - OK
    */
@@ -192,9 +197,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all APNs tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<ApnsTokenCollection>>} - OK
    */
@@ -326,9 +331,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all Expo tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<ExpoTokenCollection>>} - OK
    */
@@ -460,9 +465,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all FCM tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<FcmTokenCollection>>} - OK
    */
@@ -594,9 +599,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all MagicBell SlackBot tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<SlackTokenCollection>>} - OK
    */
@@ -734,9 +739,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all Slack tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<SlackTokenCollection>>} - OK
    */
@@ -871,9 +876,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all Teams tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<TeamsTokenCollection>>} - OK
    */
@@ -1062,9 +1067,9 @@ export class ChannelsService extends BaseService {
 
   /**
    * Lists all Web Push tokens belonging to the authenticated user. Returns a paginated list of tokens, including their status, creation dates, and associated metadata.
-   * @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<WebPushTokenCollection>>} - OK
    */

package/src/user-client/services/channels/models/apns-token-collection.ts

@@ -4,7 +4,9 @@ import { Links, links, linksRequest, linksResponse } from '../../common/links.js
 import { ApnsToken, apnsToken, apnsTokenRequest, apnsTokenResponse } from './apns-token.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the ApnsTokenCollection 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 apnsTokenCollection = z.lazy(() => {
   return z.object({
@@ -22,8 +24,9 @@ export const apnsTokenCollection = z.lazy(() => {
 export type ApnsTokenCollection = z.infer<typeof apnsTokenCollection>;
 
 /**
- * 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 ApnsTokenCollection 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 apnsTokenCollectionResponse = z.lazy(() => {
   return z
@@ -38,8 +41,9 @@ export const apnsTokenCollectionResponse = 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 ApnsTokenCollection 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 apnsTokenCollectionRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/apns-token-payload.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 ApnsTokenPayload 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 apnsTokenPayload = z.lazy(() => {
   return z.object({
@@ -17,15 +19,16 @@ export const apnsTokenPayload = z.lazy(() => {
 /**
  *
  * @typedef  {ApnsTokenPayload} apnsTokenPayload
- * @property {string} - (Optional) The bundle identifier of the application that is registering this token. Use this field to override the default identifier specified in the projects APNs integration.
- * @property {string}
- * @property {ApnsTokenPayloadInstallationId} - (Optional) The APNs environment the token is registered for. If none is provided we assume the token is used in `production`.
+ * @property {string} - The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.
+ * @property {string} - The APNs device token to register with MagicBell.
+ * @property {ApnsTokenPayloadInstallationId} - The APNs environment this token belongs to. If omitted we assume it targets `production`.
  */
 export type ApnsTokenPayload = z.infer<typeof apnsTokenPayload>;
 
 /**
- * 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 ApnsTokenPayload 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 apnsTokenPayloadResponse = z.lazy(() => {
   return z
@@ -45,8 +48,9 @@ export const apnsTokenPayloadResponse = 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 ApnsTokenPayload 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 apnsTokenPayloadRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/apns-token.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 ApnsToken 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 apnsToken = z.lazy(() => {
   return z.object({
@@ -21,19 +23,20 @@ export const apnsToken = z.lazy(() => {
 /**
  *
  * @typedef  {ApnsToken} apnsToken
- * @property {string} - (Optional) The bundle identifier of the application that is registering this token. Use this field to override the default identifier specified in the projects APNs integration.
- * @property {string}
- * @property {string}
- * @property {string}
- * @property {string}
- * @property {ApnsTokenInstallationId} - (Optional) The APNs environment the token is registered for. If none is provided we assume the token is used in `production`.
- * @property {string}
+ * @property {string} - The bundle identifier of the application registering this token. Use this to override the default identifier configured on the APNs integration.
+ * @property {string} - The timestamp when the token was created.
+ * @property {string} - The APNs device token to register with MagicBell.
+ * @property {string} - The timestamp when the token was discarded, if applicable.
+ * @property {string} - The unique identifier for the token.
+ * @property {ApnsTokenInstallationId} - The APNs environment this token belongs to. If omitted we assume it targets `production`.
+ * @property {string} - The timestamp when the token metadata last changed.
  */
 export type ApnsToken = z.infer<typeof apnsToken>;
 
 /**
- * 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 ApnsToken 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 apnsTokenResponse = z.lazy(() => {
   return z
@@ -61,8 +64,9 @@ export const apnsTokenResponse = 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 ApnsToken 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 apnsTokenRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/categories.ts

@@ -3,7 +3,9 @@ import { z } from 'zod';
 import { Channels, channels, channelsRequest, channelsResponse } from './channels.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the Categories 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 categories = z.lazy(() => {
   return z.object({
@@ -27,8 +29,9 @@ export const categories = z.lazy(() => {
 export type Categories = z.infer<typeof categories>;
 
 /**
- * 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 Categories 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 categoriesResponse = z.lazy(() => {
   return z
@@ -49,8 +52,9 @@ export const categoriesResponse = 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 Categories 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 categoriesRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/channels.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 Channels 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 channels = z.lazy(() => {
   return z.object({
@@ -19,8 +21,9 @@ export const channels = z.lazy(() => {
 export type Channels = z.infer<typeof channels>;
 
 /**
- * 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 Channels 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 channelsResponse = z.lazy(() => {
   return z
@@ -35,8 +38,9 @@ export const channelsResponse = 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 Channels 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 channelsRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/discard-result.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 DiscardResult 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 discardResult = z.lazy(() => {
   return z.object({
@@ -13,14 +15,15 @@ export const discardResult = z.lazy(() => {
 /**
  *
  * @typedef  {DiscardResult} discardResult
- * @property {string}
- * @property {string}
+ * @property {string} - The timestamp when the token was discarded.
+ * @property {string} - The unique identifier for the discarded token.
  */
 export type DiscardResult = z.infer<typeof discardResult>;
 
 /**
- * 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 DiscardResult 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 discardResultResponse = z.lazy(() => {
   return z
@@ -35,8 +38,9 @@ export const discardResultResponse = 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 DiscardResult 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 discardResultRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/expo-token-collection.ts

@@ -4,7 +4,9 @@ import { Links, links, linksRequest, linksResponse } from '../../common/links.js
 import { ExpoToken, expoToken, expoTokenRequest, expoTokenResponse } from './expo-token.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the ExpoTokenCollection 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 expoTokenCollection = z.lazy(() => {
   return z.object({
@@ -22,8 +24,9 @@ export const expoTokenCollection = z.lazy(() => {
 export type ExpoTokenCollection = z.infer<typeof expoTokenCollection>;
 
 /**
- * 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 ExpoTokenCollection 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 expoTokenCollectionResponse = z.lazy(() => {
   return z
@@ -38,8 +41,9 @@ export const expoTokenCollectionResponse = 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 ExpoTokenCollection 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 expoTokenCollectionRequest = z.lazy(() => {
   return z

package/src/user-client/services/channels/models/expo-token-payload.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 ExpoTokenPayload 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 expoTokenPayload = z.lazy(() => {
   return z.object({
@@ -12,13 +14,14 @@ export const expoTokenPayload = z.lazy(() => {
 /**
  *
  * @typedef  {ExpoTokenPayload} expoTokenPayload
- * @property {string}
+ * @property {string} - The Expo push token returned by the Expo client.
  */
 export type ExpoTokenPayload = z.infer<typeof expoTokenPayload>;
 
 /**
- * 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 ExpoTokenPayload 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 expoTokenPayloadResponse = z.lazy(() => {
   return z
@@ -31,8 +34,9 @@ export const expoTokenPayloadResponse = 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 ExpoTokenPayload 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 expoTokenPayloadRequest = z.lazy(() => {
   return z