magicbell-js 1.5.0 → 1.6.0

package/src/project-client/services/workflows/models/workflow-definition-steps.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for the WorkflowDefinitionSteps 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 workflowDefinitionSteps = z.lazy(() => {
+  return z.object({
+    command: z.string().regex(/^[a-z_]+$/),
+    if: z.string().optional().nullable(),
+    input: z.any().optional().nullable(),
+  });
+});
+
+/**
+ *
+ * @typedef  {WorkflowDefinitionSteps} workflowDefinitionSteps
+ * @property {string} - Command to execute (e.g., broadcast, pause, wait, abort)
+ * @property {string} - JMESPath condition that must evaluate truthy for the step to run.
+ * @property {any} - Optional payload passed to the command when it executes.
+ */
+export type WorkflowDefinitionSteps = z.infer<typeof workflowDefinitionSteps>;
+
+/**
+ * Zod schema for mapping API responses to the WorkflowDefinitionSteps 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 workflowDefinitionStepsResponse = z.lazy(() => {
+  return z
+    .object({
+      command: z.string().regex(/^[a-z_]+$/),
+      if: z.string().optional().nullable(),
+      input: z.any().optional().nullable(),
+    })
+    .transform((data) => ({
+      command: data['command'],
+      if: data['if'],
+      input: data['input'],
+    }));
+});
+
+/**
+ * Zod schema for mapping the WorkflowDefinitionSteps 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 workflowDefinitionStepsRequest = z.lazy(() => {
+  return z
+    .object({
+      command: z.string().regex(/^[a-z_]+$/),
+      if: z.string().optional().nullable(),
+      input: z.any().optional().nullable(),
+    })
+    .transform((data) => ({
+      command: data['command'],
+      if: data['if'],
+      input: data['input'],
+    }));
+});

package/src/project-client/services/workflows/models/workflow-definition.ts

@@ -1,9 +1,16 @@
 import { z } from 'zod';
 
-import { Steps, steps, stepsRequest, stepsResponse } from './steps.js';
+import {
+  WorkflowDefinitionSteps,
+  workflowDefinitionSteps,
+  workflowDefinitionStepsRequest,
+  workflowDefinitionStepsResponse,
+} from './workflow-definition-steps.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the WorkflowDefinition 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 workflowDefinition = z.lazy(() => {
   return z.object({
@@ -12,22 +19,23 @@ export const workflowDefinition = z.lazy(() => {
       .string()
       .min(3)
       .regex(/^[A-Za-z0-9\_\.\-\:]+$/),
-    steps: z.array(steps),
+    steps: z.array(workflowDefinitionSteps),
   });
 });
 
 /**
  *
  * @typedef  {WorkflowDefinition} workflowDefinition
- * @property {boolean}
- * @property {string}
- * @property {Steps[]}
+ * @property {boolean} - When true, prevents the workflow from being triggered.
+ * @property {string} - Unique identifier for this workflow definition.
+ * @property {WorkflowDefinitionSteps[]} - Ordered list describing each action that will run inside the workflow.
  */
 export type WorkflowDefinition = z.infer<typeof workflowDefinition>;
 
 /**
- * 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 WorkflowDefinition 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 workflowDefinitionResponse = z.lazy(() => {
   return z
@@ -37,7 +45,7 @@ export const workflowDefinitionResponse = z.lazy(() => {
         .string()
         .min(3)
         .regex(/^[A-Za-z0-9\_\.\-\:]+$/),
-      steps: z.array(stepsResponse),
+      steps: z.array(workflowDefinitionStepsResponse),
     })
     .transform((data) => ({
       disabled: data['disabled'],
@@ -47,8 +55,9 @@ export const workflowDefinitionResponse = 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 WorkflowDefinition 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 workflowDefinitionRequest = z.lazy(() => {
   return z
@@ -58,7 +67,7 @@ export const workflowDefinitionRequest = z.lazy(() => {
         .string()
         .min(3)
         .regex(/^[A-Za-z0-9\_\.\-\:]+$/),
-      steps: z.array(stepsRequest),
+      steps: z.array(workflowDefinitionStepsRequest),
     })
     .transform((data) => ({
       disabled: data['disabled'],

package/src/project-client/services/workflows/models/workflow-list.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+import { Items, items, itemsRequest, itemsResponse } from './items.js';
+
+/**
+ * Zod schema for the WorkflowList 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 workflowList = z.lazy(() => {
+  return z.object({
+    items: z.array(items).optional(),
+  });
+});
+
+/**
+ *
+ * @typedef  {WorkflowList} workflowList
+ * @property {Items[]}
+ */
+export type WorkflowList = z.infer<typeof workflowList>;
+
+/**
+ * Zod schema for mapping API responses to the WorkflowList 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 workflowListResponse = z.lazy(() => {
+  return z
+    .object({
+      items: z.array(itemsResponse).optional(),
+    })
+    .transform((data) => ({
+      items: data['items'],
+    }));
+});
+
+/**
+ * Zod schema for mapping the WorkflowList 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 workflowListRequest = z.lazy(() => {
+  return z
+    .object({
+      items: z.array(itemsRequest).optional(),
+    })
+    .transform((data) => ({
+      items: data['items'],
+    }));
+});

package/src/project-client/services/workflows/models/workflow-run-collection.ts

@@ -4,7 +4,9 @@ import { Links, links, linksRequest, linksResponse } from '../../common/links.js
 import { WorkflowRun, workflowRun, workflowRunRequest, workflowRunResponse } from './workflow-run.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the WorkflowRunCollection 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 workflowRunCollection = z.lazy(() => {
   return z.object({
@@ -22,8 +24,9 @@ export const workflowRunCollection = z.lazy(() => {
 export type WorkflowRunCollection = z.infer<typeof workflowRunCollection>;
 
 /**
- * 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 WorkflowRunCollection 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 workflowRunCollectionResponse = z.lazy(() => {
   return z
@@ -38,8 +41,9 @@ export const workflowRunCollectionResponse = 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 WorkflowRunCollection 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 workflowRunCollectionRequest = z.lazy(() => {
   return z

package/src/project-client/services/workflows/models/workflow-run-status.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 WorkflowRunStatus 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 workflowRunStatus = z.lazy(() => {
   return z.object({
@@ -25,8 +27,9 @@ export const workflowRunStatus = z.lazy(() => {
 export type WorkflowRunStatus = z.infer<typeof workflowRunStatus>;
 
 /**
- * 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 WorkflowRunStatus 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 workflowRunStatusResponse = z.lazy(() => {
   return z
@@ -47,8 +50,9 @@ export const workflowRunStatusResponse = 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 WorkflowRunStatus 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 workflowRunStatusRequest = z.lazy(() => {
   return z

package/src/project-client/services/workflows/models/workflow-run.ts

@@ -8,7 +8,9 @@ import {
 } from './workflow-run-status.js';
 
 /**
- * The shape of the model inside the application code - what the users use
+ * Zod schema for the WorkflowRun 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 workflowRun = z.lazy(() => {
   return z.object({
@@ -30,8 +32,9 @@ export const workflowRun = z.lazy(() => {
 export type WorkflowRun = z.infer<typeof workflowRun>;
 
 /**
- * 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 WorkflowRun 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 workflowRunResponse = z.lazy(() => {
   return z
@@ -50,8 +53,9 @@ export const workflowRunResponse = 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 WorkflowRun 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 workflowRunRequest = z.lazy(() => {
   return z

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

@@ -14,9 +14,41 @@ import {
   workflowDefinitionRequest,
   workflowDefinitionResponse,
 } from './models/workflow-definition.js';
+import { WorkflowList, workflowListResponse } from './models/workflow-list.js';
 import { WorkflowRunCollection, workflowRunCollectionResponse } from './models/workflow-run-collection.js';
 
+/**
+ * Service class for WorkflowsService operations.
+ * Provides methods to interact with WorkflowsService-related API endpoints.
+ * All methods return promises and handle request/response serialization automatically.
+ */
 export class WorkflowsService extends BaseService {
+  /**
+   * Retrieves all workflow definitions for the project
+   * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
+   * @returns {Promise<HttpResponse<WorkflowList>>} - OK
+   */
+  async fetchWorkflows(requestConfig?: RequestConfig): Promise<HttpResponse<WorkflowList>> {
+    const request = new RequestBuilder()
+      .setBaseUrl(requestConfig?.baseUrl || this.config.baseUrl || this.config.environment || Environment.DEFAULT)
+      .setConfig(this.config)
+      .setMethod('GET')
+      .setPath('/workflows')
+      .setRequestSchema(z.any())
+      .addAccessTokenAuth(this.config.token, 'Bearer')
+      .setRequestContentType(ContentType.Json)
+      .addResponse({
+        schema: workflowListResponse,
+        contentType: ContentType.Json,
+        status: 200,
+      })
+      .setRetryAttempts(this.config, requestConfig)
+      .setRetryDelayMs(this.config, requestConfig)
+      .setResponseValidation(this.config, requestConfig)
+      .build();
+    return this.client.call<WorkflowList>(request);
+  }
+
   /**
    * Creates or updates a workflow definition for the project
    * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.

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

@@ -9,9 +9,19 @@ import { Request } from './transport/request.js';
 import { isRequestCursorPagination } from './transport/types.js';
 import { CursorPaginatedHttpResponse, HttpResponse, PaginatedHttpResponse, SdkConfig } from './types.js';
 
+/**
+ * Core HTTP client for making API requests.
+ * Manages request/response handling through a chain of handlers for validation, retry, hooks, and more.
+ */
 export class HttpClient {
+  /** Chain of request handlers that process requests in sequence */
   private readonly requestHandlerChain = new RequestHandlerChain();
 
+  /**
+   * Creates a new HTTP client with configured request handlers.
+   * @param config - SDK configuration including base URL and authentication
+   * @param hook - Optional custom hook for request/response interception
+   */
   constructor(private config: SdkConfig, hook = new CustomHook()) {
     this.requestHandlerChain.addHandler(new ResponseValidationHandler());
     this.requestHandlerChain.addHandler(new RequestValidationHandler());
@@ -20,14 +30,34 @@ export class HttpClient {
     this.requestHandlerChain.addHandler(new TerminatingHandler());
   }
 
+  /**
+   * Executes a standard HTTP request.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to execute
+   * @returns A promise that resolves to the HTTP response
+   */
   call<T>(request: Request): Promise<HttpResponse<T>> {
     return this.requestHandlerChain.callChain(request);
   }
 
+  /**
+   * Executes a streaming HTTP request that yields responses incrementally.
+   * @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* this.requestHandlerChain.streamChain(request);
   }
 
+  /**
+   * Executes a paginated HTTP request and extracts the page data from the response.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The paginated HTTP request to execute
+   * @returns A promise that resolves to the paginated HTTP response
+   * @throws Error if the response contains no data to paginate through
+   */
   public async callPaginated<FullResponse, Page>(request: Request<Page>): Promise<PaginatedHttpResponse<Page>> {
     const response = await this.call<FullResponse>(request as any);
 
@@ -43,6 +73,14 @@ export class HttpClient {
     };
   }
 
+  /**
+   * Executes a cursor-paginated HTTP request and extracts both page data and the next cursor.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The cursor-paginated HTTP request to execute
+   * @returns A promise that resolves to the cursor-paginated HTTP response with next cursor
+   * @throws Error if the response contains no data to paginate through
+   */
   public async callCursorPaginated<FullResponse, Page>(
     request: Request<Page>,
   ): Promise<CursorPaginatedHttpResponse<Page>> {
@@ -62,14 +100,31 @@ export class HttpClient {
     };
   }
 
+  /**
+   * Updates the base URL for all subsequent requests.
+   * @param url - The new base URL to use
+   */
   setBaseUrl(url: string): void {
     this.config.baseUrl = url;
   }
 
+  /**
+   * Updates the SDK configuration.
+   * @param config - The new SDK configuration
+   */
   setConfig(config: SdkConfig): void {
     this.config = config;
   }
 
+  /**
+   * Extracts page data from a full API response using the configured pagination path.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The request containing pagination configuration
+   * @param data - The full response data to extract the page from
+   * @returns The extracted and parsed page data
+   * @throws Error if pagination is not configured or page extraction fails
+   */
   private getPage<FullResponse, Page>(request: Request<Page>, data: FullResponse): Page {
     if (!request.pagination) {
       throw new Error('getPage called for request without pagination property');
@@ -91,6 +146,14 @@ export class HttpClient {
     return page;
   }
 
+  /**
+   * Extracts the next cursor from a full API response for cursor-based pagination.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The request containing cursor pagination configuration
+   * @param data - The full response data to extract the cursor from
+   * @returns The next cursor string, null if no more pages, or undefined if not cursor pagination
+   */
   private getNextCursor<FullResponse, Page>(request: Request<Page>, data: FullResponse): string | null | undefined {
     if (!isRequestCursorPagination(request.pagination)) {
       return undefined;

package/src/user-client/http/environment.ts

@@ -1,3 +1,8 @@
+/**
+ * Available API environments with their base URLs.
+ * Use these constants to configure the SDK for different environments (production, staging, etc.).
+ */
 export enum Environment {
+  /** DEFAULT environment base URL */
   DEFAULT = 'https://api.magicbell.com/v2',
 }

package/src/user-client/http/error.ts

@@ -1,10 +1,23 @@
 import { HttpMetadata } from './types.js';
 
+/**
+ * Error class for HTTP request failures.
+ * Captures error details including status, metadata, and the raw response.
+ */
 export class HttpError extends Error {
+  /** Error message or status text */
   public readonly error: string;
+  /** HTTP response metadata (status, headers, etc.) */
   public readonly metadata: HttpMetadata;
+  /** Raw response object from the HTTP client */
   public readonly raw?: ArrayBuffer;
 
+  /**
+   * Creates a new HTTP error.
+   * @param metadata - HTTP response metadata
+   * @param raw - Raw response object (optional)
+   * @param error - Custom error message (optional, defaults to status text)
+   */
   constructor(metadata: HttpMetadata, raw?: ArrayBuffer, error?: string) {
     super(error);
     this.error = metadata.statusText;

package/src/user-client/http/errors/throwable-error.ts

@@ -1,8 +1,22 @@
+/**
+ * Error class that can be thrown explicitly via a throw() method.
+ * Extends the built-in Error class with a convenience method for throwing.
+ */
 export class ThrowableError extends Error {
+  /**
+   * Creates a new throwable error.
+   * @param message - The error message
+   * @param response - Optional response data associated with the error
+   */
   constructor(public message: string, protected response?: unknown) {
     super(message);
   }
 
+  /**
+   * Throws this error instance.
+   * Convenience method for explicitly throwing the error.
+   * @throws This error instance
+   */
   public throw() {
     throw this;
   }

package/src/user-client/http/errors/validation-error.ts

@@ -1,8 +1,18 @@
 import { ZodError } from 'zod';
 
+/**
+ * Error class for data validation failures using Zod schemas.
+ * Provides detailed information about which properties failed validation and why.
+ */
 export class ValidationError extends Error {
+  /** Formatted error message with validation details */
   public readonly error: string;
 
+  /**
+   * Creates a new validation error from a Zod error.
+   * @param zodError - The Zod validation error containing issue details
+   * @param object - The object that failed validation
+   */
   constructor(zodError: ZodError, object: any) {
     let actual: string;
     try {

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

@@ -1,9 +1,19 @@
 import { Request } from '../transport/request.js';
 import { HttpResponse, RequestHandler } from '../types.js';
 
+/**
+ * Chain of Responsibility pattern implementation for request handlers.
+ * Manages a linked chain of handlers that process HTTP requests sequentially.
+ */
 export class RequestHandlerChain {
+  /** Array of handlers in the chain */
   private readonly handlers: RequestHandler[] = [];
 
+  /**
+   * Adds a handler to the end of the chain.
+   * Links the new handler to the previous one in the chain.
+   * @param handler - The request handler to add
+   */
   addHandler(handler: RequestHandler): void {
     if (this.handlers.length > 0) {
       const previousHandler = this.handlers[this.handlers.length - 1];
@@ -12,6 +22,13 @@ export class RequestHandlerChain {
     this.handlers.push(handler);
   }
 
+  /**
+   * Executes the handler chain for a standard request.
+   * @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 handlers are added to the chain
+   */
   async callChain<T>(request: Request): Promise<HttpResponse<T>> {
     if (!this.handlers.length) {
       throw new Error('No handlers added to the chain');
@@ -20,6 +37,13 @@ export class RequestHandlerChain {
     return this.handlers[0].handle<T>(request);
   }
 
+  /**
+   * Executes the handler chain for a streaming 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
+   * @throws Error if no handlers are added to the chain
+   */
   async *streamChain<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
     if (!this.handlers.length) {
       throw new Error('No handlers added to the chain');

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

@@ -7,11 +7,24 @@ import { ErrorDefinition } from '../transport/types.js';
 import { ContentType, HttpResponse, RequestHandler } from '../types.js';
 import { getContentTypeDefinition } from '../utils/content-type.js';
 
+/**
+ * Request handler that invokes custom hooks before requests and after responses.
+ * Enables request/response interception and custom error handling.
+ */
 export class HookHandler implements RequestHandler {
+  /** Next handler in the chain */
   next?: RequestHandler;
 
   constructor(private readonly hook: Hook) {}
 
+  /**
+   * Handles a standard HTTP request with hook invocation.
+   * Calls beforeRequest hook, processes the request, and calls afterResponse or onError hooks.
+   * @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 error handling fails
+   */
   async handle<T>(request: Request): Promise<HttpResponse<T>> {
     if (!this.next) {
       throw new Error('No next handler set in hook handler.');
@@ -54,6 +67,14 @@ export class HookHandler implements RequestHandler {
     );
   }
 
+  /**
+   * Handles a streaming HTTP request with hook invocation.
+   * Calls beforeRequest hook and afterResponse/onError hooks for each chunk.
+   * @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 error handling fails
+   */
   async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
     if (!this.next) {
       throw new Error('No next handler set in hook handler.');
@@ -76,6 +97,12 @@ export class HookHandler implements RequestHandler {
     }
   }
 
+  /**
+   * Extracts hook parameters from the request configuration.
+   * @template T - The response data type
+   * @param request - The HTTP request
+   * @returns A map of hook parameter names to values
+   */
   private getHookParams<T>(_request: Request): Map<string, string> {
     const hookParams: Map<string, string> = new Map();
     return hookParams;