@cavi-ai/api-client 0.1.0

package/dist/core/gateway/client/runtime-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-targets.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/client/runtime-targets.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,kCAAkC,GAAG;IAC/C,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC3C,MAAM,GAAG,IAAI,CAMf;AAcD,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACtC,OAAO,CA0BT;AAQD,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,kCAAuC,GAC/C,MAAM,CAqBR;AAED,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,kCAAuC,GAC/C,MAAM,CAuBR;AAED,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kCAAuC,GAC/C,MAAM,CAGR"}

package/dist/core/gateway/client/runtime-targets.js

@@ -0,0 +1,86 @@
+import { resolveGatewayTargets } from "../../ws/targets.js";
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
+const DEFAULT_LOCAL_GATEWAY_WS_URL = "ws://127.0.0.1:18789/ws";
+export function normalizeGatewayBaseUrl(rawGatewayBaseUrl) {
+    const trimmed = rawGatewayBaseUrl?.trim() ?? "";
+    if (!trimmed) {
+        return null;
+    }
+    return trimmed.replace(/\/+$/u, "");
+}
+function loopbackEquivalenceKey(url) {
+    const proto = url.protocol.toLowerCase();
+    if (proto !== "http:" && proto !== "https:") {
+        return null;
+    }
+    if (!LOOPBACK_HOSTNAMES.has(url.hostname.toLowerCase())) {
+        return null;
+    }
+    const effectivePort = url.port || (proto === "https:" ? "443" : "80");
+    return `${proto}//loopback:${effectivePort}`;
+}
+export function sameGatewayDaemon(leftBaseUrl, rightBaseUrl) {
+    const left = normalizeGatewayBaseUrl(leftBaseUrl);
+    const right = normalizeGatewayBaseUrl(rightBaseUrl);
+    if (!left || !right) {
+        return false;
+    }
+    if (left === right) {
+        return true;
+    }
+    let leftUrl;
+    let rightUrl;
+    try {
+        leftUrl = new URL(left);
+        rightUrl = new URL(right);
+    }
+    catch {
+        return false;
+    }
+    const leftLoopback = loopbackEquivalenceKey(leftUrl);
+    const rightLoopback = loopbackEquivalenceKey(rightUrl);
+    return (leftLoopback !== null &&
+        rightLoopback !== null &&
+        leftLoopback === rightLoopback);
+}
+function originToWsUrl(origin) {
+    const wsProtocol = origin.startsWith("https") ? "wss:" : "ws:";
+    const url = new URL(origin);
+    return `${wsProtocol}//${url.host}/ws`;
+}
+export function resolveGatewayRuntimeHttpBase(gatewayBaseUrl, options = {}) {
+    const normalizedGatewayBaseUrl = normalizeGatewayBaseUrl(gatewayBaseUrl);
+    const configuredGatewayBaseUrl = normalizeGatewayBaseUrl(options.configuredGatewayBaseUrl);
+    const windowOrigin = options.windowOrigin?.trim() || null;
+    if (normalizedGatewayBaseUrl &&
+        configuredGatewayBaseUrl &&
+        windowOrigin &&
+        sameGatewayDaemon(normalizedGatewayBaseUrl, configuredGatewayBaseUrl)) {
+        return windowOrigin;
+    }
+    if (!normalizedGatewayBaseUrl) {
+        return windowOrigin ?? "";
+    }
+    return resolveGatewayTargets(normalizedGatewayBaseUrl).httpBase;
+}
+export function resolveGatewayRuntimeWsUrl(gatewayBaseUrl, options = {}) {
+    const normalizedGatewayBaseUrl = normalizeGatewayBaseUrl(gatewayBaseUrl);
+    const configuredGatewayBaseUrl = normalizeGatewayBaseUrl(options.configuredGatewayBaseUrl);
+    const windowOrigin = options.windowOrigin?.trim() || null;
+    if (normalizedGatewayBaseUrl &&
+        configuredGatewayBaseUrl &&
+        windowOrigin &&
+        sameGatewayDaemon(normalizedGatewayBaseUrl, configuredGatewayBaseUrl)) {
+        return originToWsUrl(windowOrigin);
+    }
+    if (!normalizedGatewayBaseUrl) {
+        return windowOrigin
+            ? originToWsUrl(windowOrigin)
+            : (options.fallbackWsUrl ?? DEFAULT_LOCAL_GATEWAY_WS_URL);
+    }
+    return resolveGatewayTargets(normalizedGatewayBaseUrl).wsUrl;
+}
+export function resolveGatewayRuntimeHttpUrl(gatewayBaseUrl, pathname, options = {}) {
+    const normalizedPath = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    return `${resolveGatewayRuntimeHttpBase(gatewayBaseUrl, options)}${normalizedPath}`;
+}

package/dist/core/gateway/envelope/envelope.d.ts

@@ -0,0 +1,25 @@
+import type { ContractGap, ContractGapReason, DataEnvelope, MutationResult } from "./types.js";
+export type { ConnectivityDomain, ConnectivityStatus, ContractGap, ContractGapReason, DataEnvelope, DataSourceMode, MutationResult, } from "./types.js";
+export declare function fallbackGap(area: string, expectedContract: string, note: string, reason?: ContractGapReason, httpStatus?: number): ContractGap;
+export declare function classifyFallbackError(error: unknown): {
+    message: string;
+    reason: ContractGapReason;
+    httpStatus?: number;
+};
+/** @deprecated Use {@link classifyFallbackError} for structured diagnostics. */
+export declare function describeFallbackReason(error: unknown): string;
+export declare function withFallback<TData>(params: {
+    run: () => Promise<TData>;
+    fallback: TData;
+    area: string;
+    expectedContract: string;
+    note: string;
+}): Promise<DataEnvelope<TData>>;
+export declare function withMutationResult<TData>(params: {
+    run: () => Promise<TData>;
+    fallback: () => TData;
+    area: string;
+    expectedContract: string;
+    note: string;
+}): Promise<MutationResult<TData>>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/core/gateway/envelope/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/envelope/envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,iBAAiB,EAC1B,UAAU,CAAC,EAAE,MAAM,GAClB,WAAW,CAQb;AAgCD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAyDA;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7D;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE;IAChD,GAAG,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAoC/B;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE;IACtD,GAAG,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,KAAK,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAqBjC"}

package/dist/core/gateway/envelope/envelope.js

@@ -0,0 +1,141 @@
+import { GatewayHttpError } from "../../http/gateway-error.js";
+export function fallbackGap(area, expectedContract, note, reason, httpStatus) {
+    return {
+        area,
+        expectedContract,
+        note,
+        reason,
+        httpStatus,
+    };
+}
+function normalizeErrorMessage(error) {
+    return (error instanceof Error ? error.message : String(error)).trim();
+}
+function isBackendFailureMessage(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("unavailable") ||
+        normalized.includes("not available") ||
+        normalized.includes("fetch failed") ||
+        normalized.includes("failed to fetch") ||
+        normalized.includes("network error") ||
+        normalized.includes("networkerror") ||
+        normalized.includes("econn") ||
+        normalized.includes("timed out") ||
+        normalized.includes("timeout") ||
+        normalized.includes("refused"));
+}
+function isTransportFailureMessage(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("not connected") ||
+        normalized.includes("gateway client not connected") ||
+        normalized.includes("socket") ||
+        normalized.includes("websocket"));
+}
+export function classifyFallbackError(error) {
+    if (error instanceof GatewayHttpError) {
+        if (error.status === 404) {
+            return {
+                message: "The current gateway does not expose one or more required routes yet.",
+                reason: "endpoint-not-found",
+                httpStatus: 404,
+            };
+        }
+        if (error.status === 502 || error.status === 503) {
+            return {
+                message: `Backend unavailable (${error.status}).`,
+                reason: "backend-unavailable",
+                httpStatus: error.status,
+            };
+        }
+        return {
+            message: `Gateway request failed with ${error.status}.`,
+            reason: "backend-unavailable",
+            httpStatus: error.status,
+        };
+    }
+    const msg = normalizeErrorMessage(error);
+    // Gateway returns `unknown method: …` when the running binary predates a WS handler.
+    // Treat as unavailable so dashboards degrade to mock data + contract gap instead of hard-failing queries.
+    if (/unknown method\b/i.test(msg)) {
+        return {
+            message: `Gateway RPC not supported: ${msg}`,
+            reason: "backend-unavailable",
+        };
+    }
+    if (isTransportFailureMessage(msg)) {
+        return {
+            message: `Transport disconnected: ${msg}.`,
+            reason: "transport-disconnected",
+        };
+    }
+    if (isBackendFailureMessage(msg)) {
+        return {
+            message: error instanceof TypeError
+                ? "The gateway request failed before a response was received."
+                : `Backend unavailable: ${msg}.`,
+            reason: "backend-unavailable",
+        };
+    }
+    if (error instanceof TypeError) {
+        return {
+            message: `Runtime: ${msg}.`,
+            reason: "unknown",
+        };
+    }
+    return {
+        message: `Runtime: ${msg}.`,
+        reason: "unknown",
+    };
+}
+/** @deprecated Use {@link classifyFallbackError} for structured diagnostics. */
+export function describeFallbackReason(error) {
+    return classifyFallbackError(error).message;
+}
+export async function withFallback(params) {
+    try {
+        const data = await params.run();
+        return {
+            data,
+            source: "gateway",
+            fetchedAt: Date.now(),
+            contractGaps: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof GatewayHttpError &&
+            (error.status === 401 || error.status === 403)) {
+            throw error;
+        }
+        const classified = classifyFallbackError(error);
+        if (classified.reason === "unknown") {
+            throw error;
+        }
+        return {
+            data: params.fallback,
+            source: "mock",
+            fetchedAt: Date.now(),
+            contractGaps: [
+                fallbackGap(params.area, params.expectedContract, `${params.note}. ${classified.message}`, classified.reason, classified.httpStatus),
+            ],
+        };
+    }
+}
+export async function withMutationResult(params) {
+    try {
+        const data = await params.run();
+        return {
+            data,
+            source: "gateway",
+            appliedAt: Date.now(),
+            contractGaps: [],
+        };
+    }
+    catch (error) {
+        if (error instanceof GatewayHttpError &&
+            (error.status === 401 || error.status === 403)) {
+            throw error;
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`${params.note}. ${params.expectedContract} unavailable: ${reason}`, { cause: error });
+    }
+}

package/dist/core/gateway/envelope/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./envelope.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/gateway/envelope/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/envelope/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,mBAAmB,YAAY,CAAC"}

package/dist/core/gateway/envelope/index.js

@@ -0,0 +1 @@
+export * from "./envelope.js";

package/dist/core/gateway/envelope/types.d.ts

@@ -0,0 +1,32 @@
+export type DataSourceMode = "gateway" | "mock";
+export type ContractGapReason = "backend-unavailable" | "backend-not-configured" | "endpoint-not-found" | "auth-insufficient" | "transport-disconnected" | "unknown";
+export type ContractGap = {
+    area: string;
+    expectedContract: string;
+    note: string;
+    reason?: ContractGapReason;
+    httpStatus?: number;
+};
+export type DataEnvelope<TData> = {
+    data: TData;
+    source: DataSourceMode;
+    fetchedAt: number;
+    contractGaps: ContractGap[];
+};
+export type ConnectivityStatus = "live" | "empty-but-valid" | "mock-fallback" | "conditional-unavailable" | "not-loaded";
+export type ConnectivityDomain = {
+    domain: string;
+    label: string;
+    transport: "ws" | "http" | "mixed";
+    source: DataSourceMode | "not-loaded";
+    status: ConnectivityStatus;
+    contractGaps: readonly ContractGap[];
+    fetchedAt: number | null;
+};
+export type MutationResult<TData> = {
+    data: TData;
+    source: DataSourceMode;
+    appliedAt: number;
+    contractGaps: ContractGap[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/gateway/envelope/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/envelope/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD,MAAM,MAAM,iBAAiB,GACzB,qBAAqB,GACrB,wBAAwB,GACxB,oBAAoB,GACpB,mBAAmB,GACnB,wBAAwB,GACxB,SAAS,CAAC;AAEd,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,KAAK,IAAI;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,iBAAiB,GACjB,eAAe,GACf,yBAAyB,GACzB,YAAY,CAAC;AAEjB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IACnC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI;IAClC,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B,CAAC"}

package/dist/core/gateway/envelope/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/gateway/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./client/index.js";
+export * from "./agent/index.js";
+export * from "./run/index.js";
+export * from "./rpc/index.js";
+export * from "./snapshots/index.js";
+export * from "./resources/index.js";
+export * from "./envelope/index.js";
+export * from "./portal/index.js";
+export * from "./providers/index.js";
+export * from "./jobs.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/gateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/gateway/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC"}

package/dist/core/gateway/index.js

@@ -0,0 +1,10 @@
+export * from "./client/index.js";
+export * from "./agent/index.js";
+export * from "./run/index.js";
+export * from "./rpc/index.js";
+export * from "./snapshots/index.js";
+export * from "./resources/index.js";
+export * from "./envelope/index.js";
+export * from "./portal/index.js";
+export * from "./providers/index.js";
+export * from "./jobs.js";

package/dist/core/gateway/jobs.d.ts

@@ -0,0 +1,44 @@
+export type GatewayJobStatus = "queued" | "running" | "completed" | "succeeded" | "failed" | "cancelled" | "canceled" | "stopping" | "stopped" | string;
+export type GatewayJobLike = {
+    status?: GatewayJobStatus | null;
+    error?: unknown;
+};
+export declare const GATEWAY_JOB_SUCCESS_STATUSES: readonly ["completed", "succeeded", "success"];
+export declare const GATEWAY_JOB_TERMINAL_STATUSES: readonly ["completed", "succeeded", "success", "failed", "error", "cancelled", "canceled", "stopped"];
+export type GatewayJobWaitUpdate<TJob extends GatewayJobLike> = {
+    attempt: number;
+    elapsedMs: number;
+    job: TJob;
+};
+export type GatewayJobSleep = (delayMs: number, signal?: AbortSignal) => Promise<void>;
+export type GatewayJobWaitOptions<TJob extends GatewayJobLike> = {
+    fetchJob: () => Promise<TJob>;
+    intervalMs?: number;
+    timeoutMs?: number;
+    maxAttempts?: number;
+    signal?: AbortSignal;
+    onUpdate?: (update: GatewayJobWaitUpdate<TJob>) => void;
+    isTerminal?: (job: TJob) => boolean;
+    sleep?: GatewayJobSleep;
+    now?: () => number;
+};
+export declare class GatewayJobTimeoutError<TJob extends GatewayJobLike> extends Error {
+    readonly name = "GatewayJobTimeoutError";
+    readonly attempts: number;
+    readonly elapsedMs: number;
+    readonly lastJob: TJob | null;
+    constructor(params: {
+        attempts: number;
+        elapsedMs: number;
+        lastJob: TJob | null;
+    });
+}
+export declare class GatewayJobAbortError extends Error {
+    readonly name = "GatewayJobAbortError";
+    readonly reason: unknown;
+    constructor(reason?: unknown);
+}
+export declare function isGatewayJobSuccessfulStatus(status: GatewayJobStatus | null | undefined): boolean;
+export declare function isGatewayJobTerminalStatus(status: GatewayJobStatus | null | undefined): boolean;
+export declare function waitForGatewayJob<TJob extends GatewayJobLike>(options: GatewayJobWaitOptions<TJob>): Promise<TJob>;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/core/gateway/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../../src/core/gateway/jobs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,WAAW,GACX,UAAU,GACV,UAAU,GACV,SAAS,GACT,MAAM,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,4BAA4B,gDAI/B,CAAC;AAEX,eAAO,MAAM,6BAA6B,uGAOhC,CAAC;AAEX,MAAM,MAAM,oBAAoB,CAAC,IAAI,SAAS,cAAc,IAAI;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,MAAM,qBAAqB,CAAC,IAAI,SAAS,cAAc,IAAI;IAC/D,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACxD,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC;IACpC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,sBAAsB,CAAC,IAAI,SAAS,cAAc,CAAE,SAAQ,KAAK;IAC5E,QAAQ,CAAC,IAAI,4BAA4B;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;gBAElB,MAAM,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;KACtB;CAUF;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,0BAA0B;IACvC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,CAAC,EAAE,OAAO;CAI7B;AAmCD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC1C,OAAO,CAKT;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC1C,OAAO,CAKT;AAED,wBAAsB,iBAAiB,CAAC,IAAI,SAAS,cAAc,EACjE,OAAO,EAAE,qBAAqB,CAAC,IAAI,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/core/gateway/jobs.js

@@ -0,0 +1,104 @@
+export const GATEWAY_JOB_SUCCESS_STATUSES = [
+    "completed",
+    "succeeded",
+    "success",
+];
+export const GATEWAY_JOB_TERMINAL_STATUSES = [
+    ...GATEWAY_JOB_SUCCESS_STATUSES,
+    "failed",
+    "error",
+    "cancelled",
+    "canceled",
+    "stopped",
+];
+export class GatewayJobTimeoutError extends Error {
+    name = "GatewayJobTimeoutError";
+    attempts;
+    elapsedMs;
+    lastJob;
+    constructor(params) {
+        super(`gateway job: timed out after ${params.attempts} attempt${params.attempts === 1 ? "" : "s"}`);
+        this.attempts = params.attempts;
+        this.elapsedMs = params.elapsedMs;
+        this.lastJob = params.lastJob;
+    }
+}
+export class GatewayJobAbortError extends Error {
+    name = "GatewayJobAbortError";
+    reason;
+    constructor(reason) {
+        super("gateway job: wait aborted");
+        this.reason = reason;
+    }
+}
+function normalizeStatus(status) {
+    return typeof status === "string" ? status.trim().toLowerCase() : "";
+}
+function assertPositiveInteger(value, label) {
+    if (!Number.isFinite(value) || value <= 0 || Math.floor(value) !== value) {
+        throw new Error(`gateway job: ${label} must be a positive integer`);
+    }
+    return value;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new GatewayJobAbortError(signal.reason);
+    }
+}
+function defaultSleep(delayMs, signal) {
+    throwIfAborted(signal);
+    let abort = null;
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(resolve, delayMs);
+        abort = () => {
+            clearTimeout(timeout);
+            reject(new GatewayJobAbortError(signal?.reason));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    }).finally(() => {
+        if (abort)
+            signal?.removeEventListener("abort", abort);
+    });
+}
+export function isGatewayJobSuccessfulStatus(status) {
+    const normalized = normalizeStatus(status);
+    return GATEWAY_JOB_SUCCESS_STATUSES.includes(normalized);
+}
+export function isGatewayJobTerminalStatus(status) {
+    const normalized = normalizeStatus(status);
+    return GATEWAY_JOB_TERMINAL_STATUSES.includes(normalized);
+}
+export async function waitForGatewayJob(options) {
+    const intervalMs = assertPositiveInteger(options.intervalMs ?? 1_000, "intervalMs");
+    const timeoutMs = options.timeoutMs === undefined
+        ? 60_000
+        : assertPositiveInteger(options.timeoutMs, "timeoutMs");
+    const maxAttempts = options.maxAttempts === undefined
+        ? null
+        : assertPositiveInteger(options.maxAttempts, "maxAttempts");
+    const isTerminal = options.isTerminal ??
+        ((job) => isGatewayJobTerminalStatus(job.status));
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    let attempts = 0;
+    let lastJob = null;
+    while (true) {
+        throwIfAborted(options.signal);
+        attempts += 1;
+        const job = await options.fetchJob();
+        lastJob = job;
+        const elapsedMs = Math.max(0, now() - startedAt);
+        options.onUpdate?.({ attempt: attempts, elapsedMs, job });
+        if (isTerminal(job)) {
+            return job;
+        }
+        if (maxAttempts !== null && attempts >= maxAttempts) {
+            throw new GatewayJobTimeoutError({ attempts, elapsedMs, lastJob });
+        }
+        if (elapsedMs >= timeoutMs) {
+            throw new GatewayJobTimeoutError({ attempts, elapsedMs, lastJob });
+        }
+        await sleep(Math.min(intervalMs, timeoutMs - elapsedMs), options.signal);
+    }
+}

package/dist/core/gateway/portal/config-patch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared HTTP contract for portal dashboard config updates (POST).
+ * Any client (mobile, web, scripts) may call {@link postPortalConfigPatch} against
+ * the portal config surface once the gateway implements the route.
+ */
+export declare const PORTAL_CONFIG_PATCH_CONTRACT: "PORTAL_CONFIG_PATCH_V1";
+export declare const PORTAL_CONFIG_PATCH_CONTRACT_VERSION: 1;
+/** Optional header some gateways require for audit / routing. */
+export declare const PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER: "X-Portal-Client-Id";
+export type PortalConfigPatchRequestBody = {
+    contract: typeof PORTAL_CONFIG_PATCH_CONTRACT;
+    v: typeof PORTAL_CONFIG_PATCH_CONTRACT_VERSION;
+    /** Gateway-defined scope (e.g. `readiness`, `snapshot.thresholds`). */
+    scope: string;
+    /** Nested object; build from flat UI keys with {@link unflattenPortalConfigPatchKeys}. */
+    patch: Record<string, unknown>;
+};
+export type PostPortalConfigPatchParams = {
+    httpBase: string;
+    /** Bearer secret without the `Bearer ` prefix. */
+    authToken: string;
+    /** URL segment only, e.g. `portal-a`. */
+    portalSlug: string;
+    scope: string;
+    patch: Record<string, unknown>;
+    /** Sent as {@link PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER} when non-empty. */
+    clientId?: string;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+};
+export declare class PortalConfigPatchError extends Error {
+    readonly status: number;
+    readonly responseBody: string | null;
+    constructor(status: number, message: string, responseBody: string | null);
+}
+export declare function portalConfigPatchPath(portalSlug: string): string;
+/**
+ * Turns flat keys like `foo › bar` into `{ foo: { bar: value } }`.
+ */
+export declare function unflattenPortalConfigPatchKeys(flat: Record<string, unknown>, separator?: string): Record<string, unknown>;
+export declare function postPortalConfigPatch(params: PostPortalConfigPatchParams): Promise<unknown>;
+//# sourceMappingURL=config-patch.d.ts.map

package/dist/core/gateway/portal/config-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-patch.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/portal/config-patch.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,eAAO,MAAM,4BAA4B,EAAG,wBAAiC,CAAC;AAC9E,eAAO,MAAM,oCAAoC,EAAG,CAAU,CAAC;AAE/D,iEAAiE;AACjE,eAAO,MAAM,oCAAoC,sBAA0B,CAAC;AAE5E,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,EAAE,OAAO,4BAA4B,CAAC;IAC9C,CAAC,EAAE,OAAO,oCAAoC,CAAC;IAC/C,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEzB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;CAMzE;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,SAAQ,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBzB;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,OAAO,CAAC,CA2ClB"}

package/dist/core/gateway/portal/config-patch.js

@@ -0,0 +1,99 @@
+import { PORTAL_CLIENT_ID_HEADER } from "../../http/types.js";
+import { GATEWAY_PORTAL_API_ENDPOINTS } from "../../../contracts/paths.js";
+/**
+ * Shared HTTP contract for portal dashboard config updates (POST).
+ * Any client (mobile, web, scripts) may call {@link postPortalConfigPatch} against
+ * the portal config surface once the gateway implements the route.
+ */
+export const PORTAL_CONFIG_PATCH_CONTRACT = "PORTAL_CONFIG_PATCH_V1";
+export const PORTAL_CONFIG_PATCH_CONTRACT_VERSION = 1;
+/** Optional header some gateways require for audit / routing. */
+export const PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER = PORTAL_CLIENT_ID_HEADER;
+export class PortalConfigPatchError extends Error {
+    status;
+    responseBody;
+    constructor(status, message, responseBody) {
+        super(message);
+        this.name = "PortalConfigPatchError";
+        this.status = status;
+        this.responseBody = responseBody;
+    }
+}
+export function portalConfigPatchPath(portalSlug) {
+    const slug = portalSlug.trim().replace(/^\/+/u, "").replace(/\/+$/u, "");
+    if (!slug || slug.includes("/")) {
+        throw new Error(`portalConfigPatchPath: invalid portal slug "${portalSlug}"`);
+    }
+    return GATEWAY_PORTAL_API_ENDPOINTS.config(slug);
+}
+/**
+ * Turns flat keys like `foo › bar` into `{ foo: { bar: value } }`.
+ */
+export function unflattenPortalConfigPatchKeys(flat, separator = " › ") {
+    const root = {};
+    for (const [path, value] of Object.entries(flat)) {
+        const parts = path
+            .split(separator)
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0);
+        if (!parts.length)
+            continue;
+        let cur = root;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const p = parts[i];
+            const next = cur[p];
+            if (next && typeof next === "object" && !Array.isArray(next)) {
+                cur = next;
+            }
+            else {
+                const nested = {};
+                cur[p] = nested;
+                cur = nested;
+            }
+        }
+        const leaf = parts[parts.length - 1];
+        cur[leaf] = value;
+    }
+    return root;
+}
+export async function postPortalConfigPatch(params) {
+    const base = params.httpBase.trim().replace(/\/+$/u, "");
+    const url = `${base}${portalConfigPatchPath(params.portalSlug)}`;
+    const headers = {
+        Authorization: `Bearer ${params.authToken}`,
+        Accept: "application/json",
+        "Content-Type": "application/json",
+    };
+    const cid = params.clientId?.trim();
+    if (cid) {
+        headers[PORTAL_CONFIG_PATCH_CLIENT_ID_HEADER] = cid;
+    }
+    const body = {
+        contract: PORTAL_CONFIG_PATCH_CONTRACT,
+        v: PORTAL_CONFIG_PATCH_CONTRACT_VERSION,
+        scope: params.scope,
+        patch: params.patch,
+    };
+    const fetchFn = params.fetchImpl ?? fetch;
+    const res = await fetchFn(url, {
+        method: "POST",
+        signal: params.signal,
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        const hint = res.status === 404 || res.status === 501
+            ? " (gateway may not expose the portal.config surface yet)"
+            : "";
+        throw new PortalConfigPatchError(res.status, `Portal config PATCH failed: HTTP ${res.status}${hint}`, text.length ? text : null);
+    }
+    if (!text)
+        return { ok: true };
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { ok: true, raw: text };
+    }
+}

package/dist/core/gateway/portal/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./config-patch.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/gateway/portal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/portal/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/dist/core/gateway/portal/index.js

@@ -0,0 +1 @@
+export * from "./config-patch.js";