@cavi-ai/api-client 0.1.0

package/dist/core/gateway/run/sse-run-event-provider.js

@@ -0,0 +1,394 @@
+import { GATEWAY_API_ENDPOINTS } from "../../../contracts/paths.js";
+import { combineAbortSignals, consumeSseStream, isSseContentType, } from "../../sse/index.js";
+import { PORTAL_CLIENT_ID_HEADER } from "../../http/types.js";
+import { RUN_STREAM_EVENT_NAMES, } from "./contracts.js";
+const DEFAULT_POLL_INTERVAL_MS = 1_250;
+const DEFAULT_POLL_TIMEOUT_MS = 120_000;
+const APPROVAL_CHOICES = new Set([
+    "once",
+    "session",
+    "always",
+    "deny",
+]);
+function normalizeHttpBase(httpBase) {
+    const normalized = httpBase.trim().replace(/\/+$/u, "");
+    if (!normalized) {
+        throw new Error("GatewaySseRunEventProvider requires httpBase");
+    }
+    return normalized;
+}
+function normalizeClientId(clientId) {
+    const normalized = clientId.trim();
+    if (!normalized) {
+        throw new Error("GatewaySseRunEventProvider requires clientId");
+    }
+    return normalized;
+}
+/**
+ * Provider-neutral run-event SSE reader. Generic stream mechanics live in
+ * core/sse; this class owns gateway request headers, canonical run-event
+ * translation, and status polling fallback. Provider adapters should only
+ * supply endpoint maps and any gateway-specific session/routing headers.
+ */
+export class GatewaySseRunEventProvider {
+    httpBase;
+    authToken;
+    clientId;
+    endpoints;
+    headers;
+    resolveHeaders;
+    fallbackToPoll;
+    pollIntervalMs;
+    pollTimeoutMs;
+    fetchImpl;
+    constructor(options) {
+        this.httpBase = normalizeHttpBase(options.httpBase);
+        this.authToken = options.authToken?.trim() ?? "";
+        this.clientId = normalizeClientId(options.clientId);
+        this.endpoints = options.endpoints ?? GATEWAY_API_ENDPOINTS;
+        this.headers = options.headers ?? {};
+        this.resolveHeaders = options.resolveHeaders;
+        this.fallbackToPoll = options.fallbackToPoll ?? true;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.pollTimeoutMs = options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async subscribe(params, handlers) {
+        const localController = new AbortController();
+        const signal = combineAbortSignals(localController.signal, params.signal);
+        let disposed = false;
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            localController.abort();
+        };
+        void (async () => {
+            try {
+                await this.streamEvents(params.runId, signal, handlers);
+                if (!disposed)
+                    handlers.onComplete?.();
+            }
+            catch (error) {
+                if (!disposed)
+                    handlers.onError?.(error);
+            }
+            finally {
+                disposed = true;
+            }
+        })();
+        return { dispose };
+    }
+    buildHeaders(runId, phase, accept) {
+        const headers = {
+            Accept: accept,
+            [PORTAL_CLIENT_ID_HEADER]: this.clientId,
+        };
+        if (this.authToken) {
+            headers.Authorization = `Bearer ${this.authToken}`;
+        }
+        mergeHeaders(headers, this.headers);
+        if (this.resolveHeaders) {
+            mergeHeaders(headers, this.resolveHeaders({ runId, phase }));
+        }
+        return headers;
+    }
+    async streamEvents(runId, signal, handlers) {
+        const response = await this.fetchImpl(`${this.httpBase}${this.endpoints.runEvents(runId)}`, {
+            method: "GET",
+            headers: this.buildHeaders(runId, "events", "text/event-stream"),
+            cache: "no-store",
+            signal,
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            if (this.fallbackToPoll && shouldFallbackToPoll(response.status, body)) {
+                return this.pollUntilTerminal(runId, signal, handlers);
+            }
+            throw new Error(formatHttpError("run events failed", response.status, body));
+        }
+        const contentType = response.headers?.get?.("Content-Type") ?? "";
+        if (this.fallbackToPoll &&
+            contentType &&
+            !isSseContentType(contentType)) {
+            return this.pollUntilTerminal(runId, signal, handlers);
+        }
+        if (!response.body || typeof response.body.getReader !== "function") {
+            if (this.fallbackToPoll) {
+                return this.pollUntilTerminal(runId, signal, handlers);
+            }
+            throw new Error("run events response missing readable body");
+        }
+        await consumeSseStream(response.body, signal, (message) => {
+            emitFromSseMessage(message, runId, handlers);
+        });
+    }
+    async pollUntilTerminal(runId, signal, handlers) {
+        const startedAt = Date.now();
+        while (true) {
+            if (signal.aborted)
+                throw new Error("run polling aborted");
+            const response = await this.fetchImpl(`${this.httpBase}${this.endpoints.run(runId)}`, {
+                method: "GET",
+                headers: this.buildHeaders(runId, "poll", "application/json"),
+                cache: "no-store",
+                signal,
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                throw new Error(formatHttpError("run status polling failed", response.status, text));
+            }
+            let payload;
+            try {
+                payload = text.trim() ? JSON.parse(text) : {};
+            }
+            catch {
+                throw new Error(`run status polling returned invalid JSON: ${text.slice(0, 240)}`);
+            }
+            const status = typeof payload.status === "string" ? payload.status : "";
+            const resolvedRunId = typeof payload.run_id === "string" && payload.run_id.trim()
+                ? payload.run_id
+                : runId;
+            const at = parseTimestamp(payload.timestamp);
+            if (status === "completed") {
+                handlers.onEvent({
+                    event: RUN_STREAM_EVENT_NAMES.RUN_COMPLETED,
+                    runId: resolvedRunId,
+                    output: typeof payload.output === "string" ? payload.output : undefined,
+                    at,
+                });
+                return;
+            }
+            if (status === "failed") {
+                handlers.onEvent({
+                    event: RUN_STREAM_EVENT_NAMES.RUN_FAILED,
+                    runId: resolvedRunId,
+                    error: typeof payload.error === "string" ? payload.error : "run failed",
+                    at,
+                });
+                return;
+            }
+            if (status === "cancelled") {
+                handlers.onEvent({
+                    event: RUN_STREAM_EVENT_NAMES.RUN_CANCELLED,
+                    runId: resolvedRunId,
+                    reason: typeof payload.error === "string" ? payload.error : undefined,
+                    at,
+                });
+                return;
+            }
+            if (Date.now() - startedAt > this.pollTimeoutMs) {
+                throw new Error(`run polling timed out after ${this.pollTimeoutMs}ms`);
+            }
+            await wait(this.pollIntervalMs, signal);
+        }
+    }
+}
+function emitFromRaw(raw, defaultRunId, handlers) {
+    const eventName = typeof raw.event === "string" ? raw.event : "";
+    const runId = typeof raw.run_id === "string" && raw.run_id.trim()
+        ? raw.run_id
+        : defaultRunId;
+    const at = parseTimestamp(raw.timestamp);
+    if (eventName === RUN_STREAM_EVENT_NAMES.MESSAGE_DELTA) {
+        handlers.onEvent({
+            event: RUN_STREAM_EVENT_NAMES.MESSAGE_DELTA,
+            runId,
+            delta: typeof raw.delta === "string" ? raw.delta : "",
+            at,
+        });
+        return;
+    }
+    if (eventName === RUN_STREAM_EVENT_NAMES.RUN_COMPLETED) {
+        handlers.onEvent({
+            event: RUN_STREAM_EVENT_NAMES.RUN_COMPLETED,
+            runId,
+            output: typeof raw.output === "string" ? raw.output : undefined,
+            at,
+        });
+        return;
+    }
+    if (eventName === RUN_STREAM_EVENT_NAMES.RUN_FAILED) {
+        handlers.onEvent({
+            event: RUN_STREAM_EVENT_NAMES.RUN_FAILED,
+            runId,
+            error: typeof raw.error === "string" ? raw.error : "run failed",
+            at,
+        });
+        return;
+    }
+    if (eventName === RUN_STREAM_EVENT_NAMES.RUN_CANCELLED) {
+        handlers.onEvent({
+            event: RUN_STREAM_EVENT_NAMES.RUN_CANCELLED,
+            runId,
+            reason: typeof raw.error === "string" ? raw.error : undefined,
+            at,
+        });
+        return;
+    }
+    if (eventName === RUN_STREAM_EVENT_NAMES.APPROVAL_REQUEST) {
+        handlers.onEvent({
+            event: RUN_STREAM_EVENT_NAMES.APPROVAL_REQUEST,
+            runId,
+            choices: normalizeApprovalChoices(raw.choices),
+            at,
+        });
+        return;
+    }
+    const toolEvent = parseToolEvent(raw, runId, at);
+    if (toolEvent)
+        handlers.onEvent(toolEvent);
+}
+function emitFromSseMessage(message, runId, handlers) {
+    const raw = parseRawEvent(message.data);
+    if (raw)
+        emitFromRaw(raw, runId, handlers);
+}
+function parseToolEvent(raw, runId, at) {
+    const eventName = typeof raw.event === "string" ? raw.event : "";
+    const lowerEvent = eventName.toLowerCase();
+    const explicitName = readString(raw, "tool_name", "toolName", "function_name", "functionName");
+    const toolFieldName = readString(raw, "tool");
+    const genericName = lowerEvent.includes("tool") ? readString(raw, "name") : null;
+    const explicit = explicitName ?? toolFieldName ?? genericName;
+    if (!lowerEvent.includes("tool") && !explicitName && !toolFieldName)
+        return null;
+    const status = normalizeToolStatus(readString(raw, "status", "state", "phase"), lowerEvent);
+    const eventVariant = status === "failed"
+        ? RUN_STREAM_EVENT_NAMES.TOOL_CALL_FAILED
+        : status === "completed"
+            ? RUN_STREAM_EVENT_NAMES.TOOL_CALL_COMPLETED
+            : RUN_STREAM_EVENT_NAMES.TOOL_CALL_STARTED;
+    const fallbackName = `tool ${eventName
+        .replace(/^run[.:_-]|^tool[.:_-]/i, "")
+        .replace(/[.:_-]+/g, " ")
+        .trim() || "call"}`;
+    const toolCall = {
+        id: `${runId}:${explicit ?? fallbackName}:${at ?? Date.now()}`,
+        name: explicit ?? fallbackName,
+        status,
+        event: eventName || undefined,
+        input: stringifyPayload(raw.input ?? raw.args ?? raw.arguments ?? raw.params ?? raw.request),
+        output: stringifyPayload(raw.output ?? raw.result ?? raw.response),
+        error: readString(raw, "error", "errorMessage", "message") ?? undefined,
+        durationMs: readNumber(raw, "duration_ms", "durationMs", "elapsed_ms", "elapsedMs"),
+        at,
+    };
+    return { event: eventVariant, runId, toolCall, at };
+}
+function normalizeToolStatus(value, eventName) {
+    const lower = (value || eventName).toLowerCase();
+    if (lower.includes("fail") || lower.includes("error"))
+        return "failed";
+    if (lower.includes("complete") || lower.includes("success") || lower.includes("done")) {
+        return "completed";
+    }
+    if (lower.includes("start") || lower.includes("run") || lower.includes("delta"))
+        return "running";
+    return "pending";
+}
+function normalizeApprovalChoices(value) {
+    if (!Array.isArray(value))
+        return ["once", "session", "always", "deny"];
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string")
+            continue;
+        if (APPROVAL_CHOICES.has(item)) {
+            out.push(item);
+        }
+    }
+    return out.length > 0 ? out : ["once", "session", "always", "deny"];
+}
+function mergeHeaders(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value !== "string")
+            continue;
+        const trimmedKey = key.trim();
+        if (!trimmedKey)
+            continue;
+        target[trimmedKey] = value;
+    }
+}
+function readString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return null;
+}
+function readNumber(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+    }
+    return undefined;
+}
+function stringifyPayload(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? trimmed.slice(0, 900) : undefined;
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    try {
+        const json = JSON.stringify(value, null, 2);
+        return json.length > 900 ? `${json.slice(0, 900)}...` : json;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseTimestamp(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function parseRawEvent(data) {
+    try {
+        const parsed = JSON.parse(data);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function shouldFallbackToPoll(status, body) {
+    if (status === 404 || status === 405 || status === 406 || status === 501)
+        return true;
+    const lower = body.toLowerCase();
+    return status === 400 && lower.includes("stream") && lower.includes("enabled");
+}
+function formatHttpError(prefix, status, body) {
+    const trimmed = body.trim();
+    return `${prefix} with HTTP ${status}${trimmed ? `: ${trimmed.slice(0, 240)}` : ""}`;
+}
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new Error("aborted"));
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/core/gateway/run/stream-failure.d.ts

@@ -0,0 +1,11 @@
+export type NormalizedGatewayStreamFailure = {
+    state: "idle" | "connecting" | "reconnecting" | "connected" | "error";
+    error: string | null;
+    retryable: boolean;
+};
+/**
+ * Classifies stream / RPC failures for reconnect vs hard-error UX.
+ * GatewayRpcError codes are checked before substring heuristics on messages.
+ */
+export declare function normalizeGatewayStreamFailure(error: unknown): NormalizedGatewayStreamFailure;
+//# sourceMappingURL=stream-failure.d.ts.map

package/dist/core/gateway/run/stream-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-failure.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/run/stream-failure.ts"],"names":[],"mappings":"AAsGA,MAAM,MAAM,8BAA8B,GAAG;IAC3C,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,OAAO,CAAC;IACtE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,8BAA8B,CAsB5F"}

package/dist/core/gateway/run/stream-failure.js

@@ -0,0 +1,101 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+import { GatewayRpcError } from "../rpc/error.js";
+const TERMINAL_GATEWAY_RPC_CODES = new Set([
+    "unauthorized",
+    "forbidden",
+    "invalid_token",
+    "auth_failed",
+    "authentication_failed",
+    "not_authenticated",
+    "not_paired",
+    "pairing_required",
+    "device_identity_required",
+    "origin_not_allowed",
+    "socket_policy_violation",
+].map((c) => c.toLowerCase()));
+const RETRYABLE_GATEWAY_RPC_CODES = new Set(["socket_error", "socket_closed", "socket_unavailable", "timeout", "closed"].map((c) => c.toLowerCase()));
+function isTerminalGatewayRpcError(error) {
+    return TERMINAL_GATEWAY_RPC_CODES.has(error.code.trim().toLowerCase());
+}
+function isAuthLikeStreamError(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("unauthorized") ||
+        normalized.includes("forbidden") ||
+        normalized.includes("authentication") ||
+        normalized.includes("pairing required") ||
+        normalized.includes("not paired") ||
+        normalized.includes("device identity required") ||
+        normalized.includes("not authorized") ||
+        normalized.includes("401") ||
+        normalized.includes("403"));
+}
+function isOriginPolicyLikeStreamError(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("origin not allowed") ||
+        normalized.includes("gateway.controlui.allowedorigins") ||
+        (normalized.includes("code=1008") && normalized.includes("policy")));
+}
+function isDevicePairingLikeStreamError(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("pairing") ||
+        normalized.includes("not paired") ||
+        normalized.includes("device pairing") ||
+        (normalized.includes("device") &&
+            (normalized.includes("approve") ||
+                normalized.includes("pending") ||
+                normalized.includes("pair"))));
+}
+function isTerminalStreamErrorMessage(message) {
+    return (isAuthLikeStreamError(message) ||
+        isOriginPolicyLikeStreamError(message) ||
+        isDevicePairingLikeStreamError(message));
+}
+function describeUnknownError(error) {
+    if (typeof error === "string") {
+        return error;
+    }
+    if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") {
+        return `${error}`;
+    }
+    if (typeof error === "symbol") {
+        return error.description ? `Symbol(${error.description})` : "Symbol()";
+    }
+    if (error === undefined) {
+        return "undefined";
+    }
+    if (error === null) {
+        return "null";
+    }
+    try {
+        const json = JSON.stringify(error);
+        if (typeof json === "string" && json.length > 0) {
+            return json;
+        }
+    }
+    catch {
+        // Fall through to a stable object tag when JSON serialization is unavailable.
+    }
+    return Object.prototype.toString.call(error);
+}
+/**
+ * Classifies stream / RPC failures for reconnect vs hard-error UX.
+ * GatewayRpcError codes are checked before substring heuristics on messages.
+ */
+export function normalizeGatewayStreamFailure(error) {
+    if (!error) {
+        return { state: "idle", error: null, retryable: false };
+    }
+    const normalizedError = error instanceof Error ? error : new Error(describeUnknownError(error));
+    if (normalizedError instanceof GatewayRpcError && isTerminalGatewayRpcError(normalizedError)) {
+        return { state: "error", error: normalizedError.message, retryable: false };
+    }
+    if (isTerminalStreamErrorMessage(normalizedError.message)) {
+        return { state: "error", error: normalizedError.message, retryable: false };
+    }
+    if (normalizedError instanceof GatewayRpcError) {
+        if (RETRYABLE_GATEWAY_RPC_CODES.has(normalizedError.code.trim().toLowerCase())) {
+            return { state: "reconnecting", error: normalizedError.message, retryable: true };
+        }
+    }
+    return { state: "reconnecting", error: normalizedError.message, retryable: true };
+}

package/dist/core/gateway/snapshots/cache.d.ts

@@ -0,0 +1,7 @@
+export type TtlCacheEntry<TPayload> = {
+    payload: TPayload | null;
+    expiresAt: number;
+    inFlight: Promise<TPayload> | null;
+};
+export declare function getOrCreateTtlCacheEntry<TPayload>(cache: Map<string, TtlCacheEntry<TPayload>>, cacheKey: string): TtlCacheEntry<TPayload>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/core/gateway/snapshots/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/snapshots/cache.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,CAAC,QAAQ,IAAI;IACpC,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;CACpC,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,QAAQ,EAC/C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,EAC3C,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,QAAQ,CAAC,CAYzB"}

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

@@ -0,0 +1,13 @@
+export function getOrCreateTtlCacheEntry(cache, cacheKey) {
+    const existing = cache.get(cacheKey);
+    if (existing) {
+        return existing;
+    }
+    const entry = {
+        payload: null,
+        expiresAt: 0,
+        inFlight: null,
+    };
+    cache.set(cacheKey, entry);
+    return entry;
+}