@archora/forge-runtime 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+type ApiClientOptions = {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    auth?: ApiAuthOptions;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    retry?: ApiRetryOptions;
+    onRequest?: (request: {
+        method: string;
+        url: string;
+        options?: ApiRequestOptions;
+    }) => void | Promise<void>;
+    onResponse?: (response: Response) => void | Promise<void>;
+    onError?: (error: unknown) => void | Promise<void>;
+};
+type ApiRetryOptions = {
+    attempts?: number;
+    delayMs?: number;
+    methods?: string[];
+    statuses?: number[];
+};
+type ApiQueryParamOptions = {
+    style?: 'form';
+    explode?: boolean;
+};
+type ApiQueryParam = ApiQueryParamOptions & {
+    value: unknown;
+};
+type ApiAuthValue = string | (() => string | Promise<string>);
+type ApiAuthOptions = {
+    type: 'bearer';
+    token: ApiAuthValue;
+} | {
+    type: 'apiKey';
+    headerName: string;
+    value: ApiAuthValue;
+};
+type ApiRequestOptions = {
+    params?: Record<string, unknown | ApiQueryParam>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+type ApiClient = {
+    request: <TResponse>(method: string, path: string, options?: ApiRequestOptions) => Promise<TResponse>;
+};
+declare class ForgeHttpError<TBody = unknown> extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: TBody;
+    readonly method: string;
+    readonly url: string;
+    constructor(input: {
+        status: number;
+        statusText: string;
+        body: TBody;
+        method: string;
+        url: string;
+    });
+}
+declare function isForgeHttpError<TBody = unknown>(error: unknown): error is ForgeHttpError<TBody>;
+declare function createApiClient(options: ApiClientOptions): ApiClient;
+declare function createApiClientOptions(options: ApiClientOptions): ApiClient;
+declare function queryParam(value: unknown, options?: ApiQueryParamOptions): ApiQueryParam;
+
+export { type ApiAuthOptions, type ApiAuthValue, type ApiClient, type ApiClientOptions, type ApiQueryParam, type ApiQueryParamOptions, type ApiRequestOptions, type ApiRetryOptions, ForgeHttpError, createApiClient, createApiClientOptions, isForgeHttpError, queryParam };

package/dist/index.js

@@ -0,0 +1,219 @@
+// src/index.ts
+var ForgeHttpError = class extends Error {
+  status;
+  statusText;
+  body;
+  method;
+  url;
+  constructor(input) {
+    super(`${input.method} ${input.url} failed with ${input.status} ${input.statusText}`.trim());
+    this.name = "ForgeHttpError";
+    this.status = input.status;
+    this.statusText = input.statusText;
+    this.body = input.body;
+    this.method = input.method;
+    this.url = input.url;
+  }
+};
+function isForgeHttpError(error) {
+  return error instanceof ForgeHttpError;
+}
+function createApiClient(options) {
+  return {
+    async request(method, path, requestOptions = {}) {
+      const fetchImpl = options.fetchImpl ?? fetch;
+      const url = buildUrl(options.baseUrl, path, requestOptions.params);
+      const headers = await buildHeaders(options, requestOptions);
+      const abortScope = createAbortScope(requestOptions.signal, requestOptions.timeoutMs ?? options.timeoutMs);
+      const init = {
+        method,
+        headers,
+        signal: abortScope.signal
+      };
+      if (requestOptions.body !== void 0 && method.toUpperCase() !== "GET") {
+        const body = requestOptions.body;
+        init.body = isNativeRequestBody(body) ? body : JSON.stringify(body);
+        if (!isNativeRequestBody(body) && !hasHeader(headers, "content-type")) {
+          headers["content-type"] = "application/json";
+        }
+      }
+      await options.onRequest?.({ method, url, options: requestOptions });
+      try {
+        const retry = normalizeRetryOptions(options.retry);
+        let attempt = 0;
+        while (true) {
+          attempt += 1;
+          try {
+            const response = await fetchImpl(url, init);
+            await options.onResponse?.(response);
+            const body = await parseResponseBody(response);
+            if (!response.ok) {
+              const error = new ForgeHttpError({ status: response.status, statusText: response.statusText, body, method, url });
+              if (shouldRetryHttpError(error, method, retry, attempt)) {
+                await wait(retry.delayMs);
+                continue;
+              }
+              throw error;
+            }
+            return body;
+          } catch (error) {
+            if (error instanceof ForgeHttpError || isAbortError(error) || !shouldRetryNetworkError(method, retry, attempt)) {
+              throw error;
+            }
+            await wait(retry.delayMs);
+          }
+        }
+      } catch (error) {
+        await options.onError?.(error);
+        throw error;
+      } finally {
+        abortScope.cleanup();
+      }
+    }
+  };
+}
+function createApiClientOptions(options) {
+  return createApiClient(options);
+}
+function queryParam(value, options = {}) {
+  return { value, ...options };
+}
+function buildUrl(baseUrl, path, params) {
+  if (baseUrl === "") {
+    return buildRelativeUrl(path, params);
+  }
+  const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  for (const [key, value] of Object.entries(params ?? {})) {
+    appendQueryParam(url.searchParams, key, value);
+  }
+  return url.toString();
+}
+function buildRelativeUrl(path, params) {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params ?? {})) {
+    appendQueryParam(searchParams, key, value);
+  }
+  const query = searchParams.toString();
+  if (!query) return path;
+  return `${path}${path.includes("?") ? "&" : "?"}${query}`;
+}
+function appendQueryParam(searchParams, key, input) {
+  const param = isApiQueryParam(input) ? input : { value: input };
+  const { value } = param;
+  if (value === void 0 || value === null) return;
+  if (!Array.isArray(value)) {
+    searchParams.append(key, String(value));
+    return;
+  }
+  const items = value.filter((item) => item !== void 0 && item !== null);
+  if (items.length === 0) return;
+  if (param.style === "form" && param.explode === false) {
+    searchParams.append(key, items.map(String).join(","));
+    return;
+  }
+  for (const item of items) {
+    searchParams.append(key, String(item));
+  }
+}
+function isApiQueryParam(value) {
+  return typeof value === "object" && value !== null && "value" in value && ("style" in value || "explode" in value);
+}
+async function buildHeaders(options, requestOptions) {
+  return {
+    ...options.headers ?? {},
+    ...await buildAuthHeaders(options.auth),
+    ...await options.getHeaders?.() ?? {},
+    ...requestOptions.headers ?? {}
+  };
+}
+async function buildAuthHeaders(auth) {
+  if (!auth) return {};
+  if (auth.type === "bearer") {
+    const token = await resolveAuthValue(auth.token);
+    return token ? { authorization: `Bearer ${token}` } : {};
+  }
+  const value = await resolveAuthValue(auth.value);
+  return value ? { [auth.headerName]: value } : {};
+}
+async function resolveAuthValue(value) {
+  return typeof value === "function" ? value() : value;
+}
+async function parseResponseBody(response) {
+  if (response.status === 204) return void 0;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (isJsonContentType(contentType)) {
+    const text = await response.text();
+    return text.trim() ? JSON.parse(text) : void 0;
+  }
+  if (isBinaryContentType(contentType)) {
+    return response.blob();
+  }
+  return response.text();
+}
+function isJsonContentType(contentType) {
+  const normalized = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return normalized === "application/json" || normalized.endsWith("+json");
+}
+function isBinaryContentType(contentType) {
+  const normalized = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return normalized === "application/octet-stream" || normalized === "application/pdf" || normalized.startsWith("image/");
+}
+function hasHeader(headers, name) {
+  return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+}
+function isNativeRequestBody(body) {
+  return typeof body === "string" || isInstanceOfGlobal(body, "FormData") || isInstanceOfGlobal(body, "URLSearchParams") || isInstanceOfGlobal(body, "Blob") || isInstanceOfGlobal(body, "ArrayBuffer") || isInstanceOfGlobal(body, "ReadableStream") || ArrayBuffer.isView(body);
+}
+function isInstanceOfGlobal(value, name) {
+  const constructor = globalThis[name];
+  return typeof constructor === "function" && value instanceof constructor;
+}
+function normalizeRetryOptions(retry) {
+  return {
+    attempts: Math.max(1, retry?.attempts ?? 1),
+    delayMs: Math.max(0, retry?.delayMs ?? 0),
+    methods: retry?.methods ?? ["GET", "HEAD", "OPTIONS"],
+    statuses: retry?.statuses ?? [408, 429, 500, 502, 503, 504]
+  };
+}
+function shouldRetryHttpError(error, method, retry, attempt) {
+  return attempt < retry.attempts && retry.methods.includes(method.toUpperCase()) && retry.statuses.includes(error.status);
+}
+function shouldRetryNetworkError(method, retry, attempt) {
+  return attempt < retry.attempts && retry.methods.includes(method.toUpperCase());
+}
+function createAbortScope(signal, timeoutMs) {
+  if (timeoutMs === void 0) {
+    return { signal, cleanup: () => {
+    } };
+  }
+  const controller = new AbortController();
+  const abortFromSignal = () => controller.abort(signal?.reason);
+  const timeout = setTimeout(() => controller.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, "TimeoutError")), Math.max(0, timeoutMs));
+  if (signal?.aborted) {
+    abortFromSignal();
+  } else {
+    signal?.addEventListener("abort", abortFromSignal, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abortFromSignal);
+    }
+  };
+}
+function isAbortError(error) {
+  return error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError") || error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+async function wait(delayMs) {
+  if (delayMs <= 0) return;
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+export {
+  ForgeHttpError,
+  createApiClient,
+  createApiClientOptions,
+  isForgeHttpError,
+  queryParam
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@archora/forge-runtime",
+  "version": "1.2.0",
+  "description": "Runtime helpers used by Archora Forge generated frontend modules.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/archora-dev/archora-forge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/archora-dev/archora-forge/issues"
+  },
+  "homepage": "https://github.com/archora-dev/archora-forge#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}