magicbell-js 0.0.3 → 0.0.4

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

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

@@ -0,0 +1,222 @@
+import { ZodType } from 'zod';
+
+import { HttpRequest } from '../hooks/hook.js';
+import { SerializationStyle } from '../serialization/base-serializer.js';
+import { HeaderSerializer } from '../serialization/header-serializer.js';
+import { PathSerializer } from '../serialization/path-serializer.js';
+import { QuerySerializer } from '../serialization/query-serializer.js';
+import { ContentType, HttpMethod, RetryOptions, SdkConfig, ValidationOptions } from '../types.js';
+import {
+  CreateRequestParameters,
+  ErrorDefinition,
+  RequestPagination,
+  RequestParameter,
+  ResponseDefinition,
+} from './types.js';
+
+export class Request<PageSchema = unknown[]> {
+  public baseUrl = '';
+
+  public headers: Map<string, RequestParameter> = new Map();
+
+  public queryParams: Map<string, RequestParameter> = new Map();
+
+  public pathParams: Map<string, RequestParameter> = new Map();
+
+  public body?: any;
+
+  public method: HttpMethod;
+
+  public path: string;
+
+  public config: SdkConfig;
+
+  public responses: ResponseDefinition[];
+
+  public errors: ErrorDefinition[];
+
+  public requestSchema: ZodType;
+
+  public requestContentType: ContentType;
+
+  public validation: ValidationOptions = {} as any;
+
+  public retry: RetryOptions = {} as any;
+
+  public pagination?: RequestPagination<PageSchema>;
+
+  private readonly pathPattern: string;
+
+  constructor(params: CreateRequestParameters<PageSchema>) {
+    this.baseUrl = params.baseUrl;
+    this.method = params.method;
+    this.pathPattern = params.path;
+    this.body = params.body;
+    this.path = this.constructPath();
+    this.config = params.config;
+    this.pathParams = params.pathParams;
+    this.headers = params.headers;
+    this.queryParams = params.queryParams;
+    this.responses = params.responses;
+    this.errors = params.errors;
+    this.requestSchema = params.requestSchema;
+    this.requestContentType = params.requestContentType;
+    this.retry = params.retry;
+    this.validation = params.validation;
+    this.pagination = params.pagination;
+  }
+
+  addHeaderParam(key: string, param: RequestParameter): void {
+    if (param.value === undefined) {
+      return;
+    }
+
+    if (param.explode === undefined) {
+      param.explode = false;
+    }
+
+    if (param.style === undefined) {
+      param.style = SerializationStyle.SIMPLE;
+    }
+
+    if (param.encode === undefined) {
+      param.encode = false;
+    }
+
+    this.headers.set(key, param);
+  }
+
+  addQueryParam(key: string, param: RequestParameter): void {
+    if (param.value === undefined) {
+      return;
+    }
+
+    if (param.explode === undefined) {
+      param.explode = true;
+    }
+
+    if (param.style === undefined) {
+      param.style = SerializationStyle.FORM;
+    }
+
+    if (param.encode === undefined) {
+      param.encode = true;
+    }
+
+    this.queryParams.set(key, param);
+  }
+
+  addPathParam(key: string, param: RequestParameter): void {
+    if (param.value === undefined) {
+      return;
+    }
+
+    if (param.explode === undefined) {
+      param.explode = false;
+    }
+
+    if (param.style === undefined) {
+      param.style = SerializationStyle.SIMPLE;
+    }
+
+    if (param.encode === undefined) {
+      param.encode = true;
+    }
+
+    this.pathParams.set(key, param);
+  }
+
+  addBody(body: any): void {
+    if (body === undefined) {
+      return;
+    }
+
+    this.body = body;
+  }
+
+  public updateFromHookRequest(hookRequest: HttpRequest): void {
+    this.baseUrl = hookRequest.baseUrl;
+    this.method = hookRequest.method;
+    this.path = hookRequest.path;
+    this.body = hookRequest.body;
+  }
+
+  public constructFullUrl(): string {
+    const queryString = new QuerySerializer().serialize(this.queryParams);
+    const path = this.constructPath();
+    const baseUrl = this.baseUrl;
+
+    return `${baseUrl}${path}${queryString}`;
+  }
+
+  public copy(overrides?: Partial<CreateRequestParameters>) {
+    const createRequestParams: CreateRequestParameters = {
+      baseUrl: overrides?.baseUrl ?? this.baseUrl,
+      errors: overrides?.errors ?? this.errors,
+      method: overrides?.method ?? this.method,
+      path: overrides?.path ?? this.path,
+      body: overrides?.body ?? this.body,
+      config: overrides?.config ?? this.config,
+      pathParams: overrides?.pathParams ?? this.pathParams,
+      queryParams: overrides?.queryParams ?? this.queryParams,
+      headers: overrides?.headers ?? this.headers,
+      responses: overrides?.responses ?? this.responses,
+      requestSchema: overrides?.requestSchema ?? this.requestSchema,
+      requestContentType: overrides?.requestContentType ?? this.requestContentType,
+      retry: overrides?.retry ?? this.retry,
+      validation: overrides?.validation ?? this.validation,
+    };
+    return new Request({
+      ...createRequestParams,
+      ...overrides,
+    });
+  }
+
+  public getHeaders(): HeadersInit | undefined {
+    if (!this.headers || !this.headers.size) {
+      return undefined;
+    }
+
+    return new HeaderSerializer().serialize(this.headers);
+  }
+
+  public nextPage(): void {
+    if (!this.pagination) {
+      return;
+    }
+
+    const offsetParam = this.getOffsetParam();
+    if (!offsetParam) {
+      return;
+    }
+
+    offsetParam.value = Number(offsetParam.value) + this.pagination.pageSize;
+  }
+
+  private constructPath(): string {
+    return new PathSerializer().serialize(this.pathPattern, this.pathParams);
+  }
+
+  private getOffsetParam(): RequestParameter | undefined {
+    const offsetParam = this.getAllParams().find((param) => param.isOffset);
+    return offsetParam;
+  }
+
+  private getAllParams(): RequestParameter[] {
+    const allParams: RequestParameter[] = [];
+
+    this.headers.forEach((val, _) => {
+      allParams.push(val);
+    });
+
+    this.queryParams.forEach((val, _) => {
+      allParams.push(val);
+    });
+
+    this.pathParams.forEach((val, _) => {
+      allParams.push(val);
+    });
+
+    return allParams;
+  }
+}

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

@@ -0,0 +1,91 @@
+import { CustomHook } from '../hooks/custom-hook.js';
+import { HttpError, HttpRequest } from '../hooks/hook.js';
+import { SerializationStyle } from '../serialization/base-serializer.js';
+import { HttpResponse } from '../types.js';
+import { Request } from './request.js';
+import { RequestParameter } from './types.js';
+
+export class TransportHookAdapter<T> {
+  private hook: CustomHook = new CustomHook();
+
+  public async beforeRequest(request: Request, params: Map<string, string>): Promise<Request> {
+    const hookRequest = this.requestToHookRequest(request);
+
+    const newRequest = await this.hook.beforeRequest(hookRequest, params);
+
+    const newTransportRequest = request.copy({
+      baseUrl: newRequest.baseUrl,
+      method: newRequest.method,
+      path: newRequest.path,
+      body: newRequest.body,
+      queryParams: this.hookParamsToTransportParams(newRequest.queryParams, request.queryParams, true),
+      headers: this.hookParamsToTransportParams(newRequest.headers, request.headers, false),
+      pathParams: this.hookParamsToTransportParams(newRequest.pathParams, request.headers, false),
+    });
+
+    return newTransportRequest;
+  }
+
+  public async afterResponse(
+    request: Request,
+    response: HttpResponse<T>,
+    params: Map<string, string>,
+  ): Promise<HttpResponse<T>> {
+    const hookRequest = this.requestToHookRequest(request);
+    return this.hook.afterResponse(hookRequest, response, params);
+  }
+
+  public async onError(request: Request, response: HttpResponse<T>, params: Map<string, string>): Promise<HttpError> {
+    const hookRequest = this.requestToHookRequest(request);
+    return this.hook.onError(hookRequest, response, params);
+  }
+
+  private requestToHookRequest(request: Request): HttpRequest {
+    const hookHeaders: Map<string, unknown> = new Map();
+    request.headers.forEach((header, key) => {
+      hookHeaders.set(key, header.value);
+    });
+
+    const hookQueryParams: Map<string, unknown> = new Map();
+    request.queryParams.forEach((queryParam, key) => {
+      hookQueryParams.set(key, queryParam.value);
+    });
+
+    const hookPathParams: Map<string, unknown> = new Map();
+    request.pathParams.forEach((pathParam, key) => {
+      hookPathParams.set(key, pathParam.value);
+    });
+
+    const hookRequest: HttpRequest = {
+      baseUrl: request.baseUrl,
+      method: request.method,
+      path: request.path,
+      headers: hookHeaders,
+      body: request.body,
+      queryParams: hookQueryParams,
+      pathParams: hookPathParams,
+    };
+    return hookRequest;
+  }
+
+  private hookParamsToTransportParams<T>(
+    hookParams: Map<string, unknown>,
+    originalTransportParams: Map<string, RequestParameter>,
+    encode: boolean,
+  ): Map<string, RequestParameter> {
+    const transportParams: Map<string, RequestParameter> = new Map();
+    hookParams.forEach((hookParamValue, hookParamKey) => {
+      const requestParam = originalTransportParams.get(hookParamKey);
+      transportParams.set(hookParamKey, {
+        key: hookParamKey,
+        value: hookParamValue,
+        encode: requestParam?.encode ?? false,
+        style: requestParam?.style || SerializationStyle.NONE,
+        explode: requestParam?.explode ?? false,
+        isLimit: requestParam?.isLimit ?? false,
+        isOffset: requestParam?.isOffset ?? false,
+      });
+    });
+    return transportParams;
+  }
+}

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

@@ -0,0 +1,50 @@
+import { ZodType } from 'zod';
+
+import { SerializationStyle } from '../serialization/base-serializer.js';
+import { ContentType, HttpMethod, RetryOptions, SdkConfig, ValidationOptions } from '../types.js';
+
+export interface ResponseDefinition {
+  schema: ZodType;
+  contentType: ContentType;
+  status: number;
+}
+
+export interface ErrorDefinition {
+  error: new (...args: any[]) => Error;
+  contentType: ContentType;
+  status: number;
+}
+
+export interface CreateRequestParameters<Page = unknown[]> {
+  baseUrl: string;
+  method: HttpMethod;
+  body?: any;
+  headers: Map<string, RequestParameter>;
+  queryParams: Map<string, RequestParameter>;
+  pathParams: Map<string, RequestParameter>;
+  path: string;
+  config: SdkConfig;
+  responses: ResponseDefinition[];
+  errors: ErrorDefinition[];
+  requestSchema: ZodType;
+  requestContentType: ContentType;
+  validation: ValidationOptions;
+  retry: RetryOptions;
+  pagination?: RequestPagination<Page>;
+}
+
+export interface RequestParameter {
+  key: string | undefined;
+  value: unknown;
+  explode: boolean;
+  encode: boolean;
+  style: SerializationStyle;
+  isLimit: boolean;
+  isOffset: boolean;
+}
+
+export interface RequestPagination<Page> {
+  pageSize: number;
+  pagePath: string[];
+  pageSchema?: ZodType<Page, any, any>;
+}

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

@@ -0,0 +1,74 @@
+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 interface SdkConfig {
+  baseUrl?: string;
+  environment?: Environment;
+  timeoutMs?: number;
+  token?: string;
+  retry?: RetryOptions;
+  validation?: ValidationOptions;
+}
+
+export interface HttpMetadata {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+}
+
+export interface HttpResponse<T = unknown> {
+  data?: T;
+  metadata: HttpMetadata;
+  raw: ArrayBuffer;
+}
+
+export interface RequestHandler {
+  next?: RequestHandler;
+
+  handle<T>(request: Request): Promise<HttpResponse<T>>;
+  stream<T>(request: Request): AsyncGenerator<HttpResponse<T>>;
+}
+
+export enum ContentType {
+  Json = 'json',
+  Xml = 'xml',
+  Pdf = 'pdf',
+  Image = 'image',
+  File = 'file',
+  Binary = 'binary',
+  FormUrlEncoded = 'form',
+  Text = 'text',
+  MultipartFormData = 'multipartFormData',
+  EventStream = 'eventStream',
+  NoContent = 'noContent',
+}
+
+export interface Options<T> {
+  responseSchema: ZodType<T, any, any>;
+  requestSchema?: ZodType;
+  body?: any;
+  requestContentType?: ContentType;
+  responseContentType?: ContentType;
+  abortSignal?: AbortSignal;
+  queryParams?: Record<string, unknown>;
+  retry?: RetryOptions;
+}
+
+export interface RequestConfig {
+  retry?: RetryOptions;
+  validation?: ValidationOptions;
+  baseUrl?: string;
+}
+
+export interface RetryOptions {
+  attempts: number;
+  delayMs?: number;
+}
+
+export interface ValidationOptions {
+  responseValidation?: boolean;
+}

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

@@ -0,0 +1,33 @@
+import { ContentType } from '../types.js';
+
+export function getContentTypeDefinition(contentType: string): ContentType {
+  if (contentType.startsWith('application/') && contentType.includes('xml')) {
+    return ContentType.Xml;
+  }
+
+  if (contentType.toLowerCase() === 'application/x-www-form-urlencoded') {
+    return ContentType.FormUrlEncoded;
+  }
+
+  if (contentType.toLowerCase() === 'text/event-stream') {
+    return ContentType.EventStream;
+  }
+
+  if (contentType.toLowerCase().startsWith('text/')) {
+    return ContentType.Text;
+  }
+
+  if (contentType.toLowerCase().startsWith('image/')) {
+    return ContentType.Image;
+  }
+
+  if (contentType.toLowerCase() === 'application/octet-stream') {
+    return ContentType.Binary;
+  }
+
+  if (contentType.toLowerCase() === 'application/json') {
+    return ContentType.Json;
+  }
+
+  return ContentType.Json;
+}

package/src/user-client/http/utils/line-decoder.ts

@@ -0,0 +1,35 @@
+export class LineDecoder {
+  private lineBuffer = '';
+  private decoder = new TextDecoder();
+  private encoder = new TextEncoder();
+
+  /**
+   * Splits the given chunk into lines.
+   * Stores incomplete lines in a buffer and returns them when the next chunk arrives.
+   */
+  public splitLines(chunk: Uint8Array): Uint8Array[] {
+    this.lineBuffer += this.decoder.decode(chunk);
+
+    let lineEndIndex;
+    const lines: Uint8Array[] = [];
+    while ((lineEndIndex = this.lineBuffer.indexOf('\n')) >= 0) {
+      const line = this.lineBuffer.slice(0, lineEndIndex + 1); // Include the newline character
+      this.lineBuffer = this.lineBuffer.slice(lineEndIndex + 1);
+      if (line.length > 1) {
+        lines.push(this.encoder.encode(line));
+      }
+    }
+
+    return lines;
+  }
+
+  /** Returns the remaining lines in the buffer. */
+  public flush(): Uint8Array[] {
+    if (this.lineBuffer.length === 0) {
+      return [];
+    }
+    const lines = [this.encoder.encode(this.lineBuffer)];
+    this.lineBuffer = '';
+    return lines;
+  }
+}

package/src/user-client/http/utils/response-matcher.ts

@@ -0,0 +1,25 @@
+import { ResponseDefinition } from '../transport/types.js';
+import { ContentType, HttpResponse } from '../types.js';
+import { getContentTypeDefinition } from './content-type.js';
+
+export class ResponseMatcher {
+  constructor(private responses: ResponseDefinition[]) {}
+
+  public getResponseDefinition(response: HttpResponse): ResponseDefinition | undefined {
+    const rawContentType = response.metadata.headers['content-type']?.toLocaleLowerCase() || '';
+    const contentType = getContentTypeDefinition(rawContentType);
+    const statusCode = response.metadata.status;
+
+    if (!this.responses.length) {
+      return;
+    }
+
+    if (this.responses.length === 1) {
+      return this.responses[0];
+    }
+
+    return this.responses.find((response) => {
+      return response.contentType === contentType && response.status === statusCode;
+    });
+  }
+}