magicbell-js 0.0.3 → 0.0.4

package/src/user-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/user-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/user-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/user-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/user-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/user-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/user-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/user-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/user-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('&')}` : '';
+  }
+}

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

@@ -0,0 +1,242 @@
+import z, { ZodType } from 'zod';
+
+import { Environment } from '../environment.js';
+import { SerializationStyle } from '../serialization/base-serializer.js';
+import { ContentType, HttpMethod, RequestConfig, RetryOptions, SdkConfig, ValidationOptions } from '../types.js';
+import { Request } from './request.js';
+import {
+  CreateRequestParameters,
+  ErrorDefinition,
+  RequestPagination,
+  RequestParameter,
+  ResponseDefinition,
+} from './types.js';
+
+export class RequestBuilder<Page extends unknown[] = unknown[]> {
+  private params: CreateRequestParameters<Page>;
+
+  constructor() {
+    this.params = {
+      baseUrl: Environment.DEFAULT,
+      method: 'GET',
+      path: '',
+      config: {},
+      responses: [],
+      errors: [],
+      requestSchema: z.any(),
+      requestContentType: ContentType.Json,
+      retry: {
+        attempts: 3,
+        delayMs: 150,
+      },
+      validation: {
+        responseValidation: true,
+      },
+      pathParams: new Map(),
+      queryParams: new Map(),
+      headers: new Map(),
+    };
+  }
+
+  setRetryAttempts(sdkConfig?: SdkConfig, requestConfig?: RequestConfig): RequestBuilder<Page> {
+    if (requestConfig?.retry?.attempts !== undefined) {
+      this.params.retry.attempts = requestConfig.retry.attempts;
+    } else if (sdkConfig?.retry?.attempts !== undefined) {
+      this.params.retry.attempts = sdkConfig.retry.attempts;
+    }
+
+    return this;
+  }
+
+  setRetryDelayMs(sdkConfig?: SdkConfig, requestConfig?: RequestConfig): RequestBuilder<Page> {
+    if (requestConfig?.retry?.delayMs !== undefined) {
+      this.params.retry.delayMs = requestConfig.retry.delayMs;
+    } else if (sdkConfig?.retry?.delayMs !== undefined) {
+      this.params.retry.delayMs = sdkConfig.retry.delayMs;
+    }
+
+    return this;
+  }
+
+  setResponseValidation(sdkConfig: SdkConfig, requestConfig?: RequestConfig): RequestBuilder<Page> {
+    if (requestConfig?.validation?.responseValidation !== undefined) {
+      this.params.validation.responseValidation = requestConfig.validation.responseValidation;
+    } else if (sdkConfig?.validation?.responseValidation !== undefined) {
+      this.params.validation.responseValidation = sdkConfig.validation.responseValidation;
+    }
+
+    return this;
+  }
+
+  setBaseUrl(baseUrl: string | undefined): RequestBuilder<Page> {
+    if (baseUrl) {
+      this.params.baseUrl = baseUrl;
+    }
+
+    return this;
+  }
+
+  setMethod(method: HttpMethod): RequestBuilder<Page> {
+    this.params.method = method;
+    return this;
+  }
+
+  setPath(path: string): RequestBuilder<Page> {
+    this.params.path = path;
+    return this;
+  }
+
+  setConfig(config: SdkConfig): RequestBuilder<Page> {
+    this.params.config = config;
+    return this;
+  }
+
+  setRequestContentType(contentType: ContentType): RequestBuilder<Page> {
+    this.params.requestContentType = contentType;
+    return this;
+  }
+
+  setRequestSchema(requestSchema: ZodType): RequestBuilder<Page> {
+    this.params.requestSchema = requestSchema;
+    return this;
+  }
+
+  setPagination(pagination: RequestPagination<Page>): RequestBuilder<Page> {
+    this.params.pagination = pagination;
+    return this;
+  }
+
+  addAccessTokenAuth(accessToken?: string, prefix?: string): RequestBuilder<Page> {
+    if (accessToken === undefined) {
+      return this;
+    }
+
+    this.params.headers.set('Authorization', {
+      key: 'Authorization',
+      value: `${prefix ?? 'Bearer'} ${accessToken}`,
+      explode: false,
+      style: SerializationStyle.SIMPLE,
+      encode: true,
+      isLimit: false,
+      isOffset: false,
+    });
+    return this;
+  }
+
+  addBasicAuth(username?: string, password?: string): RequestBuilder<Page> {
+    if (username === undefined || password === undefined) {
+      return this;
+    }
+
+    this.params.headers.set('Authorization', {
+      key: 'Authorization',
+      value: `Basic ${this.toBase64(`${username}:${password}`)}`,
+      explode: false,
+      style: SerializationStyle.SIMPLE,
+      encode: true,
+      isLimit: false,
+      isOffset: false,
+    });
+    return this;
+  }
+
+  addApiKeyAuth(apiKey?: string, keyName?: string): RequestBuilder<Page> {
+    if (apiKey === undefined) {
+      return this;
+    }
+
+    this.params.headers.set(keyName ?? 'X-API-KEY', {
+      key: keyName ?? 'X-API-KEY',
+      value: apiKey,
+      explode: false,
+      style: SerializationStyle.SIMPLE,
+      encode: true,
+      isLimit: false,
+      isOffset: false,
+    });
+    return this;
+  }
+
+  addResponse(response: ResponseDefinition): RequestBuilder<Page> {
+    this.params.responses.push(response);
+    return this;
+  }
+
+  addError(error: ErrorDefinition): RequestBuilder<Page> {
+    this.params.errors.push(error);
+    return this;
+  }
+
+  addBody(body?: any): RequestBuilder<Page> {
+    if (body !== undefined) {
+      this.params.body = body;
+    }
+    return this;
+  }
+
+  addPathParam(param: Partial<RequestParameter>): RequestBuilder<Page> {
+    if (param.value === undefined || param.key === undefined) {
+      return this;
+    }
+
+    this.params.pathParams.set(param.key, {
+      key: param.key,
+      value: param.value,
+      explode: param.explode ?? true,
+      style: param.style ?? SerializationStyle.SIMPLE,
+      encode: param.encode ?? true,
+      isLimit: !!param.isLimit,
+      isOffset: !!param.isOffset,
+    });
+
+    return this;
+  }
+
+  addQueryParam(param: Partial<RequestParameter>): RequestBuilder<Page> {
+    if (param.value === undefined || param.key === undefined) {
+      return this;
+    }
+
+    this.params.queryParams.set(param.key, {
+      key: param.key,
+      value: param.value,
+      explode: param.explode ?? true,
+      style: param.style ?? SerializationStyle.FORM,
+      encode: param.encode ?? true,
+      isLimit: !!param.isLimit,
+      isOffset: !!param.isOffset,
+    });
+
+    return this;
+  }
+
+  addHeaderParam(param: Partial<RequestParameter>): RequestBuilder<Page> {
+    if (param.value === undefined || param.key === undefined) {
+      return this;
+    }
+
+    this.params.headers.set(param.key, {
+      key: param.key,
+      value: param.value,
+      explode: param.explode ?? true,
+      style: param.style ?? SerializationStyle.SIMPLE,
+      encode: param.encode ?? false,
+      isLimit: !!param.isLimit,
+      isOffset: !!param.isOffset,
+    });
+
+    return this;
+  }
+
+  public build(): Request<Page> {
+    return new Request<Page>(this.params);
+  }
+
+  private toBase64(str: string): string {
+    if (typeof window === 'undefined') {
+      return Buffer.from(str, 'utf-8').toString('base64');
+    } else {
+      return btoa(unescape(encodeURIComponent(str)));
+    }
+  }
+}