@solarisdk/core 0.1.0

package/dist/handle.d.ts

@@ -0,0 +1,169 @@
+import { ControlChannel, type ControlChannelConfig } from "./transport.js";
+import type { CommandHandle, CommandOptions, CommandResult, FsEntry, FsSearchMatch, FsStat, FsWatchEvent, MetricsResult, PtyHandle, PtyOptions, RunCodeOptions, RunCodeResult } from "./types.js";
+/** Wiring supplied by the owning sub-client so handle-level admin calls reach
+ * the gateway without the handle holding an HTTP client. */
+export interface SessionHooks {
+    /** `GET /sandboxes/:id/metrics`. */
+    metrics?(id: string): Promise<MetricsResult>;
+    /** `POST /sandboxes/:id/snapshots`. */
+    snapshot?(id: string, name?: string): Promise<{
+        snapshotId: string;
+    }>;
+    /** `POST /sandboxes/:id/revert`. */
+    revert?(id: string, snapshotId: string): Promise<void>;
+    /** `POST /sandboxes/:id/pause`. */
+    pause?(id: string): Promise<void>;
+    /** `POST /sandboxes/:id/resume` → fresh controlUrl. */
+    resume?(id: string): Promise<{
+        controlUrl: string;
+    }>;
+    /** `POST /sandboxes/:id/timeout`. */
+    setTimeout?(id: string, timeoutMs: number): Promise<{
+        expiresAt: string;
+    }>;
+    /** `GET /sandboxes/:id/files/download-url?path=` — signed direct download URL. */
+    downloadUrl?(id: string, path: string): Promise<{
+        url: string;
+        expiresAt?: string;
+    }>;
+    /** `GET /sandboxes/:id/files/upload-url?path=` — signed direct upload URL. */
+    uploadUrl?(id: string, path?: string): Promise<{
+        url: string;
+        expiresAt?: string;
+    }>;
+    /** `GET /sandboxes/:id/ports/:port` — public preview URL for an in-guest port. */
+    previewUrl?(id: string, port: number): Promise<{
+        url: string;
+        token?: string;
+    }>;
+    /** `DELETE /sandboxes/:id`. */
+    kill?(id: string): Promise<void>;
+}
+export interface SessionConfig extends ControlChannelConfig {
+    hooks?: SessionHooks;
+}
+export declare class SessionHandle {
+    /** The session id (sandboxId / sessionId). */
+    readonly id: string;
+    readonly controlUrl: string;
+    readonly expiresAt: string;
+    protected readonly channel: ControlChannel;
+    protected readonly hooks: SessionHooks;
+    constructor(id: string, controlUrl: string, expiresAt: string, config?: SessionConfig);
+    /** Whether the control channel is open. */
+    get connected(): boolean;
+    /** Subclass hook: send a raw JSON-RPC call over the control channel. */
+    protected rpc<T>(method: string, params: unknown): Promise<T>;
+    /** Subclass hook: send a v1 streamed call (per-`id` stdout/stderr frames). */
+    protected rpcStream<T>(method: string, params: unknown, onStream: (c: {
+        stream: "stdout" | "stderr";
+        data?: string;
+    }) => void): Promise<T>;
+    /** Open the control WebSocket. Idempotent. */
+    connect(): Promise<void>;
+    /** Reconnect after a drop (re-opens the socket). */
+    reconnect(): Promise<void>;
+    /** Close the control channel locally (does NOT release the remote session). */
+    close(): void;
+    readonly commands: {
+        /**
+         * Run a command to completion. `onStdout`/`onStderr` receive output as it
+         * streams (via `cmd.data` frames); the promise resolves with the terminal
+         * exit code (from `cmd.exit`).
+         */
+        run: (cmd: string, opts?: CommandOptions) => Promise<CommandResult>;
+        /**
+         * Start a command and return a handle immediately (does not wait for exit).
+         * Output streams as `cmd.data`; the handle exposes `stdin`, `onData`,
+         * `wait()`, and `kill()`.
+         */
+        start: (cmd: string, opts?: CommandOptions) => Promise<CommandHandle>;
+        /** Reconnect the control channel (e.g. to resume receiving frames). */
+        connect: () => Promise<void>;
+    };
+    private startCommand;
+    private runCommand;
+    readonly pty: {
+        /** Open a PTY; output streams as `pty.data` frames. */
+        create: (opts: PtyOptions) => Promise<PtyHandle>;
+    };
+    private createPty;
+    /**
+     * Run code in a stateful kernel (`code.run`). Rich outputs (png/html/json/…)
+     * come back as `results` items; `onStdout`/`onStderr` receive streamed text.
+     */
+    runCode(code: string, opts?: RunCodeOptions): Promise<RunCodeResult>;
+    /** Create a fresh stateful kernel context (`code.context.create`). */
+    createCodeContext(language?: CodeLanguageArg): Promise<string>;
+    readonly files: {
+        read: (path: string) => Promise<Uint8Array>;
+        readText: (path: string) => Promise<string>;
+        write: (path: string, data: Uint8Array | string, mode?: number) => Promise<void>;
+        list: (path: string) => Promise<FsEntry[]>;
+        stat: (path: string) => Promise<FsStat>;
+        rename: (from: string, to: string) => Promise<void>;
+        remove: (path: string, recursive?: boolean) => Promise<void>;
+        mkdir: (path: string) => Promise<void>;
+        /** Recursively grep `query` under `path`. */
+        search: (path: string, query: string, maxResults?: number) => Promise<FsSearchMatch[]>;
+        /**
+         * Watch `path` for changes; `cb` is invoked for each `fs.event` frame.
+         * Returns an unwatch function.
+         */
+        watch: (path: string, cb: (ev: FsWatchEvent) => void, recursive?: boolean) => Promise<() => Promise<void>>;
+        /** Upload local bytes to an in-guest path (chunked base64 under the hood). */
+        upload: (path: string, data: Uint8Array | string) => Promise<void>;
+        /** Download an in-guest file's bytes. */
+        download: (path: string) => Promise<Uint8Array>;
+    };
+    /** Inject/replace per-session env vars in the guest (`setEnv`). */
+    env(vars: Record<string, string>): Promise<void>;
+    /** Signed, time-limited URL to download an in-guest file directly over HTTP
+     *  (bypasses the control channel — good for large files). */
+    downloadUrl(path: string): Promise<{
+        url: string;
+        expiresAt?: string;
+    }>;
+    /** Signed, time-limited URL to upload a file into the guest directly over
+     *  HTTP. `path` is the destination (optional; some backends return a prefix). */
+    uploadUrl(path?: string): Promise<{
+        url: string;
+        expiresAt?: string;
+    }>;
+    readonly volumes: {
+        /**
+         * Mount a volume into the guest at `path`. Thin pass-through to the guest
+         * `volume.mount` RPC; the gateway volume routes may be a 501 stub today.
+         */
+        mount: (volId: string, path: string) => Promise<void>;
+    };
+    /** Live resource metrics. */
+    metrics(): Promise<MetricsResult>;
+    /** Checkpoint this RUNNING session; it keeps running. Returns the snapshot id. */
+    snapshot(name?: string): Promise<string>;
+    /** Restore this session in place from a snapshot (id stays stable). */
+    revert(snapshotId: string): Promise<void>;
+    /** Pause (snapshot RAM+disk, free the slot). Closes the control channel. */
+    pause(): Promise<void>;
+    /** Resume a paused session; re-points the control channel at the fresh slot. */
+    resume(): Promise<void>;
+    /** Extend the idle/keep-alive window. */
+    setTimeout(timeoutMs: number): Promise<{
+        expiresAt: string;
+    }>;
+    /**
+     * Resolve a public preview URL for an in-guest port (e.g. a dev server on
+     * `:3000`). Returns the routable `https://` URL and, when the gateway signs
+     * one, an access `token`.
+     */
+    previewUrl(port: number): Promise<{
+        url: string;
+        token?: string;
+    }>;
+    /** Destroy the remote session and close the channel. Idempotent. */
+    kill(): Promise<void>;
+}
+/** Local helper type for `createCodeContext` to avoid a hard import cycle. */
+type CodeLanguageArg = "python" | "javascript" | "typescript" | "bash" | "r";
+export {};
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"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"}

package/dist/handle.js

@@ -0,0 +1,386 @@
+// `SessionHandle` — the shared base for {@link Sandbox} and {@link Desktop}.
+//
+// Wraps a {@link ControlChannel} and exposes the CONTRACTS-V2 §4 primitives
+// (commands, pty, runCode, files) plus the gateway-routed lifecycle/admin calls
+// (metrics, snapshot, revert, pause/resume, setTimeout, env, volumes,
+// kill). Both Sandbox and Desktop extend this; Desktop adds the GUI surface.
+//
+// Streaming model: async output from `commands.start`/`pty.create`/`files.watch`
+// arrives as v2 frames `{type:"cmd.data"|"cmd.exit"|"pty.data"|"fs.event", ...}`
+// dispatched by the ControlChannel by `type` + the stream's own id, NOT by the
+// originating request id. We register/unregister those frame handlers as
+// commands/ptys/watches are created and torn down.
+import { base64ToBytes, bytesToBase64, ControlChannel, } from "./transport.js";
+export class SessionHandle {
+    /** The session id (sandboxId / sessionId). */
+    id;
+    controlUrl;
+    expiresAt;
+    channel;
+    hooks;
+    constructor(id, controlUrl, expiresAt, config = {}) {
+        this.id = id;
+        this.controlUrl = controlUrl;
+        this.expiresAt = expiresAt;
+        this.channel = new ControlChannel(controlUrl, config);
+        this.hooks = config.hooks ?? {};
+    }
+    /** Whether the control channel is open. */
+    get connected() {
+        return this.channel.connected;
+    }
+    /** Subclass hook: send a raw JSON-RPC call over the control channel. */
+    rpc(method, params) {
+        return this.channel.call(method, params);
+    }
+    /** Subclass hook: send a v1 streamed call (per-`id` stdout/stderr frames). */
+    rpcStream(method, params, onStream) {
+        return this.channel.call(method, params, { onStream });
+    }
+    /** Open the control WebSocket. Idempotent. */
+    connect() {
+        return this.channel.connect();
+    }
+    /** Reconnect after a drop (re-opens the socket). */
+    reconnect() {
+        return this.channel.reconnect();
+    }
+    /** Close the control channel locally (does NOT release the remote session). */
+    close() {
+        this.channel.close();
+    }
+    // --- commands -------------------------------------------------------------
+    commands = {
+        /**
+         * Run a command to completion. `onStdout`/`onStderr` receive output as it
+         * streams (via `cmd.data` frames); the promise resolves with the terminal
+         * exit code (from `cmd.exit`).
+         */
+        run: (cmd, opts = {}) => this.runCommand(cmd, opts),
+        /**
+         * Start a command and return a handle immediately (does not wait for exit).
+         * Output streams as `cmd.data`; the handle exposes `stdin`, `onData`,
+         * `wait()`, and `kill()`.
+         */
+        start: (cmd, opts = {}) => this.startCommand(cmd, opts),
+        /** Reconnect the control channel (e.g. to resume receiving frames). */
+        connect: () => this.channel.reconnect(),
+    };
+    async startCommand(cmd, opts) {
+        const r = await this.channel.call("cmd.start", {
+            cmd,
+            args: opts.args,
+            cwd: opts.cwd,
+            env: opts.env,
+            user: opts.user,
+        });
+        const cmdId = r.cmdId;
+        const dataCbs = [];
+        // Frames can arrive in the microtask gap between this method returning the
+        // handle and the caller (e.g. runCommand) attaching its onData accumulator.
+        // Buffer chunks while no consumer is attached, then replay on first onData
+        // so early stdout/stderr is never dropped (would surface as exit=0 + "").
+        const buffered = [];
+        let exitResolve = null;
+        let exitReject = null;
+        const exitPromise = new Promise((res, rej) => {
+            exitResolve = res;
+            exitReject = rej;
+        });
+        // If the control channel drops before `cmd.exit` arrives, reject the wait so
+        // callers get a ConnectionError instead of hanging forever.
+        this.channel.onStreamClose(cmdId, (err) => exitReject?.(err));
+        if (opts.onStdout || opts.onStderr) {
+            dataCbs.push((c) => {
+                if (c.stream === "stdout")
+                    opts.onStdout?.(c.data);
+                else
+                    opts.onStderr?.(c.data);
+            });
+        }
+        this.channel.onFrame("cmd.data", cmdId, (f) => {
+            const stream = f.stream ?? "stdout";
+            const data = f.base64 ? new TextDecoder().decode(base64ToBytes(f.base64)) : "";
+            const chunk = { stream, data };
+            if (dataCbs.length === 0)
+                buffered.push(chunk);
+            else
+                for (const cb of dataCbs)
+                    cb(chunk);
+        });
+        this.channel.onFrame("cmd.exit", cmdId, (f) => {
+            this.channel.offFrame("cmd.data", cmdId);
+            this.channel.offFrame("cmd.exit", cmdId);
+            this.channel.offStreamClose(cmdId);
+            exitResolve?.(typeof f.exitCode === "number" ? f.exitCode : 0);
+        });
+        return {
+            cmdId,
+            stdin: (data) => this.channel
+                .call("cmd.stdin", { cmdId, base64: toB64(data) })
+                .then(() => undefined),
+            onData: (cb) => {
+                if (buffered.length > 0) {
+                    for (const c of buffered)
+                        cb(c);
+                    buffered.length = 0;
+                }
+                dataCbs.push(cb);
+            },
+            wait: () => exitPromise,
+            kill: (signal) => this.channel
+                .call("cmd.kill", { cmdId, signal })
+                .then(() => undefined),
+        };
+    }
+    async runCommand(cmd, opts) {
+        const handle = await this.startCommand(cmd, opts);
+        let stdout = "";
+        let stderr = "";
+        handle.onData((c) => {
+            if (c.stream === "stdout")
+                stdout += c.data;
+            else
+                stderr += c.data;
+        });
+        if (opts.background) {
+            // Detached: don't block on exit. Caller drives via callbacks/handle.
+            return { exitCode: 0, stdout: "", stderr: "" };
+        }
+        const exitCode = await handle.wait();
+        return { exitCode, stdout, stderr };
+    }
+    // --- pty ------------------------------------------------------------------
+    pty = {
+        /** Open a PTY; output streams as `pty.data` frames. */
+        create: (opts) => this.createPty(opts),
+    };
+    async createPty(opts) {
+        const r = await this.channel.call("pty.create", {
+            cols: opts.cols,
+            rows: opts.rows,
+            cmd: opts.cmd,
+            cwd: opts.cwd,
+            env: opts.env,
+        });
+        const ptyId = r.ptyId;
+        const dataCbs = [];
+        this.channel.onFrame("pty.data", ptyId, (f) => {
+            const bytes = f.base64 ? base64ToBytes(f.base64) : new Uint8Array();
+            for (const cb of dataCbs)
+                cb(bytes);
+        });
+        return {
+            ptyId,
+            write: (data) => this.channel
+                .call("pty.input", { ptyId, base64: toB64(data) })
+                .then(() => undefined),
+            resize: (cols, rows) => this.channel
+                .call("pty.resize", { ptyId, cols, rows })
+                .then(() => undefined),
+            onData: (cb) => {
+                dataCbs.push(cb);
+            },
+            kill: () => {
+                this.channel.offFrame("pty.data", ptyId);
+                return this.channel
+                    .call("pty.kill", { ptyId })
+                    .then(() => undefined);
+            },
+        };
+    }
+    // --- runCode --------------------------------------------------------------
+    /**
+     * Run code in a stateful kernel (`code.run`). Rich outputs (png/html/json/…)
+     * come back as `results` items; `onStdout`/`onStderr` receive streamed text.
+     */
+    async runCode(code, opts = {}) {
+        const r = await this.channel.call("code.run", {
+            code,
+            language: opts.language,
+            contextId: opts.contextId,
+        });
+        const results = Array.isArray(r.results) ? r.results : [];
+        for (const item of results) {
+            if (item.type === "stdout" && item.text)
+                opts.onStdout?.(item.text);
+            if (item.type === "stderr" && item.text)
+                opts.onStderr?.(item.text);
+        }
+        const charts = results
+            .filter((i) => i.chart !== undefined)
+            .map((i) => i.chart);
+        return { results, charts, ...(r.error !== undefined ? { error: r.error } : {}) };
+    }
+    /** Create a fresh stateful kernel context (`code.context.create`). */
+    async createCodeContext(language = "python") {
+        const r = await this.channel.call("code.context.create", { language });
+        return r.contextId;
+    }
+    // --- files ----------------------------------------------------------------
+    files = {
+        read: async (path) => {
+            const r = await this.channel.call("fs.read", { path });
+            return base64ToBytes(r.base64);
+        },
+        readText: async (path) => {
+            const bytes = await this.files.read(path);
+            return new TextDecoder().decode(bytes);
+        },
+        write: (path, data, mode) => this.channel
+            .call("fs.write", { path, base64: toB64(data), mode })
+            .then(() => undefined),
+        list: async (path) => {
+            const r = await this.channel.call("fs.list", {
+                path,
+            });
+            return r.entries;
+        },
+        stat: (path) => this.channel.call("fs.stat", { path }),
+        rename: (from, to) => this.channel
+            .call("fs.rename", { from, to })
+            .then(() => undefined),
+        remove: (path, recursive = false) => this.channel
+            .call("fs.remove", { path, recursive })
+            .then(() => undefined),
+        mkdir: (path) => this.channel
+            .call("fs.mkdir", { path })
+            .then(() => undefined),
+        /** Recursively grep `query` under `path`. */
+        search: async (path, query, maxResults) => {
+            const r = await this.channel.call("fs.search", { path, query, maxResults });
+            return r.matches ?? [];
+        },
+        /**
+         * Watch `path` for changes; `cb` is invoked for each `fs.event` frame.
+         * Returns an unwatch function.
+         */
+        watch: async (path, cb, recursive = false) => {
+            const r = await this.channel.call("fs.watch", {
+                path,
+                recursive,
+            });
+            const watchId = r.watchId;
+            this.channel.onFrame("fs.event", watchId, (f) => {
+                cb({ type: String(f.type ?? "change"), path: String(f.path ?? "") });
+            });
+            return async () => {
+                this.channel.offFrame("fs.event", watchId);
+                await this.channel.call("fs.unwatch", { watchId });
+            };
+        },
+        /** Upload local bytes to an in-guest path (chunked base64 under the hood). */
+        upload: (path, data) => this.channel
+            .call("fs.upload", { path, base64: toB64(data) })
+            .then(() => undefined),
+        /** Download an in-guest file's bytes. */
+        download: async (path) => {
+            const r = await this.channel.call("fs.download", {
+                path,
+            });
+            return base64ToBytes(r.base64);
+        },
+    };
+    // --- env ------------------------------------------------------------------
+    /** Inject/replace per-session env vars in the guest (`setEnv`). */
+    env(vars) {
+        return this.channel
+            .call("setEnv", { env: vars })
+            .then(() => undefined);
+    }
+    /** Signed, time-limited URL to download an in-guest file directly over HTTP
+     *  (bypasses the control channel — good for large files). */
+    downloadUrl(path) {
+        if (!this.hooks.downloadUrl) {
+            return Promise.reject(new Error("downloadUrl requires a client-created handle"));
+        }
+        return this.hooks.downloadUrl(this.id, path);
+    }
+    /** Signed, time-limited URL to upload a file into the guest directly over
+     *  HTTP. `path` is the destination (optional; some backends return a prefix). */
+    uploadUrl(path) {
+        if (!this.hooks.uploadUrl) {
+            return Promise.reject(new Error("uploadUrl requires a client-created handle"));
+        }
+        return this.hooks.uploadUrl(this.id, path);
+    }
+    // --- volumes --------------------------------------------------------------
+    volumes = {
+        /**
+         * Mount a volume into the guest at `path`. Thin pass-through to the guest
+         * `volume.mount` RPC; the gateway volume routes may be a 501 stub today.
+         */
+        mount: (volId, path) => this.channel
+            .call("volume.mount", { volumeId: volId, path })
+            .then(() => undefined),
+    };
+    // --- lifecycle / admin (gateway-routed via hooks) -------------------------
+    /** Live resource metrics. */
+    metrics() {
+        if (!this.hooks.metrics) {
+            return Promise.reject(new Error("metrics requires a client-created handle"));
+        }
+        return this.hooks.metrics(this.id);
+    }
+    /** Checkpoint this RUNNING session; it keeps running. Returns the snapshot id. */
+    async snapshot(name) {
+        if (!this.hooks.snapshot) {
+            throw new Error("snapshot requires a client-created handle");
+        }
+        const r = await this.hooks.snapshot(this.id, name);
+        return r.snapshotId;
+    }
+    /** Restore this session in place from a snapshot (id stays stable). */
+    revert(snapshotId) {
+        if (!this.hooks.revert) {
+            return Promise.reject(new Error("revert requires a client-created handle"));
+        }
+        return this.hooks.revert(this.id, snapshotId);
+    }
+    /** Pause (snapshot RAM+disk, free the slot). Closes the control channel. */
+    async pause() {
+        if (!this.hooks.pause) {
+            throw new Error("pause requires a client-created handle");
+        }
+        await this.hooks.pause(this.id);
+        this.close();
+    }
+    /** Resume a paused session; re-points the control channel at the fresh slot. */
+    async resume() {
+        if (!this.hooks.resume) {
+            throw new Error("resume requires a client-created handle");
+        }
+        const r = await this.hooks.resume(this.id);
+        this.channel.setControlUrl(r.controlUrl);
+        await this.channel.reconnect();
+    }
+    /** Extend the idle/keep-alive window. */
+    setTimeout(timeoutMs) {
+        if (!this.hooks.setTimeout) {
+            return Promise.reject(new Error("setTimeout requires a client-created handle"));
+        }
+        return this.hooks.setTimeout(this.id, timeoutMs);
+    }
+    /**
+     * Resolve a public preview URL for an in-guest port (e.g. a dev server on
+     * `:3000`). Returns the routable `https://` URL and, when the gateway signs
+     * one, an access `token`.
+     */
+    previewUrl(port) {
+        if (!this.hooks.previewUrl) {
+            return Promise.reject(new Error("previewUrl requires a client-created handle"));
+        }
+        return this.hooks.previewUrl(this.id, port);
+    }
+    /** Destroy the remote session and close the channel. Idempotent. */
+    async kill() {
+        if (this.hooks.kill)
+            await this.hooks.kill(this.id);
+        this.close();
+    }
+}
+function toB64(data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    return bytesToBase64(bytes);
+}
+//# sourceMappingURL=handle.js.map

package/dist/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,sEAAsE;AACtE,6EAA6E;AAC7E,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,+EAA+E;AAC/E,yEAAyE;AACzE,mDAAmD;AAEnD,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,GAGf,MAAM,gBAAgB,CAAC;AA+CxB,MAAM,OAAO,aAAa;IACxB,8CAA8C;IACrC,EAAE,CAAS;IACX,UAAU,CAAS;IACnB,SAAS,CAAS;IAER,OAAO,CAAiB;IACxB,KAAK,CAAe;IAEvC,YACE,EAAU,EACV,UAAkB,EAClB,SAAiB,EACjB,SAAwB,EAAE;QAE1B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,CAAC;IAED,2CAA2C;IAC3C,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IAChC,CAAC;IAED,wEAAwE;IAC9D,GAAG,CAAI,MAAc,EAAE,MAAe;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAI,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,8EAA8E;IACpE,SAAS,CACjB,MAAc,EACd,MAAe,EACf,QAAqE;QAErE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAI,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,8CAA8C;IAC9C,OAAO;QACL,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;IAED,oDAAoD;IACpD,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAClC,CAAC;IAED,+EAA+E;IAC/E,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,6EAA6E;IAEpE,QAAQ,GAAG;QAClB;;;;WAIG;QACH,GAAG,EAAE,CAAC,GAAW,EAAE,OAAuB,EAAE,EAA0B,EAAE,CACtE,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC;QAC5B;;;;WAIG;QACH,KAAK,EAAE,CAAC,GAAW,EAAE,OAAuB,EAAE,EAA0B,EAAE,CACxE,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC;QAC9B,uEAAuE;QACvE,OAAO,EAAE,GAAkB,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE;KACvD,CAAC;IAEM,KAAK,CAAC,YAAY,CACxB,GAAW,EACX,IAAoB;QAEpB,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAoB,WAAW,EAAE;YAChE,GAAG;YACH,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAEtB,MAAM,OAAO,GAAsE,EAAE,CAAC;QACtF,2EAA2E;QAC3E,4EAA4E;QAC5E,2EAA2E;QAC3E,0EAA0E;QAC1E,MAAM,QAAQ,GAAyD,EAAE,CAAC;QAC1E,IAAI,WAAW,GAAoC,IAAI,CAAC;QACxD,IAAI,UAAU,GAAkC,IAAI,CAAC;QACrD,MAAM,WAAW,GAAG,IAAI,OAAO,CAAS,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACnD,WAAW,GAAG,GAAG,CAAC;YAClB,UAAU,GAAG,GAAG,CAAC;QACnB,CAAC,CAAC,CAAC;QACH,6EAA6E;QAC7E,4DAA4D;QAC5D,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAE9D,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;gBACjB,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;oBAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;;oBAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAa,EAAE,EAAE;YACxD,MAAM,MAAM,GAAI,CAAC,CAAC,MAA8B,IAAI,QAAQ,CAAC;YAC7D,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;gBAC1C,KAAK,MAAM,EAAE,IAAI,OAAO;oBAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAa,EAAE,EAAE;YACxD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YACzC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACnC,WAAW,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,KAAK;YACL,KAAK,EAAE,CAAC,IAAyB,EAAiB,EAAE,CAClD,IAAI,CAAC,OAAO;iBACT,IAAI,CAAe,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;iBAC/D,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;YAC1B,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;gBACb,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,KAAK,MAAM,CAAC,IAAI,QAAQ;wBAAE,EAAE,CAAC,CAAC,CAAC,CAAC;oBAChC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;gBACtB,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;YACD,IAAI,EAAE,GAAG,EAAE,CAAC,WAAW;YACvB,IAAI,EAAE,CAAC,MAAe,EAAiB,EAAE,CACvC,IAAI,CAAC,OAAO;iBACT,IAAI,CAAe,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;iBACjD,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SAC3B,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,UAAU,CACtB,GAAW,EACX,IAAoB;QAEpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YAClB,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;gBAAE,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC;;gBACvC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC;QACxB,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,qEAAqE;YACrE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACjD,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACtC,CAAC;IAED,6EAA6E;IAEpE,GAAG,GAAG;QACb,uDAAuD;QACvD,MAAM,EAAE,CAAC,IAAgB,EAAsB,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KACvE,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,IAAgB;QACtC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAoB,YAAY,EAAE;YACjE,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACtB,MAAM,OAAO,GAAmC,EAAE,CAAC;QACnD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAa,EAAE,EAAE;YACxD,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC;YACpE,KAAK,MAAM,EAAE,IAAI,OAAO;gBAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QACH,OAAO;YACL,KAAK;YACL,KAAK,EAAE,CAAC,IAAyB,EAAiB,EAAE,CAClD,IAAI,CAAC,OAAO;iBACT,IAAI,CAAe,WAAW,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;iBAC/D,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;YAC1B,MAAM,EAAE,CAAC,IAAY,EAAE,IAAY,EAAiB,EAAE,CACpD,IAAI,CAAC,OAAO;iBACT,IAAI,CAAe,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;iBACvD,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;YAC1B,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;gBACb,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;YACD,IAAI,EAAE,GAAkB,EAAE;gBACxB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;gBACzC,OAAO,IAAI,CAAC,OAAO;qBAChB,IAAI,CAAe,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC;qBACzC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC3B,CAAC;SACF,CAAC;IACJ,CAAC;IAED,6EAA6E;IAE7E;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,OAAuB,EAAE;QACnD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAgB,UAAU,EAAE;YAC3D,IAAI;YACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,KAAK,MAAM,IAAI,IAAI,OAA2B,EAAE,CAAC;YAC/C,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI;gBAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpE,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI;gBAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,MAAM,GAAI,OAA4B;aACzC,MAAM,CAAC,CAAC,CAAC,EAA0C,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC;aAC5E,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACnF,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,iBAAiB,CAAC,WAA4B,QAAQ;QAC1D,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAC/B,qBAAqB,EACrB,EAAE,QAAQ,EAAE,CACb,CAAC;QACF,OAAO,CAAC,CAAC,SAAS,CAAC;IACrB,CAAC;IAED,6EAA6E;IAEpE,KAAK,GAAG;QACf,IAAI,EAAE,KAAK,EAAE,IAAY,EAAuB,EAAE;YAChD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAqB,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3E,OAAO,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,QAAQ,EAAE,KAAK,EAAE,IAAY,EAAmB,EAAE;YAChD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1C,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,EAAE,CACL,IAAY,EACZ,IAAyB,EACzB,IAAa,EACE,EAAE,CACjB,IAAI,CAAC,OAAO;aACT,IAAI,CAAe,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;aACnE,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1B,IAAI,EAAE,KAAK,EAAE,IAAY,EAAsB,EAAE;YAC/C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAyB,SAAS,EAAE;gBACnE,IAAI;aACL,CAAC,CAAC;YACH,OAAO,CAAC,CAAC,OAAO,CAAC;QACnB,CAAC;QACD,IAAI,EAAE,CAAC,IAAY,EAAmB,EAAE,CACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAS,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC;QAChD,MAAM,EAAE,CAAC,IAAY,EAAE,EAAU,EAAiB,EAAE,CAClD,IAAI,CAAC,OAAO;aACT,IAAI,CAAe,WAAW,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;aAC7C,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1B,MAAM,EAAE,CAAC,IAAY,EAAE,SAAS,GAAG,KAAK,EAAiB,EAAE,CACzD,IAAI,CAAC,OAAO;aACT,IAAI,CAAe,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;aACpD,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,CAAC,IAAY,EAAiB,EAAE,CACrC,IAAI,CAAC,OAAO;aACT,IAAI,CAAe,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC;aACxC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1B,6CAA6C;QAC7C,MAAM,EAAE,KAAK,EACX,IAAY,EACZ,KAAa,EACb,UAAmB,EACO,EAAE;YAC5B,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAC/B,WAAW,EACX,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAC5B,CAAC;YACF,OAAO,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;QACzB,CAAC;QACD;;;WAGG;QACH,KAAK,EAAE,KAAK,EACV,IAAY,EACZ,EAA8B,EAC9B,SAAS,GAAG,KAAK,EACa,EAAE;YAChC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAsB,UAAU,EAAE;gBACjE,IAAI;gBACJ,SAAS;aACV,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,CAAa,EAAE,EAAE;gBAC1D,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC,CAAC,CAAC;YACH,OAAO,KAAK,IAAI,EAAE;gBAChB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBAC3C,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAe,YAAY,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACnE,CAAC,CAAC;QACJ,CAAC;QACD,8EAA8E;QAC9E,MAAM,EAAE,CAAC,IAAY,EAAE,IAAyB,EAAiB,EAAE,CACjE,IAAI,CAAC,OAAO;aACT,IAAI,CAAe,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;aAC9D,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1B,yCAAyC;QACzC,QAAQ,EAAE,KAAK,EAAE,IAAY,EAAuB,EAAE;YACpD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAqB,aAAa,EAAE;gBACnE,IAAI;aACL,CAAC,CAAC;YACH,OAAO,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;IAEF,6EAA6E;IAE7E,mEAAmE;IACnE,GAAG,CAAC,IAA4B;QAC9B,OAAO,IAAI,CAAC,OAAO;aAChB,IAAI,CAAe,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;aAC3C,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IAED;iEAC6D;IAC7D,WAAW,CAAC,IAAY;QACtB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YAC5B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED;qFACiF;IACjF,SAAS,CAAC,IAAa;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,6EAA6E;IAEpE,OAAO,GAAG;QACjB;;;WAGG;QACH,KAAK,EAAE,CAAC,KAAa,EAAE,IAAY,EAAiB,EAAE,CACpD,IAAI,CAAC,OAAO;aACT,IAAI,CAAe,cAAc,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;aAC7D,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;KAC3B,CAAC;IAEF,6EAA6E;IAE7E,6BAA6B;IAC7B,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,QAAQ,CAAC,IAAa;QAC1B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACnD,OAAO,CAAC,CAAC,UAAU,CAAC;IACtB,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,UAAkB;QACvB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,yCAAyC;IACzC,UAAU,CAAC,SAAiB;QAC1B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,KAAK,CAAC,6CAA6C,CAAC,CACzD,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;CACF;AAKD,SAAS,KAAK,CAAC,IAAyB;IACtC,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,35 @@
+export interface HttpTransportOptions {
+    apiKey: string;
+    baseUrl: string;
+    /** Optional `fetch` implementation (defaults to the global). */
+    fetch?: typeof fetch;
+    /** Max retry attempts for idempotent requests. Default 3. */
+    maxRetries?: number;
+    /** Per-request timeout in ms (AbortSignal). Default 30000. */
+    requestTimeoutMs?: number;
+    /** Fixed retry delay in ms. When unset, uses exponential backoff + jitter.
+     *  Mainly for tests (pass 0) and ops tuning. */
+    retryDelayMs?: number;
+}
+export interface HttpRequestOptions {
+    /** Send an `Idempotency-Key` header AND make this request retry-safe. */
+    idempotencyKey?: string;
+}
+/** A fresh idempotency key (UUID where available). */
+export declare function newIdempotencyKey(): string;
+export declare class HttpTransport {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly requestTimeoutMs;
+    private readonly retryDelayMs;
+    constructor(o: HttpTransportOptions);
+    /** `Authorization` header for handles + WS upgrades. */
+    authHeaders(): Record<string, string>;
+    /** ws:// (or wss://) origin derived from the gateway base URL. */
+    wsOrigin(): string;
+    request<T>(method: string, path: string, body?: unknown, opts?: HttpRequestOptions): Promise<T>;
+    private backoffMs;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;oDACgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,sDAAsD;AACtD,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;gBAEtC,CAAC,EAAE,oBAAoB;IAenC,wDAAwD;IACxD,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIrC,kEAAkE;IAClE,QAAQ,IAAI,MAAM;IAIZ,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,EACd,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,CAAC,CAAC;IAsDb,OAAO,CAAC,SAAS;CAIlB"}