@scalebun-release/web 2.2.2

package/dist/features/push/PushFeature.js

@@ -0,0 +1,319 @@
+/**
+ * F-PUSH — Web Push (VAPID) subscribe + device-token registration. LAZY: the facade dynamic-imports
+ * this module only when the host calls `ScaleBun.enablePush()` from a user gesture, so it stays out of
+ * the core bundle entirely (it is NOT in the FEATURES manifest).
+ *
+ * Flow: feature-detect → request Notification permission (host gesture) → register the host-served
+ * service worker (`/scalebun-push-sw.js`) → fetch the tenant VAPID public key (`/sdk/engage/push-config`)
+ * → `pushManager.subscribe({ userVisibleOnly, applicationServerKey })` → POST the browser
+ * PushSubscription JSON to `/sdk/engage/device-token` (platform:'web', pushProvider:'webpush').
+ *
+ * The differentiator vs OneSignal/Braze: the subscription is registered on the SAME device/session the
+ * recorder is capturing, so a push open is replay-correlated (E6 stamps the coord). Zero third-party:
+ * only ServiceWorker / PushManager / Notification / atob — degrades to a no-op (never throws) when the
+ * browser lacks support or the user denied permission.
+ */
+/** SW contract version this SDK build expects. Bump in lockstep with WZB_SW_VERSION in
+ *  public/scalebun-push-sw.js — push.check() compares them to catch a stale hand-copied worker. */
+export const EXPECTED_SW_VERSION = 5;
+/** Default path the host serves the worker at. Shared by enable() and check() so a diagnostic can
+ *  never disagree with what was actually registered. */
+export const DEFAULT_SW_URL = '/scalebun-push-sw.js';
+export { PUSH_STATE_COPY, resolvePushState } from './pushState.js';
+import { resolvePushState } from './pushState.js';
+/** Feature-detect the three APIs Web Push needs. Any missing ⇒ we no-op. */
+function isSupported() {
+    return (typeof navigator !== 'undefined' &&
+        'serviceWorker' in navigator &&
+        typeof window !== 'undefined' &&
+        'PushManager' in window &&
+        'Notification' in window);
+}
+/** VAPID keys travel as base64url; PushManager wants a BufferSource. Dependency-free (atob only).
+ *  Backed by an explicit ArrayBuffer so the result is a `Uint8Array<ArrayBuffer>` (assignable to
+ *  applicationServerKey under lib.dom's generic-typed-array typings). */
+function urlBase64ToUint8Array(base64) {
+    const padding = '='.repeat((4 - (base64.length % 4)) % 4);
+    const normalized = (base64 + padding).replace(/-/g, '+').replace(/_/g, '/');
+    const raw = atob(normalized);
+    const buffer = new ArrayBuffer(raw.length);
+    const out = new Uint8Array(buffer);
+    for (let i = 0; i < raw.length; i++)
+        out[i] = raw.charCodeAt(i);
+    return out;
+}
+export class PushFeature {
+    constructor(deps) {
+        this.reg = null;
+        this.lastEndpoint = null;
+        /** Remembers where enable() actually registered the worker, so check() diagnoses THAT path. */
+        this.swUrl = DEFAULT_SW_URL;
+        this.openedCbs = new Set();
+        this.swMessageBound = false;
+        this.deps = deps;
+    }
+    log(...args) {
+        this.deps.log?.('[scalebun:push]', ...args);
+    }
+    /** Current permission without prompting. */
+    permission() {
+        if (typeof Notification === 'undefined')
+            return 'default';
+        return Notification.permission;
+    }
+    /**
+     * Subscribe this browser to Web Push and register the subscription with the backend. MUST be called
+     * from a user gesture (browsers gate `Notification.requestPermission()`). Idempotent: a repeat call
+     * reuses the existing subscription and re-registers it (cheap upsert). Never throws.
+     */
+    async enable(opts = {}) {
+        try {
+            if (!isSupported()) {
+                this.log('unsupported browser — skipping');
+                return 'unsupported';
+            }
+            if (!this.deps.clientKey || !this.deps.apiBaseUrl)
+                return 'error';
+            // Don't prompt if already denied — a second prompt is impossible and reads as spam.
+            if (this.permission() === 'denied')
+                return 'denied';
+            // 1. VAPID key first — no point prompting if the tenant hasn't set Web Push up.
+            const cfg = await this.fetchPushConfig();
+            if (!cfg || cfg.enabled === false || !cfg.vapidPublicKey) {
+                this.log('web push not configured for this app');
+                return 'not-configured';
+            }
+            // 2. Permission (host gesture drives this).
+            const permission = await Notification.requestPermission();
+            if (permission !== 'granted')
+                return permission === 'denied' ? 'denied' : 'error';
+            // 3. Register the host-served service worker.
+            const swUrl = opts.serviceWorkerUrl || DEFAULT_SW_URL;
+            this.swUrl = swUrl;
+            this.reg = await navigator.serviceWorker.register(swUrl, opts.serviceWorkerScope ? { scope: opts.serviceWorkerScope } : undefined);
+            await navigator.serviceWorker.ready;
+            this.bindSwMessages();
+            // 4. Subscribe (reuse an existing subscription if present).
+            const existing = await this.reg.pushManager.getSubscription();
+            const sub = existing ||
+                (await this.reg.pushManager.subscribe({
+                    userVisibleOnly: true,
+                    applicationServerKey: urlBase64ToUint8Array(cfg.vapidPublicKey),
+                }));
+            // 5. Register the subscription with the backend (idempotent device upsert).
+            const ok = await this.registerDeviceToken(sub);
+            this.lastEndpoint = sub.endpoint;
+            return ok ? 'subscribed' : 'error';
+        }
+        catch (err) {
+            this.log('enable failed', err);
+            return 'error';
+        }
+    }
+    /**
+     * P2 — opt out of Web Push. Unsubscribes this browser AND tells the backend to revoke the token, so
+     * the device stops being addressable immediately instead of lingering until a send eats a 410.
+     *
+     * Order matters: unsubscribe LOCALLY first (the part that must not fail), then revoke server-side.
+     * The revoke is best-effort — if it fails we simply fall back to the old 410-cleanup behaviour, so
+     * this is belt-and-braces rather than a correctness dependency. The return value reflects the local
+     * unsubscribe; a network failure must not tell the host their opt-out didn't work, because locally
+     * it did.
+     */
+    async disable(opts = {}) {
+        try {
+            const reg = this.reg || (isSupported() ? await navigator.serviceWorker.getRegistration() : null);
+            const sub = reg ? await reg.pushManager.getSubscription() : null;
+            // Capture the endpoint BEFORE unsubscribing — the backend needs it as ownership proof, and it is
+            // unreadable once the subscription is gone.
+            const endpoint = sub?.endpoint ?? this.lastEndpoint ?? null;
+            const done = sub ? await sub.unsubscribe() : true;
+            this.lastEndpoint = null;
+            if (opts.revokeServerSide !== false)
+                await this.revokeDeviceToken(endpoint);
+            return done;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Tell the backend this device opted out. Best-effort; never throws. */
+    async revokeDeviceToken(endpoint) {
+        if (!this.deps.clientKey || !this.deps.apiBaseUrl)
+            return false;
+        try {
+            const res = await fetch(`${this.deps.apiBaseUrl}/sdk/engage/device-token/revoke`, {
+                method: 'POST',
+                headers: this.headers(),
+                // The host may be navigating away when they hit "unsubscribe" — keepalive lets it land anyway.
+                keepalive: true,
+                body: JSON.stringify({
+                    deviceId: this.deps.deviceId,
+                    ...(endpoint ? { endpoint } : {}),
+                }),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Subscribe to notification-open events (the SW postMessages the page on click). Returns an unsub. */
+    onNotificationOpened(cb) {
+        this.openedCbs.add(cb);
+        this.bindSwMessages();
+        return () => this.openedCbs.delete(cb);
+    }
+    /** The current subscription (or null). */
+    async getSubscription() {
+        try {
+            const reg = this.reg || (isSupported() ? await navigator.serviceWorker.getRegistration() : null);
+            const sub = reg ? await reg.pushManager.getSubscription() : null;
+            return sub ? sub.toJSON() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * P1 — full self-diagnosis: HTTPS, API support, worker reachable/registered/current, VAPID set up,
+     * permission, subscription validity (incl. VAPID-rotation detection), and what the SERVER thinks of
+     * this device. Returns a structured, self-describing report — never prompts, never throws.
+     *
+     * The diagnostics module is a SEPARATE dynamic chunk, so hosts that use push but never call check()
+     * do not download it.
+     */
+    async check(opts = {}) {
+        const { runPushDiagnostics } = await import('./diagnostics.js');
+        return runPushDiagnostics({
+            apiBaseUrl: this.deps.apiBaseUrl,
+            clientKey: this.deps.clientKey,
+            deviceId: this.deps.deviceId,
+            serviceWorkerUrl: opts.serviceWorkerUrl || this.swUrl,
+            expectedSwVersion: EXPECTED_SW_VERSION,
+        });
+    }
+    everSubscribed() {
+        try {
+            return localStorage.getItem(PushFeature.EVER_KEY) === '1';
+        }
+        catch {
+            // Private mode / blocked storage — degrade, never throw out of a status read.
+            return false;
+        }
+    }
+    markEverSubscribed() {
+        try {
+            localStorage.setItem(PushFeature.EVER_KEY, '1');
+        }
+        catch {
+            /* storage is a nicety here, not a requirement */
+        }
+    }
+    /** A synchronous-ish snapshot for a Dev Panel / debugging. */
+    async status() {
+        const supported = isSupported();
+        const sub = supported ? await this.getSubscription() : null;
+        if (sub)
+            this.markEverSubscribed();
+        return {
+            supported,
+            permission: this.permission(),
+            subscribed: !!sub,
+            endpoint: sub?.endpoint ?? this.lastEndpoint ?? null,
+            // The actionable state. `permission` above is the raw browser value and keeps its old meaning;
+            // this is the one a product should branch on, because it separates the three situations
+            // `denied`/`granted` conflate. See `pushState.ts`.
+            state: resolvePushState({
+                supported,
+                permission: this.permission(),
+                hasSubscription: !!sub,
+                everSubscribed: this.everSubscribed(),
+            }),
+        };
+    }
+    // ── SW message bridge (click reports + subscription rotation) ──────────────────────────────────
+    bindSwMessages() {
+        if (this.swMessageBound || typeof navigator === 'undefined' || !('serviceWorker' in navigator))
+            return;
+        this.swMessageBound = true;
+        navigator.serviceWorker.addEventListener('message', (event) => {
+            const msg = event.data;
+            if (!msg || typeof msg.type !== 'string')
+                return;
+            if (msg.type === 'scalebun-push-click') {
+                const data = msg.data ?? {};
+                for (const cb of this.openedCbs) {
+                    try {
+                        cb({ data, action: msg.action ?? null });
+                    }
+                    catch {
+                        /* never let a host callback break the bridge */
+                    }
+                }
+            }
+            else if (msg.type === 'scalebun-push-resubscribe' && msg.subscription) {
+                // The browser rotated the subscription — re-register the new one with the backend.
+                void this.registerDeviceTokenJson(msg.subscription).then((ok) => {
+                    if (ok && msg.subscription?.endpoint)
+                        this.lastEndpoint = msg.subscription.endpoint;
+                });
+            }
+        });
+    }
+    // ── Backend lanes (self-contained; no core-transport coupling so core stays untouched) ──────────
+    headers() {
+        return { 'content-type': 'application/json', 'x-scalebun-client-key': this.deps.clientKey };
+    }
+    async fetchPushConfig() {
+        try {
+            const res = await fetch(`${this.deps.apiBaseUrl}/sdk/engage/push-config`, {
+                headers: this.headers(),
+                cache: 'no-store',
+            });
+            if (!res.ok)
+                return null;
+            return (await res.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    registerDeviceToken(sub) {
+        return this.registerDeviceTokenJson(sub.toJSON());
+    }
+    async registerDeviceTokenJson(sub) {
+        if (!sub || !sub.endpoint)
+            return false;
+        try {
+            const res = await fetch(`${this.deps.apiBaseUrl}/sdk/engage/device-token`, {
+                method: 'POST',
+                headers: this.headers(),
+                keepalive: true,
+                body: JSON.stringify({
+                    schemaVersion: 1,
+                    deviceId: this.deps.deviceId,
+                    platform: 'web',
+                    pushProvider: 'webpush',
+                    pushToken: JSON.stringify(sub),
+                    tokenStatus: 'active',
+                    ...(this.deps.sdkVersion ? { sdkVersion: this.deps.sdkVersion } : {}),
+                }),
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Has this browser EVER held a subscription?
+ *
+ * The one extra fact that makes `revoked` separable from `blocked`, and `expired` from
+ * `never-granted` — `Notification.permission` cannot tell those pairs apart on its own. Stored
+ * under the SDK's own key; a cleared storage degrades to "never", which is the safe direction (an
+ * opt-out reads as a first refusal rather than the reverse).
+ */
+PushFeature.EVER_KEY = 'scalebun.push.everSubscribed';
+//# sourceMappingURL=PushFeature.js.map

package/dist/features/push/PushFeature.js.map

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

package/dist/features/push/diagnostics.d.ts

@@ -0,0 +1,55 @@
+/**
+ * P1 — Web Push self-diagnosis. `ScaleBun.push.check()` answers "why isn't push working?" without the
+ * customer opening a support ticket.
+ *
+ * Loaded as its own dynamic chunk from PushFeature.check(), so even hosts that DO use push pay nothing
+ * for diagnostics unless they ask for them. Core bundle untouched.
+ *
+ * Three rules this module must never break:
+ *   1. **It never prompts.** A diagnostic that calls Notification.requestPermission() is a bug — it
+ *      burns the one prompt the host gets, from a non-gesture context, and can permanently deny.
+ *   2. **It never throws.** Every check is independently guarded; an indeterminate check reports
+ *      `unknown`, which is information, not failure.
+ *   3. **The result is self-describing.** Each check carries its own label + fix copy so a dashboard
+ *      can render the report generically, with no second copy of the vocabulary to drift.
+ *
+ * Checks are ordered by CAUSALITY: the first failure is the root cause, and everything downstream of
+ * it reports `unknown` rather than piling on derived failures. The list length is stable so a UI can
+ * render fixed rows.
+ */
+export type PushCheckId = 'secure_context' | 'api_support' | 'sw_reachable' | 'sw_registered' | 'sw_version' | 'vapid_configured' | 'permission' | 'subscription_valid' | 'device_registered' | 'identified';
+export type PushCheckStatus = 'pass' | 'fail' | 'warn' | 'unknown';
+export interface PushCheck {
+    id: PushCheckId;
+    status: PushCheckStatus;
+    /** Short human label — safe to render as-is. */
+    label: string;
+    /** What was actually observed. */
+    detail?: string;
+    /** What the developer should DO about it. Present on fail/warn. */
+    fix?: string;
+}
+export interface PushDiagnostics {
+    /** True when nothing is failing (warnings are allowed — they do not stop delivery). */
+    ok: boolean;
+    /** The first failing check — the root cause to show the developer. */
+    blocking: PushCheckId | null;
+    checks: PushCheck[];
+}
+export interface DiagnosticsDeps {
+    apiBaseUrl: string;
+    clientKey: string;
+    deviceId: string;
+    /** Where the host serves the worker. Must match what enablePush() registered. */
+    serviceWorkerUrl: string;
+    /** The SW version this SDK build expects; a lower reported version means a stale copied file. */
+    expectedSwVersion: number;
+}
+export declare function runPushDiagnostics(deps: DiagnosticsDeps): Promise<PushDiagnostics>;
+/**
+ * The report for "push.check() was called before ScaleBun.init()". Lives HERE rather than inline in
+ * the facade so its strings stay in this lazy chunk — the facade is eager core, and core is under a
+ * hard size gate.
+ */
+export declare function notInitializedReport(): PushDiagnostics;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/features/push/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/features/push/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,eAAe,GACf,YAAY,GACZ,kBAAkB,GAClB,YAAY,GACZ,oBAAoB,GACpB,mBAAmB,GACnB,YAAY,CAAC;AAEjB,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEnE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,WAAW,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC;IACxB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,EAAE,EAAE,OAAO,CAAC;IACZ,sEAAsE;IACtE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAgED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAqRxF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,CActD"}