magicbell-js 0.0.3 → 0.1.0

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

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

@@ -0,0 +1,131 @@
+import { HttpError } from '../error.js';
+import { HttpMetadata, HttpMethod, HttpResponse } from '../types.js';
+import { LineDecoder } from '../utils/line-decoder.js';
+import { Request } from './request.js';
+
+interface HttpAdapter {
+  send(): Promise<HttpResponse>;
+  stream(): AsyncGenerator<HttpResponse>;
+}
+
+export class RequestFetchAdapter<T> implements HttpAdapter {
+  private requestInit: RequestInit = {};
+
+  constructor(private request: Request) {
+    this.setMethod(request.method);
+    this.setHeaders(request.getHeaders());
+    this.setBody(request.body);
+    this.setTimeout(request.config.timeoutMs);
+  }
+
+  public async send(): Promise<HttpResponse<T>> {
+    const response = await fetch(this.request.constructFullUrl(), this.requestInit);
+
+    const metadata: HttpMetadata = {
+      status: response.status,
+      statusText: response.statusText || '',
+      headers: this.getHeaders(response),
+    };
+
+    return {
+      metadata,
+      raw: await response.clone().arrayBuffer(),
+    };
+  }
+
+  public async *stream(): AsyncGenerator<HttpResponse<T>> {
+    const response = await fetch(this.request.constructFullUrl(), this.requestInit);
+
+    const metadata: HttpMetadata = {
+      status: response.status,
+      statusText: response.statusText || '',
+      headers: this.getHeaders(response),
+    };
+
+    if (response.status >= 400) {
+      throw new HttpError(metadata, await response.clone().arrayBuffer());
+    }
+
+    if (!response.body) {
+      return yield {
+        metadata,
+        raw: await response.clone().arrayBuffer(),
+      };
+    }
+
+    const reader = response.body.getReader();
+    const lineDecoder = new LineDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      for (const line of lineDecoder.splitLines(value)) {
+        yield {
+          metadata,
+          raw: line,
+        };
+      }
+    }
+
+    for (const line of lineDecoder.flush()) {
+      yield {
+        metadata,
+        raw: line,
+      };
+    }
+  }
+
+  private setMethod(method: HttpMethod): void {
+    if (!method) {
+      return;
+    }
+    this.requestInit = {
+      ...this.requestInit,
+      method,
+    };
+  }
+
+  private setBody(body: ReadableStream<Uint8Array> | null): void {
+    if (!body) {
+      return;
+    }
+    this.requestInit = {
+      ...this.requestInit,
+      body,
+    };
+  }
+
+  private setHeaders(headers: HeadersInit | undefined): void {
+    if (!headers) {
+      return;
+    }
+
+    this.requestInit = {
+      ...this.requestInit,
+      headers,
+    };
+  }
+
+  private setTimeout(timeoutMs: number | undefined): void {
+    if (!timeoutMs) {
+      return;
+    }
+
+    this.requestInit = {
+      ...this.requestInit,
+      signal: AbortSignal.timeout(timeoutMs),
+    };
+  }
+
+  private getHeaders(response: Response): Record<string, string> {
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value: string, key: string) => {
+      headers[key] = value;
+    });
+
+    return headers;
+  }
+}