@catalyst-cloud/sdk 0.12.2 → 0.13.0

package/dist/tenant-client.js

@@ -1,4 +1,6 @@
 import { parseLinearIdentityView } from "./linear-identity.js";
+import { AuthError } from "./live-sync-client.js";
+import { iterateNdjson } from "./ndjson.js";
 import { CONTRACT_ROUTE, readTenantContract, routeByName, } from "./tenant-contract.js";
 // ── Options ─────────────────────────────────────────────────────────────────────────────────────
 /** Default per-request deadline — the bundle's `REQUEST_TIMEOUT_MS`. */
@@ -238,6 +240,7 @@ export function createTenantClient(opts) {
     const store = opts.contractCache ?? memoryContractCache();
     const now = opts.now ?? Date.now;
     const origin = normalizeBaseUrl(opts.baseUrl);
+    const auth = opts.auth ?? { kind: "token", token: opts.key };
     function url(path, query) {
         const u = new URL(`${origin}${path}`);
         for (const [k, v] of Object.entries(query ?? {})) {
@@ -246,12 +249,32 @@ export function createTenantClient(opts) {
         }
         return u.toString();
     }
+    /** Async because a `bearer` token rotates (~15 min) and must be resolved FRESH per request — the
+     *  same rule `CatalystReplica.feedHeaders()` follows (src/replica/catalyst-replica.ts:1416). */
+    async function authHeaders() {
+        if (auth.kind === "token")
+            return { authorization: `Bearer ${auth.token}` };
+        if (auth.kind === "cookie")
+            return {};
+        let token;
+        try {
+            token = await auth.getToken();
+        }
+        catch (err) {
+            throw new AuthError(401, `bearer getToken() rejected: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { authorization: `Bearer ${token}` };
+    }
     async function send(method, target, extraHeaders, body) {
-        const headers = {
-            authorization: `Bearer ${opts.key}`,
-            accept: "application/json",
-            ...extraHeaders,
-        };
+        let resolved;
+        try {
+            resolved = await authHeaders();
+        }
+        catch (err) {
+            const reason = err instanceof AuthError ? err.message : err instanceof Error ? err.message : String(err);
+            return { ok: false, failure: { outcome: "unauthorized", status: 401, reason, ref: null } };
+        }
+        const headers = { ...resolved, accept: "application/json", ...extraHeaders };
         if (body !== undefined)
             headers["content-type"] = "application/json";
         let res;
@@ -262,6 +285,7 @@ export function createTenantClient(opts) {
                 headers,
                 ...(body === undefined ? {} : { body: JSON.stringify(body) }),
                 signal: AbortSignal.timeout(timeoutMs),
+                ...(auth.kind === "cookie" ? { credentials: "include" } : {}),
             });
             // ⛔ THE BODY READ IS INSIDE THE TRY (Codex #65 r1, P2). `fetch` resolves once the HEADERS
             // arrive; the stream can still fail, or the deadline fire, while `text()` consumes it — and
@@ -284,6 +308,108 @@ export function createTenantClient(opts) {
         }
         return { ok: true, answer: { status: res.status, headers: res.headers, json, textHead: text.slice(0, 200) } };
     }
+    /**
+     * An IDLE deadline for the streaming path, NOT the wall-clock one `AbortSignal.timeout()` gives.
+     * ⛔ `AbortSignal.timeout(timeoutMs)` keeps governing the response BODY once the headers have
+     * arrived, so it truncated any `/changes` replay that took longer than `timeoutMs` to drain and
+     * lost every row already read (CTC-2132 validate attempt 1, code-review Finding 2) — which defeats
+     * the whole point of `changes.stream`. The timer is rearmed on every chunk (`iterateNdjson`'s
+     * `onProgress` refund, the same one the replica's snapshot seed uses), so a feed that keeps
+     * delivering never expires while a feed that STALLS for `timeoutMs` still does. `release()` clears
+     * it when the stream ends, normally or not.
+     */
+    function idleDeadline() {
+        const controller = new AbortController();
+        let timer;
+        const release = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        };
+        const rearm = () => {
+            if (controller.signal.aborted)
+                return;
+            release();
+            timer = setTimeout(() => {
+                timer = undefined;
+                controller.abort(new Error(`The operation timed out after ${timeoutMs}ms without progress.`));
+            }, timeoutMs);
+        };
+        rearm();
+        return { signal: controller.signal, rearm, release };
+    }
+    /** A raw-response sibling of `send()`: resolves auth exactly as `send()` does but hands back the
+     *  `Response` UNREAD, so an NDJSON body can be streamed instead of buffered through `text()`. The
+     *  returned `deadline` is the caller's to drive — see {@link idleDeadline}.
+     *
+     *  ⛔ `signal` IS THE CALLER'S OWN, AND IT REACHES THE FETCH (CTC-2132 validate attempt 14,
+     *  code-review Finding 4). Threading it into `iterateNdjson` alone bounds only the BODY loop, so an
+     *  abort raised before the response HEADERS arrived left the request in flight and uncancelled —
+     *  invisible to a suite that only ever aborts mid-body. It is composed with the idle deadline's
+     *  signal here, so EITHER cancels the request at any point in its life. */
+    async function sendRaw(method, target, extraHeaders, body, signal) {
+        let resolved;
+        try {
+            resolved = await authHeaders();
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return { ok: false, failure: { outcome: "unauthorized", status: 401, reason, ref: null } };
+        }
+        const headers = { ...resolved, ...extraHeaders };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const deadline = idleDeadline();
+        const composed = signal === undefined ? deadline.signal : AbortSignal.any([deadline.signal, signal]);
+        try {
+            const res = await fetchImpl(target, {
+                method,
+                headers,
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: composed,
+                ...(auth.kind === "cookie" ? { credentials: "include" } : {}),
+            });
+            deadline.rearm(); // the headers arrived: the deadline now bounds IDLE time on the body, not the whole read
+            return { ok: true, res, deadline };
+        }
+        catch (err) {
+            deadline.release();
+            const reason = err instanceof Error ? err.message : String(err);
+            return { ok: false, failure: { outcome: "network", reason: `could not reach ${target}: ${reason}` } };
+        }
+    }
+    /**
+     * Read a `Response` `sendRaw` handed back into the same `Answer` shape `send()` produces — used for
+     * the refusal path of an NDJSON route, whose refusal body IS JSON.
+     *
+     * ⛔ THE BODY READ IS INSIDE THE TRY, for exactly the reason `send()`'s is (CTC-2132 validate
+     * attempt 14, code-review Finding 1). `fetch` resolved when the HEADERS arrived; this stream can
+     * still fault — or the idle deadline fire — while `text()` drains it, and that is a transport
+     * failure to FOLD, never an exception the public call may leak. It leaked: `changes.list()` and
+     * `snapshot.head()` are both documented as never-throwing, and a refusal whose socket reset
+     * mid-body rejected straight out of them. Returns `Sent` so every caller folds this read exactly
+     * as it already folds `send()`'s.
+     */
+    async function answerOf(res, target) {
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return { ok: false, failure: { outcome: "network", reason: `could not read ${target}: ${reason}` } };
+        }
+        let json;
+        if (text !== "") {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = undefined;
+            }
+        }
+        return { ok: true, answer: { status: res.status, headers: res.headers, json, textHead: text.slice(0, 200) } };
+    }
     // ── contract() ────────────────────────────────────────────────────────────────────────────────
     async function contract(o = {}) {
         const cached = await store.get();
@@ -321,8 +447,14 @@ export function createTenantClient(opts) {
             return fromCache(cached);
         };
         const sent = await send("GET", url(CONTRACT_ROUTE), cached?.etag ? { "if-none-match": cached.etag } : {});
+        // CTC-2132 widened `Sent`'s failure arm from `network` to `network | unauthorized` so a bearer
+        // `getToken()` rejection can be returned as a typed arm — which made this line funnel a CREDENTIAL
+        // REFUSAL through the stale-cache tolerance above, so a client whose OAuth refresh had failed was
+        // told `{outcome:"ok",source:"cache"}` (validate attempt 1, code-review Finding 3). A refusal is
+        // not transient; it is returned as itself, exactly as the comment above `unavailable` states and
+        // as the 401/403 answered by the SERVER already is (they fall through to `classify` below).
         if (!sent.ok)
-            return unavailable(sent.failure);
+            return sent.failure.outcome === "unauthorized" ? sent.failure : unavailable(sent.failure);
         const { answer } = sent;
         if (answer.status === 429 || answer.status >= 500)
             return unavailable(classify(answer));
@@ -482,6 +614,290 @@ export function createTenantClient(opts) {
         }
         return { outcome: "ok", account, slug, name, permissions, principal };
     }
+    async function issuesExecution(identifier) {
+        const sent = await send("GET", url(`/api/v1/issues/${encodeURIComponent(identifier)}/execution`), {});
+        if (!sent.ok)
+            return sent.failure;
+        const { answer } = sent;
+        if (answer.status === 404)
+            return { outcome: "not-found", status: 404 };
+        if (answer.status !== 200)
+            return classify(answer);
+        if (!isRecord(answer.json)) {
+            return { outcome: "shape", status: 200, reason: "GET /api/v1/issues/:id/execution did not answer an object" };
+        }
+        return { outcome: "ok", status: 200, report: answer.json };
+    }
+    // ── The diagnosis / telemetry reads ───────────────────────────────────────────────────────────
+    /** A literal-path open read whose body is one object. The shape check is the CONTAINER only
+     *  (Decision 4, CTC-2132) — `check` never inspects a field the cloud might rename. */
+    async function objectRead(path, query, label, check = () => true) {
+        const sent = await send("GET", url(path, query), {});
+        if (!sent.ok)
+            return sent.failure;
+        const { answer } = sent;
+        if (answer.status !== 200)
+            return classify(answer);
+        if (!isRecord(answer.json) || !check(answer.json)) {
+            return { outcome: "shape", status: 200, reason: `${label} did not answer the documented shape` };
+        }
+        return { outcome: "ok", status: 200, body: answer.json };
+    }
+    /** A literal-path open read whose body is a bare array. */
+    async function arrayRead(path, query, label) {
+        const sent = await send("GET", url(path, query), {});
+        if (!sent.ok)
+            return sent.failure;
+        const { answer } = sent;
+        if (answer.status !== 200)
+            return classify(answer);
+        const rows = Array.isArray(answer.json) ? rowsOf(answer.json) : null;
+        if (rows === null)
+            return { outcome: "shape", status: 200, reason: `${label} did not answer an array` };
+        return { outcome: "ok", status: 200, rows };
+    }
+    async function workEligibility(params = {}) {
+        const r = await objectRead("/api/v1/work-eligibility", { team: params.team }, "GET /api/v1/work-eligibility");
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, report: r.body } : r;
+    }
+    async function dispatchQueue(params = {}) {
+        const r = await objectRead("/api/v1/dispatch-queue/current", { team: params.team }, "GET /api/v1/dispatch-queue/current", (body) => Array.isArray(body["entries"]));
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, queue: r.body } : r;
+    }
+    async function fleetActivity(params = {}) {
+        const r = await arrayRead("/api/v1/fleet-activity/current", { account: params.account }, "GET /api/v1/fleet-activity/current");
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, rows: r.rows } : r;
+    }
+    async function agentRoster() {
+        const r = await arrayRead("/api/v1/agent-roster/current", {}, "GET /api/v1/agent-roster/current");
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, rows: r.rows } : r;
+    }
+    async function leaseAttributions(params) {
+        const sent = await send("GET", url("/api/v1/lease/attributions", { ticket: params.ticket, phase: params.phase }), {});
+        if (!sent.ok)
+            return sent.failure;
+        const { answer } = sent;
+        if (answer.status !== 200)
+            return classify(answer);
+        if (answer.json === undefined) {
+            return { outcome: "shape", status: 200, reason: "GET /api/v1/lease/attributions did not answer JSON" };
+        }
+        return { outcome: "ok", status: 200, body: answer.json };
+    }
+    async function codingAccounts() {
+        const r = await objectRead("/api/v1/coding-accounts", {}, "GET /api/v1/coding-accounts", (body) => Array.isArray(body["accounts"]));
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, report: r.body } : r;
+    }
+    // ── The query reads ────────────────────────────────────────────────────────────────────────────
+    async function cyclesList() {
+        const r = await arrayRead("/api/v1/cycles", {}, "GET /api/v1/cycles");
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, rows: r.rows } : r;
+    }
+    async function search(params) {
+        const r = await objectRead("/api/v1/search", { q: params.q, limit: params.limit }, "GET /api/v1/search");
+        return r.outcome === "ok" ? { outcome: "ok", status: 200, results: r.body } : r;
+    }
+    /** Tolerant (Decision 7): accepts `{stages, source?}` OR a bare array, normalizing both — mirroring
+     *  the bundle's own `fetchWorkflowStates`, which already defends against three shapes. */
+    async function workflowStages() {
+        const sent = await send("GET", url("/api/v1/workflow-stages"), {});
+        if (!sent.ok)
+            return sent.failure;
+        const { answer } = sent;
+        if (answer.status !== 200)
+            return classify(answer);
+        if (Array.isArray(answer.json)) {
+            const rows = rowsOf(answer.json);
+            if (rows !== null)
+                return { outcome: "ok", status: 200, stages: rows, source: null };
+        }
+        if (isRecord(answer.json) && Array.isArray(answer.json["stages"])) {
+            const rows = rowsOf(answer.json["stages"]);
+            if (rows !== null) {
+                return { outcome: "ok", status: 200, stages: rows, source: stringField(answer.json, "source") };
+            }
+        }
+        return { outcome: "shape", status: 200, reason: "GET /api/v1/workflow-stages did not answer a recognised shape" };
+    }
+    /** ⛔ The returned generator MAY THROW mid-iteration — a transport fault after the promise already
+     *  resolved cannot be folded into an already-resolved union. Use {@link changesList} for the
+     *  nothing-throws, buffered alternative. */
+    async function changesStream(params) {
+        const target = url("/api/v1/changes", { since: params.since });
+        const sent = await sendRaw("GET", target, { accept: "application/x-ndjson" }, undefined, params.signal);
+        if (!sent.ok)
+            return sent.failure;
+        const { res, deadline } = sent;
+        if (res.status === 409) {
+            // ⛔ RELEASE THE DEADLINE *AFTER* THE REFUSAL BODY, NEVER BEFORE (CTC-2132 validate attempt 14,
+            // code-review Finding 2). The deadline's signal is the ONLY one bounding this read — it is the
+            // signal `sendRaw` handed the fetch — so releasing first left a tenant that sends 409 HEADERS
+            // and then stalls the body wedged with no timeout at all. `send()` does not behave this way:
+            // its own `AbortSignal.timeout` keeps governing its body read.
+            const head = integerHeader(res.headers, HEAD_SEQ_HEADER);
+            const read = await answerOf(res, target).finally(() => deadline.release());
+            if (!read.ok)
+                return read.failure;
+            return { outcome: "resync", status: 409, head, reason: reasonOf(read.answer) };
+        }
+        if (res.status !== 200) {
+            const read = await answerOf(res, target).finally(() => deadline.release());
+            return read.ok ? classify(read.answer) : read.failure;
+        }
+        const head = integerHeader(res.headers, HEAD_SEQ_HEADER);
+        // ⛔ ARM THE IDLE DEADLINE LAZILY, AND HAND BACK A `close()` (CTC-2132 validate attempt 14,
+        // code-review Finding 3). `deadline.release()` lives in `rows()`'s `finally`, which NEVER RUNS for
+        // a caller that awaits this promise, reads `head` and then discards the generator — the shape
+        // `test/tenant-client-changes.test.ts`'s own `since:'head'` case has. That left an armed timer
+        // holding the event loop open for `timeoutMs` and then firing an abort on a controller nobody was
+        // listening to, with `res.body` never cancelled and the connection still referenced. So: nothing
+        // is armed while the stream is UNSTARTED (`rows()` arms on entry and `onProgress` refunds per
+        // chunk thereafter), and a caller that will not drain the feed releases the body through `close()`.
+        deadline.release();
+        let closed = false;
+        const close = async () => {
+            if (closed)
+                return;
+            closed = true;
+            deadline.release();
+            // Locked once `rows()` holds a reader — `iterateNdjson`'s own `finally` cancels that one.
+            await res.body?.cancel().catch(() => { });
+        };
+        async function* rows() {
+            deadline.rearm(); // the idle clock starts at the first READ, not when the headers arrived
+            try {
+                // `onProgress` refunds the idle deadline per chunk, so a long replay is never truncated at
+                // `timeoutMs` (attempt 1, code-review Finding 2); `finally` releases it on every exit — EOF,
+                // caller abort, a `break` out of the for-await, or a throw from the parse below.
+                for await (const line of iterateNdjson(res, {
+                    ...(params.signal === undefined ? {} : { signal: params.signal }),
+                    onProgress: deadline.rearm,
+                })) {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(line);
+                    }
+                    catch {
+                        throw new Error(`/api/v1/changes emitted a line that is not JSON: ${line.slice(0, 120)}`);
+                    }
+                    if (!isRecord(parsed))
+                        throw new Error("/api/v1/changes emitted a line that is not an object");
+                    // ⛔ PAUSE THE IDLE CLOCK WHILE SUSPENDED AT `yield` (CTC-2132 validate attempt 30). It bounds
+                    // time spent awaiting the NETWORK; the caller's per-row work between pulls is not a stall,
+                    // so a slow consumer of one chunk's rows no longer aborts a feed that never went quiet.
+                    deadline.release();
+                    yield parsed;
+                    deadline.rearm();
+                }
+            }
+            finally {
+                deadline.release();
+            }
+        }
+        return { outcome: "ok", status: 200, head, rows: rows(), close };
+    }
+    async function changesListFn(params) {
+        const sent = await changesStream(params);
+        if (sent.outcome !== "ok")
+            return sent;
+        try {
+            const rows = [];
+            for await (const row of sent.rows)
+                rows.push(row);
+            return { outcome: "ok", status: 200, head: sent.head, rows };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return { outcome: "network", reason: `/api/v1/changes stream faulted mid-body: ${reason}` };
+        }
+        finally {
+            // `rows()`'s own `finally` already ran on every path above; `close()` is idempotent and makes
+            // the buffered caller provably leak-free without it having to know that (Finding 3).
+            await sent.close();
+        }
+    }
+    /** The cheap probe (Decision 7) — NEVER falls back to a full snapshot fetch. Reads the head from
+     *  `X-Mirror-Cursor` if present, else a JSON body's `head`/`seq`/`cursor`, else the first NDJSON
+     *  line parsed as JSON. */
+    async function snapshotHead() {
+        const target = url("/api/v1/snapshot", { head: 1 });
+        const sent = await sendRaw("GET", target, { accept: "application/x-ndjson, application/json" });
+        if (!sent.ok)
+            return sent.failure;
+        const { res, deadline } = sent;
+        try {
+            // ⛔ STATUS FIRST, THEN THE HEADER. `X-Mirror-Cursor` rides REFUSALS too — `changesStream`
+            // above reads the head straight off a 409 — so reading it before the status gate reported a
+            // 403 as `{outcome:"ok",status:200,head:…}` and told a liveness probe the mirror was healthy
+            // while the client was de-authorized (CTC-2132 validate attempt 1, code-review Finding 1).
+            // Past this gate `res.status` IS 200, so the literal below is the status, not an assumption.
+            if (res.status !== 200) {
+                const read = await answerOf(res, target);
+                return read.ok ? classify(read.answer) : read.failure;
+            }
+            const headerHead = integerHeader(res.headers, HEAD_SEQ_HEADER);
+            if (headerHead !== null) {
+                await res.body?.cancel().catch(() => { });
+                return { outcome: "ok", status: 200, head: headerHead, source: "header" };
+            }
+            const contentType = res.headers.get("content-type") ?? "";
+            if (contentType.includes("application/json")) {
+                const read = await answerOf(res, target);
+                if (!read.ok)
+                    return read.failure;
+                const answer = read.answer;
+                const fromBody = isRecord(answer.json)
+                    ? (numberField(answer.json, "head") ?? numberField(answer.json, "seq") ?? numberField(answer.json, "cursor"))
+                    : null;
+                if (fromBody !== null)
+                    return { outcome: "ok", status: 200, head: fromBody, source: "body" };
+                return { outcome: "shape", status: 200, reason: "GET /api/v1/snapshot?head=1 did not answer a finite head" };
+            }
+            for await (const line of iterateNdjson(res, { onProgress: deadline.rearm })) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (isRecord(parsed)) {
+                    const fromLine = numberField(parsed, "head") ?? numberField(parsed, "seq") ?? numberField(parsed, "cursor");
+                    if (fromLine !== null)
+                        return { outcome: "ok", status: 200, head: fromLine, source: "body" };
+                }
+                break;
+            }
+            return { outcome: "shape", status: 200, reason: "GET /api/v1/snapshot?head=1 did not answer a finite head" };
+        }
+        catch (err) {
+            // The SAME never-throws contract Finding 1 is about, on this function's OTHER body read: the
+            // NDJSON line scan above streams `res.body`, which can fault (or the deadline fire) exactly as
+            // `answerOf`'s `text()` can. `SnapshotHeadResult` has no throw arm — fold it as `send()` would.
+            const reason = err instanceof Error ? err.message : String(err);
+            return { outcome: "network", reason: `could not read ${target}: ${reason}` };
+        }
+        finally {
+            deadline.release();
+        }
+    }
+    // ── The generic escape hatch ───────────────────────────────────────────────────────────────────
+    async function request(req) {
+        if (!req.path.startsWith("/") || req.path.startsWith("//")) {
+            return {
+                outcome: "rejected",
+                status: 0,
+                reason: `request(): path must be an absolute path under the tenant origin, got ${req.path}`,
+            };
+        }
+        const sent = await send(req.method ?? "GET", url(req.path, req.query), req.headers ?? {}, req.body);
+        if (!sent.ok)
+            return sent.failure;
+        const { answer } = sent;
+        if (answer.status < 200 || answer.status >= 300)
+            return classify(answer);
+        return { outcome: "ok", status: answer.status, json: answer.json, headers: answer.headers };
+    }
     async function linearIdentityCall(linearUserId) {
         const sent = await send(linearUserId === undefined ? "GET" : "POST", url("/me/linear-identity"), {}, linearUserId === undefined ? undefined : { linearUserId });
         if (!sent.ok)
@@ -783,12 +1199,26 @@ export function createTenantClient(opts) {
     return {
         contract,
         me,
+        request,
         linearIdentity: { get: () => linearIdentityCall(), set: (linearUserId) => linearIdentityCall(linearUserId) },
         personalConnections: { start: personalConnectionStart, status: personalConnectionStatus },
         teamWorkflow,
-        issues: { list: issuesList, get: issuesGet },
+        issues: { list: issuesList, get: issuesGet, execution: issuesExecution },
         pulls: { list: pullsList, get: pullsGet },
         projects: { list: projectsList },
+        cycles: { list: cyclesList },
+        search,
+        workflowStages,
+        changes: { stream: changesStream, list: changesListFn },
+        snapshot: { head: snapshotHead },
+        diagnostics: {
+            workEligibility,
+            dispatchQueue,
+            fleetActivity,
+            agentRoster,
+            leaseAttributions,
+            codingAccounts,
+        },
         agent,
     };
 }