@cavi-ai/api-client 0.1.0

package/dist/core/gateway/snapshots/transforms.js

@@ -0,0 +1,328 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+import { GATEWAY_PROBE_ENDPOINTS } from "../../../contracts/paths.js";
+import { asNumber, asString } from "../../data/guards.js";
+export { asNumber, asString };
+const ACTIVE_WINDOW_MS = 5 * 60_000;
+const STALLED_WINDOW_MS = 30 * 60_000;
+export function toIntInRange(raw, fallback, min, max) {
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, Math.round(parsed)));
+}
+export function deriveRunStatus(run) {
+    return deriveRunStatusAt(run, Date.now());
+}
+function deriveRunStatusAt(run, now) {
+    if (run.errors > 0) {
+        return "error";
+    }
+    if (run.updatedAt === null) {
+        return "idle";
+    }
+    const age = now - run.updatedAt;
+    if (age <= ACTIVE_WINDOW_MS) {
+        return "active";
+    }
+    if (age >= STALLED_WINDOW_MS) {
+        return "stalled";
+    }
+    return "idle";
+}
+export function normalizeRun(row, index) {
+    return normalizeRunAt(row, index, Date.now());
+}
+function normalizeRunAt(row, index, now) {
+    const title = asString(row.label) ?? asString(row.derivedTitle) ?? `Session ${index + 1}`;
+    const channel = asString(row.channel) ?? asString(row.origin?.provider) ?? "unknown";
+    const base = {
+        key: asString(row.key) ?? `unknown-${index}`,
+        title,
+        agentId: asString(row.agentId) ?? "unknown",
+        channel,
+        updatedAt: asNumber(row.updatedAt),
+        status: "idle",
+        totalTokens: asNumber(row.totalTokens) ?? 0,
+        errors: row.abortedLastRun === true ? 1 : 0,
+    };
+    return {
+        ...base,
+        status: deriveRunStatusAt(base, now),
+    };
+}
+export function resolveRunModel(row) {
+    if (!row) {
+        return undefined;
+    }
+    const explicitOverride = asString(row.modelOverride);
+    if (explicitOverride) {
+        return explicitOverride;
+    }
+    const providerOverride = asString(row.providerOverride);
+    const provider = providerOverride ??
+        asString(row.modelProvider) ??
+        asString(row.origin?.provider);
+    const model = asString(row.model);
+    if (provider && model) {
+        return `${provider}/${model}`;
+    }
+    return model ?? provider ?? undefined;
+}
+export function extractLogIncident(line) {
+    const lower = line.toLowerCase();
+    if (!lower.includes("error") &&
+        !lower.includes("warn") &&
+        !lower.includes("timeout")) {
+        return null;
+    }
+    const severity = lower.includes("fatal")
+        ? "critical"
+        : lower.includes("error")
+            ? "high"
+            : lower.includes("warn") || lower.includes("timeout")
+                ? "medium"
+                : "low";
+    const title = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+    return { severity, title };
+}
+export function utcDateYmd(date) {
+    return date.toISOString().slice(0, 10);
+}
+export function buildOverviewSnapshot(sessions, usage, readiness, options) {
+    const checkedAt = Date.now();
+    const providerBreakdown = Array.isArray(usage.aggregates?.byProvider)
+        ? usage.aggregates.byProvider
+            .map((entry) => ({
+            provider: asString(entry.provider) ?? "unknown",
+            tokens: asNumber(entry.totals?.totalTokens) ?? 0,
+            cost: asNumber(entry.totals?.totalCost) ?? 0,
+        }))
+            .sort((left, right) => right.tokens - left.tokens)
+        : [];
+    const topAgents = Array.isArray(usage.aggregates?.byAgent)
+        ? usage.aggregates.byAgent
+            .map((entry) => ({
+            agentId: asString(entry.agentId) ?? "unknown",
+            messages: asNumber(entry.messages) ?? 0,
+            cost: asNumber(entry.totals?.totalCost) ?? 0,
+        }))
+            .sort((left, right) => right.messages - left.messages)
+            .slice(0, 5)
+        : [];
+    const activeSessions = sessions.filter((row) => {
+        const updatedAt = asNumber(row.updatedAt);
+        return updatedAt !== null && checkedAt - updatedAt <= ACTIVE_WINDOW_MS;
+    }).length;
+    const totalFromOptions = options?.totalSessions;
+    const totalSessions = typeof totalFromOptions === "number" &&
+        Number.isFinite(totalFromOptions) &&
+        totalFromOptions >= 0
+        ? Math.trunc(totalFromOptions)
+        : sessions.length;
+    return {
+        health: {
+            live: true,
+            ready: readiness.ready,
+            checkedAt,
+            probes: {
+                healthz: {
+                    path: GATEWAY_PROBE_ENDPOINTS.healthz,
+                    ok: true,
+                    statusCode: 200,
+                },
+                readyz: {
+                    path: GATEWAY_PROBE_ENDPOINTS.readyz,
+                    ok: readiness.ready,
+                    statusCode: readiness.statusCode,
+                    failing: readiness.failing,
+                    uptimeMs: readiness.uptimeMs,
+                },
+            },
+        },
+        kpis: {
+            activeSessions,
+            totalSessions,
+            totalMessages: asNumber(usage.aggregates?.messages?.total) ?? 0,
+            totalToolCalls: asNumber(usage.aggregates?.messages?.toolCalls) ?? 0,
+            totalErrors: asNumber(usage.aggregates?.messages?.errors) ?? 0,
+            estimatedCostUsd: asNumber(usage.totals?.totalCost) ?? 0,
+        },
+        providerBreakdown,
+        topAgents,
+    };
+}
+export function buildRunsSnapshot(rows, usage) {
+    const now = Date.now();
+    const usageByKey = new Map((Array.isArray(usage.sessions) ? usage.sessions : [])
+        .map((entry) => {
+        const key = asString(entry.key);
+        return key ? [key, entry] : null;
+    })
+        .filter((entry) => Boolean(entry)));
+    const normalized = rows.map((row, index) => {
+        const base = normalizeRunAt(row, index, now);
+        const usageSession = usageByKey.get(base.key) ?? null;
+        const totalTokens = asNumber(usageSession?.usage?.totalTokens) ?? base.totalTokens;
+        return {
+            ...base,
+            totalTokens,
+            model: resolveRunModel(usageSession),
+            totalCostUsd: asNumber(usageSession?.usage?.totalCost) ?? undefined,
+        };
+    });
+    const history = [...normalized].sort((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0));
+    const live = history.filter((run) => run.status === "active" || run.status === "idle");
+    return {
+        live,
+        history,
+        summary: {
+            active: normalized.filter((run) => run.status === "active").length,
+            idle: normalized.filter((run) => run.status === "idle").length,
+            stalled: normalized.filter((run) => run.status === "stalled").length,
+            error: normalized.filter((run) => run.status === "error").length,
+        },
+    };
+}
+export function buildRunDetailSnapshot(run, usageSession, preview) {
+    const items = Array.isArray(preview?.items)
+        ? preview.items.map((item) => ({
+            role: asString(item.role) ??
+                asString(item.sender) ??
+                "unknown",
+            text: asString(item.text) ?? "",
+            at: asNumber(item.at),
+        }))
+        : [];
+    return {
+        run,
+        preview: {
+            status: asString(preview?.status) ?? "missing",
+            items,
+        },
+        usage: {
+            totalTokens: asNumber(usageSession?.usage?.totalTokens) ?? 0,
+            totalCostUsd: asNumber(usageSession?.usage?.totalCost) ?? 0,
+            messages: asNumber(usageSession?.usage?.messageCounts?.total) ?? 0,
+            toolCalls: asNumber(usageSession?.usage?.messageCounts?.toolCalls) ?? 0,
+            errors: asNumber(usageSession?.usage?.messageCounts?.errors) ?? 0,
+        },
+    };
+}
+export function buildRoutingMatrix(usage) {
+    const sessions = Array.isArray(usage.sessions) ? usage.sessions : [];
+    const matrix = new Map();
+    for (const session of sessions) {
+        const handler = asString(session.agentId) ?? "unknown";
+        const channel = asString(session.channel) ??
+            asString(session.origin?.provider) ??
+            "unknown";
+        const key = `${channel}::${handler}`;
+        const errors = asNumber(session.usage?.messageCounts?.errors) ?? 0;
+        const messages = asNumber(session.usage?.messageCounts?.total) ?? 0;
+        const row = matrix.get(key) ?? {
+            channel,
+            handler,
+            totalRuns: 0,
+            successRuns: 0,
+            failedRuns: 0,
+            successRate: 1,
+            messages: 0,
+        };
+        row.totalRuns += 1;
+        row.messages += messages;
+        if (errors > 0) {
+            row.failedRuns += 1;
+        }
+        else {
+            row.successRuns += 1;
+        }
+        row.successRate = row.totalRuns > 0 ? row.successRuns / row.totalRuns : 1;
+        matrix.set(key, row);
+    }
+    const rows = Array.from(matrix.values()).sort((left, right) => right.totalRuns - left.totalRuns);
+    const totals = rows.reduce((acc, row) => {
+        acc.totalRuns += row.totalRuns;
+        acc.successRuns += row.successRuns;
+        acc.failedRuns += row.failedRuns;
+        return acc;
+    }, { totalRuns: 0, successRuns: 0, failedRuns: 0 });
+    return { rows, totals };
+}
+export function buildIncidentsSnapshot(logs, sessions) {
+    const now = Date.now();
+    const lines = Array.isArray(logs.lines) ? logs.lines : [];
+    const incidents = new Map();
+    for (const line of lines) {
+        const extracted = extractLogIncident(line);
+        if (!extracted) {
+            continue;
+        }
+        const id = `log-${extracted.title.slice(0, 48)}`;
+        const existing = incidents.get(id);
+        if (!existing) {
+            incidents.set(id, {
+                id,
+                title: extracted.title,
+                summary: "Derived from logs.tail until dedicated incident APIs land.",
+                severity: extracted.severity,
+                status: extracted.severity === "critical" ? "blocked" : "open",
+                firstSeenAt: now,
+                lastSeenAt: now,
+                count: 1,
+                owner: "gateway",
+            });
+            continue;
+        }
+        existing.count += 1;
+        existing.lastSeenAt = now;
+    }
+    const rows = Array.from(incidents.values()).sort((left, right) => {
+        const weight = {
+            critical: 4,
+            high: 3,
+            medium: 2,
+            low: 1,
+        };
+        const severityDelta = weight[right.severity] - weight[left.severity];
+        if (severityDelta !== 0) {
+            return severityDelta;
+        }
+        return right.count - left.count;
+    });
+    const blockersFromRuns = sessions
+        .filter((row) => row.abortedLastRun === true)
+        .slice(0, 8)
+        .map((row, index) => ({
+        id: `abort-${asString(row.key) ?? index}`,
+        title: asString(row.label) ?? asString(row.derivedTitle) ?? "Aborted run",
+        summary: "Latest run ended with an abort flag.",
+        severity: "high",
+        status: "blocked",
+        firstSeenAt: asNumber(row.updatedAt) ?? now,
+        lastSeenAt: asNumber(row.updatedAt) ?? now,
+        count: 1,
+        owner: asString(row.agentId) ?? "unknown",
+    }));
+    const blockers = [
+        ...rows.filter((incident) => incident.status === "blocked"),
+        ...blockersFromRuns,
+    ];
+    return { incidents: rows, blockers };
+}
+export function parseGatewaySessionRunsQuery(searchParams) {
+    return {
+        search: searchParams.get("search")?.trim() ?? "",
+        activeMinutes: toIntInRange(searchParams.get("activeMinutes"), 60, 1, 60 * 24 * 14),
+        limit: toIntInRange(searchParams.get("limit"), 100, 1, 500),
+    };
+}
+export function parseGatewayRoutingQuery(searchParams) {
+    return {
+        windowDays: toIntInRange(searchParams.get("windowDays"), 7, 1, 90),
+    };
+}
+export const parseGatewayRunsQuery = parseGatewaySessionRunsQuery;

package/dist/core/http/client-id.d.ts

@@ -0,0 +1,6 @@
+import { PORTAL_CLIENT_ID_HEADER } from "./types.js";
+export { PORTAL_CLIENT_ID_HEADER };
+export declare function requirePortalClientId(value: string | null | undefined): string;
+export declare function normalizePortalClientId(value: string | null | undefined): string | null;
+export declare function isValidPortalClientId(value: string | null | undefined): boolean;
+//# sourceMappingURL=client-id.d.ts.map

package/dist/core/http/client-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-id.d.ts","sourceRoot":"","sources":["../../../src/core/http/client-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAInC,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,CAYR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CASf;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAET"}

package/dist/core/http/client-id.js

@@ -0,0 +1,29 @@
+import { PORTAL_CLIENT_ID_HEADER } from "./types.js";
+export { PORTAL_CLIENT_ID_HEADER };
+const PORTAL_CLIENT_ID_PATTERN = /^[a-z0-9._-]+$/u;
+export function requirePortalClientId(value) {
+    if (typeof value !== "string") {
+        throw new Error("Missing clientId. Pass a clientId explicitly.");
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        throw new Error("Missing clientId. Pass a clientId explicitly.");
+    }
+    if (!PORTAL_CLIENT_ID_PATTERN.test(normalized)) {
+        throw new Error("Portal client id must be a lowercase slug.");
+    }
+    return normalized;
+}
+export function normalizePortalClientId(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!normalized || !PORTAL_CLIENT_ID_PATTERN.test(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+export function isValidPortalClientId(value) {
+    return normalizePortalClientId(value) !== null;
+}

package/dist/core/http/client.d.ts

@@ -0,0 +1,25 @@
+import { type HttpApiClientOptions, type HttpApiHttpMethod, type HttpApiRequestInit, type HttpApiTrace, type HttpApiTransport } from "./types.js";
+export declare class BaseHttpApiClient {
+    readonly surface: HttpApiTrace["surface"];
+    readonly baseUrl: string;
+    readonly basePath: string;
+    readonly authToken: string;
+    readonly clientId: string;
+    readonly defaultTimeoutMs: number;
+    readonly cache: RequestCache;
+    readonly credentials?: RequestCredentials;
+    private readonly fetchImpl;
+    private readonly onTrace?;
+    constructor(surface: HttpApiTrace["surface"], options: HttpApiClientOptions);
+    protected resolvePath(path: string): string;
+    protected resolveUrl(path: string): string;
+    protected buildHeaders(init?: HttpApiRequestInit): Record<string, string>;
+    protected buildBody(init?: HttpApiRequestInit): BodyInit | undefined;
+    protected buildFetchInit(method: HttpApiHttpMethod, headers: Record<string, string>, body: BodyInit | undefined, signal: AbortSignal, init?: HttpApiRequestInit): RequestInit;
+    protected emitTrace(trace: HttpApiTrace): void;
+    protected requestRaw(path: string, init?: HttpApiRequestInit): Promise<Response>;
+    protected requestJson<TResponse>(path: string, init?: HttpApiRequestInit): Promise<TResponse>;
+    protected requestBlob(path: string, init?: HttpApiRequestInit): Promise<Blob>;
+    createTransport(): HttpApiTransport;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/core/http/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/core/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAwEpB,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAE1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAgC;gBAE7C,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,oBAAoB;IAa3E,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3C,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI1C,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAmBzE,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,QAAQ,GAAG,SAAS;IAIpE,SAAS,CAAC,cAAc,CACtB,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,IAAI,EAAE,QAAQ,GAAG,SAAS,EAC1B,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE,kBAAkB,GACxB,WAAW;IAWd,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;cAQ9B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;cA+EtE,WAAW,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC;cAoBnF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnF,eAAe,IAAI,gBAAgB;CAIpC"}

package/dist/core/http/client.js

@@ -0,0 +1,234 @@
+import { IDEMPOTENCY_KEY_HEADER, PORTAL_CLIENT_ID_HEADER, } from "./types.js";
+import { HttpApiError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_CLIENT_ID = "cavi-api-client";
+function normalizeBaseUrl(baseUrl, allowRelative = false) {
+    const trimmed = baseUrl.trim();
+    if (!trimmed && allowRelative)
+        return "";
+    if (!trimmed)
+        throw new Error("Missing baseUrl for HTTP API client");
+    return trimmed.replace(/\/+$/, "");
+}
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return "/";
+    return trimmed.charAt(0) === "/" ? trimmed : `/${trimmed}`;
+}
+function normalizeBasePath(basePath) {
+    if (!basePath)
+        return "";
+    const path = normalizePath(basePath).replace(/\/+$/, "");
+    return path === "/" ? "" : path;
+}
+function previewErrorBody(body) {
+    return body.length > 500 ? `${body.slice(0, 500)}…` : body;
+}
+function buildUrl(baseUrl, basePath, path) {
+    return `${baseUrl}${basePath}${normalizePath(path)}`;
+}
+function buildRequestBody(init) {
+    if (!init)
+        return undefined;
+    if ("rawBody" in init && init.rawBody !== undefined)
+        return init.rawBody;
+    if (!("body" in init) || init.body === undefined)
+        return undefined;
+    return JSON.stringify(init.body);
+}
+function createRequestAbortSignal(timeoutMs, inputSignal) {
+    const controller = new AbortController();
+    const abort = (reason) => {
+        if (controller.signal.aborted)
+            return;
+        if (reason !== undefined) {
+            controller.abort(reason);
+            return;
+        }
+        controller.abort();
+    };
+    const abortFromInputSignal = () => abort(inputSignal?.reason);
+    if (inputSignal?.aborted) {
+        abortFromInputSignal();
+    }
+    else {
+        inputSignal?.addEventListener("abort", abortFromInputSignal, { once: true });
+    }
+    const timeout = setTimeout(() => abort(), timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            inputSignal?.removeEventListener("abort", abortFromInputSignal);
+        },
+    };
+}
+export class BaseHttpApiClient {
+    surface;
+    baseUrl;
+    basePath;
+    authToken;
+    clientId;
+    defaultTimeoutMs;
+    cache;
+    credentials;
+    fetchImpl;
+    onTrace;
+    constructor(surface, options) {
+        this.surface = surface;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl, options.allowRelativeBaseUrl);
+        this.basePath = normalizeBasePath(options.basePath);
+        this.authToken = options.auth?.bearerToken?.trim() ?? "";
+        this.clientId = options.auth?.clientId?.trim() || DEFAULT_CLIENT_ID;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.cache = options.cache ?? "no-store";
+        this.credentials = options.credentials;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.onTrace = options.onTrace;
+    }
+    resolvePath(path) {
+        return normalizePath(path);
+    }
+    resolveUrl(path) {
+        return buildUrl(this.baseUrl, this.basePath, path);
+    }
+    buildHeaders(init) {
+        const headers = {
+            Accept: "application/json",
+            [PORTAL_CLIENT_ID_HEADER]: this.clientId,
+            ...(init?.headers ?? {}),
+        };
+        if (this.authToken) {
+            headers.Authorization = `Bearer ${this.authToken}`;
+        }
+        if (init?.idempotencyKey) {
+            headers[IDEMPOTENCY_KEY_HEADER] = init.idempotencyKey;
+        }
+        if (init && "body" in init && init.body !== undefined) {
+            headers["Content-Type"] = headers["Content-Type"] ?? "application/json";
+        }
+        return headers;
+    }
+    buildBody(init) {
+        return buildRequestBody(init);
+    }
+    buildFetchInit(method, headers, body, signal, init) {
+        return {
+            method,
+            headers,
+            body,
+            cache: init?.cache ?? this.cache,
+            credentials: init?.credentials ?? this.credentials,
+            signal,
+        };
+    }
+    emitTrace(trace) {
+        try {
+            this.onTrace?.(trace);
+        }
+        catch {
+            // Trace observers must not change request behavior.
+        }
+    }
+    async requestRaw(path, init) {
+        const normalizedPath = this.resolvePath(path);
+        const method = init?.method ?? "GET";
+        const startedAt = Date.now();
+        const timeoutMs = init?.timeoutMs ?? this.defaultTimeoutMs;
+        const abortSignal = createRequestAbortSignal(timeoutMs, init?.signal);
+        const headers = this.buildHeaders(init);
+        const body = this.buildBody(init);
+        const url = this.resolveUrl(normalizedPath);
+        try {
+            const response = await this.fetchImpl(url, this.buildFetchInit(method, headers, body, abortSignal.signal, init));
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.emitTrace({
+                    at: Date.now(),
+                    surface: this.surface,
+                    method,
+                    path: normalizedPath,
+                    url,
+                    ok: false,
+                    status: response.status,
+                    durationMs: Date.now() - startedAt,
+                    error: previewErrorBody(errorText),
+                });
+                throw new HttpApiError({
+                    message: `${method} ${normalizedPath} failed with HTTP ${response.status}`,
+                    path: normalizedPath,
+                    url,
+                    method,
+                    status: response.status,
+                    body: errorText,
+                });
+            }
+            this.emitTrace({
+                at: Date.now(),
+                surface: this.surface,
+                method,
+                path: normalizedPath,
+                url,
+                ok: true,
+                status: response.status,
+                durationMs: Date.now() - startedAt,
+            });
+            return response;
+        }
+        catch (error) {
+            if (error instanceof HttpApiError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.emitTrace({
+                at: Date.now(),
+                surface: this.surface,
+                method,
+                path: normalizedPath,
+                url,
+                ok: false,
+                durationMs: Date.now() - startedAt,
+                error: message,
+            });
+            throw new HttpApiError({
+                message: `${method} ${normalizedPath} failed: ${message}`,
+                path: normalizedPath,
+                url,
+                method,
+                status: 0,
+                body: "",
+            });
+        }
+        finally {
+            abortSignal.cleanup();
+        }
+    }
+    async requestJson(path, init) {
+        const response = await this.requestRaw(path, init);
+        const text = await response.text();
+        if (!text.trim()) {
+            return {};
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new HttpApiError({
+                message: `${init?.method ?? "GET"} ${this.resolvePath(path)} returned invalid JSON`,
+                path: this.resolvePath(path),
+                url: this.resolveUrl(path),
+                method: init?.method ?? "GET",
+                status: response.status,
+                body: text,
+            });
+        }
+    }
+    async requestBlob(path, init) {
+        const response = await this.requestRaw(path, init);
+        return response.blob();
+    }
+    createTransport() {
+        return (path, init) => this.requestJson(path, init);
+    }
+}

package/dist/core/http/contracts.d.ts

@@ -0,0 +1,3 @@
+/** Human-readable HTTP contract line for envelopes and diagnostics. */
+export declare function describeHttpContract(method: string, path: string, bodyHint?: string): string;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/core/http/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/core/http/contracts.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAGR"}

package/dist/core/http/contracts.js

@@ -0,0 +1,5 @@
+/** Human-readable HTTP contract line for envelopes and diagnostics. */
+export function describeHttpContract(method, path, bodyHint) {
+    const base = `${method} ${path}`;
+    return bodyHint ? `${base} ${bodyHint}` : base;
+}

package/dist/core/http/errors.d.ts

@@ -0,0 +1,17 @@
+import type { HttpApiHttpMethod } from "./types.js";
+export declare class HttpApiError extends Error {
+    readonly path: string;
+    readonly url: string;
+    readonly method: HttpApiHttpMethod;
+    readonly status: number;
+    readonly body: string;
+    constructor(params: {
+        message: string;
+        path: string;
+        url: string;
+        method: HttpApiHttpMethod;
+        status: number;
+        body: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/http/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/http/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,iBAAiB,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd;CASF"}

package/dist/core/http/errors.js

@@ -0,0 +1,16 @@
+export class HttpApiError extends Error {
+    path;
+    url;
+    method;
+    status;
+    body;
+    constructor(params) {
+        super(params.message);
+        this.name = "HttpApiError";
+        this.path = params.path;
+        this.url = params.url;
+        this.method = params.method;
+        this.status = params.status;
+        this.body = params.body;
+    }
+}