@tracon/client 1.0.0-preview.1

package/dist/schema.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/sse.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Server-Sent Events framing for Tracon's streaming endpoints.
+ *
+ * `openapi-fetch` can already hand back the raw stream (`parseAs: 'stream'`,
+ * or the `response` every call returns), so streaming needs no special client
+ * method — but every consumer would then have to write this decoder again.
+ * It ships here instead: the Tracon UI is one consumer of it, not its
+ * owner (Phase 159).
+ */
+/** Options for {@link readSse}. */
+export interface ReadSseOptions {
+    /**
+     * Ends the stream with an {@link SseIdleTimeoutError} when no bytes at all
+     * arrive for this long. Omitted means wait forever.
+     *
+     * 🚨 Measure BYTES, not frames. Tracon sends `: waiting` comments while a run
+     * is still going and {@link SseDecoder} drops comments, so a healthy but
+     * quiet run yields no frames for as long as the run is quiet — a
+     * frame-based timeout would cut it off. Bytes tell the two apart: a run that
+     * is still going keeps sending them, a finished one closes the stream, and a
+     * connection that died without either sends nothing.
+     *
+     * Set it above the server's `RunEventPollInterval` (250 ms by default), with
+     * room for a slow link: that interval is how often the keep-alive is sent,
+     * and a threshold under it would fire between two healthy keep-alives.
+     */
+    idleTimeoutMs?: number;
+}
+/**
+ * Thrown by {@link readSse} when a stream goes completely quiet for longer
+ * than {@link ReadSseOptions.idleTimeoutMs}.
+ *
+ * A connection that drops without a close frame — a laptop going to sleep, a
+ * proxy timing out, a network that goes away mid-body — leaves the reader
+ * waiting on a chunk that will never come and throws nothing at all. Without
+ * this, a consumer cannot tell that from a run that is simply still working:
+ * both look like silence forever.
+ */
+export declare class SseIdleTimeoutError extends Error {
+    constructor(idleTimeoutMs: number);
+    /** The threshold that was exceeded, in milliseconds. */
+    readonly idleTimeoutMs: number;
+}
+/** One Server-Sent Events frame. */
+export interface SseFrame {
+    /** Value of the `id:` field, when present. */
+    id: string | null;
+    /** Value of the `event:` field. Defaults to `message`, as the spec requires. */
+    event: string;
+    /** Joined `data:` lines. */
+    data: string;
+}
+/**
+ * Incremental SSE decoder.
+ *
+ * Kept as a pure class with no I/O so the framing rules can be unit tested:
+ * chunk boundaries fall in arbitrary places and a parser that assumes whole
+ * frames per chunk works right up until a slow network proves it wrong.
+ *
+ * Comment lines (`: waiting`) are skipped. Tracon sends them as keep-alives
+ * while a run is still in progress.
+ */
+export declare class SseDecoder {
+    #private;
+    /** Feeds a chunk of text and returns every frame it completed. */
+    push(chunk: string): SseFrame[];
+}
+/**
+ * Reads a `text/event-stream` response body as frames.
+ *
+ * `EventSource` is not used: it cannot send an `Authorization` header and it
+ * cannot issue a POST, and Tracon needs both.
+ */
+export declare function readSse(response: Response, options?: ReadSseOptions): AsyncGenerator<SseFrame>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,aAAa,EAAE,MAAM;IAOjC,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,oCAAoC;AACpC,MAAM,WAAW,QAAQ;IACvB,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAU;;IAMrB,kEAAkE;IAClE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE;CAiGhC;AAED;;;;;GAKG;AACH,wBAAuB,OAAO,CAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,cAAc,CAAC,QAAQ,CAAC,CA0B1B"}

package/dist/sse.js

@@ -0,0 +1,166 @@
+/**
+ * Thrown by {@link readSse} when a stream goes completely quiet for longer
+ * than {@link ReadSseOptions.idleTimeoutMs}.
+ *
+ * A connection that drops without a close frame — a laptop going to sleep, a
+ * proxy timing out, a network that goes away mid-body — leaves the reader
+ * waiting on a chunk that will never come and throws nothing at all. Without
+ * this, a consumer cannot tell that from a run that is simply still working:
+ * both look like silence forever.
+ */
+export class SseIdleTimeoutError extends Error {
+    constructor(idleTimeoutMs) {
+        super(`The event stream sent nothing for ${idleTimeoutMs}ms and was closed.`);
+        this.name = 'SseIdleTimeoutError';
+        this.idleTimeoutMs = idleTimeoutMs;
+    }
+    /** The threshold that was exceeded, in milliseconds. */
+    idleTimeoutMs;
+}
+/**
+ * Incremental SSE decoder.
+ *
+ * Kept as a pure class with no I/O so the framing rules can be unit tested:
+ * chunk boundaries fall in arbitrary places and a parser that assumes whole
+ * frames per chunk works right up until a slow network proves it wrong.
+ *
+ * Comment lines (`: waiting`) are skipped. Tracon sends them as keep-alives
+ * while a run is still in progress.
+ */
+export class SseDecoder {
+    #buffer = '';
+    #data = [];
+    #event = null;
+    #id = null;
+    /** Feeds a chunk of text and returns every frame it completed. */
+    push(chunk) {
+        this.#buffer += chunk;
+        const frames = [];
+        let newline = this.#nextLineBreak();
+        while (newline !== null) {
+            const line = this.#buffer.slice(0, newline.index);
+            this.#buffer = this.#buffer.slice(newline.index + newline.length);
+            const frame = this.#consume(line);
+            if (frame !== null) {
+                frames.push(frame);
+            }
+            newline = this.#nextLineBreak();
+        }
+        return frames;
+    }
+    #nextLineBreak() {
+        for (let index = 0; index < this.#buffer.length; index++) {
+            const char = this.#buffer[index];
+            if (char === '\n') {
+                return { index, length: 1 };
+            }
+            if (char === '\r') {
+                // A trailing lone "\r" may be the first half of "\r\n"; wait for more.
+                if (index === this.#buffer.length - 1) {
+                    return null;
+                }
+                return this.#buffer[index + 1] === '\n'
+                    ? { index, length: 2 }
+                    : { index, length: 1 };
+            }
+        }
+        return null;
+    }
+    #consume(line) {
+        if (line.length === 0) {
+            return this.#flush();
+        }
+        if (line.startsWith(':')) {
+            return null;
+        }
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' ')) {
+            value = value.slice(1);
+        }
+        switch (field) {
+            case 'data':
+                this.#data.push(value);
+                break;
+            case 'event':
+                this.#event = value;
+                break;
+            case 'id':
+                this.#id = value;
+                break;
+            default:
+                break;
+        }
+        return null;
+    }
+    #flush() {
+        if (this.#data.length === 0 && this.#event === null) {
+            return null;
+        }
+        const frame = {
+            id: this.#id,
+            event: this.#event ?? 'message',
+            data: this.#data.join('\n'),
+        };
+        this.#data = [];
+        this.#event = null;
+        this.#id = null;
+        return frame;
+    }
+}
+/**
+ * Reads a `text/event-stream` response body as frames.
+ *
+ * `EventSource` is not used: it cannot send an `Authorization` header and it
+ * cannot issue a POST, and Tracon needs both.
+ */
+export async function* readSse(response, options) {
+    if (response.body === null) {
+        return;
+    }
+    const reader = response.body.getReader();
+    const utf8 = new TextDecoder();
+    const decoder = new SseDecoder();
+    const idleTimeoutMs = options?.idleTimeoutMs;
+    try {
+        for (;;) {
+            const { done, value } = idleTimeoutMs === undefined ? await reader.read() : await readWithin(reader, idleTimeoutMs);
+            if (done) {
+                break;
+            }
+            for (const frame of decoder.push(utf8.decode(value, { stream: true }))) {
+                yield frame;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Reads the next chunk, or throws {@link SseIdleTimeoutError} when nothing at
+ * all arrives within `idleTimeoutMs`.
+ *
+ * The reader is cancelled on the way out so the underlying connection is
+ * released rather than left half-open behind a generator nobody is pulling.
+ */
+async function readWithin(reader, idleTimeoutMs) {
+    let timer;
+    const idle = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new SseIdleTimeoutError(idleTimeoutMs)), idleTimeoutMs);
+    });
+    try {
+        return await Promise.race([reader.read(), idle]);
+    }
+    catch (error) {
+        if (error instanceof SseIdleTimeoutError) {
+            await reader.cancel().catch(() => undefined);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tracon/client",
+  "version": "1.0.0-preview.1",
+  "description": "Typed TypeScript client for the Tracon management API, generated from its OpenAPI document.",
+  "license": "PolyForm-Small-Business-1.0.0",
+  "type": "module",
+  "homepage": "https://tracon.dev",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "node scripts/generate.mjs",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}