magicbell-js 0.0.3 → 0.1.0

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

@@ -0,0 +1,203 @@
+import { ZodUndefined } from 'zod';
+
+import { Request } from '../transport/request.js';
+import { ResponseDefinition } from '../transport/types.js';
+import { ContentType, HttpResponse, RequestHandler } from '../types.js';
+import { ResponseMatcher } from '../utils/response-matcher.js';
+
+export class ResponseValidationHandler implements RequestHandler {
+  next?: RequestHandler;
+
+  async handle<T>(request: Request): Promise<HttpResponse<T>> {
+    const response = await this.next!.handle<T>(request);
+
+    return this.decodeBody<T>(request, response);
+  }
+
+  async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    const stream = this.next!.stream<T>(request);
+
+    for await (const response of stream) {
+      const responseChunks = this.splitByDataChunks<T>(response);
+      for (const chunk of responseChunks) {
+        yield this.decodeBody<T>(request, chunk);
+      }
+    }
+  }
+
+  private splitByDataChunks<T>(response: HttpResponse<T>): HttpResponse<T>[] {
+    if (!response.metadata.headers['content-type'].includes('text/event-stream')) {
+      return [response];
+    }
+
+    const text = new TextDecoder().decode(response.raw);
+    const encoder = new TextEncoder();
+    return text
+      .split('\n')
+      .filter((line) => line.startsWith('data: '))
+      .map((part) => ({
+        ...response,
+        raw: encoder.encode(part),
+      }));
+  }
+
+  private decodeBody<T>(request: Request, response: HttpResponse<T>): HttpResponse<T> {
+    const responseMatcher = new ResponseMatcher(request.responses);
+    const responseDefinition = responseMatcher.getResponseDefinition(response);
+
+    if (!responseDefinition || !this.hasContent(responseDefinition, response)) {
+      return response;
+    }
+
+    const contentType = responseDefinition.contentType;
+    const contentTypeHandlers: {
+      [key: string]: (req: Request, resDef: ResponseDefinition, res: HttpResponse<T>) => HttpResponse<T>;
+    } = {
+      [ContentType.Binary]: this.decodeFile,
+      [ContentType.Image]: this.decodeFile,
+      [ContentType.MultipartFormData]: this.decodeMultipartFormData,
+      [ContentType.Text]: this.decodeText,
+      [ContentType.Xml]: this.decodeText,
+      [ContentType.FormUrlEncoded]: this.decodeFormUrlEncoded,
+      [ContentType.EventStream]: this.decodeEventStream,
+    };
+
+    if (contentTypeHandlers[contentType]) {
+      return contentTypeHandlers[contentType].call(this, request, responseDefinition, response);
+    }
+
+    if (response.metadata.headers['content-type']?.includes('text/event-stream')) {
+      return this.decodeEventStream(request, responseDefinition, response);
+    }
+
+    return this.decodeJson(request, responseDefinition, response);
+  }
+
+  private decodeFile<T>(
+    request: Request,
+    responseDefinition: ResponseDefinition,
+    response: HttpResponse<T>,
+  ): HttpResponse<T> {
+    return {
+      ...response,
+      data: this.validate<T>(request, responseDefinition, response.raw),
+    };
+  }
+
+  private decodeMultipartFormData<T>(
+    request: Request,
+    responseDefinition: ResponseDefinition,
+    response: HttpResponse<T>,
+  ): HttpResponse<T> {
+    const formData = this.fromFormData(response.raw);
+    return {
+      ...response,
+      data: this.validate<T>(request, responseDefinition, formData),
+    };
+  }
+
+  private decodeText<T>(
+    request: Request,
+    responseDefinition: ResponseDefinition,
+    response: HttpResponse<T>,
+  ): HttpResponse<T> {
+    const decodedBody = new TextDecoder().decode(response.raw);
+    return {
+      ...response,
+      data: this.validate<T>(request, responseDefinition, decodedBody),
+    };
+  }
+
+  private decodeFormUrlEncoded<T>(
+    request: Request,
+    responseDefinition: ResponseDefinition,
+    response: HttpResponse<T>,
+  ): HttpResponse<T> {
+    const decodedBody = new TextDecoder().decode(response.raw);
+    const urlEncoded = this.fromUrlEncoded(decodedBody);
+    return {
+      ...response,
+      data: this.validate<T>(request, responseDefinition, urlEncoded),
+    };
+  }
+
+  private decodeEventStream<T>(
+    request: Request,
+    responseDefinition: ResponseDefinition,
+    response: HttpResponse<T>,
+  ): HttpResponse<T> {
+    let decodedBody = new TextDecoder().decode(response.raw);
+    if (decodedBody.startsWith('data: ')) {
+      decodedBody = decodedBody.substring(6);
+    }
+    // Note: this assumes that the content of data is a valid JSON string
+    const json = JSON.parse(decodedBody);
+    return {
+      ...response,
+      data: this.validate<T>(request, responseDefinition, json),
+    };
+  }
+
+  private decodeJson<T>(
+    request: Request,
+    responseDefinition: ResponseDefinition,
+    response: HttpResponse<T>,
+  ): HttpResponse<T> {
+    const decodedBody = new TextDecoder().decode(response.raw);
+    const json = JSON.parse(decodedBody);
+    return {
+      ...response,
+      data: this.validate<T>(request, responseDefinition, json),
+    };
+  }
+
+  private validate<T>(request: Request, response: ResponseDefinition, data: any): T {
+    if (request.validation?.responseValidation) {
+      return response.schema.parse(data);
+    }
+    return data;
+  }
+
+  private hasContent<T>(responseDefinition: ResponseDefinition, response: HttpResponse<T>): boolean {
+    return (
+      !!responseDefinition.schema &&
+      !(responseDefinition.schema instanceof ZodUndefined) &&
+      response.metadata.status !== 204
+    );
+  }
+
+  private fromUrlEncoded(urlEncodedData: string): object {
+    const pairs = urlEncodedData.split('&');
+    const result: Record<string, string> = {};
+
+    pairs.forEach((pair) => {
+      const [key, value] = pair.split('=');
+      if (key && value !== undefined) {
+        result[decodeURIComponent(key)] = decodeURIComponent(value);
+      }
+    });
+
+    return result;
+  }
+
+  private fromFormData(arrayBuffer: ArrayBuffer): Record<string, string> {
+    const decoder = new TextDecoder();
+    const text = decoder.decode(arrayBuffer);
+
+    const boundary = text.split('\r\n')[0];
+    const parts = text.split(boundary).slice(1, -1);
+
+    const formDataObj: Record<string, string> = {};
+
+    parts.forEach((part) => {
+      const [header, value] = part.split('\r\n\r\n');
+      const nameMatch = header.match(/name="([^"]+)"/);
+      if (nameMatch) {
+        const name = nameMatch[1].trim();
+        formDataObj[name] = value?.trim() || '';
+      }
+    });
+
+    return formDataObj;
+  }
+}

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

@@ -0,0 +1,60 @@
+import { HttpError } from '../error.js';
+import { Request } from '../transport/request.js';
+import { HttpResponse, RequestHandler } from '../types.js';
+
+export class RetryHandler implements RequestHandler {
+  next?: RequestHandler;
+
+  async handle<T>(request: Request): Promise<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in retry handler.');
+    }
+
+    for (let attempt = 1; attempt <= request.retry.attempts; attempt++) {
+      try {
+        return await this.next.handle<T>(request);
+      } catch (error: any) {
+        if (!this.shouldRetry(error) || attempt === request.retry.attempts) {
+          throw error;
+        }
+        await this.delay(request.retry.delayMs);
+      }
+    }
+
+    throw new Error('Error retrying request.');
+  }
+
+  async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in retry handler.');
+    }
+
+    for (let attempt = 1; attempt <= request.retry.attempts; attempt++) {
+      try {
+        yield* this.next.stream<T>(request);
+        return;
+      } catch (error: any) {
+        if (!this.shouldRetry(error) || attempt === request.retry.attempts) {
+          throw error;
+        }
+        await this.delay(request.retry.delayMs);
+      }
+    }
+
+    throw new Error('Error retrying request.');
+  }
+
+  private shouldRetry(error: Error): boolean {
+    return error instanceof HttpError && (error.metadata.status >= 500 || error.metadata.status === 408);
+  }
+
+  private delay(delayMs: number | undefined): Promise<void> {
+    if (!delayMs) {
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve, reject) => {
+      setTimeout(() => resolve(), delayMs);
+    });
+  }
+}

package/src/project-client/http/handlers/terminating-handler.ts

@@ -0,0 +1,14 @@
+import { HttpError } from '../error.js';
+import { Request } from '../transport/request.js';
+import { RequestFetchAdapter } from '../transport/request-fetch-adapter.js';
+import { HttpResponse, RequestHandler } from '../types.js';
+
+export class TerminatingHandler implements RequestHandler {
+  async handle<T>(request: Request): Promise<HttpResponse<T>> {
+    return new RequestFetchAdapter<T>(request).send();
+  }
+
+  async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    yield* new RequestFetchAdapter<T>(request).stream();
+  }
+}

package/src/project-client/http/hooks/custom-hook.ts

@@ -0,0 +1,25 @@
+import { HttpError } from '../error.js';
+import { HttpMetadata } from '../types.js';
+import { Hook, HttpRequest, HttpResponse } from './hook.js';
+
+export class CustomHook implements Hook {
+  public async beforeRequest(request: HttpRequest, params: Map<string, string>): Promise<HttpRequest> {
+    return request;
+  }
+
+  public async afterResponse(
+    request: HttpRequest,
+    response: HttpResponse<any>,
+    params: Map<string, string>,
+  ): Promise<HttpResponse<any>> {
+    return response;
+  }
+
+  public async onError(
+    request: HttpRequest,
+    response: HttpResponse<any>,
+    params: Map<string, string>,
+  ): Promise<HttpError> {
+    return new HttpError(response.metadata, response.raw);
+  }
+}

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

@@ -0,0 +1,41 @@
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+export interface HttpRequest {
+  baseUrl: string;
+  method: HttpMethod;
+  path: string;
+  headers: Map<string, unknown>;
+  body?: BodyInit;
+  abortSignal?: AbortSignal;
+  queryParams: Map<string, unknown>;
+  pathParams: Map<string, unknown>;
+}
+
+interface HttpMetadata {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+}
+
+export interface HttpResponse<T> {
+  data?: T;
+  metadata: HttpMetadata;
+  raw: ArrayBuffer;
+}
+
+export interface HttpError {
+  error: string;
+  metadata: HttpMetadata;
+}
+
+export interface Hook {
+  beforeRequest(request: HttpRequest, params: Map<string, string>): Promise<HttpRequest>;
+
+  afterResponse(
+    request: HttpRequest,
+    response: HttpResponse<any>,
+    params: Map<string, string>,
+  ): Promise<HttpResponse<any>>;
+
+  onError(request: HttpRequest, response: HttpResponse<any>, params: Map<string, string>): Promise<HttpError>;
+}

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

@@ -0,0 +1,11 @@
+export { Environment } from './environment.js';
+export type { HttpError } from './error.js';
+export type {
+  HttpMetadata,
+  HttpMethod,
+  HttpResponse,
+  RequestConfig,
+  RetryOptions,
+  SdkConfig,
+  ValidationOptions,
+} from './types.js';

package/src/project-client/http/serialization/base-serializer.ts

@@ -0,0 +1,139 @@
+import { RequestParameter } from '../transport/types.js';
+
+export type SerializationOptions = {
+  explode: boolean;
+  style: SerializationStyle;
+  encode: boolean;
+};
+
+export enum SerializationStyle {
+  SIMPLE = 'simple',
+  LABEL = 'label',
+  MATRIX = 'matrix',
+  FORM = 'form',
+  SPACE_DELIMITED = 'space_delimited',
+  PIPE_DELIMITED = 'pipe_delimited',
+  DEEP_OBJECT = 'deep_object',
+  NONE = 'none',
+}
+
+export class Serializer {
+  protected serializeValue(param: RequestParameter): string {
+    if (Array.isArray(param.value)) {
+      return this.serializeArray(param.value, param);
+    }
+
+    if (this.isNonNullObject(param.value)) {
+      return this.serializeObject(param.value, param);
+    }
+
+    return this.serializePrimitive(param);
+  }
+
+  private serializePrimitive(param: RequestParameter): string {
+    if (param.style === SerializationStyle.LABEL) {
+      return `.${param.value}`;
+    } else if (param.style === SerializationStyle.MATRIX) {
+      return `;${param.key}=${param.value}`;
+    } else if (param.style === SerializationStyle.FORM) {
+      return `${encodeURIComponent(param.key || '')}=${encodeURIComponent(`${param.value}`)}`;
+    }
+
+    return `${param.value}`;
+  }
+
+  private serializeArray(value: unknown[], param: RequestParameter): string {
+    if (param.explode) {
+      this.serializeArrayExploded(value, param);
+      return this.serializeArrayExploded(value, param);
+    }
+
+    if (param.style === SerializationStyle.SIMPLE) {
+      return `${value.join(',')}`;
+    } else if (param.style === SerializationStyle.LABEL) {
+      return `.${value.join(',')}`;
+    } else if (param.style === SerializationStyle.MATRIX) {
+      return `;${param.key}=${value.join(',')}`;
+    } else if (param.style === SerializationStyle.FORM) {
+      return `${encodeURIComponent(param.key || '')}=${encodeURIComponent(value.join(','))}`;
+    } else if (param.style === SerializationStyle.SPACE_DELIMITED) {
+      return `${param.key}=${value.join(' ')}`;
+    } else if (param.style === SerializationStyle.PIPE_DELIMITED) {
+      return `${param.key}=${value.join('|')}`;
+    }
+
+    return `${value.join(',')}`;
+  }
+
+  private serializeArrayExploded(value: unknown[], param: RequestParameter): string {
+    if (param.style === SerializationStyle.SIMPLE) {
+      return value.map((val) => `${val}`).join(',');
+    } else if (param.style === SerializationStyle.LABEL) {
+      return value.map((val) => `.${val}`).join('');
+    } else if (param.style === SerializationStyle.MATRIX) {
+      return value.map((val) => `;${param.key}=${val}`).join('');
+    } else if (
+      param.style === SerializationStyle.FORM ||
+      param.style === SerializationStyle.SPACE_DELIMITED ||
+      param.style === SerializationStyle.PIPE_DELIMITED
+    ) {
+      return value.map((val) => `${encodeURIComponent(param.key || '')}=${encodeURIComponent(`${val}`)}`).join('&');
+    }
+
+    return `${value.join(',')}`;
+  }
+
+  private serializeObject(obj: object, param: RequestParameter): string {
+    if (param.explode) {
+      if (param.style === SerializationStyle.SIMPLE) {
+        return Object.entries(obj)
+          .map(([key, val]) => `${key}=${val}`)
+          .join(',');
+      } else if (param.style === SerializationStyle.LABEL) {
+        return Object.entries(obj)
+          .map(([key, val]) => `.${key}=${val}`)
+          .join('');
+      } else if (param.style === SerializationStyle.MATRIX) {
+        return Object.entries(obj)
+          .map(([key, val]) => `;${key}=${val}`)
+          .join('');
+      } else if (param.style === SerializationStyle.FORM) {
+        return Object.entries(obj)
+          .map(([key, val]) => `${key}=${val}`)
+          .join('&');
+      }
+    }
+
+    if (param.style === SerializationStyle.SIMPLE) {
+      return Object.entries(obj)
+        .map(([key, val]) => `${key},${val}`)
+        .join(',');
+    } else if (param.style === SerializationStyle.LABEL) {
+      return `.${Object.entries(obj)
+        .map(([key, val]) => `${key},${val}`)
+        .join(',')}`;
+    } else if (param.style === SerializationStyle.MATRIX) {
+      return `;${param.key}=${Object.entries(obj)
+        .map(([key, val]) => `${key},${val}`)
+        .join(',')}`;
+    } else if (param.style === SerializationStyle.FORM) {
+      return Object.entries(obj)
+        .map(([key, val]) => `${key}=${val}`)
+        .join('&');
+    } else if (param.style === SerializationStyle.DEEP_OBJECT) {
+      return Object.entries(obj)
+        .map(([key, val]) => {
+          return `${param.key}[${key}]=${val}`;
+        })
+        .join('&');
+    }
+
+    return Object.entries(obj)
+      .map(([key, val]) => `${key}=${val}`)
+      .join('&');
+  }
+
+  private isNonNullObject(value: unknown): value is object {
+    return typeof value === 'object' && value !== null;
+  }
+}

package/src/project-client/http/serialization/header-serializer.ts

@@ -0,0 +1,19 @@
+import { RequestParameter } from '../transport/types.js';
+import { Serializer } from './base-serializer.js';
+
+export class HeaderSerializer extends Serializer {
+  public serialize(headerParams: Map<string, RequestParameter> | undefined): HeadersInit | undefined {
+    if (!headerParams || !headerParams.size) {
+      return undefined;
+    }
+
+    const headers: HeadersInit = {};
+    headerParams.forEach((param) => {
+      if (!param.key) {
+        return;
+      }
+      headers[param.key] = this.serializeValue(param);
+    });
+    return headers;
+  }
+}

package/src/project-client/http/serialization/path-serializer.ts

@@ -0,0 +1,12 @@
+import { RequestParameter } from '../transport/types.js';
+import { Serializer } from './base-serializer.js';
+
+export class PathSerializer extends Serializer {
+  public serialize(pathPattern: string, pathArguments: Map<string, RequestParameter>): string {
+    let serializedPath = pathPattern;
+    pathArguments.forEach((param: RequestParameter) => {
+      serializedPath = serializedPath.replace(`{${param.key}}`, `${this.serializeValue(param)}`);
+    });
+    return serializedPath;
+  }
+}

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

@@ -0,0 +1,18 @@
+import { RequestParameter } from '../transport/types.js';
+import { SerializationOptions, Serializer } from './base-serializer.js';
+
+export class QuerySerializer extends Serializer {
+  public serialize(queryParams: Map<string, RequestParameter>): string {
+    if (!queryParams || !queryParams.size) {
+      return '';
+    }
+
+    const query: string[] = [];
+
+    queryParams.forEach((param) => {
+      return query.push(`${this.serializeValue(param)}`);
+    });
+
+    return query.length ? `?${query.join('&')}` : '';
+  }
+}