@cadenya/cadenya 0.135.0 → 1.0.1

package/dist/core/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/core/pagination.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,MAAM,OAAO,IAAI;IAEJ;IACA;IACQ;IAHnB,YACW,KAAU,EACV,UAA8B,EACtB,SAA+C;QAFvD,UAAK,GAAL,KAAK,CAAK;QACV,eAAU,GAAV,UAAU,CAAoB;QACtB,cAAS,GAAT,SAAS,CAAsC;IAC/D,CAAC;IAEJ,WAAW;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAoB,CAAC,CAAC;IACnD,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,IAAI,IAAI,GAAmB,IAAI,CAAC;QAChC,OAAO,IAAI,EAAE,CAAC;YACZ,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,CAAC;YAC1C,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;CACF","sourcesContent":["/** Cursor pagination. Pages are async-iterable across page boundaries. */\n\nexport class Page<T> implements AsyncIterable<T> {\n  constructor(\n    readonly items: T[],\n    readonly nextCursor: string | undefined,\n    private readonly fetchPage: (cursor: string) => Promise<Page<T>>,\n  ) {}\n\n  hasNextPage(): boolean {\n    return this.nextCursor !== undefined && this.nextCursor !== '';\n  }\n\n  async getNextPage(): Promise<Page<T> | null> {\n    if (!this.hasNextPage()) return null;\n    return this.fetchPage(this.nextCursor as string);\n  }\n\n  /** Iterate every item on every page, fetching lazily. */\n  async *[Symbol.asyncIterator](): AsyncIterator<T> {\n    let page: Page<T> | null = this;\n    while (page) {\n      for (const item of page.items) yield item;\n      page = await page.getNextPage();\n    }\n  }\n}\n"]}

package/dist/core/sse.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server-sent events over fetch. Parses the wire format incrementally from a
+ * ReadableStream — multi-line data, event names, comments, CRLF — with no
+ * dependencies. Each event's `data` is JSON-decoded to `T`.
+ */
+export interface ServerSentEvent<T> {
+    event: string | undefined;
+    data: T;
+    id: string | undefined;
+}
+export declare class Stream<T> implements AsyncIterable<T> {
+    private response;
+    private readonly signal?;
+    private readonly skipEvents;
+    private readonly reconnect?;
+    /**
+     * The resume checkpoint: seeded from the id this stream was resumed with,
+     * then updated by `id:` fields (persistent across events per the SSE
+     * spec). Pass it as `options.lastEventId` to resume after a disconnect.
+     */
+    lastEventId: string | undefined;
+    private releaseDeadline;
+    /** Server `retry:` hint (ms), used as the reconnection delay when set. */
+    private retryHintMs;
+    /** Stream-owned cancellation: close() trips it so backoff sleeps and
+     * in-flight reconnect handshakes settle immediately. */
+    private readonly closer;
+    private closed;
+    private consumed;
+    private activeReader;
+    constructor(response: Response, signal?: AbortSignal | undefined, resumedFrom?: string, skipEvents?: readonly string[], reconnect?: ((lastEventId: string | undefined, signal: AbortSignal) => Promise<Response>) | undefined);
+    /**
+     * Idempotent explicit close: cancels the underlying response body exactly
+     * once and detaches deadline state. Safe before iteration (an opened but
+     * never-iterated stream would otherwise hold its connection), during
+     * iteration from another control path, and after EOF.
+     */
+    close(): Promise<void>;
+    /** Iterate decoded event payloads. */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /** Iterate full events (name + id + decoded data). */
+    events(): AsyncGenerator<ServerSentEvent<T>>;
+}
+//# sourceMappingURL=sse.d.ts.map

package/dist/core/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/core/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC;IACR,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;CACxB;AAED,qBAAa,MAAM,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAmB9C,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAIxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAM3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IA7B7B;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,OAAO,CAAC,eAAe,CAA2B;IAClD,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAAqB;IACxC;4DACwD;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAsD;gBAGhE,QAAQ,EAAE,QAAQ,EACT,MAAM,CAAC,EAAE,WAAW,YAAA,EACrC,WAAW,CAAC,EAAE,MAAM,EAGH,UAAU,GAAE,SAAS,MAAM,EAAO,EAMlC,SAAS,CAAC,GAAE,CAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,QAAQ,CAAC,aAAA;IAMxB;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB5B,sCAAsC;IAC/B,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAMjD,sDAAsD;IAC/C,MAAM,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAoPpD"}

package/dist/core/sse.js

@@ -0,0 +1,350 @@
+/**
+ * Server-sent events over fetch. Parses the wire format incrementally from a
+ * ReadableStream — multi-line data, event names, comments, CRLF — with no
+ * dependencies. Each event's `data` is JSON-decoded to `T`.
+ */
+import { APIConnectionError, APIResponseError, APIUserAbortError } from './error.js';
+import { takeStreamCleanup } from './http.js';
+export class Stream {
+    response;
+    signal;
+    skipEvents;
+    reconnect;
+    /**
+     * The resume checkpoint: seeded from the id this stream was resumed with,
+     * then updated by `id:` fields (persistent across events per the SSE
+     * spec). Pass it as `options.lastEventId` to resume after a disconnect.
+     */
+    lastEventId;
+    releaseDeadline;
+    /** Server `retry:` hint (ms), used as the reconnection delay when set. */
+    retryHintMs;
+    /** Stream-owned cancellation: close() trips it so backoff sleeps and
+     * in-flight reconnect handshakes settle immediately. */
+    closer = new AbortController();
+    closed = false;
+    consumed = false;
+    activeReader;
+    constructor(response, signal, resumedFrom, 
+    // Transport-housekeeping event names (`event:` field) skipped without
+    // decoding; their `id:` fields still advance the resume checkpoint.
+    skipEvents = [], 
+    // Re-issues the request with the current resume checkpoint. When set,
+    // a MID-STREAM transport drop reconnects automatically (like the
+    // platform's EventSource): bounded attempts, backoff honoring the
+    // server's `retry:` hint, counter reset once events flow again. A clean
+    // EOF, an explicit close(), and a caller abort NEVER reconnect.
+    reconnect) {
+        this.response = response;
+        this.signal = signal;
+        this.skipEvents = skipEvents;
+        this.reconnect = reconnect;
+        this.lastEventId = resumedFrom;
+        this.releaseDeadline = takeStreamCleanup(response);
+    }
+    /**
+     * Idempotent explicit close: cancels the underlying response body exactly
+     * once and detaches deadline state. Safe before iteration (an opened but
+     * never-iterated stream would otherwise hold its connection), during
+     * iteration from another control path, and after EOF.
+     */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closer.abort();
+        if (this.activeReader) {
+            // The body is LOCKED to the active reader: body.cancel() would
+            // reject, silently doing nothing. Cancel the reader itself — the
+            // pending read() settles, the generator's finally runs the terminal
+            // cleanup (deadline release included), and the consumer unblocks.
+            try {
+                await this.activeReader.cancel();
+            }
+            catch {
+                // Reader already errored/released; the generator finally cleans up.
+            }
+            return;
+        }
+        // Pre-iteration close: no reader owns the body yet.
+        this.releaseDeadline?.();
+        try {
+            await this.response.body?.cancel();
+        }
+        catch {
+            // Already closed.
+        }
+    }
+    /** Iterate decoded event payloads. */
+    async *[Symbol.asyncIterator]() {
+        for await (const event of this.events()) {
+            yield event.data;
+        }
+    }
+    /** Iterate full events (name + id + decoded data). */
+    async *events() {
+        // One Stream wraps exactly one response body. The consumed transition
+        // is synchronous (before any await/getReader), so a competing second
+        // iterator — concurrent or after EOF/error — deterministically gets the
+        // stable SDK error instead of a raw locked-stream TypeError or a silent
+        // empty sequence. A closed-but-never-consumed stream still ends empty.
+        if (this.closed && !this.consumed)
+            return;
+        if (this.consumed) {
+            throw new Error('stream already consumed — reconnect with a new call passing { lastEventId: stream.lastEventId }');
+        }
+        this.consumed = true;
+        const firstBody = this.response.body;
+        if (!firstBody)
+            throw new Error('SSE response has no body');
+        // Connection-local: a reconnect swaps in a FRESH decoder, so a partial
+        // UTF-8 code point from the dead connection cannot corrupt the first
+        // resumed event.
+        let decoder = new TextDecoder();
+        let reader = firstBody.getReader();
+        this.activeReader = reader;
+        let buffer = '';
+        let dataLines = [];
+        let eventName;
+        // Consecutive failed reconnects; reset whenever a chunk arrives.
+        let reconnectAttempts = 0;
+        const MAX_RECONNECTS = 5;
+        // A mid-stream transport drop swaps in a fresh connection resumed from
+        // the checkpoint. Partial buffered lines from the dead connection are
+        // DISCARDED — the server re-sends everything after Last-Event-ID.
+        const tryReconnect = async () => {
+            while (this.reconnect && !this.closed && !this.signal?.aborted && reconnectAttempts < MAX_RECONNECTS) {
+                const delay = this.retryHintMs ?? Math.min(500 * 2 ** reconnectAttempts, 10_000);
+                reconnectAttempts++;
+                // Abortable sleep: BOTH the caller's signal and the stream's own
+                // closer wake it, and listeners are removed on every exit path so a
+                // long-lived flapping stream cannot accumulate them.
+                await new Promise((resolve) => {
+                    const finish = () => {
+                        clearTimeout(timer);
+                        this.signal?.removeEventListener('abort', finish);
+                        this.closer.signal.removeEventListener('abort', finish);
+                        resolve();
+                    };
+                    const timer = setTimeout(finish, delay);
+                    this.signal?.addEventListener('abort', finish);
+                    this.closer.signal.addEventListener('abort', finish);
+                });
+                if (this.closed || this.signal?.aborted)
+                    return false;
+                let next;
+                try {
+                    next = await this.reconnect(this.lastEventId, this.closer.signal);
+                }
+                catch (err) {
+                    if (this.closed)
+                        return false;
+                    // A TRANSPORT handshake failure (server restarting, connection
+                    // refused) consumes budget and retries; an HTTP-level failure
+                    // (e.g. expired credentials -> APIError) propagates immediately —
+                    // reconnecting cannot fix it and must not mask it.
+                    if (err instanceof APIConnectionError)
+                        continue;
+                    throw err;
+                }
+                if (this.closed) {
+                    void next.body?.cancel().catch(() => { });
+                    return false;
+                }
+                // Release the SUPERSEDED connection completely: cancel its reader
+                // (unlocking the old body) and its deadline cleanup, exactly once.
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // Dead reader.
+                }
+                reader.releaseLock();
+                this.releaseDeadline?.();
+                this.response = next;
+                this.releaseDeadline = takeStreamCleanup(next);
+                const nextBody = next.body;
+                if (!nextBody)
+                    throw new Error('SSE response has no body');
+                reader = nextBody.getReader();
+                this.activeReader = reader;
+                buffer = '';
+                dataLines = [];
+                eventName = undefined;
+                decoder = new TextDecoder();
+                return true;
+            }
+            return false;
+        };
+        const flush = () => {
+            if (dataLines.length === 0)
+                return undefined;
+            const raw = dataLines.join('\n');
+            dataLines = [];
+            const name = eventName;
+            eventName = undefined;
+            // Housekeeping frames (e.g. ping/open) never reach the consumer and
+            // never JSON-decode - but their id: has already advanced the resume
+            // checkpoint above.
+            if (name !== undefined && this.skipEvents.includes(name))
+                return undefined;
+            let data;
+            try {
+                data = JSON.parse(raw);
+            }
+            catch (err) {
+                // Malformed event JSON is a PROTOCOL error, distinct from transport
+                // failure.
+                throw new APIResponseError(this.response.status, 'SSE event data is not valid JSON', err);
+            }
+            // Per the SSE spec the last-event-ID buffer persists across events
+            // until another `id:` field changes it (an empty one resets it).
+            return { event: name, data, id: this.lastEventId };
+        };
+        // WHATWG event streams terminate lines with LF, CRLF, OR bare CR; a CR
+        // at a chunk boundary must wait for the next chunk to see whether an LF
+        // follows (CRLF is one terminator, never two).
+        const nextLine = (atEof) => {
+            for (let i = 0; i < buffer.length; i++) {
+                const ch = buffer[i];
+                if (ch === '\n') {
+                    const line = buffer.slice(0, i);
+                    buffer = buffer.slice(i + 1);
+                    return line;
+                }
+                if (ch === '\r') {
+                    if (i + 1 < buffer.length) {
+                        const line = buffer.slice(0, i);
+                        buffer = buffer.slice(buffer[i + 1] === '\n' ? i + 2 : i + 1);
+                        return line;
+                    }
+                    if (atEof) {
+                        const line = buffer.slice(0, i);
+                        buffer = '';
+                        return line;
+                    }
+                    return null; // possible CRLF split across chunks
+                }
+            }
+            return null;
+        };
+        const processLine = (line) => {
+            if (line === '')
+                return flush();
+            if (line.startsWith(':'))
+                return undefined; // comment / keep-alive
+            const colonAt = line.indexOf(':');
+            const field = colonAt === -1 ? line : line.slice(0, colonAt);
+            let value = colonAt === -1 ? '' : line.slice(colonAt + 1);
+            if (value.startsWith(' '))
+                value = value.slice(1);
+            switch (field) {
+                case 'data':
+                    dataLines.push(value);
+                    break;
+                case 'event':
+                    eventName = value;
+                    break;
+                case 'id':
+                    // Per the event-stream algorithm, ids containing U+0000 are
+                    // ignored entirely; an empty id resets the buffer.
+                    if (!value.includes('\0')) {
+                        this.lastEventId = value === '' ? undefined : value;
+                    }
+                    break;
+                case 'retry':
+                    // Reconnection-delay hint; honored when auto-reconnect is active.
+                    if (/^[0-9]+$/.test(value))
+                        this.retryHintMs = Math.min(Number(value), 60_000);
+                    break;
+            }
+            return undefined;
+        };
+        try {
+            while (true) {
+                if (this.signal?.aborted)
+                    throw new APIUserAbortError();
+                let done;
+                let value;
+                try {
+                    ({ done, value } = await reader.read());
+                }
+                catch (err) {
+                    // A user abort mid-read surfaces as a raw AbortError DOMException;
+                    // the public contract is APIUserAbortError regardless of when the
+                    // abort lands. Partial buffered events are NOT flushed. Any other
+                    // read failure is a transport failure — auto-reconnect resumes
+                    // from the checkpoint when configured; otherwise the public
+                    // contract is APIConnectionError before AND after response
+                    // headers, never a runtime-specific error shape.
+                    if (this.signal?.aborted)
+                        throw new APIUserAbortError();
+                    if (this.closed)
+                        break;
+                    if (await tryReconnect())
+                        continue;
+                    if (this.closed || this.signal?.aborted)
+                        break;
+                    throw new APIConnectionError(err);
+                }
+                // Re-check AFTER every awaited read: a chunk that arrives
+                // concurrently with close() must not be processed.
+                if (this.closed)
+                    break;
+                if (done)
+                    break;
+                // Bytes flowing again: the reconnect budget is per-outage.
+                reconnectAttempts = 0;
+                buffer += decoder.decode(value, { stream: true });
+                let line;
+                while ((line = nextLine(false)) !== null) {
+                    const event = processLine(line);
+                    if (event)
+                        yield event;
+                }
+            }
+            // The stream may end without a trailing newline: the leftover buffer
+            // is still line data and must be parsed, not dropped.
+            buffer += decoder.decode();
+            let tail;
+            while ((tail = nextLine(true)) !== null) {
+                const event = processLine(tail);
+                if (event)
+                    yield event;
+            }
+            if (buffer !== '') {
+                const event = processLine(buffer);
+                if (event)
+                    yield event;
+            }
+            // Spec-compliant servers end with a blank line, but flush a trailing
+            // event if the stream closed without one.
+            const last = flush();
+            if (last)
+                yield last;
+        }
+        finally {
+            // EVERY terminal path — EOF, decode error, transport error, caller
+            // abort, explicit close, early consumer return — releases the
+            // deadline listener and the body exactly once.
+            this.closed = true;
+            this.activeReader = undefined;
+            this.releaseDeadline?.();
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // Already cancelled/errored.
+            }
+            reader.releaseLock();
+            try {
+                // The CURRENT connection's body (reconnects swap this.response).
+                await this.response.body?.cancel();
+            }
+            catch {
+                // Already closed.
+            }
+        }
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/core/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/core/sse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-sent events over fetch. Parses the wire format incrementally from a\n * ReadableStream — multi-line data, event names, comments, CRLF — with no\n * dependencies. Each event's `data` is JSON-decoded to `T`.\n */\n\nimport { APIConnectionError, APIResponseError, APIUserAbortError } from './error.js';\nimport { takeStreamCleanup } from './http.js';\n\nexport interface ServerSentEvent<T> {\n  event: string | undefined;\n  data: T;\n  id: string | undefined;\n}\n\nexport class Stream<T> implements AsyncIterable<T> {\n  /**\n   * The resume checkpoint: seeded from the id this stream was resumed with,\n   * then updated by `id:` fields (persistent across events per the SSE\n   * spec). Pass it as `options.lastEventId` to resume after a disconnect.\n   */\n  lastEventId: string | undefined;\n\n  private releaseDeadline: (() => void) | undefined;\n  /** Server `retry:` hint (ms), used as the reconnection delay when set. */\n  private retryHintMs: number | undefined;\n  /** Stream-owned cancellation: close() trips it so backoff sleeps and\n   * in-flight reconnect handshakes settle immediately. */\n  private readonly closer = new AbortController();\n  private closed = false;\n  private consumed = false;\n  private activeReader: ReadableStreamDefaultReader<Uint8Array> | undefined;\n\n  constructor(\n    private response: Response,\n    private readonly signal?: AbortSignal,\n    resumedFrom?: string,\n    // Transport-housekeeping event names (`event:` field) skipped without\n    // decoding; their `id:` fields still advance the resume checkpoint.\n    private readonly skipEvents: readonly string[] = [],\n    // Re-issues the request with the current resume checkpoint. When set,\n    // a MID-STREAM transport drop reconnects automatically (like the\n    // platform's EventSource): bounded attempts, backoff honoring the\n    // server's `retry:` hint, counter reset once events flow again. A clean\n    // EOF, an explicit close(), and a caller abort NEVER reconnect.\n    private readonly reconnect?: (\n      lastEventId: string | undefined,\n      signal: AbortSignal,\n    ) => Promise<Response>,\n  ) {\n    this.lastEventId = resumedFrom;\n    this.releaseDeadline = takeStreamCleanup(response);\n  }\n\n  /**\n   * Idempotent explicit close: cancels the underlying response body exactly\n   * once and detaches deadline state. Safe before iteration (an opened but\n   * never-iterated stream would otherwise hold its connection), during\n   * iteration from another control path, and after EOF.\n   */\n  async close(): Promise<void> {\n    if (this.closed) return;\n    this.closed = true;\n    this.closer.abort();\n    if (this.activeReader) {\n      // The body is LOCKED to the active reader: body.cancel() would\n      // reject, silently doing nothing. Cancel the reader itself — the\n      // pending read() settles, the generator's finally runs the terminal\n      // cleanup (deadline release included), and the consumer unblocks.\n      try {\n        await this.activeReader.cancel();\n      } catch {\n        // Reader already errored/released; the generator finally cleans up.\n      }\n      return;\n    }\n    // Pre-iteration close: no reader owns the body yet.\n    this.releaseDeadline?.();\n    try {\n      await this.response.body?.cancel();\n    } catch {\n      // Already closed.\n    }\n  }\n\n  /** Iterate decoded event payloads. */\n  async *[Symbol.asyncIterator](): AsyncIterator<T> {\n    for await (const event of this.events()) {\n      yield event.data;\n    }\n  }\n\n  /** Iterate full events (name + id + decoded data). */\n  async *events(): AsyncGenerator<ServerSentEvent<T>> {\n    // One Stream wraps exactly one response body. The consumed transition\n    // is synchronous (before any await/getReader), so a competing second\n    // iterator — concurrent or after EOF/error — deterministically gets the\n    // stable SDK error instead of a raw locked-stream TypeError or a silent\n    // empty sequence. A closed-but-never-consumed stream still ends empty.\n    if (this.closed && !this.consumed) return;\n    if (this.consumed) {\n      throw new Error(\n        'stream already consumed — reconnect with a new call passing { lastEventId: stream.lastEventId }',\n      );\n    }\n    this.consumed = true;\n    const firstBody = this.response.body;\n    if (!firstBody) throw new Error('SSE response has no body');\n    // Connection-local: a reconnect swaps in a FRESH decoder, so a partial\n    // UTF-8 code point from the dead connection cannot corrupt the first\n    // resumed event.\n    let decoder = new TextDecoder();\n    let reader = firstBody.getReader();\n    this.activeReader = reader;\n    let buffer = '';\n    let dataLines: string[] = [];\n    let eventName: string | undefined;\n    // Consecutive failed reconnects; reset whenever a chunk arrives.\n    let reconnectAttempts = 0;\n    const MAX_RECONNECTS = 5;\n\n    // A mid-stream transport drop swaps in a fresh connection resumed from\n    // the checkpoint. Partial buffered lines from the dead connection are\n    // DISCARDED — the server re-sends everything after Last-Event-ID.\n    const tryReconnect = async (): Promise<boolean> => {\n      while (this.reconnect && !this.closed && !this.signal?.aborted && reconnectAttempts < MAX_RECONNECTS) {\n        const delay = this.retryHintMs ?? Math.min(500 * 2 ** reconnectAttempts, 10_000);\n        reconnectAttempts++;\n        // Abortable sleep: BOTH the caller's signal and the stream's own\n        // closer wake it, and listeners are removed on every exit path so a\n        // long-lived flapping stream cannot accumulate them.\n        await new Promise<void>((resolve) => {\n          const finish = () => {\n            clearTimeout(timer);\n            this.signal?.removeEventListener('abort', finish);\n            this.closer.signal.removeEventListener('abort', finish);\n            resolve();\n          };\n          const timer = setTimeout(finish, delay);\n          this.signal?.addEventListener('abort', finish);\n          this.closer.signal.addEventListener('abort', finish);\n        });\n        if (this.closed || this.signal?.aborted) return false;\n        let next: Response;\n        try {\n          next = await this.reconnect(this.lastEventId, this.closer.signal);\n        } catch (err) {\n          if (this.closed) return false;\n          // A TRANSPORT handshake failure (server restarting, connection\n          // refused) consumes budget and retries; an HTTP-level failure\n          // (e.g. expired credentials -> APIError) propagates immediately —\n          // reconnecting cannot fix it and must not mask it.\n          if (err instanceof APIConnectionError) continue;\n          throw err;\n        }\n        if (this.closed) {\n          void next.body?.cancel().catch(() => {});\n          return false;\n        }\n        // Release the SUPERSEDED connection completely: cancel its reader\n        // (unlocking the old body) and its deadline cleanup, exactly once.\n        try {\n          await reader.cancel();\n        } catch {\n          // Dead reader.\n        }\n        reader.releaseLock();\n        this.releaseDeadline?.();\n        this.response = next;\n        this.releaseDeadline = takeStreamCleanup(next);\n        const nextBody = next.body;\n        if (!nextBody) throw new Error('SSE response has no body');\n        reader = nextBody.getReader();\n        this.activeReader = reader;\n        buffer = '';\n        dataLines = [];\n        eventName = undefined;\n        decoder = new TextDecoder();\n        return true;\n      }\n      return false;\n    };\n\n    const flush = (): ServerSentEvent<T> | undefined => {\n      if (dataLines.length === 0) return undefined;\n      const raw = dataLines.join('\\n');\n      dataLines = [];\n      const name = eventName;\n      eventName = undefined;\n      // Housekeeping frames (e.g. ping/open) never reach the consumer and\n      // never JSON-decode - but their id: has already advanced the resume\n      // checkpoint above.\n      if (name !== undefined && this.skipEvents.includes(name)) return undefined;\n      let data: T;\n      try {\n        data = JSON.parse(raw) as T;\n      } catch (err) {\n        // Malformed event JSON is a PROTOCOL error, distinct from transport\n        // failure.\n        throw new APIResponseError(this.response.status, 'SSE event data is not valid JSON', err);\n      }\n      // Per the SSE spec the last-event-ID buffer persists across events\n      // until another `id:` field changes it (an empty one resets it).\n      return { event: name, data, id: this.lastEventId };\n    };\n\n    // WHATWG event streams terminate lines with LF, CRLF, OR bare CR; a CR\n    // at a chunk boundary must wait for the next chunk to see whether an LF\n    // follows (CRLF is one terminator, never two).\n    const nextLine = (atEof: boolean): string | null => {\n      for (let i = 0; i < buffer.length; i++) {\n        const ch = buffer[i];\n        if (ch === '\\n') {\n          const line = buffer.slice(0, i);\n          buffer = buffer.slice(i + 1);\n          return line;\n        }\n        if (ch === '\\r') {\n          if (i + 1 < buffer.length) {\n            const line = buffer.slice(0, i);\n            buffer = buffer.slice(buffer[i + 1] === '\\n' ? i + 2 : i + 1);\n            return line;\n          }\n          if (atEof) {\n            const line = buffer.slice(0, i);\n            buffer = '';\n            return line;\n          }\n          return null; // possible CRLF split across chunks\n        }\n      }\n      return null;\n    };\n\n    const processLine = (line: string): ServerSentEvent<T> | undefined => {\n      if (line === '') return flush();\n      if (line.startsWith(':')) return undefined; // comment / keep-alive\n\n      const colonAt = line.indexOf(':');\n      const field = colonAt === -1 ? line : line.slice(0, colonAt);\n      let value = colonAt === -1 ? '' : line.slice(colonAt + 1);\n      if (value.startsWith(' ')) value = value.slice(1);\n\n      switch (field) {\n        case 'data':\n          dataLines.push(value);\n          break;\n        case 'event':\n          eventName = value;\n          break;\n        case 'id':\n          // Per the event-stream algorithm, ids containing U+0000 are\n          // ignored entirely; an empty id resets the buffer.\n          if (!value.includes('\\0')) {\n            this.lastEventId = value === '' ? undefined : value;\n          }\n          break;\n        case 'retry':\n          // Reconnection-delay hint; honored when auto-reconnect is active.\n          if (/^[0-9]+$/.test(value)) this.retryHintMs = Math.min(Number(value), 60_000);\n          break;\n      }\n      return undefined;\n    };\n\n    try {\n      while (true) {\n        if (this.signal?.aborted) throw new APIUserAbortError();\n        let done: boolean;\n        let value: Uint8Array | undefined;\n        try {\n          ({ done, value } = await reader.read());\n        } catch (err) {\n          // A user abort mid-read surfaces as a raw AbortError DOMException;\n          // the public contract is APIUserAbortError regardless of when the\n          // abort lands. Partial buffered events are NOT flushed. Any other\n          // read failure is a transport failure — auto-reconnect resumes\n          // from the checkpoint when configured; otherwise the public\n          // contract is APIConnectionError before AND after response\n          // headers, never a runtime-specific error shape.\n          if (this.signal?.aborted) throw new APIUserAbortError();\n          if (this.closed) break;\n          if (await tryReconnect()) continue;\n          if (this.closed || this.signal?.aborted) break;\n          throw new APIConnectionError(err);\n        }\n        // Re-check AFTER every awaited read: a chunk that arrives\n        // concurrently with close() must not be processed.\n        if (this.closed) break;\n        if (done) break;\n        // Bytes flowing again: the reconnect budget is per-outage.\n        reconnectAttempts = 0;\n        buffer += decoder.decode(value, { stream: true });\n\n        let line: string | null;\n        while ((line = nextLine(false)) !== null) {\n          const event = processLine(line);\n          if (event) yield event;\n        }\n      }\n      // The stream may end without a trailing newline: the leftover buffer\n      // is still line data and must be parsed, not dropped.\n      buffer += decoder.decode();\n      let tail: string | null;\n      while ((tail = nextLine(true)) !== null) {\n        const event = processLine(tail);\n        if (event) yield event;\n      }\n      if (buffer !== '') {\n        const event = processLine(buffer);\n        if (event) yield event;\n      }\n      // Spec-compliant servers end with a blank line, but flush a trailing\n      // event if the stream closed without one.\n      const last = flush();\n      if (last) yield last;\n    } finally {\n      // EVERY terminal path — EOF, decode error, transport error, caller\n      // abort, explicit close, early consumer return — releases the\n      // deadline listener and the body exactly once.\n      this.closed = true;\n      this.activeReader = undefined;\n      this.releaseDeadline?.();\n      try {\n        await reader.cancel();\n      } catch {\n        // Already cancelled/errored.\n      }\n      reader.releaseLock();\n      try {\n        // The CURRENT connection's body (reconnects swap this.response).\n        await this.response.body?.cancel();\n      } catch {\n        // Already closed.\n      }\n    }\n  }\n}\n"]}

package/dist/core/webhooks.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Standard Webhooks verification (https://www.standardwebhooks.com), built on
+ * WebCrypto — no dependencies. The signature is HMAC-SHA256 over
+ * `${id}.${timestamp}.${payload}` keyed by the base64-decoded secret
+ * (`whsec_` prefix optional); `webhook-signature` may carry several
+ * space-separated `v1,<base64>` candidates.
+ */
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+export interface WebhookVerifyOptions {
+    /** Max allowed clock skew for webhook-timestamp, in seconds. Default 300. */
+    toleranceSeconds?: number;
+}
+/** Plain header records and Fetch-style Headers objects are both accepted. */
+export type WebhookHeaders = Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+};
+export declare class WebhookVerifier {
+    private readonly key;
+    constructor(secret: string);
+    /** Throws WebhookVerificationError unless the payload is authentic. */
+    verify(payload: string, headers: WebhookHeaders, options?: WebhookVerifyOptions): Promise<void>;
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/core/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/core/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,MAAM,cAAc,GACtB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC7C;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEzC,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;gBAE7B,MAAM,EAAE,MAAM;IA+B1B,uEAAuE;IACjE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;CA0C1G"}

package/dist/core/webhooks.js

@@ -0,0 +1,124 @@
+/**
+ * Standard Webhooks verification (https://www.standardwebhooks.com), built on
+ * WebCrypto — no dependencies. The signature is HMAC-SHA256 over
+ * `${id}.${timestamp}.${payload}` keyed by the base64-decoded secret
+ * (`whsec_` prefix optional); `webhook-signature` may carry several
+ * space-separated `v1,<base64>` candidates.
+ */
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebhookVerificationError';
+    }
+}
+export class WebhookVerifier {
+    key;
+    constructor(secret) {
+        if (!secret?.trim()) {
+            throw new WebhookVerificationError('webhook secret must be a non-empty string');
+        }
+        const encoded = secret.startsWith('whsec_') ? secret.slice('whsec_'.length) : secret;
+        // atob is forgiving (whitespace, missing padding); require the canonical
+        // form so every SDK accepts exactly the same secrets.
+        if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
+            throw new WebhookVerificationError('webhook secret is not valid base64');
+        }
+        const raw = (() => {
+            try {
+                return base64ToBytes(encoded);
+            }
+            catch {
+                throw new WebhookVerificationError('webhook secret is not valid base64');
+            }
+        })();
+        // Standard Webhooks symmetric keys are 24–64 bytes. A shorter key —
+        // especially the zero-byte key from a bare "whsec_" — must never verify.
+        if (raw.length < 24 || raw.length > 64) {
+            throw new WebhookVerificationError(`decoded webhook secret must be 24-64 bytes, got ${raw.length}`);
+        }
+        this.key = crypto.subtle
+            .importKey('raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+            .catch(() => {
+            throw new WebhookVerificationError('webhook secret could not be imported as an HMAC key');
+        });
+    }
+    /** Throws WebhookVerificationError unless the payload is authentic. */
+    async verify(payload, headers, options = {}) {
+        const header = normalizeHeaders(headers);
+        const id = header['webhook-id'];
+        const timestamp = header['webhook-timestamp'];
+        const signatures = header['webhook-signature'];
+        if (!id || !timestamp || !signatures) {
+            throw new WebhookVerificationError('missing webhook-id, webhook-timestamp, or webhook-signature header');
+        }
+        const tolerance = options.toleranceSeconds ?? 300;
+        if (!Number.isFinite(tolerance) || tolerance < 0) {
+            // An infinite tolerance would disable the replay window entirely.
+            throw new WebhookVerificationError('toleranceSeconds must be a finite non-negative number');
+        }
+        // The spec calls webhook-timestamp an integer Unix timestamp; Number()'s
+        // broader grammar would disagree with the other SDKs on the same input.
+        if (!/^[0-9]+$/.test(timestamp)) {
+            throw new WebhookVerificationError('webhook-timestamp is not an integer');
+        }
+        const sent = Number(timestamp);
+        if (!Number.isSafeInteger(sent)) {
+            throw new WebhookVerificationError('webhook-timestamp is out of range');
+        }
+        const now = Math.floor(Date.now() / 1000);
+        if (Math.abs(now - sent) > tolerance) {
+            throw new WebhookVerificationError('webhook-timestamp outside tolerance');
+        }
+        const key = await this.key;
+        const data = new TextEncoder().encode(`${id}.${timestamp}.${payload}`);
+        const expected = new Uint8Array(await crypto.subtle.sign('HMAC', key, data));
+        for (const candidate of signatures.split(' ')) {
+            const [version, signature] = candidate.split(',', 2);
+            if (version !== 'v1' || !signature)
+                continue;
+            const provided = tryBase64ToBytes(signature);
+            if (provided && constantTimeEqual(provided, expected))
+                return;
+        }
+        throw new WebhookVerificationError('no matching v1 signature');
+    }
+}
+function normalizeHeaders(headers) {
+    const out = {};
+    if (typeof headers.get === 'function') {
+        // Fetch-style Headers: Object.entries would not see its values.
+        const getter = headers;
+        for (const name of ['webhook-id', 'webhook-timestamp', 'webhook-signature']) {
+            out[name] = getter.get(name) ?? undefined;
+        }
+        return out;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        out[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+    }
+    return out;
+}
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function tryBase64ToBytes(b64) {
+    try {
+        return base64ToBytes(b64);
+    }
+    catch {
+        return undefined;
+    }
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/core/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/core/webhooks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Standard Webhooks verification (https://www.standardwebhooks.com), built on\n * WebCrypto — no dependencies. The signature is HMAC-SHA256 over\n * `${id}.${timestamp}.${payload}` keyed by the base64-decoded secret\n * (`whsec_` prefix optional); `webhook-signature` may carry several\n * space-separated `v1,<base64>` candidates.\n */\n\nexport class WebhookVerificationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'WebhookVerificationError';\n  }\n}\n\nexport interface WebhookVerifyOptions {\n  /** Max allowed clock skew for webhook-timestamp, in seconds. Default 300. */\n  toleranceSeconds?: number;\n}\n\n/** Plain header records and Fetch-style Headers objects are both accepted. */\nexport type WebhookHeaders =\n  | Record<string, string | string[] | undefined>\n  | { get(name: string): string | null };\n\nexport class WebhookVerifier {\n  private readonly key: Promise<CryptoKey>;\n\n  constructor(secret: string) {\n    if (!secret?.trim()) {\n      throw new WebhookVerificationError('webhook secret must be a non-empty string');\n    }\n    const encoded = secret.startsWith('whsec_') ? secret.slice('whsec_'.length) : secret;\n    // atob is forgiving (whitespace, missing padding); require the canonical\n    // form so every SDK accepts exactly the same secrets.\n    if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {\n      throw new WebhookVerificationError('webhook secret is not valid base64');\n    }\n    const raw = (() => {\n      try {\n        return base64ToBytes(encoded);\n      } catch {\n        throw new WebhookVerificationError('webhook secret is not valid base64');\n      }\n    })();\n    // Standard Webhooks symmetric keys are 24–64 bytes. A shorter key —\n    // especially the zero-byte key from a bare \"whsec_\" — must never verify.\n    if (raw.length < 24 || raw.length > 64) {\n      throw new WebhookVerificationError(\n        `decoded webhook secret must be 24-64 bytes, got ${raw.length}`,\n      );\n    }\n    this.key = crypto.subtle\n      .importKey('raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])\n      .catch(() => {\n        throw new WebhookVerificationError('webhook secret could not be imported as an HMAC key');\n      });\n  }\n\n  /** Throws WebhookVerificationError unless the payload is authentic. */\n  async verify(payload: string, headers: WebhookHeaders, options: WebhookVerifyOptions = {}): Promise<void> {\n    const header = normalizeHeaders(headers);\n    const id = header['webhook-id'];\n    const timestamp = header['webhook-timestamp'];\n    const signatures = header['webhook-signature'];\n    if (!id || !timestamp || !signatures) {\n      throw new WebhookVerificationError(\n        'missing webhook-id, webhook-timestamp, or webhook-signature header',\n      );\n    }\n\n    const tolerance = options.toleranceSeconds ?? 300;\n    if (!Number.isFinite(tolerance) || tolerance < 0) {\n      // An infinite tolerance would disable the replay window entirely.\n      throw new WebhookVerificationError('toleranceSeconds must be a finite non-negative number');\n    }\n    // The spec calls webhook-timestamp an integer Unix timestamp; Number()'s\n    // broader grammar would disagree with the other SDKs on the same input.\n    if (!/^[0-9]+$/.test(timestamp)) {\n      throw new WebhookVerificationError('webhook-timestamp is not an integer');\n    }\n    const sent = Number(timestamp);\n    if (!Number.isSafeInteger(sent)) {\n      throw new WebhookVerificationError('webhook-timestamp is out of range');\n    }\n    const now = Math.floor(Date.now() / 1000);\n    if (Math.abs(now - sent) > tolerance) {\n      throw new WebhookVerificationError('webhook-timestamp outside tolerance');\n    }\n\n    const key = await this.key;\n    const data = new TextEncoder().encode(`${id}.${timestamp}.${payload}`);\n    const expected = new Uint8Array(await crypto.subtle.sign('HMAC', key, data));\n\n    for (const candidate of signatures.split(' ')) {\n      const [version, signature] = candidate.split(',', 2);\n      if (version !== 'v1' || !signature) continue;\n      const provided = tryBase64ToBytes(signature);\n      if (provided && constantTimeEqual(provided, expected)) return;\n    }\n    throw new WebhookVerificationError('no matching v1 signature');\n  }\n}\n\nfunction normalizeHeaders(headers: WebhookHeaders): Record<string, string | undefined> {\n  const out: Record<string, string | undefined> = {};\n  if (typeof (headers as { get?: unknown }).get === 'function') {\n    // Fetch-style Headers: Object.entries would not see its values.\n    const getter = headers as { get(name: string): string | null };\n    for (const name of ['webhook-id', 'webhook-timestamp', 'webhook-signature']) {\n      out[name] = getter.get(name) ?? undefined;\n    }\n    return out;\n  }\n  for (const [key, value] of Object.entries(headers)) {\n    out[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;\n  }\n  return out;\n}\n\nfunction base64ToBytes(b64: string) {\n  const binary = atob(b64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);\n  return bytes;\n}\n\nfunction tryBase64ToBytes(b64: string) {\n  try {\n    return base64ToBytes(b64);\n  } catch {\n    return undefined;\n  }\n}\n\nfunction constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];\n  return diff === 0;\n}\n"]}