@scalebun/web 1.0.0

package/dist/features/push/diagnostics.js

@@ -0,0 +1,383 @@
+/**
+ * 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.
+ */
+/** The SW takes a moment to answer a ping; a missing/stale worker never answers at all. */
+const SW_PING_TIMEOUT_MS = 1500;
+// ── helpers ───────────────────────────────────────────────────────────────────
+function isSupported() {
+    return (typeof navigator !== 'undefined' &&
+        'serviceWorker' in navigator &&
+        typeof window !== 'undefined' &&
+        'PushManager' in window &&
+        'Notification' in window);
+}
+function urlBase64ToBytes(base64) {
+    const padding = '='.repeat((4 - (base64.length % 4)) % 4);
+    const normalized = (base64 + padding).replace(/-/g, '+').replace(/_/g, '/');
+    const raw = atob(normalized);
+    const out = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i++)
+        out[i] = raw.charCodeAt(i);
+    return out;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Ask the active worker its version over a MessageChannel. A worker that predates the ping handler
+ * simply never replies — indistinguishable from "no worker", which is why the caller reports both
+ * causes in one message rather than guessing.
+ */
+function pingServiceWorker(reg) {
+    return new Promise((resolve) => {
+        const worker = reg.active;
+        if (!worker || typeof MessageChannel === 'undefined') {
+            resolve(null);
+            return;
+        }
+        let settled = false;
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(v);
+        };
+        try {
+            const channel = new MessageChannel();
+            channel.port1.onmessage = (event) => {
+                const data = event.data;
+                done(data && data.type === 'scalebun-sw-pong' ? { version: data.version } : null);
+            };
+            worker.postMessage({ type: 'scalebun-sw-ping' }, [channel.port2]);
+            setTimeout(() => done(null), SW_PING_TIMEOUT_MS);
+        }
+        catch {
+            done(null);
+        }
+    });
+}
+// ── the report ────────────────────────────────────────────────────────────────
+export async function runPushDiagnostics(deps) {
+    const checks = [];
+    const add = (c) => {
+        checks.push(c);
+        return c;
+    };
+    /** Downstream of a root-cause failure: report honestly as not-evaluated, don't invent failures. */
+    const skip = (id, label, because) => {
+        add({ id, status: 'unknown', label, detail: `Not evaluated — ${because}` });
+    };
+    // 1. Secure context. isSecureContext (NOT protocol === 'https:') so localhost passes, as browsers
+    //    themselves treat it.
+    const secure = typeof window !== 'undefined' && window.isSecureContext === true;
+    add({
+        id: 'secure_context',
+        status: secure ? 'pass' : 'fail',
+        label: 'Secure context (HTTPS)',
+        detail: secure ? undefined : 'Page is not a secure context',
+        fix: secure ? undefined : 'Serve the site over HTTPS. Web Push is unavailable on plain HTTP (localhost is exempt).',
+    });
+    // 2. Browser API support — name the MISSING api, and call out the iOS case explicitly since
+    //    "works on my Android" vs "nothing on iPhone" is the most common confusion.
+    const missing = [];
+    if (typeof navigator === 'undefined' || !('serviceWorker' in navigator))
+        missing.push('ServiceWorker');
+    if (typeof window === 'undefined' || !('PushManager' in window))
+        missing.push('PushManager');
+    if (typeof window === 'undefined' || !('Notification' in window))
+        missing.push('Notification');
+    const supported = missing.length === 0 && isSupported();
+    const iosLike = typeof navigator !== 'undefined' && /iPad|iPhone|iPod/.test(navigator.userAgent || '');
+    add({
+        id: 'api_support',
+        status: supported ? 'pass' : 'fail',
+        label: 'Browser supports Web Push',
+        detail: supported ? undefined : `Missing: ${missing.join(', ') || 'push APIs'}`,
+        fix: supported
+            ? undefined
+            : iosLike
+                ? 'On iOS, Web Push only works when the site is installed to the Home Screen as a PWA (iOS 16.4+). In a normal Safari tab these APIs are absent.'
+                : 'This browser cannot receive Web Push. Hide your opt-in UI when ScaleBun.push.check() reports this.',
+    });
+    if (!supported) {
+        // Everything below depends on the push APIs existing.
+        skip('sw_reachable', 'Service worker file is reachable', 'push APIs are unavailable');
+        skip('sw_registered', 'Service worker is registered', 'push APIs are unavailable');
+        skip('sw_version', 'Service worker is up to date', 'push APIs are unavailable');
+        skip('vapid_configured', 'Web Push configured for this app', 'push APIs are unavailable');
+        skip('permission', 'Notification permission', 'push APIs are unavailable');
+        skip('subscription_valid', 'Push subscription is valid', 'push APIs are unavailable');
+        skip('device_registered', 'Device registered with ScaleBun', 'push APIs are unavailable');
+        skip('identified', 'User is identified', 'push APIs are unavailable');
+        return finish(checks);
+    }
+    // 3. Is the worker FILE actually served? Integration step 2 is a manual file copy, so a 404 here is
+    //    the single most likely failure — and nothing else in the stack reports it clearly.
+    let swReachable = null;
+    try {
+        const res = await fetch(deps.serviceWorkerUrl, { method: 'HEAD', cache: 'no-store' });
+        swReachable = res.ok;
+        add({
+            id: 'sw_reachable',
+            status: res.ok ? 'pass' : 'fail',
+            label: 'Service worker file is reachable',
+            detail: `GET ${deps.serviceWorkerUrl} → ${res.status}`,
+            fix: res.ok
+                ? undefined
+                : `Copy scalebun-push-sw.js from @scalebun/web/dist/ to your web root so it is served at ${deps.serviceWorkerUrl}.`,
+        });
+    }
+    catch (err) {
+        add({
+            id: 'sw_reachable',
+            status: 'unknown',
+            label: 'Service worker file is reachable',
+            detail: `Could not fetch ${deps.serviceWorkerUrl}`,
+            fix: 'Check that the file is served from the same origin and not blocked by CSP.',
+        });
+    }
+    // 4. Registered — and registered to OUR worker. A host may have another service worker claiming
+    //    the same scope, which looks fine until pushes silently go nowhere.
+    let reg = null;
+    try {
+        reg = (await navigator.serviceWorker.getRegistration(deps.serviceWorkerUrl)) ?? null;
+    }
+    catch {
+        reg = null;
+    }
+    const scriptUrl = reg?.active?.scriptURL ?? reg?.installing?.scriptURL ?? reg?.waiting?.scriptURL ?? null;
+    const isOurs = !!scriptUrl && scriptUrl.indexOf('scalebun-push-sw') >= 0;
+    add({
+        id: 'sw_registered',
+        status: reg && isOurs ? 'pass' : 'fail',
+        label: 'Service worker is registered',
+        detail: !reg
+            ? 'No registration found for this scope'
+            : isOurs
+                ? `Active: ${scriptUrl}`
+                : `A different worker owns this scope: ${scriptUrl}`,
+        fix: !reg
+            ? swReachable === false
+                ? 'The worker file is missing (see the check above) — fix that first, then call ScaleBun.enablePush().'
+                : 'Call ScaleBun.enablePush() from a user gesture to register the worker.'
+            : isOurs
+                ? undefined
+                : 'Another service worker controls this scope. Serve the ScaleBun worker at a path it can own, and pass serviceWorkerScope to enablePush().',
+    });
+    // 5. Version — the worker is copied by hand and therefore goes stale silently.
+    if (reg && isOurs) {
+        const pong = await pingServiceWorker(reg);
+        if (!pong || typeof pong.version !== 'number') {
+            add({
+                id: 'sw_version',
+                status: 'warn',
+                label: 'Service worker is up to date',
+                // Honest ambiguity: a worker predating the ping handler cannot report that it is stale.
+                detail: 'The worker did not answer a version ping',
+                fix: `Your copy of scalebun-push-sw.js is older than v${deps.expectedSwVersion} (versions before v3 cannot report themselves). Re-copy it from @scalebun/web/dist/.`,
+            });
+        }
+        else if (pong.version < deps.expectedSwVersion) {
+            add({
+                id: 'sw_version',
+                status: 'warn',
+                label: 'Service worker is up to date',
+                detail: `Worker is v${pong.version}, this SDK expects v${deps.expectedSwVersion}`,
+                fix: 'Re-copy scalebun-push-sw.js from @scalebun/web/dist/ to your web root — the deployed copy is stale.',
+            });
+        }
+        else {
+            add({ id: 'sw_version', status: 'pass', label: 'Service worker is up to date', detail: `v${pong.version}` });
+        }
+    }
+    else {
+        skip('sw_version', 'Service worker is up to date', 'no ScaleBun worker is registered');
+    }
+    // 6. Has the TENANT set Web Push up at all?
+    let vapidKey = null;
+    try {
+        const res = await fetch(`${deps.apiBaseUrl}/sdk/engage/push-config`, {
+            headers: { 'content-type': 'application/json', 'x-scalebun-client-key': deps.clientKey },
+            cache: 'no-store',
+        });
+        const cfg = res.ok ? (await res.json()) : null;
+        vapidKey = cfg?.enabled === false ? null : (cfg?.vapidPublicKey ?? null);
+        add({
+            id: 'vapid_configured',
+            status: vapidKey ? 'pass' : 'fail',
+            label: 'Web Push configured for this app',
+            detail: vapidKey ? undefined : 'No VAPID key served for this client key',
+            fix: vapidKey
+                ? undefined
+                : 'In the ScaleBun dashboard: Settings → Integrations → Web Push (VAPID) → Generate VAPID keys.',
+        });
+    }
+    catch {
+        add({
+            id: 'vapid_configured',
+            status: 'unknown',
+            label: 'Web Push configured for this app',
+            detail: 'Could not reach the ScaleBun API',
+            fix: 'Check apiBaseUrl, network access, and CORS.',
+        });
+    }
+    // 7. Permission — READ ONLY. Never prompts.
+    const permission = typeof Notification === 'undefined' ? 'default' : Notification.permission;
+    add({
+        id: 'permission',
+        status: permission === 'granted' ? 'pass' : permission === 'denied' ? 'fail' : 'warn',
+        label: 'Notification permission',
+        detail: permission,
+        fix: permission === 'granted'
+            ? undefined
+            : permission === 'denied'
+                ? 'The user blocked notifications. This cannot be re-prompted from code — they must re-allow it in browser site settings.'
+                : 'Not asked yet. Call ScaleBun.enablePush() from a click handler.',
+    });
+    // 8. Subscription — exists, unexpired, and minted with the VAPID key the tenant is CURRENTLY using.
+    //    The last part catches the silent killer: rotating VAPID in the dashboard leaves every existing
+    //    subscription dead while it still looks perfectly healthy.
+    try {
+        const sub = reg ? await reg.pushManager.getSubscription() : null;
+        if (!sub) {
+            add({
+                id: 'subscription_valid',
+                status: 'fail',
+                label: 'Push subscription is valid',
+                detail: 'No subscription on this browser',
+                fix: permission === 'granted'
+                    ? 'Permission is granted but no subscription exists — call ScaleBun.enablePush() to create one.'
+                    : 'Call ScaleBun.enablePush() from a user gesture.',
+            });
+        }
+        else {
+            const json = sub.toJSON();
+            const expired = typeof json.expirationTime === 'number' && json.expirationTime <= Date.now();
+            let keyMatches = null;
+            if (vapidKey) {
+                const appKey = sub.options?.applicationServerKey;
+                keyMatches = appKey ? sameBytes(new Uint8Array(appKey), urlBase64ToBytes(vapidKey)) : null;
+            }
+            const bad = expired || keyMatches === false;
+            add({
+                id: 'subscription_valid',
+                status: bad ? 'fail' : keyMatches === null && vapidKey ? 'warn' : 'pass',
+                label: 'Push subscription is valid',
+                detail: expired
+                    ? 'Subscription has expired'
+                    : keyMatches === false
+                        ? 'Subscription was created with a DIFFERENT VAPID key than this app now uses'
+                        : keyMatches === null && vapidKey
+                            ? 'Could not read the subscription key to compare against the tenant VAPID key'
+                            : sub.endpoint,
+                fix: expired
+                    ? 'Call ScaleBun.enablePush() again to mint a fresh subscription.'
+                    : keyMatches === false
+                        ? 'The VAPID keypair was rotated after this browser subscribed, so pushes to it will fail. Call ScaleBun.push.disable() then ScaleBun.enablePush() to re-subscribe.'
+                        : undefined,
+            });
+        }
+    }
+    catch {
+        add({
+            id: 'subscription_valid',
+            status: 'unknown',
+            label: 'Push subscription is valid',
+            detail: 'Could not read the push subscription',
+        });
+    }
+    // 9 + 10. What does the SERVER think? Without this the SDK can only claim "we POSTed and got a 200".
+    try {
+        const res = await fetch(`${deps.apiBaseUrl}/sdk/engage/device-token/status?deviceId=${encodeURIComponent(deps.deviceId)}`, {
+            headers: { 'content-type': 'application/json', 'x-scalebun-client-key': deps.clientKey },
+            cache: 'no-store',
+        });
+        const echo = res.ok
+            ? (await res.json())
+            : null;
+        if (!echo) {
+            add({ id: 'device_registered', status: 'unknown', label: 'Device registered with ScaleBun', detail: `Status lane returned ${res.status}` });
+            skip('identified', 'User is identified', 'the server did not answer');
+        }
+        else {
+            const dead = echo.tokenStatus === 'dead';
+            add({
+                id: 'device_registered',
+                status: echo.registered && !dead ? 'pass' : 'fail',
+                label: 'Device registered with ScaleBun',
+                detail: !echo.registered ? 'No push token stored for this device' : dead ? 'Token marked dead by the push service' : 'Registered and active',
+                fix: !echo.registered
+                    ? 'Call ScaleBun.enablePush() — the subscription never reached the backend.'
+                    : dead
+                        ? 'The browser push service rejected this token (410 Gone). Call ScaleBun.enablePush() to re-subscribe.'
+                        : undefined,
+            });
+            // Anonymous is NOT an error — but it silently excludes this browser from every journey and
+            // lifecycle program, which is exactly the kind of thing people lose days to.
+            add({
+                id: 'identified',
+                status: echo.identified ? 'pass' : 'warn',
+                label: 'User is identified',
+                detail: echo.identified ? 'Bound to a person' : 'Anonymous device',
+                fix: echo.identified
+                    ? undefined
+                    : 'Call ScaleBun.identify() — journeys and lifecycle programs only target identified people, so this browser can receive broadcasts but never an automated lifecycle push.',
+            });
+        }
+    }
+    catch {
+        add({ id: 'device_registered', status: 'unknown', label: 'Device registered with ScaleBun', detail: 'Could not reach the ScaleBun API' });
+        skip('identified', 'User is identified', 'the server was unreachable');
+    }
+    return finish(checks);
+}
+/**
+ * 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 function notInitializedReport() {
+    return {
+        ok: false,
+        blocking: 'api_support',
+        checks: [
+            {
+                id: 'api_support',
+                status: 'fail',
+                label: 'ScaleBun is initialized',
+                detail: 'push.check() was called before ScaleBun.init()',
+                fix: 'Call ScaleBun.init({ clientKey, apiBaseUrl }) first — diagnostics need the resolved config.',
+            },
+        ],
+    };
+}
+function finish(checks) {
+    const firstFail = checks.find((c) => c.status === 'fail');
+    return {
+        ok: !firstFail,
+        blocking: firstFail?.id ?? null,
+        checks,
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/features/push/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA6CH,2FAA2F;AAC3F,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,iFAAiF;AACjF,SAAS,WAAW;IAClB,OAAO,CACL,OAAO,SAAS,KAAK,WAAW;QAChC,eAAe,IAAI,SAAS;QAC5B,OAAO,MAAM,KAAK,WAAW;QAC7B,aAAa,IAAI,MAAM;QACvB,cAAc,IAAI,MAAM,CACzB,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,UAAU,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,SAAS,CAAC,CAAa,EAAE,CAAa;IAC7C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,GAA8B;IACvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,MAAM,IAAI,OAAO,cAAc,KAAK,WAAW,EAAE,CAAC;YACrD,OAAO,CAAC,IAAI,CAAC,CAAC;YACd,OAAO;QACT,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,IAAI,GAAG,CAAC,CAA8B,EAAQ,EAAE;YACpD,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,CAAC,CAAC,CAAC,CAAC;QACb,CAAC,CAAC;QACF,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;YACrC,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,KAAmB,EAAE,EAAE;gBAChD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAuD,CAAC;gBAC3E,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACpF,CAAC,CAAC;YACF,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAClE,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAqB;IAC5D,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,GAAG,GAAG,CAAC,CAAY,EAAa,EAAE;QACtC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IACF,mGAAmG;IACnG,MAAM,IAAI,GAAG,CAAC,EAAe,EAAE,KAAa,EAAE,OAAe,EAAQ,EAAE;QACrE,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,OAAO,EAAE,EAAE,CAAC,CAAC;IAC9E,CAAC,CAAC;IAEF,kGAAkG;IAClG,0BAA0B;IAC1B,MAAM,MAAM,GAAG,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,eAAe,KAAK,IAAI,CAAC;IAChF,GAAG,CAAC;QACF,EAAE,EAAE,gBAAgB;QACpB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QAChC,KAAK,EAAE,wBAAwB;QAC/B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,8BAA8B;QAC3D,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,yFAAyF;KACpH,CAAC,CAAC;IAEH,4FAA4F;IAC5F,gFAAgF;IAChF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,CAAC,CAAC,eAAe,IAAI,SAAS,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACvG,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,aAAa,IAAI,MAAM,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7F,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,cAAc,IAAI,MAAM,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC/F,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;IACxD,MAAM,OAAO,GACX,OAAO,SAAS,KAAK,WAAW,IAAI,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IACzF,GAAG,CAAC;QACF,EAAE,EAAE,aAAa;QACjB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACnC,KAAK,EAAE,2BAA2B;QAClC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,EAAE;QAC/E,GAAG,EAAE,SAAS;YACZ,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,OAAO;gBACP,CAAC,CAAC,+IAA+I;gBACjJ,CAAC,CAAC,oGAAoG;KAC3G,CAAC,CAAC;IAEH,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,sDAAsD;QACtD,IAAI,CAAC,cAAc,EAAE,kCAAkC,EAAE,2BAA2B,CAAC,CAAC;QACtF,IAAI,CAAC,eAAe,EAAE,8BAA8B,EAAE,2BAA2B,CAAC,CAAC;QACnF,IAAI,CAAC,YAAY,EAAE,8BAA8B,EAAE,2BAA2B,CAAC,CAAC;QAChF,IAAI,CAAC,kBAAkB,EAAE,kCAAkC,EAAE,2BAA2B,CAAC,CAAC;QAC1F,IAAI,CAAC,YAAY,EAAE,yBAAyB,EAAE,2BAA2B,CAAC,CAAC;QAC3E,IAAI,CAAC,oBAAoB,EAAE,4BAA4B,EAAE,2BAA2B,CAAC,CAAC;QACtF,IAAI,CAAC,mBAAmB,EAAE,iCAAiC,EAAE,2BAA2B,CAAC,CAAC;QAC1F,IAAI,CAAC,YAAY,EAAE,oBAAoB,EAAE,2BAA2B,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,oGAAoG;IACpG,wFAAwF;IACxF,IAAI,WAAW,GAAmB,IAAI,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QACtF,WAAW,GAAG,GAAG,CAAC,EAAE,CAAC;QACrB,GAAG,CAAC;YACF,EAAE,EAAE,cAAc;YAClB,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YAChC,KAAK,EAAE,kCAAkC;YACzC,MAAM,EAAE,OAAO,IAAI,CAAC,gBAAgB,MAAM,GAAG,CAAC,MAAM,EAAE;YACtD,GAAG,EAAE,GAAG,CAAC,EAAE;gBACT,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,yFAAyF,IAAI,CAAC,gBAAgB,GAAG;SACtH,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC;YACF,EAAE,EAAE,cAAc;YAClB,MAAM,EAAE,SAAS;YACjB,KAAK,EAAE,kCAAkC;YACzC,MAAM,EAAE,mBAAmB,IAAI,CAAC,gBAAgB,EAAE;YAClD,GAAG,EAAE,4EAA4E;SAClF,CAAC,CAAC;IACL,CAAC;IAED,gGAAgG;IAChG,wEAAwE;IACxE,IAAI,GAAG,GAAqC,IAAI,CAAC;IACjD,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,SAAS,CAAC,aAAa,CAAC,eAAe,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,IAAI,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,GAAG,IAAI,CAAC;IACb,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,EAAE,MAAM,EAAE,SAAS,IAAI,GAAG,EAAE,UAAU,EAAE,SAAS,IAAI,GAAG,EAAE,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;IAC1G,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,IAAI,SAAS,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACzE,GAAG,CAAC;QACF,EAAE,EAAE,eAAe;QACnB,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACvC,KAAK,EAAE,8BAA8B;QACrC,MAAM,EAAE,CAAC,GAAG;YACV,CAAC,CAAC,sCAAsC;YACxC,CAAC,CAAC,MAAM;gBACN,CAAC,CAAC,WAAW,SAAS,EAAE;gBACxB,CAAC,CAAC,uCAAuC,SAAS,EAAE;QACxD,GAAG,EAAE,CAAC,GAAG;YACP,CAAC,CAAC,WAAW,KAAK,KAAK;gBACrB,CAAC,CAAC,qGAAqG;gBACvG,CAAC,CAAC,wEAAwE;YAC5E,CAAC,CAAC,MAAM;gBACN,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,0IAA0I;KACjJ,CAAC,CAAC;IAEH,+EAA+E;IAC/E,IAAI,GAAG,IAAI,MAAM,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC9C,GAAG,CAAC;gBACF,EAAE,EAAE,YAAY;gBAChB,MAAM,EAAE,MAAM;gBACd,KAAK,EAAE,8BAA8B;gBACrC,wFAAwF;gBACxF,MAAM,EAAE,0CAA0C;gBAClD,GAAG,EAAE,mDAAmD,IAAI,CAAC,iBAAiB,sFAAsF;aACrK,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACjD,GAAG,CAAC;gBACF,EAAE,EAAE,YAAY;gBAChB,MAAM,EAAE,MAAM;gBACd,KAAK,EAAE,8BAA8B;gBACrC,MAAM,EAAE,cAAc,IAAI,CAAC,OAAO,uBAAuB,IAAI,CAAC,iBAAiB,EAAE;gBACjF,GAAG,EAAE,qGAAqG;aAC3G,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,8BAA8B,EAAE,MAAM,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC/G,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,YAAY,EAAE,8BAA8B,EAAE,kCAAkC,CAAC,CAAC;IACzF,CAAC;IAED,4CAA4C;IAC5C,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,UAAU,yBAAyB,EAAE;YACnE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,IAAI,CAAC,SAAS,EAAE;YACxF,KAAK,EAAE,UAAU;SAClB,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAoD,CAAC,CAAC,CAAC,IAAI,CAAC;QACnG,QAAQ,GAAG,GAAG,EAAE,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,cAAc,IAAI,IAAI,CAAC,CAAC;QACzE,GAAG,CAAC;YACF,EAAE,EAAE,kBAAkB;YACtB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YAClC,KAAK,EAAE,kCAAkC;YACzC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,yCAAyC;YACxE,GAAG,EAAE,QAAQ;gBACX,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,8FAA8F;SACnG,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,CAAC;YACF,EAAE,EAAE,kBAAkB;YACtB,MAAM,EAAE,SAAS;YACjB,KAAK,EAAE,kCAAkC;YACzC,MAAM,EAAE,kCAAkC;YAC1C,GAAG,EAAE,6CAA6C;SACnD,CAAC,CAAC;IACL,CAAC;IAED,4CAA4C;IAC5C,MAAM,UAAU,GAAG,OAAO,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC;IAC7F,GAAG,CAAC;QACF,EAAE,EAAE,YAAY;QAChB,MAAM,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACrF,KAAK,EAAE,yBAAyB;QAChC,MAAM,EAAE,UAAU;QAClB,GAAG,EACD,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,KAAK,QAAQ;gBACvB,CAAC,CAAC,wHAAwH;gBAC1H,CAAC,CAAC,iEAAiE;KAC1E,CAAC,CAAC;IAEH,oGAAoG;IACpG,oGAAoG;IACpG,+DAA+D;IAC/D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,CAAC;gBACF,EAAE,EAAE,oBAAoB;gBACxB,MAAM,EAAE,MAAM;gBACd,KAAK,EAAE,4BAA4B;gBACnC,MAAM,EAAE,iCAAiC;gBACzC,GAAG,EACD,UAAU,KAAK,SAAS;oBACtB,CAAC,CAAC,8FAA8F;oBAChG,CAAC,CAAC,iDAAiD;aACxD,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,cAAc,KAAK,QAAQ,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7F,IAAI,UAAU,GAAmB,IAAI,CAAC;YACtC,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,MAAM,GAAI,GAAG,CAAC,OAA+C,EAAE,oBAAoB,CAAC;gBAC1F,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC7F,CAAC;YACD,MAAM,GAAG,GAAG,OAAO,IAAI,UAAU,KAAK,KAAK,CAAC;YAC5C,GAAG,CAAC;gBACF,EAAE,EAAE,oBAAoB;gBACxB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,KAAK,IAAI,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;gBACxE,KAAK,EAAE,4BAA4B;gBACnC,MAAM,EAAE,OAAO;oBACb,CAAC,CAAC,0BAA0B;oBAC5B,CAAC,CAAC,UAAU,KAAK,KAAK;wBACpB,CAAC,CAAC,4EAA4E;wBAC9E,CAAC,CAAC,UAAU,KAAK,IAAI,IAAI,QAAQ;4BAC/B,CAAC,CAAC,6EAA6E;4BAC/E,CAAC,CAAC,GAAG,CAAC,QAAQ;gBACpB,GAAG,EAAE,OAAO;oBACV,CAAC,CAAC,gEAAgE;oBAClE,CAAC,CAAC,UAAU,KAAK,KAAK;wBACpB,CAAC,CAAC,kKAAkK;wBACpK,CAAC,CAAC,SAAS;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,CAAC;YACF,EAAE,EAAE,oBAAoB;YACxB,MAAM,EAAE,SAAS;YACjB,KAAK,EAAE,4BAA4B;YACnC,MAAM,EAAE,sCAAsC;SAC/C,CAAC,CAAC;IACL,CAAC;IAED,qGAAqG;IACrG,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CACrB,GAAG,IAAI,CAAC,UAAU,4CAA4C,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EACjG;YACE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,IAAI,CAAC,SAAS,EAAE;YACxF,KAAK,EAAE,UAAU;SAClB,CACF,CAAC;QACF,MAAM,IAAI,GAAG,GAAG,CAAC,EAAE;YACjB,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiF;YACrG,CAAC,CAAC,IAAI,CAAC;QACT,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,GAAG,CAAC,EAAE,EAAE,EAAE,mBAAmB,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,iCAAiC,EAAE,MAAM,EAAE,wBAAwB,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC5I,IAAI,CAAC,YAAY,EAAE,oBAAoB,EAAE,2BAA2B,CAAC,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,KAAK,MAAM,CAAC;YACzC,GAAG,CAAC;gBACF,EAAE,EAAE,mBAAmB;gBACvB,MAAM,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;gBAClD,KAAK,EAAE,iCAAiC;gBACxC,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,uCAAuC,CAAC,CAAC,CAAC,uBAAuB;gBAC5I,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU;oBACnB,CAAC,CAAC,0EAA0E;oBAC5E,CAAC,CAAC,IAAI;wBACJ,CAAC,CAAC,sGAAsG;wBACxG,CAAC,CAAC,SAAS;aAChB,CAAC,CAAC;YACH,2FAA2F;YAC3F,6EAA6E;YAC7E,GAAG,CAAC;gBACF,EAAE,EAAE,YAAY;gBAChB,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;gBACzC,KAAK,EAAE,oBAAoB;gBAC3B,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,kBAAkB;gBAClE,GAAG,EAAE,IAAI,CAAC,UAAU;oBAClB,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,yKAAyK;aAC9K,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,CAAC,EAAE,EAAE,EAAE,mBAAmB,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,iCAAiC,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC,CAAC;QAC1I,IAAI,CAAC,YAAY,EAAE,oBAAoB,EAAE,4BAA4B,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,EAAE,EAAE,KAAK;QACT,QAAQ,EAAE,aAAa;QACvB,MAAM,EAAE;YACN;gBACE,EAAE,EAAE,aAAa;gBACjB,MAAM,EAAE,MAAM;gBACd,KAAK,EAAE,yBAAyB;gBAChC,MAAM,EAAE,gDAAgD;gBACxD,GAAG,EAAE,6FAA6F;aACnG;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,MAAmB;IACjC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAC1D,OAAO;QACL,EAAE,EAAE,CAAC,SAAS;QACd,QAAQ,EAAE,SAAS,EAAE,EAAE,IAAI,IAAI;QAC/B,MAAM;KACP,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,58 @@
+/**
+ * The push state a host can actually act on.
+ *
+ * ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────────
+ * `Notification.permission` has three values and they do NOT map onto the three situations a product
+ * needs to tell apart. `denied` covers both "they said no when we asked" and "they had it on and
+ * turned it off in browser settings" — different people, needing different copy and different
+ * treatment. And `granted` says nothing about whether a subscription still exists: a browser can
+ * expire or drop one while permission stays granted, which is the case that silently stops delivery
+ * with every signal still reading green.
+ *
+ * So the SDK collapsed three distinct states into `denied` plus an unrepresented fourth. The
+ * distinction is recoverable from one extra fact — whether this browser has EVER held a subscription
+ * — which is why `everSubscribed` is persisted.
+ *
+ * Pure so it can be tested exhaustively without a browser; `PushFeature` supplies the inputs.
+ */
+export type PushPermission = 'granted' | 'denied' | 'default';
+export type PushState = 
+/** Working: permission granted and a live subscription registered. */
+'subscribed'
+/** Never asked. The only state where prompting is appropriate. */
+ | 'never-granted'
+/** Asked, and they said no. Re-prompting is impossible — the browser will not show it again. */
+ | 'blocked'
+/** They HAD it and turned it off. A different person from `blocked`, and a different conversation. */
+ | 'revoked'
+/**
+ * Permission is still granted but the subscription is gone — expired, or dropped by the browser.
+ * Recoverable WITHOUT a prompt, which is what makes it worth separating: calling subscribe again
+ * just works, and treating it as "denied" would hide a user who never refused anything.
+ */
+ | 'expired'
+/** The browser cannot do web push at all. */
+ | 'unsupported';
+export interface PushStateInput {
+    supported: boolean;
+    permission: PushPermission;
+    /** A live `PushSubscription` exists right now. */
+    hasSubscription: boolean;
+    /** This browser has held a subscription at some point — persisted by the SDK. */
+    everSubscribed: boolean;
+}
+export declare function resolvePushState(input: PushStateInput): PushState;
+export interface PushStateCopy {
+    /** One line stating what is true. Never a euphemism — a blocked user is not "not subscribed yet". */
+    title: string;
+    detail: string;
+    /** Can calling `enablePush()` plausibly fix this? Drives whether a UI offers the button at all. */
+    actionable: boolean;
+}
+/**
+ * The three-states requirement is a COPY requirement as much as a data one: they "must read
+ * differently". Kept beside the resolver so a new state cannot be added without answering what it
+ * says to a person.
+ */
+export declare const PUSH_STATE_COPY: Record<PushState, PushStateCopy>;
+//# sourceMappingURL=pushState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pushState.d.ts","sourceRoot":"","sources":["../../../src/features/push/pushState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,SAAS;AACnB,sEAAsE;AACpE,YAAY;AACd,kEAAkE;GAChE,eAAe;AACjB,gGAAgG;GAC9F,SAAS;AACX,sGAAsG;GACpG,SAAS;AACX;;;;GAIG;GACD,SAAS;AACX,6CAA6C;GAC3C,aAAa,CAAC;AAElB,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,kDAAkD;IAClD,eAAe,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAgBjE;AAED,MAAM,WAAW,aAAa;IAC5B,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,aAAa,CAqC5D,CAAC"}

package/dist/features/push/pushState.js

@@ -0,0 +1,75 @@
+/**
+ * The push state a host can actually act on.
+ *
+ * ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────────
+ * `Notification.permission` has three values and they do NOT map onto the three situations a product
+ * needs to tell apart. `denied` covers both "they said no when we asked" and "they had it on and
+ * turned it off in browser settings" — different people, needing different copy and different
+ * treatment. And `granted` says nothing about whether a subscription still exists: a browser can
+ * expire or drop one while permission stays granted, which is the case that silently stops delivery
+ * with every signal still reading green.
+ *
+ * So the SDK collapsed three distinct states into `denied` plus an unrepresented fourth. The
+ * distinction is recoverable from one extra fact — whether this browser has EVER held a subscription
+ * — which is why `everSubscribed` is persisted.
+ *
+ * Pure so it can be tested exhaustively without a browser; `PushFeature` supplies the inputs.
+ */
+export function resolvePushState(input) {
+    if (!input.supported)
+        return 'unsupported';
+    if (input.permission === 'denied') {
+        // The whole point of `everSubscribed`: a first-ask refusal and a later opt-out are the same
+        // browser value and completely different situations.
+        return input.everSubscribed ? 'revoked' : 'blocked';
+    }
+    if (input.permission === 'default')
+        return 'never-granted';
+    // granted
+    if (input.hasSubscription)
+        return 'subscribed';
+    // Granted but no subscription. If we never had one, the host simply has not called enable() yet —
+    // that is still "never granted a subscription", not a failure. If we DID have one, it is gone.
+    return input.everSubscribed ? 'expired' : 'never-granted';
+}
+/**
+ * The three-states requirement is a COPY requirement as much as a data one: they "must read
+ * differently". Kept beside the resolver so a new state cannot be added without answering what it
+ * says to a person.
+ */
+export const PUSH_STATE_COPY = {
+    subscribed: {
+        title: 'Notifications are on',
+        detail: 'This browser is registered and can receive push.',
+        actionable: false,
+    },
+    'never-granted': {
+        title: 'Not asked yet',
+        detail: 'This browser has never been prompted. Ask from a click — browsers ignore the prompt otherwise.',
+        actionable: true,
+    },
+    blocked: {
+        title: 'Blocked in this browser',
+        detail: 'Notifications were declined, and the browser will not show the prompt again. Only the person can re-enable it, from the site settings beside the address bar.',
+        // Deliberately false: offering an Enable button here does nothing and teaches people the product
+        // is broken. The recovery is in browser chrome we cannot reach.
+        actionable: false,
+    },
+    revoked: {
+        title: 'Turned off after being enabled',
+        detail: 'This browser had notifications and they were switched off. Like blocking, only the person can restore it from the site settings — but unlike a first refusal, they opted in once, so a reminder in-product is fair.',
+        actionable: false,
+    },
+    expired: {
+        title: 'Registration expired',
+        detail: 'Permission is still granted but the subscription is gone — browsers drop them after long inactivity or a data clear. Re-registering fixes it and does NOT prompt.',
+        // The one recoverable state that looks like a failure. Worth separating precisely for this.
+        actionable: true,
+    },
+    unsupported: {
+        title: 'Not supported in this browser',
+        detail: 'Web push needs a service worker, the Push API and Notifications. This browser is missing at least one.',
+        actionable: false,
+    },
+};
+//# sourceMappingURL=pushState.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pushState.js","sourceRoot":"","sources":["../../../src/features/push/pushState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA+BH,MAAM,UAAU,gBAAgB,CAAC,KAAqB;IACpD,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,aAAa,CAAC;IAE3C,IAAI,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAClC,4FAA4F;QAC5F,qDAAqD;QACrD,OAAO,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC;IAE3D,UAAU;IACV,IAAI,KAAK,CAAC,eAAe;QAAE,OAAO,YAAY,CAAC;IAC/C,kGAAkG;IAClG,+FAA+F;IAC/F,OAAO,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC;AAC5D,CAAC;AAUD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqC;IAC/D,UAAU,EAAE;QACV,KAAK,EAAE,sBAAsB;QAC7B,MAAM,EAAE,kDAAkD;QAC1D,UAAU,EAAE,KAAK;KAClB;IACD,eAAe,EAAE;QACf,KAAK,EAAE,eAAe;QACtB,MAAM,EAAE,gGAAgG;QACxG,UAAU,EAAE,IAAI;KACjB;IACD,OAAO,EAAE;QACP,KAAK,EAAE,yBAAyB;QAChC,MAAM,EACJ,+JAA+J;QACjK,iGAAiG;QACjG,gEAAgE;QAChE,UAAU,EAAE,KAAK;KAClB;IACD,OAAO,EAAE;QACP,KAAK,EAAE,gCAAgC;QACvC,MAAM,EACJ,qNAAqN;QACvN,UAAU,EAAE,KAAK;KAClB;IACD,OAAO,EAAE;QACP,KAAK,EAAE,sBAAsB;QAC7B,MAAM,EACJ,mKAAmK;QACrK,4FAA4F;QAC5F,UAAU,EAAE,IAAI;KACjB;IACD,WAAW,EAAE;QACX,KAAK,EAAE,+BAA+B;QACtC,MAAM,EAAE,wGAAwG;QAChH,UAAU,EAAE,KAAK;KAClB;CACF,CAAC"}

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

@@ -0,0 +1,68 @@
+/**
+ * Soft-ask — the in-page prompt that comes BEFORE the browser's permission prompt.
+ *
+ * Why this exists at all, and why it is not just "prompt on load":
+ *
+ * `Notification.requestPermission()` needs transient user activation, so a page physically cannot
+ * prompt by itself. But the deeper reason is asymmetry, and it is the whole design:
+ *
+ *   • A "Not now" here costs NOTHING. Ask again next week.
+ *   • A browser "Block" is PERMANENT. `pushState` reports it as `blocked` with `actionable: false`
+ *     precisely because the recovery lives in browser chrome the SDK cannot reach — an Enable button
+ *     after a block does nothing and teaches people the product is broken.
+ *
+ * So the one irreversible prompt is spent only on people who already said yes to a reversible one.
+ * Chrome reinforces this: sites with poor accept rates get demoted to "quiet" notification UI, where
+ * the real prompt collapses into an address-bar icon almost nobody clicks. One bad auto-prompt can
+ * cost a tenant the ability to ask properly at all.
+ *
+ * ⚠️ ENTIRELY LAZY. Core sits at ~31.5 KB against a 32 KB gate, so none of this — markup, styles,
+ * trigger logic — may land in the eager bundle. `ScaleBunFacade` imports it dynamically and only when
+ * `push.softAsk` is configured, so a tenant that does not use it pays zero bytes.
+ *
+ * ⚠️ No third-party runtime deps, per the SDK's core rule: browser APIs only.
+ */
+import type { PushEnableStatus } from './PushFeature';
+export interface SoftAskOptions {
+    /**
+     * When to show it.
+     *   • `'immediate'`      — on init (still safe: this is OUR dialog, not the browser's)
+     *   • `{ afterMs }`      — after a dwell period
+     *   • `{ onSelector }`   — when the visitor clicks something (a bell icon, "notify me")
+     * A selector is the best of the three: intent is already expressed.
+     */
+    trigger?: 'immediate' | {
+        afterMs: number;
+    } | {
+        onSelector: string;
+    };
+    title?: string;
+    body?: string;
+    allowText?: string;
+    denyText?: string;
+    /**
+     * Days to wait before asking again after a "Not now". Persisted in localStorage, so a dismissal is
+     * respected across sessions — asking every page load is how a soft-ask becomes the thing it exists
+     * to prevent.
+     */
+    remindAfterDays?: number;
+    /** Accent colour for the allow button. Defaults to the SDK brand. */
+    accent?: string;
+}
+export interface SoftAskDeps {
+    enable: () => Promise<PushEnableStatus>;
+    /** Current permission, so we never re-ask someone who already answered the browser. */
+    permission: () => NotificationPermission;
+    log?: (m: string) => void;
+}
+/**
+ * Arm the soft-ask. Resolves once a decision is made (or immediately when it should not run).
+ *
+ * Every early return is a case where asking would be wrong, not merely unnecessary:
+ *   • already `granted` — they are subscribed; a dialog would be noise
+ *   • already `denied`  — the browser prompt is unavailable, so "Allow" could not work. Offering a
+ *     button that cannot succeed is worse than offering nothing.
+ *   • snoozed           — they said not now, and meant it
+ */
+export declare function armSoftAsk(opts: SoftAskOptions, deps: SoftAskDeps): Promise<void>;
+//# sourceMappingURL=softAsk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"softAsk.d.ts","sourceRoot":"","sources":["../../../src/features/push/softAsk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA6FD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxC,uFAAuF;IACvF,UAAU,EAAE,MAAM,sBAAsB,CAAC;IACzC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCvF"}