magicbell-js 1.3.0 → 1.4.0

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

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+/**
+ * The shape of the model inside the application code - what the users use
+ */
+export const workflowRunStatus = z.lazy(() => {
+  return z.object({
+    completedAt: z.string().optional(),
+    error: z.string().optional(),
+    nextStep: z.number().optional(),
+    startedAt: z.string().optional(),
+    state: z.number().optional(),
+  });
+});
+
+/**
+ *
+ * @typedef  {WorkflowRunStatus} workflowRunStatus
+ * @property {string}
+ * @property {string}
+ * @property {number}
+ * @property {string}
+ * @property {number}
+ */
+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
+ */
+export const workflowRunStatusResponse = z.lazy(() => {
+  return z
+    .object({
+      completed_at: z.string().optional(),
+      error: z.string().optional(),
+      next_step: z.number().optional(),
+      started_at: z.string().optional(),
+      state: z.number().optional(),
+    })
+    .transform((data) => ({
+      completedAt: data['completed_at'],
+      error: data['error'],
+      nextStep: data['next_step'],
+      startedAt: data['started_at'],
+      state: data['state'],
+    }));
+});
+
+/**
+ * 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
+ */
+export const workflowRunStatusRequest = z.lazy(() => {
+  return z
+    .object({
+      completedAt: z.string().optional(),
+      error: z.string().optional(),
+      nextStep: z.number().optional(),
+      startedAt: z.string().optional(),
+      state: z.number().optional(),
+    })
+    .transform((data) => ({
+      completed_at: data['completedAt'],
+      error: data['error'],
+      next_step: data['nextStep'],
+      started_at: data['startedAt'],
+      state: data['state'],
+    }));
+});

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

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+
+import {
+  WorkflowRunStatus,
+  workflowRunStatus,
+  workflowRunStatusRequest,
+  workflowRunStatusResponse,
+} from './workflow-run-status.js';
+
+/**
+ * The shape of the model inside the application code - what the users use
+ */
+export const workflowRun = z.lazy(() => {
+  return z.object({
+    createdAt: z.string().optional(),
+    id: z.string().optional(),
+    status: workflowRunStatus.optional(),
+    workflowKey: z.string().optional(),
+  });
+});
+
+/**
+ *
+ * @typedef  {WorkflowRun} workflowRun
+ * @property {string}
+ * @property {string}
+ * @property {WorkflowRunStatus}
+ * @property {string}
+ */
+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
+ */
+export const workflowRunResponse = z.lazy(() => {
+  return z
+    .object({
+      created_at: z.string().optional(),
+      id: z.string().optional(),
+      status: workflowRunStatusResponse.optional(),
+      workflow_key: z.string().optional(),
+    })
+    .transform((data) => ({
+      createdAt: data['created_at'],
+      id: data['id'],
+      status: data['status'],
+      workflowKey: data['workflow_key'],
+    }));
+});
+
+/**
+ * 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
+ */
+export const workflowRunRequest = z.lazy(() => {
+  return z
+    .object({
+      createdAt: z.string().optional(),
+      id: z.string().optional(),
+      status: workflowRunStatusRequest.optional(),
+      workflowKey: z.string().optional(),
+    })
+    .transform((data) => ({
+      created_at: data['createdAt'],
+      id: data['id'],
+      status: data['status'],
+      workflow_key: data['workflowKey'],
+    }));
+});

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

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+
+import { Environment } from '../../http/environment.js';
+import { ThrowableError } from '../../http/errors/throwable-error.js';
+import { SerializationStyle } from '../../http/serialization/base-serializer.js';
+import { RequestBuilder } from '../../http/transport/request-builder.js';
+import { ContentType, HttpResponse, RequestConfig } from '../../http/types.js';
+import { BaseService } from '../base-service.js';
+import { CreateRunResponse, createRunResponseResponse } from './models/create-run-response.js';
+import { ExecuteWorkflowRequest, executeWorkflowRequestRequest } from './models/execute-workflow-request.js';
+import { GetRunResponse, getRunResponseResponse } from './models/get-run-response.js';
+import {
+  WorkflowDefinition,
+  workflowDefinitionRequest,
+  workflowDefinitionResponse,
+} from './models/workflow-definition.js';
+import { WorkflowRunCollection, workflowRunCollectionResponse } from './models/workflow-run-collection.js';
+
+export class WorkflowsService extends BaseService {
+  /**
+   * Creates or updates a workflow definition for the project
+   * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
+   * @returns {Promise<HttpResponse<WorkflowDefinition>>} - OK
+   */
+  async saveWorkflow(
+    body: WorkflowDefinition,
+    requestConfig?: RequestConfig,
+  ): Promise<HttpResponse<WorkflowDefinition>> {
+    const request = new RequestBuilder()
+      .setBaseUrl(requestConfig?.baseUrl || this.config.baseUrl || this.config.environment || Environment.DEFAULT)
+      .setConfig(this.config)
+      .setMethod('PUT')
+      .setPath('/workflows')
+      .setRequestSchema(workflowDefinitionRequest)
+      .addAccessTokenAuth(this.config.token, 'Bearer')
+      .setRequestContentType(ContentType.Json)
+      .addResponse({
+        schema: workflowDefinitionResponse,
+        contentType: ContentType.Json,
+        status: 200,
+      })
+      .setRetryAttempts(this.config, requestConfig)
+      .setRetryDelayMs(this.config, requestConfig)
+      .setResponseValidation(this.config, requestConfig)
+      .addHeaderParam({ key: 'Content-Type', value: 'application/json' })
+      .addBody(body)
+      .build();
+    return this.client.call<WorkflowDefinition>(request);
+  }
+
+  /**
+   * Retrieves a workflow definition by key
+   * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
+   * @returns {Promise<HttpResponse<WorkflowDefinition>>} - OK
+   */
+  async fetchWorkflow(requestConfig?: RequestConfig): Promise<HttpResponse<WorkflowDefinition>> {
+    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: workflowDefinitionResponse,
+        contentType: ContentType.Json,
+        status: 200,
+      })
+      .setRetryAttempts(this.config, requestConfig)
+      .setRetryDelayMs(this.config, requestConfig)
+      .setResponseValidation(this.config, requestConfig)
+      .build();
+    return this.client.call<WorkflowDefinition>(request);
+  }
+
+  /**
+   * Executes a workflow with the provided input parameters
+   * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
+   * @returns {Promise<HttpResponse<CreateRunResponse>>} - Created
+   */
+  async createWorkflowRun(
+    body: ExecuteWorkflowRequest,
+    requestConfig?: RequestConfig,
+  ): Promise<HttpResponse<CreateRunResponse>> {
+    const request = new RequestBuilder()
+      .setBaseUrl(requestConfig?.baseUrl || this.config.baseUrl || this.config.environment || Environment.DEFAULT)
+      .setConfig(this.config)
+      .setMethod('POST')
+      .setPath('/workflows/runs')
+      .setRequestSchema(executeWorkflowRequestRequest)
+      .addAccessTokenAuth(this.config.token, 'Bearer')
+      .setRequestContentType(ContentType.Json)
+      .addResponse({
+        schema: createRunResponseResponse,
+        contentType: ContentType.Json,
+        status: 201,
+      })
+      .setRetryAttempts(this.config, requestConfig)
+      .setRetryDelayMs(this.config, requestConfig)
+      .setResponseValidation(this.config, requestConfig)
+      .addHeaderParam({ key: 'Content-Type', value: 'application/json' })
+      .addBody(body)
+      .build();
+    return this.client.call<CreateRunResponse>(request);
+  }
+
+  /**
+   * Retrieves the status and details of a workflow run
+   * @param {string} runId -
+   * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
+   * @returns {Promise<HttpResponse<GetRunResponse>>} - OK
+   */
+  async fetchWorkflowRun(runId: string, requestConfig?: RequestConfig): Promise<HttpResponse<GetRunResponse>> {
+    const request = new RequestBuilder()
+      .setBaseUrl(requestConfig?.baseUrl || this.config.baseUrl || this.config.environment || Environment.DEFAULT)
+      .setConfig(this.config)
+      .setMethod('GET')
+      .setPath('/workflows/runs/{run_id}')
+      .setRequestSchema(z.any())
+      .addAccessTokenAuth(this.config.token, 'Bearer')
+      .setRequestContentType(ContentType.Json)
+      .addResponse({
+        schema: getRunResponseResponse,
+        contentType: ContentType.Json,
+        status: 200,
+      })
+      .setRetryAttempts(this.config, requestConfig)
+      .setRetryDelayMs(this.config, requestConfig)
+      .setResponseValidation(this.config, requestConfig)
+      .addPathParam({
+        key: 'run_id',
+        value: runId,
+      })
+      .build();
+    return this.client.call<GetRunResponse>(request);
+  }
+
+  /**
+   * Retrieves all runs for a specific workflow
+   * @param {string} workflowKey -
+   * @param {RequestConfig} [requestConfig] - The request configuration for retry and validation.
+   * @returns {Promise<HttpResponse<WorkflowRunCollection>>} - OK
+   */
+  async listWorkflowRuns(
+    workflowKey: string,
+    requestConfig?: RequestConfig,
+  ): Promise<HttpResponse<WorkflowRunCollection>> {
+    const request = new RequestBuilder()
+      .setBaseUrl(requestConfig?.baseUrl || this.config.baseUrl || this.config.environment || Environment.DEFAULT)
+      .setConfig(this.config)
+      .setMethod('GET')
+      .setPath('/workflows/{workflow_key}/runs')
+      .setRequestSchema(z.any())
+      .addAccessTokenAuth(this.config.token, 'Bearer')
+      .setRequestContentType(ContentType.Json)
+      .addResponse({
+        schema: workflowRunCollectionResponse,
+        contentType: ContentType.Json,
+        status: 200,
+      })
+      .setRetryAttempts(this.config, requestConfig)
+      .setRetryDelayMs(this.config, requestConfig)
+      .setResponseValidation(this.config, requestConfig)
+      .addPathParam({
+        key: 'workflow_key',
+        value: workflowKey,
+      })
+      .build();
+    return this.client.call<WorkflowRunCollection>(request);
+  }
+}

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

@@ -6,7 +6,8 @@ import { RetryHandler } from './handlers/retry-handler.js';
 import { TerminatingHandler } from './handlers/terminating-handler.js';
 import { CustomHook } from './hooks/custom-hook.js';
 import { Request } from './transport/request.js';
-import { HttpResponse, SdkConfig } from './types.js';
+import { isRequestCursorPagination } from './transport/types.js';
+import { CursorPaginatedHttpResponse, HttpResponse, PaginatedHttpResponse, SdkConfig } from './types.js';
 
 export class HttpClient {
   private readonly requestHandlerChain = new RequestHandlerChain();
@@ -27,16 +28,37 @@ export class HttpClient {
     yield* this.requestHandlerChain.streamChain(request);
   }
 
-  public async callPaginated<FullResponse, Page>(request: Request<Page>): Promise<HttpResponse<Page>> {
+  public async callPaginated<FullResponse, Page>(request: Request<Page>): Promise<PaginatedHttpResponse<Page>> {
     const response = await this.call<FullResponse>(request as any);
 
     if (!response.data) {
       throw new Error('no response data to paginate through');
     }
 
+    const page = this.getPage<FullResponse, Page>(request, response.data);
+
     return {
       ...response,
-      data: this.getPage<FullResponse, Page>(request, response.data),
+      data: page,
+    };
+  }
+
+  public async callCursorPaginated<FullResponse, Page>(
+    request: Request<Page>,
+  ): Promise<CursorPaginatedHttpResponse<Page>> {
+    const response = await this.call<FullResponse>(request as any);
+
+    if (!response.data) {
+      throw new Error('no response data to paginate through');
+    }
+
+    const page = this.getPage<FullResponse, Page>(request, response.data);
+    const nextCursor = this.getNextCursor<FullResponse, Page>(request, response.data);
+
+    return {
+      ...response,
+      data: page,
+      nextCursor,
     };
   }
 
@@ -54,18 +76,34 @@ export class HttpClient {
     }
 
     let curr: any = data;
-    for (const segment of request.pagination?.pagePath || []) {
+    for (const segment of request.pagination.pagePath || []) {
       curr = curr[segment];
     }
 
-    const page = request.pagination?.pageSchema?.parse(curr);
+    const page = request.pagination.pageSchema?.parse(curr);
     if (!page) {
       throw new Error(
         `error getting page data. Curr: ${JSON.stringify(curr)}. PagePath: ${
-          request.pagination?.pagePath
+          request.pagination.pagePath
         }. Data: ${JSON.stringify(data)}`,
       );
     }
     return page;
   }
+
+  private getNextCursor<FullResponse, Page>(request: Request<Page>, data: FullResponse): string | null | undefined {
+    if (!isRequestCursorPagination(request.pagination)) {
+      return undefined;
+    }
+
+    let curr: any = data;
+    for (const segment of request.pagination.cursorPath) {
+      if (curr === null || curr === undefined) {
+        return null;
+      }
+      curr = curr[segment];
+    }
+
+    return request.pagination.cursorSchema?.parse(curr) ?? null;
+  }
 }

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

@@ -29,6 +29,9 @@ export class HookHandler implements RequestHandler {
       return await hook.afterResponse(nextRequest, response, hookParams);
     }
 
+    // Handle error responses
+    const arrayBuffer = response.raw;
+
     const rawContentType = response.metadata.headers['content-type']?.toLocaleLowerCase() || '';
     const contentType = getContentTypeDefinition(rawContentType);
     const statusCode = response.metadata.status;
@@ -38,15 +41,15 @@ export class HookHandler implements RequestHandler {
     });
 
     if (error) {
-      const decodedBody = new TextDecoder().decode(response.raw);
+      const decodedBody = new TextDecoder().decode(arrayBuffer);
       const json = JSON.parse(decodedBody);
       new error.error((json as any)?.message || '', json).throw();
     }
 
-    const decodedBody = new TextDecoder().decode(response.raw);
+    const decodedBody = new TextDecoder().decode(arrayBuffer);
     throw new HttpError(
       response.metadata,
-      response.raw,
+      arrayBuffer,
       `Unexpected response body for error status.\nStatusCode: ${response.metadata.status}\nBody: ${decodedBody}`,
     );
   }

package/src/user-client/http/handlers/request-validation-handler.ts

@@ -48,7 +48,7 @@ export class RequestValidationHandler implements RequestHandler {
     } else if (request.requestContentType === ContentType.FormUrlEncoded) {
       request.body = this.toFormUrlEncoded(request);
     } else if (request.requestContentType === ContentType.MultipartFormData) {
-      request.body = this.toFormData(request.body);
+      request.body = this.toFormData(request.body, request.filename, request.filenames);
     } else {
       request.body = JSON.stringify(request.requestSchema?.parse(request.body));
     }
@@ -92,15 +92,25 @@ export class RequestValidationHandler implements RequestHandler {
     return '';
   }
 
-  toFormData(body: Record<string, any>): FormData | undefined {
+  toFormData(body: Record<string, any>, filename?: string, filenames?: string[]): FormData {
     const formData = new FormData();
 
     Object.keys(body).forEach((key: any) => {
       const value: any = body[key];
       if (Array.isArray(value)) {
-        value.forEach((v, i) => formData.append(`${key}[${i}]`, v));
+        value.forEach((v, i) => {
+          if (v instanceof ArrayBuffer) {
+            // For arrays of files, use the corresponding filename from filenames array
+            const fileFilename = filenames && filenames[i] ? filenames[i] : `${key}[${i}]`;
+            formData.append(`${key}[${i}]`, new Blob([v]), fileFilename);
+          } else {
+            formData.append(`${key}[${i}]`, v);
+          }
+        });
       } else if (value instanceof ArrayBuffer) {
-        formData.append(key, new Blob([value]));
+        // For single files, use the provided filename or fallback to the key name
+        const fileFilename = filename || key;
+        formData.append(key, new Blob([value]), fileFilename);
       } else {
         formData.append(key, value);
       }

package/src/user-client/http/handlers/response-validation-handler.ts

@@ -26,7 +26,7 @@ export class ResponseValidationHandler implements RequestHandler {
   }
 
   private splitByDataChunks<T>(response: HttpResponse<T>): HttpResponse<T>[] {
-    if (!response.metadata.headers['content-type'].includes('text/event-stream')) {
+    if (!response.metadata.headers['content-type']?.includes('text/event-stream')) {
       return [response];
     }
 
@@ -37,7 +37,7 @@ export class ResponseValidationHandler implements RequestHandler {
       .filter((line) => line.startsWith('data: '))
       .map((part) => ({
         ...response,
-        raw: encoder.encode(part),
+        raw: encoder.encode(part).buffer,
       }));
   }
 

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

@@ -45,7 +45,10 @@ export class RetryHandler implements RequestHandler {
   }
 
   private shouldRetry(error: Error): boolean {
-    return error instanceof HttpError && (error.metadata.status >= 500 || error.metadata.status === 408);
+    return (
+      error instanceof HttpError &&
+      (error.metadata.status >= 500 || error.metadata.status === 408 || error.metadata.status === 429)
+    );
   }
 
   private delay(delayMs: number | undefined): Promise<void> {

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

@@ -1,4 +1,4 @@
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+type HttpMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'PUT' | 'TRACE';
 
 export interface HttpRequest {
   baseUrl: string;

package/src/user-client/http/serialization/query-serializer.ts

@@ -10,6 +10,11 @@ export class QuerySerializer extends Serializer {
     const query: string[] = [];
 
     queryParams.forEach((param) => {
+      // Skip parameters with undefined values
+      if (param.value === undefined) {
+        return;
+      }
+
       return query.push(`${this.serializeValue(param)}`);
     });
 

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

@@ -7,6 +7,7 @@ import { Request } from './request.js';
 import {
   CreateRequestParameters,
   ErrorDefinition,
+  RequestCursorPagination,
   RequestPagination,
   RequestParameter,
   ResponseDefinition,
@@ -101,11 +102,30 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
     return this;
   }
 
+  setFilename(filename?: string): RequestBuilder<Page> {
+    if (filename !== undefined) {
+      this.params.filename = filename;
+    }
+    return this;
+  }
+
+  setFilenames(filenames?: string[]): RequestBuilder<Page> {
+    if (filenames !== undefined) {
+      this.params.filenames = filenames;
+    }
+    return this;
+  }
+
   setPagination(pagination: RequestPagination<Page>): RequestBuilder<Page> {
     this.params.pagination = pagination;
     return this;
   }
 
+  setCursorPagination(pagination: RequestCursorPagination<Page>): RequestBuilder<Page> {
+    this.params.pagination = pagination;
+    return this;
+  }
+
   addAccessTokenAuth(accessToken?: string, prefix?: string): RequestBuilder<Page> {
     if (accessToken === undefined) {
       return this;
@@ -119,6 +139,7 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       encode: true,
       isLimit: false,
       isOffset: false,
+      isCursor: false,
     });
     return this;
   }
@@ -136,6 +157,7 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       encode: true,
       isLimit: false,
       isOffset: false,
+      isCursor: false,
     });
     return this;
   }
@@ -153,6 +175,7 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       encode: true,
       isLimit: false,
       isOffset: false,
+      isCursor: false,
     });
     return this;
   }
@@ -187,13 +210,14 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       encode: param.encode ?? true,
       isLimit: !!param.isLimit,
       isOffset: !!param.isOffset,
+      isCursor: !!param.isCursor,
     });
 
     return this;
   }
 
   addQueryParam(param: Partial<RequestParameter>): RequestBuilder<Page> {
-    if (param.value === undefined || param.key === undefined) {
+    if (param.key === undefined) {
       return this;
     }
 
@@ -205,6 +229,7 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       encode: param.encode ?? true,
       isLimit: !!param.isLimit,
       isOffset: !!param.isOffset,
+      isCursor: !!param.isCursor,
     });
 
     return this;
@@ -223,6 +248,7 @@ export class RequestBuilder<Page extends unknown[] = unknown[]> {
       encode: param.encode ?? false,
       isLimit: !!param.isLimit,
       isOffset: !!param.isOffset,
+      isCursor: !!param.isCursor,
     });
 
     return this;

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

@@ -65,7 +65,7 @@ export class RequestFetchAdapter<T> implements HttpAdapter {
       for (const line of lineDecoder.splitLines(value)) {
         yield {
           metadata,
-          raw: line,
+          raw: this.toArrayBuffer(line),
         };
       }
     }
@@ -73,7 +73,7 @@ export class RequestFetchAdapter<T> implements HttpAdapter {
     for (const line of lineDecoder.flush()) {
       yield {
         metadata,
-        raw: line,
+        raw: this.toArrayBuffer(line),
       };
     }
   }
@@ -128,4 +128,8 @@ export class RequestFetchAdapter<T> implements HttpAdapter {
 
     return headers;
   }
+
+  private toArrayBuffer(uint8Array: Uint8Array): ArrayBuffer {
+    return uint8Array.buffer.slice(uint8Array.byteOffset, uint8Array.byteOffset + uint8Array.byteLength);
+  }
 }