@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/notifications/headless/useNotificationCapability.js

@@ -0,0 +1,411 @@
+/**
+ * CAN THIS DEVICE SHOW A BROWSER NOTIFICATION, AND IF NOT — WHAT FIXES IT?
+ *
+ * Issue #221, epic #215. A LAYER OVER `useBrowserNotificationPermission`, never
+ * a replacement for it: that hook still owns the one question the Web API
+ * actually answers ("what is `Notification.permission` right now?"). Neither
+ * hook requests permission — since #365 the shell's `usePushSubscriptionSync`
+ * does that, once per load, when push is enabled. This
+ * module adds the questions the Web API does not answer, which turn out to be
+ * the ones the user needs answered.
+ *
+ * =============================================================================
+ * WHY FOUR STATES WERE NOT ENOUGH
+ * =============================================================================
+ *
+ * `BrowserNotificationPermission` collapses `unsupported` over at least four
+ * genuinely different situations whose remedies have nothing in common:
+ *
+ *   * AN iOS SAFARI TAB. `window.Notification` is undefined there, so the
+ *     4-state hook says `unsupported` and the UI says "your browser does not
+ *     support notifications" — which is FALSE and, worse, unactionable. iOS
+ *     supports web notifications; it just only supports them for a web app the
+ *     user has ADDED TO THE HOME SCREEN. The remedy is Share → Add to Home
+ *     Screen, and a user told their browser is incapable will never find it.
+ *   * AN INSECURE CONTEXT. Plain HTTP has no `Notification` either, and it is
+ *     indistinguishable from a browser genuinely lacking the API — but the
+ *     remedy is "serve this over HTTPS", which is nobody's browser's fault.
+ *   * AN ADMINISTRATOR TURNED IT OFF. #225 shipped that switch. It had no
+ *     representation here at all, so the UI could only describe the browser's
+ *     opinion of a feature the server had already withdrawn.
+ *   * THE SERVICE WORKER DID NOT REGISTER (#218). DEGRADED, NOT BLOCKED — the
+ *     page-level `Notification` fallback may still work on desktop — so
+ *     rendering it as "blocked" would be as wrong as rendering it as "fine".
+ *
+ * Every one of those rendered identically before this file existed. The whole
+ * point of the 8-state union is that each arm names a DIFFERENT thing to do.
+ *
+ * =============================================================================
+ * THE PRECEDENCE ORDER, AND WHY IT IS THIS ORDER
+ * =============================================================================
+ *
+ * These conditions are not mutually exclusive — an iPad in a Safari tab on
+ * plain HTTP satisfies three of them at once — so the order is not a detail,
+ * it IS the behaviour. It is ordered by WHICH REMEDY IS WORTH SHOWING, i.e.
+ * outermost obstacle first: fixing an inner one while an outer one still holds
+ * changes nothing the user can see, so advertising the inner remedy first sends
+ * them off to do work that cannot possibly help.
+ *
+ *   1. `admin-disabled`    — an administrator kill switch makes EVERY
+ *                            downstream remedy unactionable. Telling somebody
+ *                            to install the app to the Home Screen, or to
+ *                            un-block the site, when the server will not send
+ *                            browser notifications to anyone, is wasted effort
+ *                            ending in a feature that still does nothing.
+ *   2. `insecure-context`  — over plain HTTP the APIs are not merely absent,
+ *                            they CANNOT be present. No browser change, no
+ *                            install, and no permission grant reaches them, so
+ *                            this outranks every capability question below it.
+ *   3. `unsupported`       — no `Notification` AND no `serviceWorker`. This is
+ *                            the genuinely hopeless case, and it is checked
+ *                            BEFORE the iOS arm on purpose: iOS Safari in a tab
+ *                            has NO `Notification` but DOES have
+ *                            `serviceWorker`, so requiring both to be missing
+ *                            is exactly what stops an iPhone from falling in
+ *                            here and being told the lie #221 exists to delete.
+ *   4. `ios-needs-install` — iOS/iPadOS, not installed. A real, specific,
+ *                            achievable remedy, and it must outrank the
+ *                            permission-shaped states below: on iOS there is no
+ *                            permission to grant until the app is installed, so
+ *                            "allow notifications" is not yet a thing that can
+ *                            be done.
+ *
+ * The remaining four are NOT a continuation of that list — they are decided
+ * TOGETHER, from the permission, because they are all permission-shaped:
+ *
+ *   5. `denied`            — the browser refused. Per-platform remedy, owned by
+ *                            the user, not by this app.
+ *   6. `default`           — not asked yet. The ONLY state in which the app may
+ *                            prompt — automatically (#365) or from a button.
+ *   7. `sw-unavailable`    — permission GRANTED, but no service worker
+ *                            registration. Delivery may be limited; see below.
+ *   8. `granted`           — permission granted and a worker is registered.
+ *
+ * =============================================================================
+ * WHY `sw-unavailable` SITS WITH THE PERMISSION ARMS AND NOT ABOVE THEM
+ * =============================================================================
+ *
+ * The obvious ordering — worker trouble outranks everything permission-shaped,
+ * since on Android the Notifications API is service-worker-only — was written
+ * first and is WRONG. It deadlocks a real user:
+ *
+ *   * The button that opens the browser's permission prompt renders in the
+ *     `default` state and nowhere else (see `NotificationSettings.tsx`).
+ *   * So if a missing registration preempted `default`, a user whose worker
+ *     failed to register could never reach the prompt, and therefore could
+ *     never move off `default` at all.
+ *   * And #222's `showAppNotification` tries `registration.showNotification()`
+ *     FIRST and falls back to `new Notification()` when there is no
+ *     registration — a fallback that exists precisely for this case. The
+ *     ordering would have made that fallback unreachable on every profile that
+ *     had not already granted permission: the capability model would be
+ *     forbidding the exact situation the delivery path is built to handle.
+ *
+ * `sw-unavailable` is DEGRADED, NOT BLOCKED — which is also why it is the one
+ * problem state that leaves its control enabled. It therefore describes a
+ * granted-but-degraded device, not a pre-permission one:
+ *
+ *     denied                          -\> denied
+ *     default                         -\> default          (prompt offered)
+ *     granted + no registration       -\> sw-unavailable   (degraded)
+ *     granted + registration          -\> granted
+ *
+ * Granting is a prerequisite for BOTH delivery paths, so offering the prompt in
+ * `default` costs nothing even when the worker is missing: the page-level
+ * `Notification` fallback can still use the result.
+ *
+ * `admin-disabled`, `insecure-context`, `unsupported` and `ios-needs-install`
+ * keep their position ahead of all four, because each is either genuinely
+ * unactionable or has a DIFFERENT remedy that must be done first — which is the
+ * distinction that justifies preempting the permission at all.
+ *
+ * =============================================================================
+ * DEFENSIVE POSTURE — INHERITED, NOT REINVENTED
+ * =============================================================================
+ *
+ * Same rules as the hook underneath: feature-detect BY ACCESS inside `try`
+ * (hardened browsers define these objects and throw on touching them), never
+ * throw out of a probe, and re-read rather than snapshot at module scope. The
+ * permission itself is not re-derived here at all — it is consumed from
+ * `useBrowserNotificationPermission`, which already tracks it through both
+ * `visibilitychange` and `navigator.permissions.query({name:'notifications'})`.
+ * Duplicating that tracking would give this file a second, subtly-different
+ * answer to a question that already has one.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { useBrowserNotificationPermission, } from './useBrowserNotificationPermission.js';
+/**
+ * The precedence order, executed. Pure — no globals, no React.
+ *
+ * Read top to bottom: this function IS the ordered list documented in the file
+ * header, and the two must never disagree.
+  *
+  * @stability experimental
+ */
+export function resolveNotificationCapability(inputs) {
+    // 1. The kill switch outranks everything: no remedy below it can produce a
+    //    notification while it is on.
+    if (inputs.adminDisabled)
+        return 'admin-disabled';
+    // 2. Plain HTTP. The APIs below cannot exist here regardless of browser.
+    if (!inputs.isSecureContext)
+        return 'insecure-context';
+    // 3. Genuinely nothing to work with. BOTH must be missing — an iOS Safari
+    //    tab has `serviceWorker` but no `Notification`, and must reach the arm
+    //    below rather than being told its browser is incapable.
+    if (!inputs.hasNotificationApi && !inputs.hasServiceWorkerApi)
+        return 'unsupported';
+    // 4. iOS only grants notifications to an installed web app.
+    if (inputs.isIos && !inputs.isStandalone)
+        return 'ios-needs-install';
+    // 5-8. THE PERMISSION-SHAPED STATES, decided together.
+    //
+    // A permission that cannot be READ at this point (a browser with
+    // `serviceWorker` but no usable `Notification`, which rule 3 deliberately let
+    // through) is honestly reported as unsupported: there is no other
+    // permission-shaped answer to give.
+    if (inputs.permission === 'unsupported')
+        return 'unsupported';
+    // `denied` and `default` are reported REGARDLESS of the worker. `default` in
+    // particular must survive a missing registration, or the user can never reach
+    // the prompt and therefore never leaves `default` — see the header. Granting
+    // is a prerequisite for both delivery paths, including #222's page-level
+    // `new Notification()` fallback, which exists for exactly this case.
+    if (inputs.permission !== 'granted')
+        return inputs.permission;
+    // Granted. NOW the worker matters: it is the only thing that can still
+    // degrade delivery, and on Android it is the only path at all.
+    if (!inputs.hasServiceWorkerRegistration)
+        return 'sw-unavailable';
+    return 'granted';
+}
+// =============================================================================
+// Environment probes — every one of them non-throwing
+// =============================================================================
+/**
+ * Is this a secure context?
+ *
+ * ONLY AN EXPLICIT `false` COUNTS. `window.isSecureContext` is `undefined` in
+ * environments that never implemented it — jsdom under this repo's test runner,
+ * and browsers old enough to predate the flag — and `!undefined` would send
+ * every one of them to "switch to HTTPS", which is the wrong remedy stated with
+ * total confidence. Nothing is lost by the leniency: every browser that has a
+ * `Notification` constructor also has this flag, so an environment that lacks
+ * it falls through to `unsupported` a line later, which is the honest answer.
+  *
+  * @stability experimental
+ */
+export function readIsSecureContext() {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        return window.isSecureContext !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Is there a `Notification` constructor, and is touching it safe?
+ *
+ * @stability experimental
+ */
+export function readHasNotificationApi() {
+    if (typeof window === 'undefined' || !('Notification' in window))
+        return false;
+    try {
+        // THE ACCESS IS THE TEST, not the presence of the key — some embedded and
+        // privacy-hardened browsers expose `Notification` and throw here. Same
+        // defence as `useBrowserNotificationPermission.readPermission`.
+        void window.Notification.permission;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is there a `navigator.serviceWorker`?
+ *
+ * @stability experimental
+ */
+export function readHasServiceWorkerApi() {
+    try {
+        return typeof navigator !== 'undefined' && 'serviceWorker' in navigator;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * iPhone / iPod / iPad — INCLUDING an iPad that says it is a Mac.
+ *
+ * =============================================================================
+ * WHY A NAIVE USER-AGENT TEST IS WRONG HERE
+ * =============================================================================
+ *
+ * Since iPadOS 13, Safari on iPad requests desktop sites BY DEFAULT and reports
+ * a Macintosh user agent with `navigator.platform === 'MacIntel'`. There is no
+ * "iPad" substring left to match on. So `/iPad|iPhone|iPod/.test(userAgent)` —
+ * the idiom every older answer suggests — silently classifies every modern iPad
+ * as a desktop Mac, which is precisely the device most likely to be browsing in
+ * a tab and most in need of the "Add to Home Screen" remedy. The bug would only
+ * ever appear on hardware the developer does not have.
+ *
+ * The standard separator is TOUCH: no Mac reports more than one touch point
+ * (they report 0, including Macs with a Touch Bar, because that is not a
+ * touchscreen for the purposes of this API), while every iPad reports 5. So a
+ * Mac-like platform WITH multi-touch is an iPad, and it is the only thing it
+ * can be.
+ *
+ * `navigator.platform` is deprecated but not removed and remains the reliable
+ * signal for exactly this check; `userAgentData` deliberately does not expose
+ * enough to replace it, and Safari does not implement it at all. Both signals
+ * are read, so a UA-spoofing extension that changes one of them still lands on
+ * the right answer as long as the other is intact.
+  *
+  * @stability experimental
+ */
+export function readIsIos() {
+    try {
+        if (typeof navigator === 'undefined')
+            return false;
+        const platform = typeof navigator.platform === 'string' ? navigator.platform : '';
+        const userAgent = typeof navigator.userAgent === 'string' ? navigator.userAgent : '';
+        // iPhone and iPod still identify themselves honestly, and so does an iPad
+        // that has been switched to "Request Mobile Website".
+        if (/iPad|iPhone|iPod/.test(platform) || /iPad|iPhone|iPod/.test(userAgent)) {
+            return true;
+        }
+        // The iPadOS-as-Mac case. Touch is the discriminator; see above.
+        const isMacLike = platform === 'MacIntel' || /Mac/.test(platform) || /Macintosh/.test(userAgent);
+        const touchPoints = typeof navigator.maxTouchPoints === 'number' ? navigator.maxTouchPoints : 0;
+        return isMacLike && touchPoints > 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is this an installed web app rather than a browser tab?
+ *
+ * Two signals because neither is universal: `display-mode: standalone` is the
+ * standard and is what Chrome/Edge/Android answer, while `navigator.standalone`
+ * is Safari's own non-standard flag and is the ONLY one older iOS answers — and
+ * iOS is the entire reason this function exists.
+  *
+  * @stability experimental
+ */
+export function readIsStandalone() {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        if (window.matchMedia?.('(display-mode: standalone)').matches)
+            return true;
+    }
+    catch {
+        // A matchMedia that throws (or is absent) is not evidence either way; fall
+        // through to the Safari flag below.
+    }
+    try {
+        // Non-standard, Safari-only, and absent everywhere else — hence the cast
+        // rather than a lib declaration this app would then have to maintain.
+        return navigator.standalone === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function useNotificationCapability(options = {}) {
+    const { adminDisabled = false } = options;
+    // THE PERMISSION IS NOT RE-DERIVED HERE. This hook consumes the existing one
+    // whole — including its `visibilitychange` and Permissions API `change`
+    // tracking — so there is exactly one implementation of "what does the browser
+    // say".
+    const { permission, refresh: refreshPermission } = useBrowserNotificationPermission();
+    const [swPresence, setSwPresence] = useState('unknown');
+    // Bumped by `refresh()` to re-run the registration probe below. A counter
+    // rather than a boolean so consecutive refreshes each trigger one.
+    const [swProbe, setSwProbe] = useState(0);
+    const refresh = useCallback(() => {
+        refreshPermission();
+        setSwProbe((n) => n + 1);
+    }, [refreshPermission]);
+    useEffect(() => {
+        if (!readHasServiceWorkerApi()) {
+            setSwPresence('absent');
+            return;
+        }
+        let cancelled = false;
+        const check = () => {
+            try {
+                // A controlling worker is proof of registration and needs no await —
+                // which also means the common case never renders the 'unknown' state
+                // for a frame.
+                if (navigator.serviceWorker.controller) {
+                    if (!cancelled)
+                        setSwPresence('present');
+                    return;
+                }
+                void navigator.serviceWorker
+                    .getRegistration()
+                    .then((registration) => {
+                    if (!cancelled)
+                        setSwPresence(registration ? 'present' : 'absent');
+                })
+                    .catch(() => {
+                    // Registration lookup can reject outright — a blocked or
+                    // partitioned storage context, notably. Treated as absent: that is
+                    // the DEGRADED arm, not a blocked one, so guessing wrong here costs
+                    // an explanatory note rather than a disabled control.
+                    if (!cancelled)
+                        setSwPresence('absent');
+                });
+            }
+            catch {
+                if (!cancelled)
+                    setSwPresence('absent');
+            }
+        };
+        check();
+        // The worker may finish registering AFTER this page mounted — the
+        // `registerSW.js` injected by vite-plugin-pwa registers on window load —
+        // so a one-shot check at mount would report `sw-unavailable` on a cold
+        // first visit and never take it back.
+        const onControllerChange = () => check();
+        try {
+            navigator.serviceWorker.addEventListener('controllerchange', onControllerChange);
+        }
+        catch {
+            // Nothing to fall back to; the mount-time answer stands.
+        }
+        return () => {
+            cancelled = true;
+            try {
+                navigator.serviceWorker.removeEventListener('controllerchange', onControllerChange);
+            }
+            catch {
+                // Removing a listener that was never added is not an error worth
+                // taking a settings page down for.
+            }
+        };
+    }, [swProbe]);
+    // Computed on every render rather than held in state. These facts are read
+    // from live globals and are cheap; snapshotting them would add a second
+    // source of truth that can only ever be more stale than the globals it copies
+    // — and `display-mode` in particular changes when an installed app is
+    // launched.
+    const capability = resolveNotificationCapability({
+        adminDisabled,
+        isSecureContext: readIsSecureContext(),
+        hasNotificationApi: readHasNotificationApi(),
+        hasServiceWorkerApi: readHasServiceWorkerApi(),
+        isIos: readIsIos(),
+        isStandalone: readIsStandalone(),
+        // 'unknown' reports as PRESENT — see `ServiceWorkerPresence`.
+        hasServiceWorkerRegistration: swPresence !== 'absent',
+        permission,
+    });
+    return { capability, permission, refresh };
+}
+//# sourceMappingURL=useNotificationCapability.js.map

package/dist/notifications/headless/useNotificationCapability.js.map

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

package/dist/notifications/headless/useNotificationChannels.d.ts

@@ -0,0 +1,39 @@
+import type { NotificationChannelDescriptor } from './types.js';
+/**
+ * What {@link useNotificationChannels} returns.
+ *
+ * @stability experimental
+ */
+export interface UseNotificationChannelsReturn {
+    /**
+     * The registered channels, in registration order (`order`), never re-sorted
+     * here. `null` until the first read resolves, which is not `[]`: an empty
+     * array is a real answer ("this deployment registers no channels"), `null`
+     * means "not known yet" (or the read failed: see `error`).
+     */
+    channels: NotificationChannelDescriptor[] | null;
+    /** A read is in flight. */
+    isLoading: boolean;
+    /** The failure message of the last read, or `null`. */
+    error: string | null;
+    /** Reads again. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Reads `GET /api/notifications/channels`: the channels, their labels and the
+ * flags the broadcast composer and the preferences matrix apply. The bundle
+ * holds no list of its own, so an app's channel appears with no edit here.
+ *
+ * @returns the descriptors and the read's state.
+ *
+ * @example
+ * ```tsx
+ * const { channels } = useNotificationChannels();
+ * const label = channels?.find((channel) => channel.id === 'slack')?.label ?? 'slack';
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useNotificationChannels(): UseNotificationChannelsReturn;
+//# sourceMappingURL=useNotificationChannels.d.ts.map

package/dist/notifications/headless/useNotificationChannels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNotificationChannels.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/useNotificationChannels.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAGhE;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,QAAQ,EAAE,6BAA6B,EAAE,GAAG,IAAI,CAAC;IACjD,2BAA2B;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mBAAmB;IACnB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,IAAI,6BAA6B,CA2BvE"}

package/dist/notifications/headless/useNotificationChannels.js

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useState } from 'react';
+import { ApiError, getNotificationChannels } from './api.js';
+import { useIsMounted } from './useIsMounted.js';
+/**
+ * Reads `GET /api/notifications/channels`: the channels, their labels and the
+ * flags the broadcast composer and the preferences matrix apply. The bundle
+ * holds no list of its own, so an app's channel appears with no edit here.
+ *
+ * @returns the descriptors and the read's state.
+ *
+ * @example
+ * ```tsx
+ * const { channels } = useNotificationChannels();
+ * const label = channels?.find((channel) => channel.id === 'slack')?.label ?? 'slack';
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useNotificationChannels() {
+    const [channels, setChannels] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    const fetchChannels = useCallback(async () => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const data = await getNotificationChannels();
+            if (isMounted())
+                setChannels([...data].sort((a, b) => a.order - b.order));
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(err instanceof ApiError ? err.message : 'Failed to load notification channels');
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [isMounted]);
+    useEffect(() => {
+        void fetchChannels();
+    }, [fetchChannels]);
+    return { channels, isLoading, error, refresh: fetchChannels };
+}
+//# sourceMappingURL=useNotificationChannels.js.map

package/dist/notifications/headless/useNotificationChannels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNotificationChannels.js","sourceRoot":"","sources":["../../../src/notifications/headless/useNotificationChannels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAuBjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAyC,IAAI,CAAC,CAAC;IACvF,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,MAAM,aAAa,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QAC3C,IAAI,CAAC;YACH,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,uBAAuB,EAAE,CAAC;YAC7C,IAAI,SAAS,EAAE;gBAAE,WAAW,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,EAAE,EAAE,CAAC;gBAChB,QAAQ,CAAC,GAAG,YAAY,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,SAAS,EAAE;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,aAAa,EAAE,CAAC;IACvB,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IAEpB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;AAChE,CAAC"}

package/dist/notifications/headless/useNotificationConfig.d.ts

@@ -0,0 +1,46 @@
+/**
+ * This deployment's client-facing notification capabilities, read from the API.
+ *
+ * Issue #227, epic #215. Deliberately a plain fetch hook in the shape of
+ * `useNotificationEvents` — same `isMounted` discipline, same "error is a
+ * string the page renders" contract, same "not cached across mounts" choice —
+ * because that is all this is: one GET of a small, per-deployment capability
+ * projection.
+ *
+ * WHY A DEDICATED HOOK RATHER THAN INLINING `useState`/`useEffect` ON THE PAGE
+ * -----------------------------------------------------------------------------
+ * `UserNotificationsPage` already fetches one adjacent thing this way
+ * (`useNotificationEvents`), and this config read has the exact same shape —
+ * fetch on mount, loading/error/data, no params, no cache. Mirroring that
+ * pattern here keeps the page's two independent fetches symmetrical instead of
+ * one being a hook and the other a hand-rolled effect for no reason other than
+ * which issue happened to add it.
+ *
+ * WHY THE DEFAULT MATTERS WHILE LOADING
+ * -----------------------------------------------------------------------------
+ * `useNotificationCapability`'s own `adminDisabled` option already defaults to
+ * `false` ("not disabled") for exactly this reason: this hook's `config` is
+ * `null` until the first read resolves, and the caller must not treat that as
+ * "disabled". `!config?.browserEnabled` would get this backwards — it reads
+ * `true` (disabled) during the loading window, which is the one thing the
+ * issue this hook exists for says must not happen: it would flicker the
+ * "Allow notifications" button (or the admin-disabled banner) in and out on
+ * every page load. The correct read is
+ * `config ? !config.browserEnabled : false`, or equivalently `config?.browserEnabled === false` — see the call
+ * site in `pages/UserNotificationsPage.tsx`.
+ */
+import type { NotificationConfigResponse } from './types.js';
+interface UseNotificationConfigReturn {
+    /**
+     * `null` until the first read resolves — NOT the same as "browser
+     * notifications disabled". See the file header: callers must treat a `null`
+     * config as "we do not know yet", never as `adminDisabled: true`.
+     */
+    config: NotificationConfigResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+}
+export declare function useNotificationConfig(): UseNotificationConfigReturn;
+export {};
+//# sourceMappingURL=useNotificationConfig.d.ts.map

package/dist/notifications/headless/useNotificationConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNotificationConfig.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/useNotificationConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAG7D,UAAU,2BAA2B;IACnC;;;;OAIG;IACH,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAgB,qBAAqB,IAAI,2BAA2B,CAgCnE"}

package/dist/notifications/headless/useNotificationConfig.js

@@ -0,0 +1,66 @@
+/**
+ * This deployment's client-facing notification capabilities, read from the API.
+ *
+ * Issue #227, epic #215. Deliberately a plain fetch hook in the shape of
+ * `useNotificationEvents` — same `isMounted` discipline, same "error is a
+ * string the page renders" contract, same "not cached across mounts" choice —
+ * because that is all this is: one GET of a small, per-deployment capability
+ * projection.
+ *
+ * WHY A DEDICATED HOOK RATHER THAN INLINING `useState`/`useEffect` ON THE PAGE
+ * -----------------------------------------------------------------------------
+ * `UserNotificationsPage` already fetches one adjacent thing this way
+ * (`useNotificationEvents`), and this config read has the exact same shape —
+ * fetch on mount, loading/error/data, no params, no cache. Mirroring that
+ * pattern here keeps the page's two independent fetches symmetrical instead of
+ * one being a hook and the other a hand-rolled effect for no reason other than
+ * which issue happened to add it.
+ *
+ * WHY THE DEFAULT MATTERS WHILE LOADING
+ * -----------------------------------------------------------------------------
+ * `useNotificationCapability`'s own `adminDisabled` option already defaults to
+ * `false` ("not disabled") for exactly this reason: this hook's `config` is
+ * `null` until the first read resolves, and the caller must not treat that as
+ * "disabled". `!config?.browserEnabled` would get this backwards — it reads
+ * `true` (disabled) during the loading window, which is the one thing the
+ * issue this hook exists for says must not happen: it would flicker the
+ * "Allow notifications" button (or the admin-disabled banner) in and out on
+ * every page load. The correct read is
+ * `config ? !config.browserEnabled : false`, or equivalently `config?.browserEnabled === false` — see the call
+ * site in `pages/UserNotificationsPage.tsx`.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { ApiError, getNotificationConfig } from './api.js';
+import { useIsMounted } from './useIsMounted.js';
+export function useNotificationConfig() {
+    const [config, setConfig] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Every `setState` past an `await` is guarded: a request that settles after
+    // the component is gone must not schedule an update on it. Same rule as the
+    // other fetch hooks in this directory.
+    const isMounted = useIsMounted();
+    const fetchConfig = useCallback(async () => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const data = await getNotificationConfig();
+            if (isMounted())
+                setConfig(data);
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(err instanceof ApiError ? err.message : 'Failed to load notification config');
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [isMounted]);
+    useEffect(() => {
+        void fetchConfig();
+    }, [fetchConfig]);
+    return { config, isLoading, error, refresh: fetchConfig };
+}
+//# sourceMappingURL=useNotificationConfig.js.map

package/dist/notifications/headless/useNotificationConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNotificationConfig.js","sourceRoot":"","sources":["../../../src/notifications/headless/useNotificationConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAcjD,MAAM,UAAU,qBAAqB;IACnC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAoC,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,4EAA4E;IAC5E,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;IAEjC,MAAM,WAAW,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACzC,IAAI,CAAC;YACH,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,qBAAqB,EAAE,CAAC;YAC3C,IAAI,SAAS,EAAE;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,SAAS,EAAE,EAAE,CAAC;gBAChB,QAAQ,CACN,GAAG,YAAY,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,oCAAoC,CAC7E,CAAC;YACJ,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,SAAS,EAAE;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,WAAW,EAAE,CAAC;IACrB,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AAC5D,CAAC"}