magicbell-js 0.0.3 → 0.1.0

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

@@ -0,0 +1,71 @@
+import { RequestHandlerChain } from './handlers/handler-chain.js';
+import { HookHandler } from './handlers/hook-handler.js';
+import { RequestValidationHandler } from './handlers/request-validation-handler.js';
+import { ResponseValidationHandler } from './handlers/response-validation-handler.js';
+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';
+
+export class HttpClient {
+  private readonly requestHandlerChain = new RequestHandlerChain();
+
+  constructor(private config: SdkConfig, hook = new CustomHook()) {
+    this.requestHandlerChain.addHandler(new ResponseValidationHandler());
+    this.requestHandlerChain.addHandler(new RequestValidationHandler());
+    this.requestHandlerChain.addHandler(new RetryHandler());
+    this.requestHandlerChain.addHandler(new HookHandler(hook));
+    this.requestHandlerChain.addHandler(new TerminatingHandler());
+  }
+
+  call<T>(request: Request): Promise<HttpResponse<T>> {
+    return this.requestHandlerChain.callChain(request);
+  }
+
+  async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    yield* this.requestHandlerChain.streamChain(request);
+  }
+
+  public async callPaginated<FullResponse, Page>(request: Request<Page>): Promise<HttpResponse<Page>> {
+    const response = await this.call<FullResponse>(request as any);
+
+    if (!response.data) {
+      throw new Error('no response data to paginate through');
+    }
+
+    return {
+      ...response,
+      data: this.getPage<FullResponse, Page>(request, response.data),
+    };
+  }
+
+  setBaseUrl(url: string): void {
+    this.config.baseUrl = url;
+  }
+
+  setConfig(config: SdkConfig): void {
+    this.config = config;
+  }
+
+  private getPage<FullResponse, Page>(request: Request<Page>, data: FullResponse): Page {
+    if (!request.pagination) {
+      throw new Error('getPage called for request without pagination property');
+    }
+
+    let curr: any = data;
+    for (const segment of request.pagination?.pagePath || []) {
+      curr = curr[segment];
+    }
+
+    const page = request.pagination?.pageSchema?.parse(curr);
+    if (!page) {
+      throw new Error(
+        `error getting page data. Curr: ${JSON.stringify(curr)}. PagePath: ${
+          request.pagination?.pagePath
+        }. Data: ${JSON.stringify(data)}`,
+      );
+    }
+    return page;
+  }
+}

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

@@ -0,0 +1,3 @@
+export enum Environment {
+  DEFAULT = 'https://api.magicbell.com/v2',
+}

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

@@ -0,0 +1,14 @@
+import { HttpMetadata } from './types.js';
+
+export class HttpError extends Error {
+  public readonly error: string;
+  public readonly metadata: HttpMetadata;
+  public readonly raw?: ArrayBuffer;
+
+  constructor(metadata: HttpMetadata, raw?: ArrayBuffer, error?: string) {
+    super(error);
+    this.error = metadata.statusText;
+    this.metadata = metadata;
+    this.raw = raw;
+  }
+}

package/src/user-client/http/errors/throwable-error.ts

@@ -0,0 +1,9 @@
+export class ThrowableError extends Error {
+  constructor(public message: string, protected response?: unknown) {
+    super(message);
+  }
+
+  public throw() {
+    throw this;
+  }
+}

package/src/user-client/http/errors/validation-error.ts

@@ -0,0 +1,25 @@
+import { ZodError } from 'zod';
+
+export class ValidationError extends Error {
+  public readonly error: string;
+
+  constructor(zodError: ZodError, object: any) {
+    let actual: string;
+    try {
+      actual = JSON.stringify(object, undefined, 2);
+    } catch (err) {
+      actual = object;
+    }
+
+    const error = [
+      `ValidationError:`,
+      ...zodError.issues.map((issue) => `  Property: ${issue.path.join('.')}. Message: ${issue.message}`),
+      '  Validated:',
+      ...actual.split('\n').map((line) => `  ${line}`),
+    ].join('\n');
+
+    super(error);
+
+    this.error = error;
+  }
+}

package/src/user-client/http/handlers/handler-chain.ts

@@ -0,0 +1,30 @@
+import { Request } from '../transport/request.js';
+import { HttpResponse, RequestHandler } from '../types.js';
+
+export class RequestHandlerChain {
+  private readonly handlers: RequestHandler[] = [];
+
+  addHandler(handler: RequestHandler): void {
+    if (this.handlers.length > 0) {
+      const previousHandler = this.handlers[this.handlers.length - 1];
+      previousHandler.next = handler;
+    }
+    this.handlers.push(handler);
+  }
+
+  async callChain<T>(request: Request): Promise<HttpResponse<T>> {
+    if (!this.handlers.length) {
+      throw new Error('No handlers added to the chain');
+    }
+
+    return this.handlers[0].handle<T>(request);
+  }
+
+  async *streamChain<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    if (!this.handlers.length) {
+      throw new Error('No handlers added to the chain');
+    }
+
+    yield* this.handlers[0].stream<T>(request);
+  }
+}

package/src/user-client/http/handlers/hook-handler.ts

@@ -0,0 +1,80 @@
+import { HttpError } from '../error.js';
+import { ThrowableError } from '../errors/throwable-error.js';
+import { Hook } from '../hooks/hook.js';
+import { Request } from '../transport/request.js';
+import { TransportHookAdapter } from '../transport/transport-hook-adapter.js';
+import { ErrorDefinition } from '../transport/types.js';
+import { ContentType, HttpResponse, RequestHandler } from '../types.js';
+import { getContentTypeDefinition } from '../utils/content-type.js';
+
+export class HookHandler implements RequestHandler {
+  next?: RequestHandler;
+
+  constructor(private readonly hook: Hook) {}
+
+  async handle<T>(request: Request): Promise<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in hook handler.');
+    }
+
+    const hook = new TransportHookAdapter<T>();
+
+    const hookParams = this.getHookParams<T>(request);
+
+    const nextRequest = await hook.beforeRequest(request, hookParams);
+
+    const response = await this.next.handle<T>(nextRequest);
+
+    if (response.metadata.status < 400) {
+      return await hook.afterResponse(nextRequest, response, hookParams);
+    }
+
+    const rawContentType = response.metadata.headers['content-type']?.toLocaleLowerCase() || '';
+    const contentType = getContentTypeDefinition(rawContentType);
+    const statusCode = response.metadata.status;
+
+    const error = request.errors.find((error): error is ErrorDefinition => {
+      return error.contentType === contentType && error.status === statusCode;
+    });
+
+    if (error) {
+      const decodedBody = new TextDecoder().decode(response.raw);
+      const json = JSON.parse(decodedBody);
+      new error.error((json as any)?.message || '', json).throw();
+    }
+
+    const decodedBody = new TextDecoder().decode(response.raw);
+    throw new HttpError(
+      response.metadata,
+      response.raw,
+      `Unexpected response body for error status.\nStatusCode: ${response.metadata.status}\nBody: ${decodedBody}`,
+    );
+  }
+
+  async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in hook handler.');
+    }
+
+    const hook = new TransportHookAdapter<T>();
+
+    const hookParams = this.getHookParams<T>(request);
+
+    const nextRequest = await hook.beforeRequest(request, hookParams);
+
+    const stream = this.next.stream<T>(nextRequest);
+
+    for await (const response of stream) {
+      if (response.metadata.status < 400) {
+        yield await hook.afterResponse(nextRequest, response, hookParams);
+      } else {
+        throw await hook.onError(nextRequest, response, hookParams);
+      }
+    }
+  }
+
+  private getHookParams<T>(_request: Request): Map<string, string> {
+    const hookParams: Map<string, string> = new Map();
+    return hookParams;
+  }
+}

package/src/user-client/http/handlers/request-validation-handler.ts

@@ -0,0 +1,111 @@
+import { ZodError } from 'zod';
+
+import { ValidationError } from '../errors/validation-error.js';
+import { Request } from '../transport/request.js';
+import { ContentType, HttpResponse, RequestHandler } from '../types.js';
+
+export class RequestValidationHandler implements RequestHandler {
+  next?: RequestHandler;
+
+  async handle<T>(request: Request): Promise<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in ContentTypeHandler.');
+    }
+
+    this.validateRequest(request);
+
+    return this.next.handle<T>(request);
+  }
+
+  async *stream<T>(request: Request): AsyncGenerator<HttpResponse<T>> {
+    if (!this.next) {
+      throw new Error('No next handler set in ContentTypeHandler.');
+    }
+
+    this.validateRequest(request);
+
+    yield* this.next.stream<T>(request);
+  }
+
+  validateRequest(request: Request): void {
+    if (request.requestContentType === ContentType.Json) {
+      try {
+        const parsedBody = request.requestSchema?.parse(request.body);
+        request.body = JSON.stringify(parsedBody);
+      } catch (error) {
+        if (error instanceof ZodError) {
+          throw new ValidationError(error, request.body);
+        }
+        throw error;
+      }
+    } else if (
+      request.requestContentType === ContentType.Xml ||
+      request.requestContentType === ContentType.Text ||
+      request.requestContentType === ContentType.Image ||
+      request.requestContentType === ContentType.Binary
+    ) {
+      request.body = request.body;
+    } else if (request.requestContentType === ContentType.FormUrlEncoded) {
+      request.body = this.toFormUrlEncoded(request);
+    } else if (request.requestContentType === ContentType.MultipartFormData) {
+      request.body = this.toFormData(request.body);
+    } else {
+      request.body = JSON.stringify(request.requestSchema?.parse(request.body));
+    }
+  }
+
+  toFormUrlEncoded(request: Request): string {
+    if (request.body === undefined) {
+      return '';
+    }
+
+    if (typeof request.body === 'string') {
+      return request.body;
+    }
+
+    if (request.body instanceof URLSearchParams) {
+      return request.body.toString();
+    }
+
+    const validatedBody = request.requestSchema?.parse(request.body);
+
+    if (validatedBody instanceof FormData) {
+      const params = new URLSearchParams();
+      validatedBody.forEach((value, key) => {
+        if (value != null) {
+          params.append(key, value.toString());
+        }
+      });
+      return params.toString();
+    }
+
+    if (typeof validatedBody === 'object' && !Array.isArray(validatedBody)) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(validatedBody)) {
+        if (value != null) {
+          params.append(key, `${value}`);
+        }
+      }
+      return params.toString();
+    }
+
+    return '';
+  }
+
+  toFormData(body: Record<string, any>): FormData | undefined {
+    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));
+      } else if (value instanceof ArrayBuffer) {
+        formData.append(key, new Blob([value]));
+      } else {
+        formData.append(key, value);
+      }
+    });
+
+    return formData;
+  }
+}

package/src/user-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/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);
+  }
+}