@sparkletree/core 0.1.0

package/dist/publishableKey.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The publishable key: `st_pk_<env>_<base64url(JSON { organizationId, apiBase })>`.
+ *
+ * It is NOT a credential — it is an ADDRESS, and the docs must say so in the
+ * same paragraph that introduces it. It is decoded locally, with zero network,
+ * and collapses the two required provider props into one dashboard
+ * copy-paste. The read path is unauthenticated BY DESIGN; security lives in
+ * the origin registry (minting requires a verified origin registered to the
+ * paying org). We ship the key because one string is better onboarding than
+ * two, not because it protects anything. `organizationId` and `apiBase`
+ * remain as explicit props for self-hosted bases and stay the documented
+ * escape hatch — when both are given, the explicit props win.
+ *
+ * Because the key is unsigned, an apiBase that arrives VIA a key is an
+ * unproven address: anyone can hand-encode a key pointing at their own host.
+ * Content fetches may follow it (they carry identity hashes, not secrets),
+ * but the signed mint token — a real spend credential — may not: the mint
+ * POST fires only for an explicit, first-party (*.sparkletree.io), or
+ * loopback apiBase (security review S-2; see isFirstPartyApiBase/maybeMint).
+ */
+export interface PublishableKeyPayload {
+    organizationId: string;
+    apiBase: string;
+}
+export type PublishableKeyEnv = "live" | "test";
+/**
+ * Decode a publishable key. Throws TypeError on anything malformed — a bad
+ * key is a configuration error at integration time, not a runtime condition
+ * to degrade around.
+ */
+export declare function decodePublishableKey(key: string): PublishableKeyPayload;
+/** Encode a publishable key. Dashboard-side counterpart of decode. */
+export declare function encodePublishableKey(options: {
+    organizationId: string;
+    apiBase: string;
+    env: PublishableKeyEnv;
+}): string;
+//# sourceMappingURL=publishableKey.d.ts.map

package/dist/publishableKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishableKey.d.ts","sourceRoot":"","sources":["../src/publishableKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAkBhD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAqBvE;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,iBAAiB,CAAC;CACxB,GAAG,MAAM,CAMT"}

package/dist/publishableKey.js

@@ -0,0 +1,69 @@
+/**
+ * The publishable key: `st_pk_<env>_<base64url(JSON { organizationId, apiBase })>`.
+ *
+ * It is NOT a credential — it is an ADDRESS, and the docs must say so in the
+ * same paragraph that introduces it. It is decoded locally, with zero network,
+ * and collapses the two required provider props into one dashboard
+ * copy-paste. The read path is unauthenticated BY DESIGN; security lives in
+ * the origin registry (minting requires a verified origin registered to the
+ * paying org). We ship the key because one string is better onboarding than
+ * two, not because it protects anything. `organizationId` and `apiBase`
+ * remain as explicit props for self-hosted bases and stay the documented
+ * escape hatch — when both are given, the explicit props win.
+ *
+ * Because the key is unsigned, an apiBase that arrives VIA a key is an
+ * unproven address: anyone can hand-encode a key pointing at their own host.
+ * Content fetches may follow it (they carry identity hashes, not secrets),
+ * but the signed mint token — a real spend credential — may not: the mint
+ * POST fires only for an explicit, first-party (*.sparkletree.io), or
+ * loopback apiBase (security review S-2; see isFirstPartyApiBase/maybeMint).
+ */
+const KEY_PATTERN = /^st_pk_(live|test)_([A-Za-z0-9_-]+)$/;
+function toBase64Url(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(encoded) {
+    const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+/**
+ * Decode a publishable key. Throws TypeError on anything malformed — a bad
+ * key is a configuration error at integration time, not a runtime condition
+ * to degrade around.
+ */
+export function decodePublishableKey(key) {
+    const match = typeof key === "string" ? KEY_PATTERN.exec(key) : null;
+    if (!match) {
+        throw new TypeError('SparkleTree: malformed publishable key — expected "st_pk_live_…" or "st_pk_test_…" copied from the dashboard.');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(fromBase64Url(match[2]));
+    }
+    catch {
+        throw new TypeError("SparkleTree: publishable key payload is not decodable JSON.");
+    }
+    const { organizationId, apiBase } = (payload ?? {});
+    if (typeof organizationId !== "string" || organizationId === "") {
+        throw new TypeError("SparkleTree: publishable key is missing organizationId.");
+    }
+    if (typeof apiBase !== "string" || apiBase === "") {
+        throw new TypeError("SparkleTree: publishable key is missing apiBase.");
+    }
+    return { organizationId, apiBase };
+}
+/** Encode a publishable key. Dashboard-side counterpart of decode. */
+export function encodePublishableKey(options) {
+    const payload = JSON.stringify({
+        organizationId: options.organizationId,
+        apiBase: options.apiBase,
+    });
+    return `st_pk_${options.env}_${toBase64Url(payload)}`;
+}
+//# sourceMappingURL=publishableKey.js.map

package/dist/publishableKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishableKey.js","sourceRoot":"","sources":["../src/publishableKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAE3D,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,SAAS,CACjB,+GAA+G,CAChH,CAAC;IACJ,CAAC;IACD,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAmC,CAAC;IACtF,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,EAAE,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;AACrC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,oBAAoB,CAAC,OAIpC;IACC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,OAAO,SAAS,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/safeUrl.d.ts

@@ -0,0 +1,56 @@
+/**
+ * URL hygiene for values that cross the wire into a customer's page.
+ *
+ * Both helpers exist because the SDK runs INSIDE the customer's origin:
+ * anything the server sends is rendered with the customer's privileges, so a
+ * value we would never type ourselves must be refused here rather than
+ * escaped downstream. Refusal is silent — never a throw, never a console
+ * line — because the failure mode this package optimises for is "the
+ * creative quietly stops adapting", not "the customer's console fills up".
+ */
+/**
+ * Vet a server-supplied action URL before it reaches an `<a href>`.
+ *
+ * Allowed through unchanged:
+ *   - absolute `https:`, `http:`, `mailto:`, `tel:` URLs;
+ *   - relative references — `/…`, `./…`, `#…`, `?…` — which resolve against
+ *     the customer's own origin; plus protocol-relative `//…`, which keeps
+ *     the page's scheme and is no worse than the absolute `https:` URLs we
+ *     already allow (both can point at any host).
+ *
+ * Anything else returns `undefined`: `javascript:`/`data:`/`vbscript:`
+ * outright, but also bare strings with no scheme and no relative prefix —
+ * we cannot prove where they point, and a CTA with no destination degrades
+ * to a plain button, which is the honest outcome.
+ *
+ * The input is trimmed first because browsers strip leading ASCII whitespace
+ * from `href` before parsing — without that, `" javascript:…"` would sneak a
+ * scheme past a prefix check that the browser would then honour.
+ */
+export declare function safeActionUrl(url: string | undefined): string | undefined;
+/**
+ * Is this apiBase allowed to carry SDK traffic?
+ *
+ * Production traffic is `https:` only — an `http:` apiBase sends campaign
+ * configuration and context over a channel any middlebox can rewrite, which
+ * is S-4 with extra steps. The one exception is loopback
+ * (`http://localhost`, `http://127.0.0.1`, any port), because local
+ * development against a dev edge is a real and legitimate setup.
+ */
+export declare function isSecureApiBase(apiBase: string): boolean;
+/**
+ * Is this apiBase first-party — the hosted SparkleTree edge, or loopback?
+ *
+ * The publishable key is an unsigned address ANYONE can hand-encode (see
+ * publishableKey.ts), so an apiBase that arrived via a key proves nothing
+ * about who chose it. The one value that must never follow an unproven
+ * address is the signed mint token: it is a real spend credential, and a
+ * doctored key pointing at an attacker host would receive it on the mint
+ * POST and replay it against the real API for its TTL (security review
+ * S-2). The mint therefore fires only when the apiBase is explicit (the
+ * developer's own prop — their choice to make), first-party, or loopback.
+ * Self-hosted bases are exactly what the explicit `apiBase` escape hatch is
+ * for; a self-made key carrying a third-party host gets content but no mint.
+ */
+export declare function isFirstPartyApiBase(apiBase: string): boolean;
+//# sourceMappingURL=safeUrl.d.ts.map

package/dist/safeUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeUrl.d.ts","sourceRoot":"","sources":["../src/safeUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAyBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CASxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAY5D"}

package/dist/safeUrl.js

@@ -0,0 +1,117 @@
+/**
+ * URL hygiene for values that cross the wire into a customer's page.
+ *
+ * Both helpers exist because the SDK runs INSIDE the customer's origin:
+ * anything the server sends is rendered with the customer's privileges, so a
+ * value we would never type ourselves must be refused here rather than
+ * escaped downstream. Refusal is silent — never a throw, never a console
+ * line — because the failure mode this package optimises for is "the
+ * creative quietly stops adapting", not "the customer's console fills up".
+ */
+/**
+ * Schemes a CTA href may carry. `https`/`http` are links; `mailto`/`tel` are
+ * the other two things a button legitimately does. Everything else —
+ * `javascript:`, `data:`, `vbscript:` — is click-XSS in the customer's origin
+ * the moment a consumer renders `ctaAction` as `<a href>`.
+ */
+const ALLOWED_ACTION_SCHEMES = new Set(["https:", "http:", "mailto:", "tel:"]);
+/** A scheme per RFC 3986: ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) ":". */
+const SCHEME_PREFIX = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+/**
+ * Sniffing base for `new URL`. Only the SCHEME is read off the result — never
+ * the resolved href — so the dummy origin can never leak into returned values.
+ */
+const SNIFF_BASE = "https://url.sparkletree.invalid";
+/**
+ * Vet a server-supplied action URL before it reaches an `<a href>`.
+ *
+ * Allowed through unchanged:
+ *   - absolute `https:`, `http:`, `mailto:`, `tel:` URLs;
+ *   - relative references — `/…`, `./…`, `#…`, `?…` — which resolve against
+ *     the customer's own origin; plus protocol-relative `//…`, which keeps
+ *     the page's scheme and is no worse than the absolute `https:` URLs we
+ *     already allow (both can point at any host).
+ *
+ * Anything else returns `undefined`: `javascript:`/`data:`/`vbscript:`
+ * outright, but also bare strings with no scheme and no relative prefix —
+ * we cannot prove where they point, and a CTA with no destination degrades
+ * to a plain button, which is the honest outcome.
+ *
+ * The input is trimmed first because browsers strip leading ASCII whitespace
+ * from `href` before parsing — without that, `" javascript:…"` would sneak a
+ * scheme past a prefix check that the browser would then honour.
+ */
+export function safeActionUrl(url) {
+    if (!url)
+        return undefined;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("/") ||
+        trimmed.startsWith("./") ||
+        trimmed.startsWith("#") ||
+        trimmed.startsWith("?")) {
+        return trimmed;
+    }
+    // No scheme and no relative prefix: unprovable, so refused. (This also
+    // catches whitespace-obfuscated schemes like "java\tscript:" — the tab is
+    // not a scheme character, so the string simply has no scheme here.)
+    if (!SCHEME_PREFIX.test(trimmed))
+        return undefined;
+    try {
+        const scheme = new URL(trimmed, SNIFF_BASE).protocol;
+        return ALLOWED_ACTION_SCHEMES.has(scheme) ? trimmed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is this apiBase allowed to carry SDK traffic?
+ *
+ * Production traffic is `https:` only — an `http:` apiBase sends campaign
+ * configuration and context over a channel any middlebox can rewrite, which
+ * is S-4 with extra steps. The one exception is loopback
+ * (`http://localhost`, `http://127.0.0.1`, any port), because local
+ * development against a dev edge is a real and legitimate setup.
+ */
+export function isSecureApiBase(apiBase) {
+    try {
+        const url = new URL(apiBase);
+        if (url.protocol === "https:")
+            return true;
+        if (url.protocol !== "http:")
+            return false;
+        return url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is this apiBase first-party — the hosted SparkleTree edge, or loopback?
+ *
+ * The publishable key is an unsigned address ANYONE can hand-encode (see
+ * publishableKey.ts), so an apiBase that arrived via a key proves nothing
+ * about who chose it. The one value that must never follow an unproven
+ * address is the signed mint token: it is a real spend credential, and a
+ * doctored key pointing at an attacker host would receive it on the mint
+ * POST and replay it against the real API for its TTL (security review
+ * S-2). The mint therefore fires only when the apiBase is explicit (the
+ * developer's own prop — their choice to make), first-party, or loopback.
+ * Self-hosted bases are exactly what the explicit `apiBase` escape hatch is
+ * for; a self-made key carrying a third-party host gets content but no mint.
+ */
+export function isFirstPartyApiBase(apiBase) {
+    try {
+        const { hostname } = new URL(apiBase);
+        return (hostname === "sparkletree.io" ||
+            hostname.endsWith(".sparkletree.io") ||
+            hostname === "localhost" ||
+            hostname === "127.0.0.1");
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=safeUrl.js.map

package/dist/safeUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeUrl.js","sourceRoot":"","sources":["../src/safeUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAE/E,6EAA6E;AAC7E,MAAM,aAAa,GAAG,2BAA2B,CAAC;AAElD;;;GAGG;AACH,MAAM,UAAU,GAAG,iCAAiC,CAAC;AAErD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,GAAuB;IACnD,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,IACE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QACvB,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QACxB,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QACvB,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EACvB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,uEAAuE;IACvE,0EAA0E;IAC1E,oEAAoE;IACpE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;QACrD,OAAO,sBAAsB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3C,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3C,OAAO,GAAG,CAAC,QAAQ,KAAK,WAAW,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO,CACL,QAAQ,KAAK,gBAAgB;YAC7B,QAAQ,CAAC,QAAQ,CAAC,iBAAiB,CAAC;YACpC,QAAQ,KAAK,WAAW;YACxB,QAAQ,KAAK,WAAW,CACzB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/sse.d.ts

@@ -0,0 +1,51 @@
+/**
+ * SSE parsing.
+ *
+ * Deliberately NOT `EventSource`, for three reasons that each cost real
+ * behaviour:
+ *
+ *   1. EventSource cannot set request headers, so it cannot send
+ *      `st-protocol` — negotiation would be query-param-only forever.
+ *   2. EventSource reconnects automatically and silently. On a stream that
+ *      ends in `error` that means retrying a request the server already
+ *      answered definitively, repeatedly, from inside a customer's page.
+ *   3. EventSource cannot read response headers, so the client could never
+ *      see which protocol version it actually got.
+ *
+ * fetch + a manual parser gives all three back. The cost is ~80 lines, which
+ * is a good trade for not having a background reconnect loop we do not
+ * control.
+ */
+export interface SseMessage {
+    /** `event:` name. Unnamed messages arrive as "message", per the spec. */
+    event: string;
+    /** `data:` payload, lines joined with "\n". */
+    data: string;
+}
+/**
+ * Incremental SSE frame parser. Feed it decoded text; it yields complete
+ * messages. Holds partial frames across chunk boundaries — a `data:` line
+ * split mid-UTF-8-sequence or mid-JSON is the normal case on a real network,
+ * not an edge case.
+ */
+export declare class SseParser {
+    private buffer;
+    /** Feed a chunk of decoded text; returns every message it completed. */
+    push(chunk: string): SseMessage[];
+    /** Flush a trailing frame that never got its blank line (server closed). */
+    flush(): SseMessage[];
+}
+export interface ReadSseOptions {
+    signal?: AbortSignal;
+    /** Called for every complete message, in order. */
+    onMessage: (message: SseMessage) => void;
+}
+/**
+ * Drain a fetch Response body as SSE.
+ *
+ * Returns when the server closes the stream. Aborting via `signal` resolves
+ * rather than throwing: a component unmounting mid-stream is the normal way
+ * these end, not an error worth surfacing in a customer's console.
+ */
+export declare function readSseStream(response: Response, options: ReadSseOptions): Promise<void>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAM;IAEpB,wEAAwE;IACxE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE;IAmBjC,4EAA4E;IAC5E,KAAK,IAAI,UAAU,EAAE;CAOtB;AAwBD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mDAAmD;IACnD,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAgDf"}

package/dist/sse.js

@@ -0,0 +1,137 @@
+/**
+ * SSE parsing.
+ *
+ * Deliberately NOT `EventSource`, for three reasons that each cost real
+ * behaviour:
+ *
+ *   1. EventSource cannot set request headers, so it cannot send
+ *      `st-protocol` — negotiation would be query-param-only forever.
+ *   2. EventSource reconnects automatically and silently. On a stream that
+ *      ends in `error` that means retrying a request the server already
+ *      answered definitively, repeatedly, from inside a customer's page.
+ *   3. EventSource cannot read response headers, so the client could never
+ *      see which protocol version it actually got.
+ *
+ * fetch + a manual parser gives all three back. The cost is ~80 lines, which
+ * is a good trade for not having a background reconnect loop we do not
+ * control.
+ */
+/**
+ * Incremental SSE frame parser. Feed it decoded text; it yields complete
+ * messages. Holds partial frames across chunk boundaries — a `data:` line
+ * split mid-UTF-8-sequence or mid-JSON is the normal case on a real network,
+ * not an edge case.
+ */
+export class SseParser {
+    buffer = "";
+    /** Feed a chunk of decoded text; returns every message it completed. */
+    push(chunk) {
+        this.buffer += chunk;
+        const messages = [];
+        // Frames are separated by a blank line. Normalise CRLF first so a proxy
+        // that rewrites line endings does not silently stop the stream.
+        const normalised = this.buffer.replace(/\r\n/g, "\n");
+        const frames = normalised.split("\n\n");
+        // The last element is either "" (buffer ended on a separator) or a
+        // partial frame. Either way it stays buffered.
+        this.buffer = frames.pop() ?? "";
+        for (const frame of frames) {
+            const message = parseFrame(frame);
+            if (message)
+                messages.push(message);
+        }
+        return messages;
+    }
+    /** Flush a trailing frame that never got its blank line (server closed). */
+    flush() {
+        const remaining = this.buffer.trim();
+        this.buffer = "";
+        if (!remaining)
+            return [];
+        const message = parseFrame(remaining);
+        return message ? [message] : [];
+    }
+}
+function parseFrame(frame) {
+    let event = "message";
+    const data = [];
+    for (const line of frame.split("\n")) {
+        if (!line || line.startsWith(":"))
+            continue; // comment / keep-alive
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        // Exactly one optional leading space is stripped, per the SSE spec.
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "event")
+            event = value;
+        else if (field === "data")
+            data.push(value);
+        // `id` and `retry` are meaningful only to EventSource's reconnect logic,
+        // which we deliberately do not have.
+    }
+    if (!data.length && event === "message")
+        return null;
+    return { event, data: data.join("\n") };
+}
+/**
+ * Drain a fetch Response body as SSE.
+ *
+ * Returns when the server closes the stream. Aborting via `signal` resolves
+ * rather than throwing: a component unmounting mid-stream is the normal way
+ * these end, not an error worth surfacing in a customer's console.
+ */
+export async function readSseStream(response, options) {
+    if (!response.body) {
+        throw new Error("SparkleTree: response has no body — SSE requires a streaming response");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const parser = new SseParser();
+    const onAbort = () => {
+        void reader.cancel().catch(() => { });
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        // A signal aborted BEFORE we started reading never fires "abort" again —
+        // without this check the drain below would run a stream its owner already
+        // cancelled.
+        if (options.signal?.aborted) {
+            await reader.cancel().catch(() => { });
+            return;
+        }
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            // `stream: true` keeps multi-byte characters intact across chunk
+            // boundaries — without it a headline can acquire a permanent U+FFFD.
+            for (const message of parser.push(decoder.decode(value, { stream: true }))) {
+                options.onMessage(message);
+            }
+        }
+        for (const message of parser.flush())
+            options.onMessage(message);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            return;
+        throw error;
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+        // Hand the body back: a locked reader pins the response's resources, and
+        // cancel is idempotent so an already-finished stream costs nothing.
+        // Both are guarded — a stream torn down mid-read can reject either call,
+        // and this is cleanup, never a reason to throw into a customer's page.
+        await reader.cancel().catch(() => { });
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* reads still pending — the lock releases with them */
+        }
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

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