@vonpay/checkout-cli 0.3.3 → 0.4.1

package/dist/utils/listen-forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-forward.d.ts","sourceRoot":"","sources":["../../src/utils/listen-forward.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,UAAU,cAAc;IACtB,wCAAwC;IACxC,GAAG,EAAE,GAAG,CAAC;IACT;;;;6EAIyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,cAAc,CAAC,CAsEzB"}

package/dist/utils/listen-forward.js

@@ -0,0 +1,113 @@
+import { createHmac } from "node:crypto";
+/**
+ * Sign + POST a JSON payload to the local URL. Returns an outcome
+ * shape that the output formatters render — never throws (errors
+ * surface via `outcome.error`).
+ */
+export async function forwardPayload(payload, opts) {
+    const body = JSON.stringify(payload);
+    // Stamp `t` at the moment we forward — NOT the server's original
+    // delivery-attempt time. The CLI is the *re-sender* for this local
+    // delivery: the dev's handler calls `webhooks.constructEvent`, which
+    // rejects any `t` outside the freshness window (>5 min old / >30 sec
+    // future). The server's original timestamp (carried on the SSE
+    // `webhook.attempt` frame) is routinely minutes old — retries,
+    // processing lag, a transcript the dev scrolled back through — so
+    // replaying it would trip the window. A fresh `t` here matches Stripe
+    // CLI's re-sign posture. Unlike the old bare-hex shape, `t` IS folded
+    // into the HMAC per the v1 contract (`${t}.${body}`).
+    const t = Math.floor(Date.now() / 1000);
+    // v1 signature contract (vonpay-checkout/docs/webhook-signature-v1.md):
+    // ONE header `x-vonpay-signature: t=<unix-seconds>,v1=<hex>`, HMAC-SHA256
+    // over `${t}.${body}`. There is NO separate timestamp header. Rotation
+    // (multiple `v1=` entries) does not apply to this synthetic local loop —
+    // we sign with a single secret (the API key). When the server ships a
+    // per-subscription signing secret on the SSE `webhook.attempt` frame,
+    // sign with that here instead of the API key. (The 0.0.0.0 loopback
+    // warning already shipped in forward-to.ts.)
+    const v1 = createHmac("sha256", opts.signingSecret)
+        .update(`${t}.${body}`)
+        .digest("hex");
+    const signatureHeader = `t=${t},v1=${v1}`;
+    const timeoutMs = opts.timeoutMs ?? 5_000;
+    const localController = new AbortController();
+    const timeoutId = setTimeout(() => localController.abort(), timeoutMs);
+    const combinedSignal = anySignal([opts.signal, localController.signal]);
+    const start = Date.now();
+    try {
+        const res = await fetch(opts.url.toString(), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-vonpay-signature": signatureHeader,
+                "User-Agent": "vonpay-cli-listen",
+            },
+            body,
+            signal: combinedSignal,
+        });
+        // Drain response body so the connection can be reused — best practice
+        // for repeated POSTs to the same local endpoint.
+        try {
+            await res.arrayBuffer();
+        }
+        catch {
+            // ignore drain errors; not relevant to forward semantics
+        }
+        return {
+            attempted: true,
+            status: res.status,
+            latencyMs: Date.now() - start,
+            error: null,
+        };
+    }
+    catch (err) {
+        if (opts.signal.aborted) {
+            return { attempted: true, status: null, latencyMs: null, error: "aborted" };
+        }
+        if (localController.signal.aborted) {
+            return { attempted: true, status: null, latencyMs: null, error: `timeout after ${timeoutMs}ms` };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { attempted: true, status: null, latencyMs: null, error: message };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Combine multiple AbortSignals into one. The returned signal is
+ * aborted when any input signal aborts. Polyfill for `AbortSignal.any`
+ * which is Node 20.5+ only — guard for older 20.x deployments.
+ *
+ * The polyfill tracks every listener it registers and removes them all
+ * once any input fires — without this, the long-lived parent
+ * `opts.signal` accumulates one orphaned listener per forward call,
+ * which on a busy listen stream is a measurable leak.
+ */
+function anySignal(signals) {
+    if (typeof AbortSignal.any === "function") {
+        return AbortSignal.any(signals);
+    }
+    const controller = new AbortController();
+    const tracked = [];
+    const onAbort = () => {
+        for (const sig of tracked) {
+            sig.removeEventListener("abort", onAbort);
+        }
+        controller.abort();
+    };
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort();
+            // Remove already-added listeners — none yet, but defensive.
+            for (const sig of tracked) {
+                sig.removeEventListener("abort", onAbort);
+            }
+            return controller.signal;
+        }
+        signal.addEventListener("abort", onAbort);
+        tracked.push(signal);
+    }
+    return controller.signal;
+}
+//# sourceMappingURL=listen-forward.js.map

package/dist/utils/listen-forward.js.map

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

package/dist/utils/listen-output.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Output formatters for `vonpay checkout listen`.
+ *
+ * Two modes:
+ *   - "human" (default) — colored transcript, one line per attempt.
+ *     Optimized for the dev sitting at a terminal watching events
+ *     flow in real time.
+ *   - "json" — one JSON object per line on stdout. Optimized for
+ *     piping to `jq`, `grep`, or log aggregators.
+ *
+ * Lifecycle messages (connecting, reconnecting, etc.) ALWAYS go to
+ * stderr in human mode so stdout stays parseable in `--json` mode
+ * even when interleaved with reconnects.
+ */
+export type OutputMode = "human" | "json";
+/**
+ * Wire shape of the SSE `webhook.attempt` payload. Mirrors
+ * vonpay-checkout's WebhookListenAttempt (snake_case on the wire).
+ *
+ * Duplicated here rather than importing from @vonpay/checkout-node
+ * because the SDK does not currently export an SSE-event type — the
+ * listen surface is CLI-only. If the SDK adds a streaming consumer in
+ * a future minor, this type should move to the SDK and be re-imported.
+ */
+export interface WebhookAttemptPayload {
+    type: "webhook.attempt";
+    subscription_id: string;
+    event_id: string;
+    event_type: string;
+    attempt: number;
+    succeeded: boolean;
+    response_status: number | null;
+    latency_ms: number;
+    timestamp: string;
+    livemode: boolean;
+}
+export interface ForwardOutcome {
+    attempted: boolean;
+    /** Local-URL response status, or null when no attempt was made (no --forward-to). */
+    status: number | null;
+    /** Latency ms of the local-URL POST. */
+    latencyMs: number | null;
+    /** Error message if the forward attempt failed at the network layer. */
+    error: string | null;
+}
+export declare function formatAttemptHuman(payload: WebhookAttemptPayload, forward: ForwardOutcome | null): string;
+export declare function formatAttemptJson(payload: WebhookAttemptPayload, forward: ForwardOutcome | null): string;
+/** Lifecycle line for human mode (stderr). */
+export declare function formatLifecycleHuman(message: string, kind: "info" | "warn" | "error"): string;
+/** Lifecycle line for JSON mode (stderr). */
+export declare function formatLifecycleJson(kind: "connecting" | "connected" | "disconnected" | "auth_failed" | "fatal" | "ready" | "shutdown" | "warning", extra?: Record<string, unknown>): string;
+//# sourceMappingURL=listen-output.d.ts.map

package/dist/utils/listen-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-output.d.ts","sourceRoot":"","sources":["../../src/utils/listen-output.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,qFAAqF;IACrF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wCAAwC;IACxC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GAAG,IAAI,GAC7B,MAAM,CAwBR;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GAAG,IAAI,GAC7B,MAAM,CAqBR;AAED,8CAA8C;AAC9C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAQ7F;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,EAC9G,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,MAAM,CAER"}

package/dist/utils/listen-output.js

@@ -0,0 +1,85 @@
+import chalk from "chalk";
+export function formatAttemptHuman(payload, forward) {
+    const ts = formatTimestamp(payload.timestamp);
+    const eventType = chalk.cyan(payload.event_type.padEnd(24));
+    const eventId = chalk.gray(payload.event_id.padEnd(28));
+    const attempt = chalk.gray(`attempt ${payload.attempt}`);
+    const arrow = chalk.gray("→");
+    const upstream = formatUpstream(payload);
+    const latency = chalk.gray(`${payload.latency_ms}ms`);
+    const liveBadge = payload.livemode ? chalk.red(" [LIVE]") : "";
+    let line = `[${ts}] ${eventType} ${eventId} ${attempt}  ${arrow} ${upstream}  ${latency}${liveBadge}`;
+    if (forward && forward.attempted) {
+        const fwdArrow = chalk.gray("→ local");
+        if (forward.error) {
+            line += `  ${fwdArrow} ${chalk.red(forward.error)}`;
+        }
+        else if (forward.status !== null) {
+            const fwdStatus = formatStatus(forward.status);
+            const fwdLatency = chalk.gray(`${forward.latencyMs}ms`);
+            line += `  ${fwdArrow} ${fwdStatus} ${fwdLatency}`;
+        }
+    }
+    return line;
+}
+export function formatAttemptJson(payload, forward) {
+    const body = {
+        type: "webhook.attempt",
+        event_id: payload.event_id,
+        event_type: payload.event_type,
+        subscription_id: payload.subscription_id,
+        attempt: payload.attempt,
+        succeeded: payload.succeeded,
+        response_status: payload.response_status,
+        latency_ms: payload.latency_ms,
+        timestamp: payload.timestamp,
+        livemode: payload.livemode,
+    };
+    if (forward && forward.attempted) {
+        body.forward = {
+            status: forward.status,
+            latency_ms: forward.latencyMs,
+            error: forward.error,
+        };
+    }
+    return JSON.stringify(body);
+}
+/** Lifecycle line for human mode (stderr). */
+export function formatLifecycleHuman(message, kind) {
+    const tag = kind === "info"
+        ? chalk.cyan("[vonpay]")
+        : kind === "warn"
+            ? chalk.yellow("[vonpay]")
+            : chalk.red("[vonpay]");
+    return `${tag} ${message}`;
+}
+/** Lifecycle line for JSON mode (stderr). */
+export function formatLifecycleJson(kind, extra = {}) {
+    return JSON.stringify({ type: `cli.${kind}`, ...extra, timestamp: new Date().toISOString() });
+}
+function formatStatus(status) {
+    if (status >= 200 && status < 300)
+        return chalk.green(String(status));
+    if (status >= 400 && status < 500)
+        return chalk.yellow(String(status));
+    if (status >= 500)
+        return chalk.red(String(status));
+    return chalk.gray(String(status));
+}
+function formatUpstream(payload) {
+    if (payload.response_status === null) {
+        return chalk.red("timeout");
+    }
+    return formatStatus(payload.response_status);
+}
+/** Local-time `HH:mm:ss` for the human stream. */
+function formatTimestamp(iso) {
+    const date = new Date(iso);
+    if (isNaN(date.getTime()))
+        return iso.slice(0, 19);
+    const h = String(date.getHours()).padStart(2, "0");
+    const m = String(date.getMinutes()).padStart(2, "0");
+    const s = String(date.getSeconds()).padStart(2, "0");
+    return `${h}:${m}:${s}`;
+}
+//# sourceMappingURL=listen-output.js.map

package/dist/utils/listen-output.js.map

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

package/dist/utils/sse-consumer.d.ts

@@ -0,0 +1,81 @@
+import { type SseEvent } from "./sse-parser.js";
+/**
+ * Long-lived SSE consumer with WHATWG-spec reconnect semantics.
+ *
+ * Wraps native `fetch()` against a streaming endpoint, parses incoming
+ * bytes via {@link SseParser}, yields events to the caller, and
+ * transparently reconnects on disconnect with exponential backoff.
+ *
+ * The `Last-Event-ID` header is sent on every reconnect after the first
+ * event. The server emits sticky `id: <event_id>:<attempt>` per frame,
+ * so a clean reconnect with the header in place skips duplicate events
+ * the consumer has already surfaced — at-least-once → effectively
+ * exactly-once for SSE.
+ *
+ * Cancellation: pass an `AbortSignal`. The consumer terminates cleanly
+ * (closes the response body reader, no more events, no more reconnects)
+ * when the signal aborts. This is the SIGINT / SIGTERM path.
+ *
+ * Backoff is exponential 1s → 2s → 4s → 8s → 30s cap with infinite
+ * retries — matches Stripe CLI / kubectl / aws CLI patterns for
+ * long-lived streaming connections. Reset to 1s after a successful
+ * read of at least one byte.
+ */
+export interface SseConsumerOptions {
+    /** Full URL of the SSE endpoint. */
+    url: string;
+    /** Headers to send on every connection. Authorization / Accept set automatically. */
+    headers?: Record<string, string>;
+    /** AbortSignal for graceful shutdown. */
+    signal: AbortSignal;
+    /**
+     * Logger for connection-lifecycle events (connect, disconnect, reconnect).
+     * The consumer never logs to stdout directly — the CLI command owns
+     * output formatting. Default is a no-op.
+     */
+    onLifecycle?: (event: LifecycleEvent) => void;
+    /** Max backoff in ms. Default 30000 (30s). */
+    maxBackoffMs?: number;
+    /** Initial backoff in ms. Default 1000 (1s). */
+    initialBackoffMs?: number;
+}
+export type LifecycleEvent = {
+    kind: "connecting";
+    lastEventId: string | undefined;
+} | {
+    kind: "connected";
+} | {
+    kind: "disconnected";
+    reason: string;
+    willRetryInMs: number;
+} | {
+    kind: "auth_failed";
+    status: number;
+    body: string;
+} | {
+    kind: "fatal";
+    error: Error;
+};
+/**
+ * Returns an async iterator of SseEvent. Iterates until the signal
+ * aborts OR an unrecoverable error occurs (e.g. 401 / 403 auth failure
+ * — those throw because retrying with the same key won't help).
+ *
+ * The 1h server ceiling fires as `event: timeout` with
+ * `data: {"reason":"server-ceiling"}` (per Phase 3d event-format.ts).
+ * The consumer surfaces the timeout event to the caller AND triggers
+ * an immediate reconnect — same as the upstream-disconnect path,
+ * but without the backoff delay.
+ */
+export declare function consumeSse(opts: SseConsumerOptions): AsyncGenerator<SseEvent, void, void>;
+/**
+ * Thrown when the server responds 401 or 403. Auth errors do not get
+ * retried — the caller is responsible for surfacing the error to the
+ * user and exiting non-zero.
+ */
+export declare class SseAuthError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+//# sourceMappingURL=sse-consumer.d.ts.map

package/dist/utils/sse-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-consumer.d.ts","sourceRoot":"","sources":["../../src/utils/sse-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,yCAAyC;IACzC,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC9C,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,wBAAuB,UAAU,CAC/B,IAAI,EAAE,kBAAkB,GACvB,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAsHtC;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAEnB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAO/B"}

package/dist/utils/sse-consumer.js

@@ -0,0 +1,172 @@
+import { SseParser } from "./sse-parser.js";
+/**
+ * Returns an async iterator of SseEvent. Iterates until the signal
+ * aborts OR an unrecoverable error occurs (e.g. 401 / 403 auth failure
+ * — those throw because retrying with the same key won't help).
+ *
+ * The 1h server ceiling fires as `event: timeout` with
+ * `data: {"reason":"server-ceiling"}` (per Phase 3d event-format.ts).
+ * The consumer surfaces the timeout event to the caller AND triggers
+ * an immediate reconnect — same as the upstream-disconnect path,
+ * but without the backoff delay.
+ */
+export async function* consumeSse(opts) {
+    const initialBackoffMs = opts.initialBackoffMs ?? 1000;
+    const maxBackoffMs = opts.maxBackoffMs ?? 30_000;
+    const parser = new SseParser();
+    let backoffMs = initialBackoffMs;
+    const onLifecycle = opts.onLifecycle ?? noop;
+    while (!opts.signal.aborted) {
+        const headers = {
+            Accept: "text/event-stream",
+            "Cache-Control": "no-cache",
+            ...opts.headers,
+        };
+        const lastEventId = parser.getLastEventId();
+        if (lastEventId !== undefined) {
+            headers["Last-Event-ID"] = lastEventId;
+        }
+        onLifecycle({ kind: "connecting", lastEventId });
+        let response;
+        try {
+            response = await fetch(opts.url, {
+                method: "GET",
+                headers,
+                signal: opts.signal,
+            });
+        }
+        catch (err) {
+            if (opts.signal.aborted)
+                return;
+            const reason = err instanceof Error ? err.message : String(err);
+            onLifecycle({ kind: "disconnected", reason, willRetryInMs: backoffMs });
+            await sleep(backoffMs, opts.signal);
+            backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+            continue;
+        }
+        if (response.status === 401 || response.status === 403) {
+            const body = await safeReadText(response);
+            onLifecycle({ kind: "auth_failed", status: response.status, body });
+            throw new SseAuthError(response.status, body);
+        }
+        if (!response.ok) {
+            const body = await safeReadText(response);
+            onLifecycle({
+                kind: "disconnected",
+                reason: `HTTP ${response.status}: ${truncate(body, 200)}`,
+                willRetryInMs: backoffMs,
+            });
+            await sleep(backoffMs, opts.signal);
+            backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+            continue;
+        }
+        if (!response.body) {
+            onLifecycle({
+                kind: "disconnected",
+                reason: "response has no body",
+                willRetryInMs: backoffMs,
+            });
+            await sleep(backoffMs, opts.signal);
+            backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+            continue;
+        }
+        onLifecycle({ kind: "connected" });
+        backoffMs = initialBackoffMs; // reset after a successful connect
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder("utf-8");
+        let serverInitiatedReconnect = false;
+        try {
+            while (!opts.signal.aborted) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                const events = parser.feed(decoder.decode(value, { stream: true }));
+                for (const ev of events) {
+                    // Server-ceiling timeout: surface to caller AND mark for
+                    // immediate reconnect without backoff. Per Phase 3d
+                    // event-format.ts the server sends this right before
+                    // closing the connection.
+                    if (ev.type === "timeout") {
+                        yield ev;
+                        serverInitiatedReconnect = true;
+                    }
+                    else {
+                        yield ev;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (opts.signal.aborted)
+                return;
+            const reason = err instanceof Error ? err.message : String(err);
+            onLifecycle({ kind: "disconnected", reason, willRetryInMs: backoffMs });
+        }
+        finally {
+            // Best-effort cancel — fetch already releases on abort but be defensive.
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (opts.signal.aborted)
+            return;
+        if (serverInitiatedReconnect) {
+            // Skip the backoff sleep; server politely told us to reconnect.
+            // backoffMs already at initial because we successfully connected.
+            continue;
+        }
+        onLifecycle({
+            kind: "disconnected",
+            reason: "stream ended",
+            willRetryInMs: backoffMs,
+        });
+        await sleep(backoffMs, opts.signal);
+        backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+    }
+}
+/**
+ * Thrown when the server responds 401 or 403. Auth errors do not get
+ * retried — the caller is responsible for surfacing the error to the
+ * user and exiting non-zero.
+ */
+export class SseAuthError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`SSE auth failed: HTTP ${status}${body ? ` — ${truncate(body, 200)}` : ""}`);
+        this.status = status;
+        this.body = body;
+        this.name = "SseAuthError";
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "";
+    }
+}
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n - 3)}...`;
+}
+function noop() {
+    /* no-op */
+}
+//# sourceMappingURL=sse-consumer.js.map

package/dist/utils/sse-consumer.js.map

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

package/dist/utils/sse-parser.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure incremental parser for the Server-Sent Events wire format
+ * (WHATWG HTML §9.2.6 "Parsing an event stream").
+ *
+ * Decoupled from I/O so the consumer can drive it from any byte source
+ * (fetch ReadableStream, Node Readable, in-memory buffer in tests).
+ *
+ * Spec details that are easy to get wrong:
+ *   - Frame separator is one blank line — any of `\n\n`, `\r\n\r\n`, `\r\r`.
+ *   - A line starting with `:` is a comment — ignored (used as heartbeat).
+ *   - `field: value` — the single space after `:` is stripped if present.
+ *   - Multiple `data:` lines within a frame concatenate with `\n` between them.
+ *   - `id:` sets the parser's lastEventId for the NEXT and subsequent
+ *     dispatched events (sticky across frames until overridden).
+ *   - `event:` defaults to `"message"` when absent.
+ *   - `retry:` is reported on the event but the consumer decides whether
+ *     to honor it (we expose it; consumer caps with its own backoff).
+ *   - Unknown fields are ignored — additive evolution is safe.
+ *
+ * Stateful only in `lastEventId` (per spec). Caller drives by repeatedly
+ * calling feed(chunk) on incoming bytes; events come back per call.
+ */
+export interface SseEvent {
+    /** Event type from `event:` field. Defaults to `"message"`. */
+    type: string;
+    /** Joined data payload — `data:` lines joined with `\n`. */
+    data: string;
+    /** Sticky id from `id:`. Undefined until the stream emits one. */
+    lastEventId: string | undefined;
+    /** Reconnect-time hint from `retry:` (ms). Undefined when absent. */
+    retry: number | undefined;
+}
+export declare class SseBufferOverflowError extends Error {
+    readonly cap: number;
+    constructor(cap: number);
+}
+export interface SseParserOptions {
+    /** Hard cap on in-flight bytes before {@link SseBufferOverflowError}. */
+    maxBufferBytes?: number;
+}
+export declare class SseParser {
+    private buffer;
+    private lastEventId;
+    private readonly maxBufferBytes;
+    constructor(options?: SseParserOptions);
+    /**
+     * Feed a chunk of decoded text. Returns any events that completed within
+     * this chunk. The remainder (partial frame) is held internally and
+     * concatenated with the next chunk.
+     *
+     * Throws {@link SseBufferOverflowError} when the in-flight buffer
+     * exceeds `maxBufferBytes` — the consumer's reconnect-on-error loop
+     * recovers by discarding the buffer and re-establishing the
+     * connection.
+     */
+    feed(chunk: string): SseEvent[];
+    /** Drain any in-flight buffer as a final event. Used when the source closes mid-frame and the consumer wants to surface the partial. Returns at most one event. Most callers don't need this — for a well-behaved server-side stream the parser never holds a complete trailing event without a separator. */
+    flush(): SseEvent | undefined;
+    private parseFrame;
+    /** Current sticky id. Consumer uses this for the Last-Event-ID header on reconnect. */
+    getLastEventId(): string | undefined;
+}
+//# sourceMappingURL=sse-parser.d.ts.map

package/dist/utils/sse-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-parser.d.ts","sourceRoot":"","sources":["../../src/utils/sse-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,qEAAqE;IACrE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAeD,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM;CAIxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,GAAE,gBAAqB;IAI1C;;;;;;;;;OASG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE;IAoB/B,8SAA8S;IAC9S,KAAK,IAAI,QAAQ,GAAG,SAAS;IAO7B,OAAO,CAAC,UAAU;IA+DlB,uFAAuF;IACvF,cAAc,IAAI,MAAM,GAAG,SAAS;CAGrC"}