zinkee 0.1.0

package/src/client.ts

@@ -0,0 +1,243 @@
+export interface ApiClientOptions {
+  baseUrl: string;
+  apiKey?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+export type ApiClientErrorCode =
+  | "network_error"
+  | "http_error"
+  | "timeout"
+  | "invalid_json";
+
+export interface ApiClientErrorDetails {
+  url: string;
+  method: string;
+  status?: number;
+  responseBody?: unknown;
+  responseText?: string;
+  cause?: unknown;
+}
+
+export class ApiClientError extends Error {
+  override name = "ApiClientError";
+
+  readonly code: ApiClientErrorCode;
+
+  readonly url: string;
+
+  readonly method: string;
+
+  readonly status?: number;
+
+  readonly responseBody?: unknown;
+
+  readonly responseText?: string;
+
+  override readonly cause?: unknown;
+
+  constructor(
+    code: ApiClientErrorCode,
+    message: string,
+    details: ApiClientErrorDetails,
+  ) {
+    super(message);
+    this.code = code;
+    this.url = details.url;
+    this.method = details.method;
+    this.status = details.status;
+    this.responseBody = details.responseBody;
+    this.responseText = details.responseText;
+    this.cause = details.cause;
+  }
+}
+
+export interface ApiRequestOptions extends RequestInit {
+  timeoutMs?: number;
+}
+
+function isJsonContentType(contentType: string | null): boolean {
+  return contentType ? /(^|\/|\+)json\b/i.test(contentType) : false;
+}
+
+function looksLikeJson(text: string): boolean {
+  const trimmed = text.trim();
+
+  return (
+    trimmed.startsWith("{") ||
+    trimmed.startsWith("[") ||
+    trimmed === "null" ||
+    trimmed === "true" ||
+    trimmed === "false" ||
+    /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/.test(trimmed) ||
+    trimmed.startsWith('"')
+  );
+}
+
+function parseJsonBody<T>(text: string, url: string, method: string): T {
+  const trimmed = text.trim();
+
+  if (trimmed.length === 0) {
+    return undefined as T;
+  }
+
+  try {
+    return JSON.parse(trimmed) as T;
+  } catch (cause) {
+    throw new ApiClientError("invalid_json", `Failed to parse JSON response from ${method} ${url}.`, {
+      url,
+      method,
+      responseText: text,
+      cause,
+    });
+  }
+}
+
+function parseErrorBody(text: string, contentType: string | null): unknown {
+  if (text.trim().length === 0) {
+    return undefined;
+  }
+
+  if (!isJsonContentType(contentType) && !looksLikeJson(text)) {
+    return text;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+export class ApiClient {
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly options: ApiClientOptions) {
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  async getJson<T>(path: string, init: ApiRequestOptions = {}): Promise<T> {
+    return this.requestJson<T>(path, { ...init, method: "GET" });
+  }
+
+  async requestJson<T>(path: string, init: ApiRequestOptions = {}): Promise<T> {
+    const response = await this.request(path, init, "application/json");
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw this.buildHttpError(response, text, init, "requestJson");
+    }
+
+    const text = await response.text();
+    return parseJsonBody<T>(text, response.url, init.method ?? "GET");
+  }
+
+  async requestBinary(path: string, init: ApiRequestOptions = {}): Promise<ArrayBuffer> {
+    const response = await this.request(path, init);
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw this.buildHttpError(response, text, init, "requestBinary");
+    }
+
+    return response.arrayBuffer();
+  }
+
+  private buildUrl(path: string): string {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+
+    return new URL(normalizedPath, this.options.baseUrl).toString();
+  }
+
+  private async request(
+    path: string,
+    init: ApiRequestOptions,
+    accept?: string,
+  ): Promise<Response> {
+    const url = this.buildUrl(path);
+    const method = init.method ?? "GET";
+    const headers = new Headers(init.headers);
+
+    if (accept && !headers.has("accept")) {
+      headers.set("accept", accept);
+    }
+
+    if (this.options.apiKey && !headers.has("authorization")) {
+      headers.set("authorization", `Bearer ${this.options.apiKey}`);
+    }
+
+    const controller = new AbortController();
+    const timeoutMs = init.timeoutMs ?? this.options.timeoutMs;
+    let timedOut = false;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
+    const abortListener = (): void => {
+      controller.abort();
+    };
+
+    if (init.signal) {
+      if (init.signal.aborted) {
+        controller.abort();
+      } else {
+        init.signal.addEventListener("abort", abortListener, { once: true });
+      }
+    }
+
+    if (timeoutMs !== undefined) {
+      timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, timeoutMs);
+    }
+
+    try {
+      return await this.fetchImpl(url, {
+        ...init,
+        headers,
+        signal: controller.signal,
+      });
+    } catch (cause) {
+      if (timedOut) {
+        throw new ApiClientError("timeout", `Request timed out after ${timeoutMs}ms.`, {
+          url,
+          method,
+          cause,
+        });
+      }
+
+      throw new ApiClientError("network_error", `Request failed for ${method} ${url}.`, {
+        url,
+        method,
+        cause,
+      });
+    } finally {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+
+      if (init.signal) {
+        init.signal.removeEventListener("abort", abortListener);
+      }
+    }
+  }
+
+  private buildHttpError(
+    response: Response,
+    text: string,
+    init: ApiRequestOptions,
+    operation: string,
+  ): ApiClientError {
+    const method = init.method ?? "GET";
+    const responseBody = parseErrorBody(text, response.headers.get("content-type"));
+
+    return new ApiClientError("http_error", `Request failed with status ${response.status} for ${method} ${response.url}.`, {
+      url: response.url,
+      method,
+      status: response.status,
+      responseBody,
+      responseText: responseBody === text ? text : undefined,
+      cause: new Error(operation),
+    });
+  }
+}