magicbell-js 1.2.0 → 1.4.0

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);
+  }
 }

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

@@ -9,6 +9,8 @@ import { ContentType, HttpMethod, RetryOptions, SdkConfig, ValidationOptions } f
 import {
   CreateRequestParameters,
   ErrorDefinition,
+  isRequestCursorPagination,
+  RequestCursorPagination,
   RequestPagination,
   RequestParameter,
   ResponseDefinition,
@@ -43,7 +45,11 @@ export class Request<PageSchema = unknown[]> {
 
   public retry: RetryOptions = {} as any;
 
-  public pagination?: RequestPagination<PageSchema>;
+  public pagination?: RequestPagination<PageSchema> | RequestCursorPagination<PageSchema>;
+
+  public filename?: string;
+
+  public filenames?: string[];
 
   private readonly pathPattern: string;
 
@@ -64,6 +70,8 @@ export class Request<PageSchema = unknown[]> {
     this.retry = params.retry;
     this.validation = params.validation;
     this.pagination = params.pagination;
+    this.filename = params.filename;
+    this.filenames = params.filenames;
   }
 
   addHeaderParam(key: string, param: RequestParameter): void {
@@ -165,6 +173,8 @@ export class Request<PageSchema = unknown[]> {
       requestContentType: overrides?.requestContentType ?? this.requestContentType,
       retry: overrides?.retry ?? this.retry,
       validation: overrides?.validation ?? this.validation,
+      filename: overrides?.filename ?? this.filename,
+      filenames: overrides?.filenames ?? this.filenames,
     };
     return new Request({
       ...createRequestParams,
@@ -180,17 +190,28 @@ export class Request<PageSchema = unknown[]> {
     return new HeaderSerializer().serialize(this.headers);
   }
 
-  public nextPage(): void {
+  public nextPage(cursor?: string): void {
     if (!this.pagination) {
       return;
     }
 
-    const offsetParam = this.getOffsetParam();
-    if (!offsetParam) {
+    // Check if this is cursor pagination using type guard
+    if (isRequestCursorPagination(this.pagination)) {
+      const cursorParam = this.getCursorParam();
+      if (cursorParam && cursor !== undefined) {
+        cursorParam.value = cursor;
+      }
       return;
     }
 
-    offsetParam.value = Number(offsetParam.value) + this.pagination.pageSize;
+    // Handle limit-offset pagination
+    const offsetParam = this.getOffsetParam();
+    if (offsetParam) {
+      if (this.pagination.pageSize === undefined) {
+        throw new Error('pageSize is required for limit-offset pagination');
+      }
+      offsetParam.value = Number(offsetParam.value) + this.pagination.pageSize;
+    }
   }
 
   private constructPath(): string {
@@ -202,6 +223,11 @@ export class Request<PageSchema = unknown[]> {
     return offsetParam;
   }
 
+  private getCursorParam(): RequestParameter | undefined {
+    const cursorParam = this.getAllParams().find((param) => param.isCursor);
+    return cursorParam;
+  }
+
   private getAllParams(): RequestParameter[] {
     const allParams: RequestParameter[] = [];
 

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

@@ -84,6 +84,7 @@ export class TransportHookAdapter<T> {
         explode: requestParam?.explode ?? false,
         isLimit: requestParam?.isLimit ?? false,
         isOffset: requestParam?.isOffset ?? false,
+        isCursor: requestParam?.isCursor ?? false,
       });
     });
     return transportParams;

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

@@ -31,7 +31,9 @@ export interface CreateRequestParameters<Page = unknown[]> {
   requestContentType: ContentType;
   validation: ValidationOptions;
   retry: RetryOptions;
-  pagination?: RequestPagination<Page>;
+  pagination?: RequestPagination<Page> | RequestCursorPagination<Page>;
+  filename?: string;
+  filenames?: string[];
 }
 
 export interface RequestParameter {
@@ -42,10 +44,24 @@ export interface RequestParameter {
   style: SerializationStyle;
   isLimit: boolean;
   isOffset: boolean;
+  isCursor: boolean;
 }
 
 export interface RequestPagination<Page> {
-  pageSize: number;
+  pageSize?: number;
   pagePath: string[];
   pageSchema?: ZodType<Page, any, any>;
 }
+
+export interface RequestCursorPagination<Page> {
+  pagePath: string[];
+  pageSchema?: ZodType<Page, any, any>;
+  cursorPath: string[];
+  cursorSchema?: ZodType<string | null | undefined>;
+}
+
+export function isRequestCursorPagination<Page>(
+  pagination: RequestPagination<Page> | RequestCursorPagination<Page> | undefined,
+): pagination is RequestCursorPagination<Page> {
+  return !!pagination && 'cursorPath' in pagination;
+}

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

@@ -3,7 +3,7 @@ import { ZodType } from 'zod';
 import { Environment } from './environment.js';
 import { Request } from './transport/request.js';
 
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type HttpMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'PUT' | 'TRACE';
 
 export interface SdkConfig {
   baseUrl?: string;
@@ -26,6 +26,14 @@ export interface HttpResponse<T = unknown> {
   raw: ArrayBuffer;
 }
 
+export interface PaginatedHttpResponse<T = unknown> extends HttpResponse<T> {
+  // Marker interface for pagination responses
+}
+
+export interface CursorPaginatedHttpResponse<T = unknown> extends HttpResponse<T> {
+  nextCursor?: string | null;
+}
+
 export interface RequestHandler {
   next?: RequestHandler;
 

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

@@ -1,33 +1,50 @@
 import { ContentType } from '../types.js';
 
 export function getContentTypeDefinition(contentType: string): ContentType {
-  if (contentType.startsWith('application/') && contentType.includes('xml')) {
+  const ct = contentType.toLowerCase();
+
+  if (ct.startsWith('application/') && ct.includes('xml')) {
     return ContentType.Xml;
   }
 
-  if (contentType.toLowerCase() === 'application/x-www-form-urlencoded') {
+  if (ct === 'application/x-www-form-urlencoded') {
     return ContentType.FormUrlEncoded;
   }
 
-  if (contentType.toLowerCase() === 'text/event-stream') {
+  if (ct === 'text/event-stream') {
     return ContentType.EventStream;
   }
 
-  if (contentType.toLowerCase().startsWith('text/')) {
+  // Check for JSON content types (including text/json) before text types
+  if (ct === 'application/json' || ct === 'text/json' || ct.includes('+json')) {
+    return ContentType.Json;
+  }
+
+  if (ct === 'application/javascript') {
+    return ContentType.Text;
+  }
+
+  if (ct.startsWith('text/')) {
+    return ContentType.Text;
+  }
+
+  // SVG is text-based XML, not binary
+  if (ct === 'image/svg+xml') {
     return ContentType.Text;
   }
 
-  if (contentType.toLowerCase().startsWith('image/')) {
+  if (ct.startsWith('image/')) {
     return ContentType.Image;
   }
 
-  if (contentType.toLowerCase() === 'application/octet-stream') {
+  if (ct === 'application/octet-stream' || ct === 'application/pdf') {
     return ContentType.Binary;
   }
 
-  if (contentType.toLowerCase() === 'application/json') {
-    return ContentType.Json;
+  // Wildcard content type
+  if (ct === '*/*') {
+    return ContentType.Binary;
   }
 
-  return ContentType.Json;
+  return ContentType.Binary;
 }