@zerotal/client 1.0.0

package/src/augment.ts

@@ -0,0 +1,8 @@
+import type { ApiClient } from "./ApiClient.ts";
+import type { ApiRouteMap } from "./types.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    client: ApiClient<ApiRouteMap>;
+  }
+}

package/src/config.ts

@@ -0,0 +1,22 @@
+import { deepMerge } from "@zerotal/core";
+import type { ApiClientConfig } from "./ApiClient.ts";
+
+export interface ClientConfigShape extends ApiClientConfig {
+  baseUrl?: string;
+}
+
+// The client carries no framework-level defaults of its own — `ApiClient` applies
+// its own internal defaults. deepMerge still gives a fresh, isolated copy of the
+// caller's options (and keeps every config factory on the one canonical merge).
+const defaults: Partial<ClientConfigShape> = {};
+
+export function ClientConfig(options: Partial<ClientConfigShape> = {}): Partial<ClientConfigShape> {
+  return deepMerge(defaults, options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    client: ClientConfigShape;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,136 @@
+import { ZerotalError } from "@zerotal/core";
+
+/**
+ * Thrown for any non-2xx HTTP response.
+ *
+ * `body` is the raw response text. For `422` validation failures the more specific
+ * {@link ValidationError} subclass is thrown instead, exposing the parsed field errors.
+ */
+export class ApiClientError extends ZerotalError {
+  /** Response headers, when available (used for `Retry-After`, rate-limit info, etc.). */
+  readonly headers: Headers | undefined;
+
+  constructor(
+    status: number,
+    readonly statusText: string,
+    readonly body: string,
+    headers?: Headers,
+  ) {
+    super(
+      `[API] ${status} ${statusText}${body ? ": " + body.slice(0, 200) : ""}`,
+      "E_API_CLIENT",
+      status,
+    );
+    this.headers = headers;
+  }
+
+  /** Parsed `Retry-After` (seconds or HTTP-date) in milliseconds, or `null` when absent. */
+  get retryAfterMs(): number | null {
+    return parseRetryAfter(this.headers?.get("retry-after"));
+  }
+}
+
+/**
+ * Thrown for `422 Unprocessable Entity` responses whose body matches the framework's
+ * validation shape (`{ message, errors: { field: string[] } }`, as produced by
+ * `@zerotal/validator`). Use the helpers to read field errors without re-parsing:
+ *
+ * @example
+ * try {
+ *   await api.post("/api/users", form);
+ * } catch (e) {
+ *   if (e instanceof ValidationError) {
+ *     setFieldErrors(e.errors);          // { email: ["…"], password: ["…"] }
+ *     if (e.has("email")) showError(e.first("email"));
+ *   }
+ * }
+ */
+export class ValidationError extends ApiClientError {
+  /** Field → messages map (always an array per field). */
+  readonly errors: Record<string, string[]>;
+  /** The top-level `message` from the response (e.g. "The given data was invalid."). */
+  readonly validationMessage: string;
+
+  constructor(
+    statusText: string,
+    body: string,
+    errors: Record<string, string[]>,
+    validationMessage: string,
+    headers?: Headers,
+  ) {
+    super(422, statusText, body, headers);
+    this.errors = errors;
+    this.validationMessage = validationMessage;
+  }
+
+  /** True when the given field has at least one error. */
+  has(field: string): boolean {
+    return (this.errors[field]?.length ?? 0) > 0;
+  }
+
+  /** The first error message for a field, or `undefined`. */
+  first(field: string): string | undefined {
+    return this.errors[field]?.[0];
+  }
+
+  /** All field errors. */
+  all(): Record<string, string[]> {
+    return this.errors;
+  }
+
+  /** The names of every field that failed. */
+  fields(): string[] {
+    return Object.keys(this.errors);
+  }
+}
+
+/**
+ * Build the right error for a non-2xx response — a {@link ValidationError} when the status is
+ * 422 and the body carries an `errors` bag, otherwise a plain {@link ApiClientError}.
+ */
+export function makeApiError(
+  status: number,
+  statusText: string,
+  body: string,
+  headers?: Headers,
+): ApiClientError {
+  if (status === 422) {
+    const parsed = _parseValidationBody(body);
+    if (parsed) {
+      return new ValidationError(statusText, body, parsed.errors, parsed.message, headers);
+    }
+  }
+  return new ApiClientError(status, statusText, body, headers);
+}
+
+/** Parse a `{ message?, errors: { field: string | string[] } }` body, or null if it doesn't match. */
+function _parseValidationBody(
+  body: string,
+): { errors: Record<string, string[]>; message: string } | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (!json || typeof json !== "object") return null;
+  const raw = (json as { errors?: unknown }).errors;
+  if (!raw || typeof raw !== "object") return null;
+
+  const errors: Record<string, string[]> = {};
+  for (const [field, val] of Object.entries(raw as Record<string, unknown>)) {
+    errors[field] = Array.isArray(val) ? val.map(String) : [String(val)];
+  }
+  const message = (json as { message?: unknown }).message;
+  return { errors, message: typeof message === "string" ? message : "The given data was invalid." };
+}
+
+/** Parse an HTTP `Retry-After` header (delta-seconds or HTTP-date) to milliseconds. */
+export function parseRetryAfter(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return null;
+}

package/src/http.ts

@@ -0,0 +1,192 @@
+import { ApiClientError } from "./errors.ts";
+import { CircuitBreakerOpenError } from "./CircuitBreaker.ts";
+
+// ── Path & query ───────────────────────────────────────────────────────────────
+
+/** Replace `{param}` placeholders in a path; throws on a missing param. */
+export function interpolatePath(
+  path: string,
+  params: Record<string, string | number> | undefined,
+): string {
+  if (!params) return path;
+  return path.replace(/\{(\w+)\}/g, (_, key: string) => {
+    const val = params[key];
+    if (val === undefined) {
+      throw new ApiClientError(0, "Bad Request", `Missing path parameter: "${key}"`);
+    }
+    return String(val);
+  });
+}
+
+/**
+ * Serialize a query object to a string, supporting nested arrays/objects with bracket notation:
+ *   { ids: [1, 2] }                 → ids[]=1&ids[]=2
+ *   { filter: { status: "open" } }  → filter[status]=open
+ *   { page: 2, active: true }       → page=2&active=true
+ * `undefined` and `null` values are skipped.
+ */
+export function serializeQuery(query: Record<string, unknown> | undefined): string {
+  if (!query) return "";
+  const pairs: [string, string][] = [];
+  for (const [key, value] of Object.entries(query)) _appendQuery(pairs, key, value);
+  if (pairs.length === 0) return "";
+  return "?" + new URLSearchParams(pairs).toString();
+}
+
+function _appendQuery(pairs: [string, string][], key: string, value: unknown): void {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) _appendQuery(pairs, `${key}[]`, item);
+  } else if (typeof value === "object" && !(value instanceof Date)) {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      _appendQuery(pairs, `${key}[${k}]`, v);
+    }
+  } else {
+    pairs.push([key, value instanceof Date ? value.toISOString() : String(value)]);
+  }
+}
+
+export function buildUrl(base: string, path: string, query?: Record<string, unknown>): string {
+  return base.replace(/\/+$/, "") + path + serializeQuery(query);
+}
+
+// ── Body serialization ──────────────────────────────────────────────────────────
+
+/**
+ * Turn a request body into a `BodyInit`. Plain objects/arrays are JSON-encoded (and get a JSON
+ * Content-Type); `FormData`, `Blob`/`File`, `URLSearchParams`, `ArrayBuffer`/typed arrays, and
+ * raw strings pass straight through so `fetch` can set the appropriate Content-Type itself
+ * (e.g. multipart boundaries for `FormData`).
+ */
+export function serializeBody(body: unknown): { body: BodyInit | undefined; contentType?: string } {
+  if (body === undefined || body === null) return { body: undefined };
+  if (typeof body === "string") return { body };
+  if (
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    body instanceof Blob ||
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body)
+  ) {
+    return { body: body as BodyInit };
+  }
+  return { body: JSON.stringify(body), contentType: "application/json" };
+}
+
+// ── Timeout / abort ──────────────────────────────────────────────────────────────
+
+/** Combine a caller-supplied signal with a timeout into one `AbortSignal` (fresh per attempt). */
+export function timeoutSignal(
+  timeoutMs?: number,
+  userSignal?: AbortSignal,
+): AbortSignal | undefined {
+  const signals: AbortSignal[] = [];
+  if (userSignal) signals.push(userSignal);
+  if (timeoutMs && timeoutMs > 0) signals.push(AbortSignal.timeout(timeoutMs));
+  if (signals.length === 0) return undefined;
+  return signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+}
+
+// ── Cookies ──────────────────────────────────────────────────────────────────────
+
+/** Read a cookie value from `document.cookie` (URL-decoded), or undefined outside the browser.
+ *  Local parser by design: this package runs in browsers and cannot import
+ *  server-side @zerotal/core (whose parseCookieHeader covers the server case). */
+export function readCookie(name: string): string | undefined {
+  const doc = (globalThis as { document?: { cookie?: string } }).document;
+  if (!doc?.cookie) return undefined;
+  for (const part of doc.cookie.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) {
+      return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+  }
+  return undefined;
+}
+
+// ── Retry policy ───────────────────────────────────────────────────────────────
+
+export interface RetryOptions {
+  /** Max retry attempts after the first try. Default: 2. */
+  attempts?: number;
+  /** HTTP methods eligible for retry. Default: idempotent verbs (GET/PUT/DELETE/HEAD/OPTIONS). */
+  methods?: string[];
+  /** HTTP statuses that should be retried. Default: 408, 425, 429, 500, 502, 503, 504. */
+  statuses?: number[];
+  /** Honor a `Retry-After` header when present. Default: true. */
+  respectRetryAfter?: boolean;
+  /** Compute the delay (ms) before attempt N. Default: exponential backoff + jitter. */
+  backoff?: (attempt: number, retryAfterMs: number | null) => number;
+}
+
+const DEFAULT_RETRY: Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff"> = {
+  attempts: 2,
+  methods: ["GET", "PUT", "DELETE", "HEAD", "OPTIONS"],
+  statuses: [408, 425, 429, 500, 502, 503, 504],
+  respectRetryAfter: true,
+};
+
+/** Resolve a `retry` config value to concrete options, or `null` when retry is disabled. */
+export function resolveRetry(
+  retry: number | RetryOptions | false | undefined,
+  method: string,
+): Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff"> {
+  if (retry === undefined || retry === false || retry === 0) {
+    return { ...DEFAULT_RETRY, attempts: 0 };
+  }
+  const opts = typeof retry === "number" ? { attempts: retry } : retry;
+  const merged = { ...DEFAULT_RETRY, ...opts };
+  // Methods are matched case-insensitively.
+  if (!merged.methods.some((m) => m.toUpperCase() === method.toUpperCase())) {
+    return { ...merged, attempts: 0 };
+  }
+  return merged;
+}
+
+function _defaultBackoff(attempt: number, retryAfterMs: number | null): number {
+  if (retryAfterMs !== null) return Math.min(retryAfterMs, 30_000);
+  const base = Math.min(1000 * 2 ** attempt, 30_000); // 1s, 2s, 4s, …
+  return base + Math.floor(base * 0.2 * Math.random()); // up to +20% jitter
+}
+
+function _isRetryable(
+  err: unknown,
+  statuses: number[],
+): { retry: false } | { retry: true; retryAfterMs: number | null } {
+  // Circuit-breaker fast-fail — never retry.
+  if (err instanceof CircuitBreakerOpenError) return { retry: false };
+  // HTTP error with a retryable status.
+  if (err instanceof ApiClientError) {
+    return statuses.includes(err.status)
+      ? { retry: true, retryAfterMs: err.retryAfterMs }
+      : { retry: false };
+  }
+  // Abort: a timeout is transient (retry); a caller cancellation is not.
+  if (err instanceof Error && err.name === "TimeoutError")
+    return { retry: true, retryAfterMs: null };
+  if (err instanceof Error && err.name === "AbortError") return { retry: false };
+  // Anything else thrown by fetch is a network/transport error → retry.
+  return { retry: true, retryAfterMs: null };
+}
+
+/** Run `fn`, retrying transient failures per `policy`. */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  policy: Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff">,
+): Promise<T> {
+  const backoff = policy.backoff ?? _defaultBackoff;
+  let attempt = 0;
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= policy.attempts) throw err;
+      const verdict = _isRetryable(err, policy.statuses);
+      if (!verdict.retry) throw err;
+      const retryAfter = policy.respectRetryAfter ? verdict.retryAfterMs : null;
+      await new Promise((r) => setTimeout(r, backoff(attempt, retryAfter)));
+      attempt++;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+export type {
+  ApiRouteMap,
+  RouteShape,
+  HttpMethod,
+  PathParams,
+  ParamRecord,
+  PathsFor,
+  ResponseOf,
+  BodyOf,
+  QueryOf,
+} from "./types.ts";
+
+export { ApiClient, ApiClientError, ValidationError } from "./ApiClient.ts";
+export type {
+  ApiClientConfig,
+  RequestConfig,
+  RequestInterceptor,
+  ResponseContext,
+  ResponseInterceptor,
+  ResponseMeta,
+  RequestOptions,
+  GetOptions,
+  MutationOptions,
+  TokenSource,
+  RetryOptions,
+} from "./ApiClient.ts";
+
+export { CircuitBreaker, CircuitBreakerOpenError } from "./CircuitBreaker.ts";
+export type { CircuitBreakerOptions, CircuitState } from "./CircuitBreaker.ts";
+
+// Realtime broadcasting client (native @zerotal/broadcasting protocol; familiar realtime-client API).
+export { Socket, Channel, PresenceChannel } from "./Socket.ts";
+export type { SocketOptions, SocketState, SocketLike, PresenceMember } from "./Socket.ts";
+
+export { ClientProvider, Client } from "./provider/ClientProvider.ts";
+export { ClientConfig } from "./config.ts";
+export type { ClientConfigShape } from "./config.ts";
+
+// ── Factory function ──────────────────────────────────────────────────────────
+
+import { ApiClient } from "./ApiClient.ts";
+import type { ApiRouteMap } from "./types.ts";
+import type { ApiClientConfig } from "./ApiClient.ts";
+
+/**
+ * Create a type-safe API client bound to your route map.
+ *
+ * @example
+ * // frontend/api.ts
+ * import { createApiClient } from '@zerotal/client';
+ * import type { Routes } from './routes';
+ *
+ * export const api = createApiClient<Routes>({
+ *   baseUrl: '/api',
+ *   headers: { 'X-Requested-With': 'XMLHttpRequest' },
+ * });
+ *
+ * // Anywhere in your UI:
+ * const user = await api.get('/users/{id}', { id: 1 });
+ * //    ^? UserResource  (inferred from Routes)
+ *
+ * const newUser = await api.post('/users', { name: 'Alice', email: 'alice@ex.com' });
+ */
+export function createApiClient<Routes extends ApiRouteMap>(
+  config: ApiClientConfig = {},
+): ApiClient<Routes> {
+  return new ApiClient<Routes>(config);
+}

package/src/provider/ClientProvider.ts

@@ -0,0 +1,26 @@
+import { ServiceProvider, createFacade } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import { ApiClient } from "../ApiClient.ts";
+import type { ClientConfigShape } from "../config.ts";
+import "../augment.ts";
+
+export class ClientProvider extends ServiceProvider {
+  static override provides = ["client"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test", "repl"];
+
+  override onRegister(): void {
+    this.app.container.singleton("client", async (c) => {
+      const cfg = (await c.make("config")) as { get<T>(path: string): T | undefined };
+      const options: ClientConfigShape = cfg.get<ClientConfigShape>("client") ?? {};
+      return new ApiClient(options);
+    });
+  }
+
+  // Pre-resolve the async singleton so the `Client` facade's makeSync access
+  // works after boot (an async factory needs one `await make()` first).
+  override async onBooted(): Promise<void> {
+    await this.app.container.make("client");
+  }
+}
+
+export const Client = createFacade<"client">("client");

package/src/types.ts

@@ -0,0 +1,112 @@
+// ── Path parameter extraction ─────────────────────────────────────────────────
+
+/**
+ * Extract the names of all `{param}` placeholders from a URL path string.
+ *
+ * @example
+ * PathParams<'/api/users/{id}/posts/{postId}'>
+ * // → 'id' | 'postId'
+ */
+export type PathParams<Path extends string> = Path extends `${string}{${infer Param}}${infer Tail}`
+  ? Param | PathParams<Tail>
+  : never;
+
+/**
+ * Build a record type from the path param names.
+ * When there are no params, resolves to `undefined` so the argument is omittable.
+ *
+ * @example
+ * ParamRecord<'/api/users/{id}'>  → { id: string | number }
+ * ParamRecord<'/api/users'>       → undefined
+ */
+export type ParamRecord<Path extends string> = [PathParams<Path>] extends [never]
+  ? undefined
+  : { [K in PathParams<Path>]: string | number };
+
+// ── Route map shape ───────────────────────────────────────────────────────────
+
+/** HTTP verbs used as route-key prefixes. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * Shape of a single route entry in the `ApiRouteMap`.
+ *
+ * All fields are optional — omit any that don't apply to a given route.
+ */
+export interface RouteShape {
+  /** URL path parameters, e.g. `{ id: string | number }` */
+  params?: Record<string, string | number>;
+  /** Query-string parameters */
+  query?: Record<string, string | number | boolean | undefined>;
+  /** Request body for POST/PUT/PATCH */
+  body?: Record<string, unknown>;
+  /** The JSON response body type */
+  response?: unknown;
+}
+
+/**
+ * The route type map you write (or generate) for your API.
+ *
+ * Keys are `'METHOD /path'` strings — e.g. `'GET /api/users/{id}'`.
+ *
+ * @example
+ * export interface Routes {
+ *   'GET /api/users': {
+ *     query:    { page?: number; perPage?: number };
+ *     response: { data: UserResource[]; total: number };
+ *   };
+ *   'GET /api/users/{id}': {
+ *     params:   { id: string | number };
+ *     response: UserResource;
+ *   };
+ *   'POST /api/users': {
+ *     body:     { name: string; email: string; password: string };
+ *     response: UserResource;
+ *   };
+ *   'DELETE /api/users/{id}': {
+ *     params:   { id: string | number };
+ *     response: void;
+ *   };
+ * }
+ */
+export type ApiRouteMap = Partial<Record<`${HttpMethod} ${string}`, RouteShape>>;
+
+// ── Accessor helpers ──────────────────────────────────────────────────────────
+
+/** Extract all paths registered for a given HTTP method from a route map. */
+export type PathsFor<Routes extends ApiRouteMap, Method extends HttpMethod> = {
+  [K in keyof Routes & string]: K extends `${Method} ${infer Path}` ? Path : never;
+}[keyof Routes & string];
+
+/** Get the `response` type for a specific method + path combination. */
+export type ResponseOf<
+  Routes extends ApiRouteMap,
+  Method extends HttpMethod,
+  Path extends string,
+> = `${Method} ${Path}` extends keyof Routes
+  ? Routes[`${Method} ${Path}`] extends { response: infer R }
+    ? R
+    : unknown
+  : unknown;
+
+/** Get the `body` type for a specific method + path combination. */
+export type BodyOf<
+  Routes extends ApiRouteMap,
+  Method extends HttpMethod,
+  Path extends string,
+> = `${Method} ${Path}` extends keyof Routes
+  ? Routes[`${Method} ${Path}`] extends { body: infer B }
+    ? B
+    : Record<string, unknown>
+  : Record<string, unknown>;
+
+/** Get the `query` type for a specific method + path combination. */
+export type QueryOf<
+  Routes extends ApiRouteMap,
+  Method extends HttpMethod,
+  Path extends string,
+> = `${Method} ${Path}` extends keyof Routes
+  ? Routes[`${Method} ${Path}`] extends { query: infer Q }
+    ? Q
+    : Record<string, string | number | boolean | undefined>
+  : Record<string, string | number | boolean | undefined>;