@mpgd/adapter-capacitor 0.10.0 → 0.11.0

package/dist/notifications-provider.js

@@ -0,0 +1,1023 @@
+import { App } from '@capacitor/app';
+import { assertLocalNotificationRequest, isRootRelativeNotificationRoute, normalizeNotificationTimestamp, notificationAdvertisingOptOutActionId, NotificationError, } from '@mpgd/platform/notifications';
+// The Capacitor notifications v2 provider (notifications RFC "Provider
+// profiles", Capacitor): app-scope OS permission, FCM device endpoints, local
+// reminders through `@capacitor/local-notifications`, and opens from the
+// notification payload. It never sends and never grants: a remote push comes
+// only from the backend, and an open is routing data.
+/** The reference provider id the backend's FCM registry entry uses. */
+export const capacitorNotificationProviderId = 'fcm';
+/**
+ * The notification category (iOS) and action type that carries the
+ * advertising opt-out action. An FCM send for an advertising topic names it
+ * (`apns.payload.aps.category`) so iOS shows the action.
+ */
+export const capacitorAdvertisingActionTypeId = 'mpgd-advertising';
+/**
+ * Keys of the push data the provider reads. A send carries the topic and the
+ * topic's root-relative route in them; every other string entry reaches the
+ * game as the open's untrusted `data`.
+ */
+export const capacitorNotificationDataKeys = Object.freeze({
+    topic: 'topic',
+    route: 'route',
+});
+/** iOS keeps at most 64 pending local notifications per app. */
+export const capacitorIosMaxPendingLocalNotifications = 64;
+/** How long `openSettings` waits for the app to leave for the settings screen. */
+export const capacitorSettingsLeaveTimeoutMs = 5_000;
+/** How long `openSettings` waits for the player to come back from settings. */
+export const capacitorSettingsReturnTimeoutMs = 120_000;
+const defaultChannels = {
+    service: { name: 'Notifications' },
+    requested: { name: 'Reminders' },
+    advertising: { name: 'Promotions' },
+};
+const extraKeys = Object.freeze({
+    key: 'mpgdKey',
+    topic: 'mpgdTopic',
+    fireAt: 'mpgdFireAt',
+    route: 'mpgdRoute',
+});
+/** Push data keys that are not the game's: the provider's own and the transport's. */
+const reservedDataKey = /^(?:topic|route|from|collapse_key|aps|fcm_options)$|^(?:google|gcm)\./u;
+const eventBufferLimit = 64;
+const maxNativeId = 0x7f_ff_ff_ff;
+/**
+ * The Android channel a topic posts to: its mapping's `channelId`, or the
+ * default channel of its purpose (`mpgd-service`, `mpgd-requested`,
+ * `mpgd-advertising`), so advertising stays in a channel of its own that the
+ * player can turn off in system settings.
+ */
+export function capacitorNotificationChannelId(topic) {
+    const mapped = topic.mapping?.['channelId'];
+    return typeof mapped === 'string' && mapped !== '' ? mapped : `mpgd-${topic.purpose}`;
+}
+/**
+ * The native id of a local reminder key: a stable positive 32-bit integer
+ * (FNV-1a), as Android requires. The provider probes the next id when another
+ * pending reminder already holds it, and finds reminders by the key it stores
+ * in `extra`, so a collision never replaces another reminder.
+ */
+export function capacitorLocalNotificationId(key) {
+    let hash = 0x81_1c_9d_c5;
+    for (const unit of new TextEncoder().encode(key)) {
+        hash ^= unit;
+        hash = Math.imul(hash, 0x01_00_01_93) >>> 0;
+    }
+    return (hash % maxNativeId) + 1;
+}
+/**
+ * Creates the Capacitor notifications provider over the two plugin SDKs.
+ *
+ * - **Listeners first.** It registers every native listener synchronously,
+ *   before any `await`, and keeps them for the process lifetime: Capacitor
+ *   retains a plugin's events only until its first native listener, so a
+ *   cold-start open reaches this provider, which keeps it for its first
+ *   subscriber.
+ * - **Permission.** It reads `LocalNotifications.checkPermissions`, which
+ *   reflects the system setting on every Android version, and maps the OS
+ *   `denied` to `blocked`: on iOS after the one denial, on Android after the
+ *   second. Only `requestPermission` shows the OS dialog; `scheduleLocal`
+ *   answers `permission-required` instead.
+ * - **Local reminders.** Inexact (`isExactNotification: false`), on the
+ *   topic's channel, at most 64 pending on iOS, keeping the nearest, one
+ *   operation at a time. A `fireAt` already past posts at once, as both
+ *   plugins do.
+ * - **Fails closed.** Without either SDK the provider is `unsupported`;
+ *   without `push` it declares no remote delivery, without `local` no local
+ *   reminders.
+ */
+export function createCapacitorNotificationProvider(input) {
+    const { push, local, platform } = input;
+    const providerId = input.provider ?? capacitorNotificationProviderId;
+    const topics = [...input.topics];
+    const topicById = new Map(topics.map((topic) => [topic.id, topic]));
+    /**
+     * The topic this target maps. A topic the catalog declares without a
+     * mapping for this target, as `resolveNotificationTopicsForTarget` keeps
+     * it, is not available here: it reads `unsupported`, a request answers
+     * `unavailable`, it schedules nothing, gets no channel, and an open naming
+     * it carries no topic, as the reference runtime treats it.
+     */
+    const mappedTopic = (id) => {
+        const declared = id === undefined ? undefined : topicById.get(id);
+        return declared?.mapping === undefined ? undefined : declared;
+    };
+    const mappedTopics = topics.filter((topic) => topic.mapping !== undefined);
+    const channels = collectChannels(mappedTopics, input.channels ?? {});
+    const unsupported = push === undefined && local === undefined;
+    // RFC "Advertising rules": an advertising push carries the opt-out action,
+    // which this provider registers through the local plugin (the iOS
+    // category, and the action type a shell renders on Android). Without it,
+    // remote advertising would go out without the action, so the provider is
+    // `configuration-required`, as a registry mismatch makes a provider.
+    const optOutMissing = push !== undefined && local === undefined
+        && mappedTopics.some((topic) => topic.purpose === 'advertising');
+    const configurationIssue = optOutMissing
+        ? 'Capacitor notifications: the catalog maps an advertising topic, whose opt-out action '
+            + 'needs @capacitor/local-notifications; install both plugins.'
+        : undefined;
+    const assertConfigured = () => {
+        if (configurationIssue !== undefined) {
+            throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+                message: configurationIssue,
+            });
+        }
+    };
+    const promptLimit = platform === 'ios' ? 1 : (input.androidPromptLimit ?? 2);
+    const app = input.app === undefined ? App : input.app;
+    const reportError = (error) => {
+        try {
+            if (input.onError === undefined) {
+                console.warn('Capacitor notifications provider failed.', error);
+            }
+            else {
+                input.onError(error);
+            }
+        }
+        catch {
+            // Reporting must not break the native listener that failed.
+        }
+    };
+    // Events.
+    const listeners = new Set();
+    const buffer = [];
+    let subscribed = false;
+    // Events wait whenever no listener is attached, not only before the first:
+    // the gateway's bridge detaches when its last listener leaves, so a game
+    // that subscribes per scene would otherwise lose an open between scenes.
+    function deliver(event, targets) {
+        for (const target of targets) {
+            try {
+                target(event);
+            }
+            catch (error) {
+                reportError(error);
+            }
+        }
+    }
+    let draining = false;
+    const dispatch = (event) => {
+        if (listeners.size === 0 || draining) {
+            // A receipt is worth nothing once the scene that showed it is gone; the
+            // opens, endpoint and permission changes are kept.
+            if (subscribed && !draining && event.type === 'received') {
+                return;
+            }
+            buffer.push(event);
+            if (buffer.length > eventBufferLimit) {
+                // Keep the opens: a cold-start open must not be lost to later events.
+                const evicted = buffer.findIndex((buffered) => buffered.type !== 'opened');
+                buffer.splice(evicted === -1 ? 0 : evicted, 1);
+            }
+            return;
+        }
+        deliver(event, [...listeners]);
+    };
+    // Permission. It is read from the local plugin, which reflects the system
+    // setting on every Android version, and asked through the push plugin,
+    // which also registers with APNs on iOS.
+    let checkPermission;
+    if (local !== undefined) {
+        checkPermission = async () => (await local.checkPermissions()).display;
+    }
+    else if (push !== undefined) {
+        // Without the local plugin, Android 12 and lower read granted whatever
+        // the system setting is: the push plugin cannot tell.
+        checkPermission = async () => (await push.checkPermissions()).receive;
+    }
+    let askPermission;
+    if (push !== undefined) {
+        askPermission = async () => (await push.requestPermissions()).receive;
+    }
+    else if (local !== undefined) {
+        askPermission = async () => (await local.requestPermissions()).display;
+    }
+    let tokenFailureReported = false;
+    let lastObserved;
+    /**
+     * The OS dialog in flight, whose answer settles `lastObserved`; a request
+     * made while it is up shares it, so a double tap never asks twice.
+     */
+    let requesting;
+    /** The answer of the last dialog that settled. */
+    let lastAnswer;
+    /** Whether a dialog that started after `generation` was taken has answered since. */
+    const answeredSince = (generation) => lastAnswer !== undefined && lastAnswer.request > generation;
+    /** Counts requests, so a read that overlapped one cannot settle `lastObserved` after it. */
+    let requests = 0;
+    const readAppState = async () => {
+        if (checkPermission === undefined) {
+            return 'unsupported';
+        }
+        const generation = requests;
+        const duringDialog = requesting !== undefined;
+        const state = await callSdk(checkPermission);
+        const mapped = toPermissionState(state);
+        // Only the request's own answer settles a request, so a read that began
+        // before or during the dialog cannot overwrite that answer, even when it
+        // finishes after the request did.
+        if (!duringDialog && requesting === undefined && !answeredSince(generation)) {
+            lastObserved = mapped;
+        }
+        return mapped;
+    };
+    const snapshotOf = (requested, state) => ({
+        app: state,
+        topics: Object.fromEntries(requested.map((topic) => [topic, mappedTopic(topic) === undefined ? 'unsupported' : state])),
+    });
+    // Settings round trips and permission changes made outside the game.
+    const appStateWaiters = new Set();
+    // One check at a time, each against the state the one before it read, so
+    // two quick returns announce one change once.
+    let resumeCheck = Promise.resolve();
+    const onAppState = (active) => {
+        for (const waiter of [...appStateWaiters]) {
+            waiter(active);
+        }
+        if (!active || unsupported) {
+            return;
+        }
+        // A push-only provider has no local reminder to retry the setup from.
+        ensureChannels().catch(reportSetupFailure);
+        ensureActionTypes().catch(reportSetupFailure);
+        resumeCheck = resumeCheck.then(async () => {
+            const before = lastObserved;
+            const generation = requests;
+            // A request's own dialog also takes the app out of the foreground (the
+            // iOS alert, the Android permission activity); the request reports that
+            // answer itself.
+            if (before === undefined || requesting !== undefined) {
+                return;
+            }
+            const state = await readAppState();
+            // A request that began, or even ended, during the read reports its own
+            // answer.
+            if (state !== before && requesting === undefined && !answeredSince(generation)) {
+                // Changed in system settings: no plugin reports it as an event.
+                dispatch({
+                    type: 'permission-changed',
+                    // Every declared topic; `snapshotOf` reads the unmapped ones `unsupported`.
+                    snapshot: snapshotOf(topics.map((topic) => topic.id), state),
+                });
+            }
+        }).catch(reportError);
+    };
+    const registrationWith = (value, permission) => {
+        const timeZone = (input.timeZone ?? defaultTimeZone)();
+        const locale = (input.locale ?? defaultLocale)();
+        return {
+            provider: providerId,
+            // FCM tokens only: `fcm-installation` addresses are reserved, because
+            // FCM HTTP v1 cannot send to a Firebase installation id and the
+            // game-services sender refuses them.
+            address: { kind: 'fcm-token', value, permission },
+            ...(locale === undefined || locale === '' ? {} : { locale }),
+            ...(timeZone === undefined || timeZone === '' ? {} : { timeZone }),
+        };
+    };
+    const registrationOf = async (value) => registrationWith(value, await readAppState());
+    /** The declared topic a push names; the payload is untrusted. */
+    const declaredTopicOf = (data) => {
+        return mappedTopic(stringOf(data[capacitorNotificationDataKeys.topic]));
+    };
+    const openedFromPush = (actionId, notification) => {
+        const data = isRecord(notification?.data) ? notification.data : {};
+        const declared = declaredTopicOf(data);
+        const topicId = declared?.id;
+        // The opt-out action opens the topic's declared opt-out screen, never a
+        // route from the payload.
+        let route;
+        if (actionId !== notificationAdvertisingOptOutActionId) {
+            route = safeRoute(data[capacitorNotificationDataKeys.route]);
+        }
+        else if (declared?.purpose === 'advertising') {
+            route = declared.optOutRoute;
+        }
+        const extra = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (typeof value === 'string' && !reservedDataKey.test(key)) {
+                extra[key] = value;
+            }
+        }
+        dispatch({
+            type: 'opened',
+            channel: 'remote',
+            source: subscribed ? 'warm' : 'cold',
+            ...(topicId === undefined ? {} : { topic: topicId }),
+            ...(route === undefined ? {} : { route }),
+            ...(Object.keys(extra).length === 0 ? {} : { data: extra }),
+        });
+    };
+    const openedFromLocal = (actionId, notification) => {
+        const entry = readLocalEntry(notification);
+        if (entry === undefined || actionId === 'dismiss') {
+            // Not one of this provider's reminders, or not an open.
+            return;
+        }
+        const topic = mappedTopic(entry.topic)?.id;
+        dispatch({
+            type: 'opened',
+            channel: 'local',
+            source: subscribed ? 'warm' : 'cold',
+            ...(topic === undefined ? {} : { topic }),
+            ...(entry.route === undefined ? {} : { route: entry.route }),
+        });
+    };
+    // Native listeners: synchronously, before any await, and never removed,
+    // because the provider lives as long as the process.
+    const listen = (register) => {
+        try {
+            register().catch(reportError);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+    if (push !== undefined) {
+        listen(() => push.addListener('tokenReceived', (event) => {
+            // A configuration-required provider announces no address, as it
+            // registers none: the backend must not reach this device yet.
+            if (configurationIssue !== undefined || typeof event.token !== 'string'
+                || event.token === '') {
+                return;
+            }
+            const { token } = event;
+            tokenFailureReported = false;
+            // A rotated token goes out at once, with the permission this provider
+            // last read: a permission changes only in system settings, and the
+            // return from there reads it again. During a request (iOS issues the
+            // first token right after the grant) it waits for that answer, and
+            // before any read it reads first.
+            if (lastObserved !== undefined && requesting === undefined) {
+                dispatch({ type: 'endpoint-changed', registration: registrationWith(token, lastObserved) });
+                return;
+            }
+            void (requesting ?? Promise.resolve())
+                .catch(() => undefined)
+                .then(() => (lastObserved === undefined
+                ? registrationOf(token)
+                : registrationWith(token, lastObserved)))
+                .then((registration) => dispatch({ type: 'endpoint-changed', registration }), reportError);
+        }));
+        listen(() => push.addListener('notificationReceived', (event) => {
+            const data = isRecord(event?.notification?.data) ? event.notification.data : {};
+            const topic = declaredTopicOf(data)?.id;
+            dispatch({ type: 'received', channel: 'remote', ...(topic === undefined ? {} : { topic }) });
+        }));
+        listen(() => push.addListener('notificationActionPerformed', (event) => {
+            openedFromPush(actionIdOf(event), event?.notification);
+        }));
+    }
+    if (local !== undefined) {
+        listen(() => local.addListener('localNotificationReceived', (notification) => {
+            const entry = readLocalEntry(notification);
+            if (entry !== undefined) {
+                const topic = mappedTopic(entry.topic)?.id;
+                dispatch({
+                    type: 'received',
+                    channel: 'local',
+                    ...(topic === undefined ? {} : { topic }),
+                });
+            }
+        }));
+        listen(() => local.addListener('localNotificationActionPerformed', (event) => {
+            openedFromLocal(actionIdOf(event), event?.notification);
+        }));
+    }
+    if (app !== null && !unsupported) {
+        listen(() => app.addListener('appStateChange', (state) => onAppState(state.isActive)));
+    }
+    // Native setup: the Android channels and the opt-out action type. A remote
+    // push needs its channel before it arrives, so both start now. Each is kept
+    // only once it succeeded. A failure is tried again on the next local
+    // reminder, which needs the channels and fails until they exist, and on
+    // each return to the foreground; it is reported once until a try succeeds.
+    let setupFailureReported = false;
+    const reportSetupFailure = (error) => {
+        if (!setupFailureReported) {
+            setupFailureReported = true;
+            reportError(error);
+        }
+    };
+    let channelsReady;
+    const ensureChannels = () => {
+        channelsReady ??= (async () => {
+            if (platform !== 'android') {
+                return;
+            }
+            const createChannel = local === undefined
+                ? push?.createChannel?.bind(push)
+                : local.createChannel.bind(local);
+            if (createChannel === undefined) {
+                return;
+            }
+            for (const channel of channels) {
+                await createChannel(channel);
+            }
+            setupFailureReported = false;
+        })().catch((error) => {
+            channelsReady = undefined;
+            throw error;
+        });
+        return channelsReady;
+    };
+    let actionTypesReady;
+    // The call sets every iOS category at once, so a catalog without
+    // advertising leaves the shell's categories alone.
+    const needsOptOut = mappedTopics.some((topic) => topic.purpose === 'advertising');
+    const ensureActionTypes = () => {
+        if (!needsOptOut) {
+            return Promise.resolve();
+        }
+        actionTypesReady ??= Promise.resolve()
+            .then(async () => {
+            if (local === undefined) {
+                return;
+            }
+            await local.registerActionTypes({
+                types: [{
+                        id: capacitorAdvertisingActionTypeId,
+                        actions: [{
+                                id: notificationAdvertisingOptOutActionId,
+                                title: input.advertisingOptOutTitle ?? '수신거부',
+                                foreground: true,
+                            }],
+                    }],
+            });
+            setupFailureReported = false;
+        })
+            .catch((error) => {
+            actionTypesReady = undefined;
+            throw error;
+        });
+        return actionTypesReady;
+    };
+    if (!unsupported) {
+        ensureChannels().catch(reportSetupFailure);
+        ensureActionTypes().catch(reportSetupFailure);
+    }
+    // Local reminder operations run one at a time: each reads the pending list
+    // and decides from it, so two at once could both take the last free slot.
+    let localQueue = Promise.resolve();
+    const serialized = (operation) => {
+        const run = localQueue.then(operation, operation);
+        localQueue = run.catch(() => undefined);
+        return run;
+    };
+    const availabilityOf = () => {
+        if (unsupported) {
+            return 'unsupported';
+        }
+        return configurationIssue === undefined ? 'available' : 'configuration-required';
+    };
+    const capabilities = () => ({
+        availability: availabilityOf(),
+        permission: {
+            scope: 'app',
+            prompt: 'os',
+            readable: true,
+            serverReadable: false,
+            allowance: 'persistent',
+            userGesture: false,
+            ...(unsupported ? {} : { promptLimit }),
+            settings: !unsupported && input.openSettings !== undefined,
+        },
+        remote: push === undefined
+            ? { supported: false, purposes: [], addressing: 'none', content: 'free-form' }
+            : {
+                supported: true,
+                purposes: ['service', 'requested', 'advertising'],
+                addressing: 'device',
+                content: 'free-form',
+            },
+        local: local === undefined
+            ? { supported: false }
+            : {
+                supported: true,
+                ...(platform === 'ios' ? { maxPending: capacitorIosMaxPendingLocalNotifications } : {}),
+            },
+        open: unsupported ? 'none' : 'payload',
+    });
+    const readPending = async (sdk) => {
+        const result = await callSdk(() => sdk.getPending());
+        const all = Array.isArray(result?.notifications) ? result.notifications : [];
+        const ours = [];
+        for (const notification of all) {
+            const entry = readLocalEntry(notification);
+            if (entry !== undefined) {
+                ours.push({
+                    ...entry,
+                    id: notification.id,
+                    ...(typeof notification.title === 'string' ? { title: notification.title } : {}),
+                    ...(typeof notification.body === 'string' ? { body: notification.body } : {}),
+                });
+            }
+        }
+        return { all, ours: sortEntries(ours) };
+    };
+    /**
+     * Schedules a validated, declared, non-advertising reminder once permission
+     * and channels are in place; runs inside `serialized`.
+     */
+    const scheduleChecked = async (sdk, checked, declared) => {
+        // Never let the plugin prompt: its schedule asks by itself.
+        if (await readAppState() !== 'granted') {
+            return { status: 'permission-required' };
+        }
+        await callSdk(ensureChannels);
+        ensureActionTypes().catch(reportSetupFailure);
+        const fireAt = normalizeNotificationTimestamp(checked.fireAt);
+        const pending = await readPending(sdk);
+        const existing = pending.ours.find((entry) => entry.key === checked.key);
+        const maxPending = platform === 'ios' ? capacitorIosMaxPendingLocalNotifications : undefined;
+        let evicted;
+        if (existing === undefined && maxPending !== undefined
+            && pending.all.length >= maxPending) {
+            // Keep the nearest: the farthest of this provider's reminders
+            // gives way, or the new one is refused.
+            const farthest = pending.ours.at(-1);
+            if (farthest === undefined || Date.parse(fireAt) >= Date.parse(farthest.fireAt)) {
+                return { status: 'capacity-exceeded' };
+            }
+            await callSdk(() => sdk.cancel({ notifications: [{ id: farthest.id }] }));
+            evicted = farthest;
+        }
+        const id = existing?.id ?? freeId(checked.key, pending.all);
+        const route = checked.route ?? declared.route;
+        try {
+            await callSdk(() => sdk.schedule({
+                notifications: [schemaOf({ ...checked, id, fireAt, route })],
+            }));
+        }
+        catch (error) {
+            // The new reminder failed after the farthest gave way: put that one back.
+            if (evicted !== undefined) {
+                await restore(sdk, evicted);
+            }
+            throw error;
+        }
+        return { status: existing === undefined ? 'scheduled' : 'replaced' };
+    };
+    /** One local notification as this provider writes it, for a new or a restored reminder. */
+    const schemaOf = (input) => {
+        const declared = mappedTopic(input.topic);
+        return {
+            id: input.id,
+            title: input.title,
+            body: input.body,
+            // Inexact, but allowed to fire in Doze: without it Android posts the
+            // reminder only when the device next wakes for another reason.
+            schedule: { at: new Date(input.fireAt), allowWhileIdle: true },
+            extra: {
+                [extraKeys.key]: input.key,
+                [extraKeys.topic]: input.topic,
+                [extraKeys.fireAt]: input.fireAt,
+                ...(input.route === undefined ? {} : { [extraKeys.route]: input.route }),
+            },
+            ...(platform === 'android' && declared !== undefined
+                ? { channelId: capacitorNotificationChannelId(declared) }
+                : {}),
+            isExactNotification: false,
+        };
+    };
+    /** Puts an evicted reminder back as `getPending` reported it; reports when it cannot. */
+    const restore = async (sdk, entry) => {
+        const { title, body } = entry;
+        if (title === undefined || body === undefined) {
+            reportError(new Error(`Capacitor notifications: could not restore the reminder ${entry.key}.`));
+            return;
+        }
+        try {
+            await callSdk(() => sdk.schedule({
+                notifications: [schemaOf({ ...entry, title, body })],
+            }));
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+    const provider = {
+        provider: providerId,
+        topics,
+        async getCapabilities() {
+            return capabilities();
+        },
+        async getPermission(request) {
+            const requested = topicsOf(request);
+            assertConfigured();
+            return snapshotOf(requested, await readAppState());
+        },
+        async requestPermission(request) {
+            const requested = topicsOf(request);
+            assertConfigured();
+            const outcomes = {};
+            if (askPermission === undefined) {
+                for (const topic of requested) {
+                    outcomes[topic] = 'unavailable';
+                }
+                return { snapshot: snapshotOf(requested, 'unsupported'), outcomes };
+            }
+            const askable = requested.filter((topic) => mappedTopic(topic) !== undefined);
+            for (const topic of requested) {
+                outcomes[topic] = 'unavailable';
+            }
+            if (askable.length === 0) {
+                return { snapshot: snapshotOf(requested, await readAppState()), outcomes };
+            }
+            let answer = requesting;
+            if (answer === undefined) {
+                const generation = requests;
+                const before = await readAppState();
+                // Another request may have opened the dialog during that read, or
+                // opened and closed it: then this call shares that answer instead
+                // of asking again from a state read before it.
+                answer = requesting
+                    // Only a dialog that started after the read began, and answered.
+                    ?? (lastAnswer !== undefined && answeredSince(generation)
+                        ? Promise.resolve(lastAnswer)
+                        : undefined);
+                if (answer === undefined && before === 'blocked') {
+                    // Only settings can change it; the dialog would not show.
+                    for (const topic of askable) {
+                        outcomes[topic] = 'blocked';
+                    }
+                    return { snapshot: snapshotOf(requested, before), outcomes };
+                }
+                if (answer === undefined) {
+                    // The push plugin also registers with APNs on iOS. Its answer is
+                    // not read: on Android 12 and lower it is granted whatever the
+                    // setting is, so the read after it decides (through the local
+                    // plugin when present).
+                    requests += 1;
+                    const request = requests;
+                    // Started in a microtask, so `requesting` is set before the dialog
+                    // opens and every read from then on sees it.
+                    const asked = Promise.resolve().then(async () => {
+                        await callSdk(askPermission);
+                        const after = await readAppState();
+                        lastObserved = after;
+                        lastAnswer = { request, before, after };
+                        return lastAnswer;
+                    });
+                    requesting = asked;
+                    const clear = () => {
+                        if (requesting === asked) {
+                            requesting = undefined;
+                        }
+                    };
+                    asked.then(clear, clear);
+                    answer = asked;
+                }
+            }
+            const { before, after } = await answer;
+            let outcome;
+            if (after === 'granted') {
+                outcome = before === 'granted' ? 'already-granted' : 'granted';
+            }
+            else if (after === before) {
+                // A dialog closed without an answer leaves the state as it was.
+                outcome = 'dismissed';
+            }
+            else {
+                outcome = 'denied';
+            }
+            for (const topic of askable) {
+                outcomes[topic] = outcome;
+            }
+            return {
+                snapshot: snapshotOf(requested, after),
+                outcomes,
+            };
+        },
+        ...(push === undefined
+            ? {}
+            : {
+                async register() {
+                    assertConfigured();
+                    let value;
+                    try {
+                        value = (await push.getToken()).token;
+                    }
+                    catch (error) {
+                        if (error instanceof NotificationError || isConfigurationFailure(error)) {
+                            throw toNotificationError(error);
+                        }
+                        // No address yet (iOS before APNs registration, offline):
+                        // `tokenReceived` announces it as `endpoint-changed`. Reported
+                        // once until a token arrives, because a Firebase set up wrongly
+                        // fails the same way.
+                        if (!tokenFailureReported) {
+                            tokenFailureReported = true;
+                            reportError(error);
+                        }
+                        return null;
+                    }
+                    if (typeof value !== 'string' || value === '') {
+                        return null;
+                    }
+                    tokenFailureReported = false;
+                    return registrationOf(value);
+                },
+            }),
+        ...(local === undefined
+            ? {}
+            : {
+                async scheduleLocal(request) {
+                    let checked;
+                    try {
+                        checked = assertLocalNotificationRequest(request);
+                    }
+                    catch (error) {
+                        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+                            message: error instanceof Error ? error.message : 'Invalid local reminder.',
+                            cause: error,
+                        });
+                    }
+                    const declared = mappedTopic(checked.topic);
+                    if (declared === undefined || declared.purpose === 'advertising') {
+                        // Outside the resolved catalog it has no channel, as a request
+                        // for it answers `unavailable`; and a device-scheduled
+                        // advertisement could not be withdrawn, labelled, or held for
+                        // the night window (RFC "Topic catalog").
+                        return { status: 'unsupported' };
+                    }
+                    // The whole operation holds the queue, so concurrent calls apply
+                    // in the order they were made.
+                    return serialized(() => scheduleChecked(local, checked, declared));
+                },
+                cancelLocal(request) {
+                    if (!Array.isArray(request?.keys)) {
+                        return Promise.reject(new NotificationError('NOTIFICATIONS_INVALID_INPUT'));
+                    }
+                    const keys = new Set(request.keys);
+                    return serialized(async () => {
+                        const ids = (await readPending(local)).ours
+                            .filter((entry) => keys.has(entry.key))
+                            .map((entry) => ({ id: entry.id }));
+                        if (ids.length > 0) {
+                            await callSdk(() => local.cancel({ notifications: ids }));
+                        }
+                    });
+                },
+                listLocal() {
+                    return serialized(async () => (await readPending(local)).ours
+                        .map(({ key, topic, fireAt }) => ({ key, topic, fireAt })));
+                },
+            }),
+        async openSettings() {
+            const open = input.openSettings;
+            if (unsupported || open === undefined) {
+                return 'unavailable';
+            }
+            // Resolve once the player is back, so the game stays paused while the
+            // settings screen is up: on Android the native call returns as soon as
+            // the screen launches, before the app reports the background.
+            let finish = () => undefined;
+            /** Whether the wait ended by a timer rather than the player's return. */
+            let timedOut = false;
+            const returned = new Promise((resolve) => {
+                let left = false;
+                const done = () => {
+                    appStateWaiters.delete(waiter);
+                    clearTimeout(leaveTimer);
+                    clearTimeout(returnTimer);
+                    resolve();
+                };
+                const expire = () => {
+                    timedOut = true;
+                    done();
+                };
+                const waiter = (active) => {
+                    if (!active) {
+                        left = true;
+                    }
+                    else if (left) {
+                        done();
+                    }
+                };
+                appStateWaiters.add(waiter);
+                // A screen that never took the app to the background does not hold the game.
+                const leaveTimer = setTimeout(() => {
+                    if (!left) {
+                        expire();
+                    }
+                }, input.settingsLeaveTimeoutMs ?? capacitorSettingsLeaveTimeoutMs);
+                const returnTimer = setTimeout(expire, input.settingsReturnTimeoutMs
+                    ?? capacitorSettingsReturnTimeoutMs);
+                finish = done;
+            });
+            // The opener is raced with the wait: one that never settles must not
+            // hold the game past the timers, and settling after they ended changes
+            // nothing (a late rejection is only reported).
+            const opening = Promise.resolve()
+                .then(() => open())
+                .then(() => 'opened', (error) => {
+                reportError(error);
+                return 'failed';
+            });
+            const outcome = await Promise.race([
+                opening,
+                returned.then(() => 'waited'),
+            ]);
+            if (outcome === 'failed') {
+                finish();
+                return 'unavailable';
+            }
+            if (outcome === 'waited') {
+                // The wait ended before the opener settled: answered as a missed
+                // return is. A timer ending it is a stall, reported once; the player
+                // coming back first is a normal round trip (some iOS openers settle
+                // only after the settings screen closes).
+                if (timedOut) {
+                    reportError(new Error('Capacitor notifications: openSettings had not settled when the settings wait timed out.'));
+                }
+                return 'opened';
+            }
+            await returned;
+            return 'opened';
+        },
+        subscribe(subscriber) {
+            // One entry per call, so the same function subscribed twice is two
+            // subscriptions, and only the handle this call returns removes this one.
+            const listener = (event) => subscriber(event);
+            const first = listeners.size === 0;
+            listeners.add(listener);
+            // `source` reads `cold` only for opens before the first subscriber ever.
+            subscribed = true;
+            if (first && !draining) {
+                // Every buffered event reaches the next subscriber exactly once, in
+                // order: an event dispatched while the buffer drains queues behind it
+                // and then reaches every listener attached by then, as a live one does.
+                draining = true;
+                // The backlog is taken whole, so an eviction while it drains touches
+                // only events dispatched meanwhile. This subscription cannot leave
+                // during the drain: it runs inside this `subscribe` call, before the
+                // call returns the only handle that removes it.
+                const backlog = buffer.splice(0);
+                try {
+                    for (const event of backlog) {
+                        deliver(event, [listener]);
+                    }
+                    for (let event = buffer.shift(); event !== undefined; event = buffer.shift()) {
+                        deliver(event, [...listeners]);
+                    }
+                }
+                finally {
+                    draining = false;
+                }
+            }
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    return provider;
+}
+function collectChannels(topics, settings) {
+    const purposes = new Map();
+    for (const topic of topics) {
+        const id = capacitorNotificationChannelId(topic);
+        const seen = purposes.get(id);
+        if (seen !== undefined && (seen === 'advertising') !== (topic.purpose === 'advertising')) {
+            // RFC "Provider profiles", Capacitor: advertising has channels of its
+            // own, so a player can turn it off without losing service messages.
+            throw new Error(`Capacitor notifications: channel ${id} mixes advertising and other topics (${topic.id}).`);
+        }
+        purposes.set(id, seen ?? topic.purpose);
+    }
+    return [...purposes].map(([id, purpose]) => {
+        const channel = Object.prototype.hasOwnProperty.call(settings, id) ? settings[id] : undefined;
+        const fallback = defaultChannels[purpose];
+        return {
+            id,
+            name: channel?.name ?? fallback.name,
+            ...(channel?.description === undefined ? {} : { description: channel.description }),
+            importance: channel?.importance ?? 3,
+        };
+    });
+}
+function topicsOf(request) {
+    if (!Array.isArray(request?.topics)
+        || !request.topics.every((topic) => typeof topic === 'string')) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'Notification topics must be a list of topic ids.',
+        });
+    }
+    return [...new Set(request.topics)];
+}
+function toPermissionState(state) {
+    switch (state) {
+        case 'granted':
+            return 'granted';
+        case 'prompt':
+            return 'prompt';
+        case 'prompt-with-rationale':
+            return 'prompt-with-rationale';
+        case 'denied':
+            // iOS after its one denial, Android after the second: only settings
+            // can change it.
+            return 'blocked';
+        default:
+            throw new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', {
+                message: `The notification plugin reported an unknown permission state: ${String(state)}.`,
+            });
+    }
+}
+/** This provider's key, topic, and time from a local notification's `extra`, or `undefined` for another one. */
+function readLocalEntry(notification) {
+    const extra = notification?.extra;
+    if (!isRecord(extra) || typeof notification?.id !== 'number') {
+        return undefined;
+    }
+    const key = stringOf(extra[extraKeys.key]);
+    const topic = stringOf(extra[extraKeys.topic]);
+    const fireAt = stringOf(extra[extraKeys.fireAt]);
+    if (key === undefined || topic === undefined || fireAt === undefined
+        || Number.isNaN(Date.parse(fireAt))) {
+        return undefined;
+    }
+    const route = safeRoute(extra[extraKeys.route]);
+    return { key, topic, fireAt, ...(route === undefined ? {} : { route }) };
+}
+/**
+ * A route the game may open, by the rule its router applies
+ * (`isRootRelativeNotificationRoute`): at most 2,048 characters and already
+ * in the form `normalizeRootRelativeRoute` from `@mpgd/platform/routes`
+ * returns, which also refuses any path a client could read as another host
+ * (`hasNetworkPathPrefix`).
+ */
+function safeRoute(value) {
+    return typeof value === 'string' && isRootRelativeNotificationRoute(value) ? value : undefined;
+}
+/** The action a native event names; `tap` when it names none. */
+function actionIdOf(event) {
+    return typeof event?.actionId === 'string' ? event.actionId : 'tap';
+}
+function freeId(key, pending) {
+    const taken = new Set(pending.map((entry) => entry.id));
+    let id = capacitorLocalNotificationId(key);
+    while (taken.has(id)) {
+        id = id === maxNativeId ? 1 : id + 1;
+    }
+    return id;
+}
+function sortEntries(entries) {
+    return [...entries].sort((left, right) => {
+        const byTime = Date.parse(left.fireAt) - Date.parse(right.fireAt);
+        if (byTime !== 0) {
+            return byTime;
+        }
+        // Code unit order, the same on every device locale.
+        if (left.key === right.key) {
+            return 0;
+        }
+        return left.key < right.key ? -1 : 1;
+    });
+}
+async function callSdk(call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        throw toNotificationError(error);
+    }
+}
+function toNotificationError(error) {
+    if (error instanceof NotificationError) {
+        return error;
+    }
+    const code = isRecord(error) ? stringOf(error['code']) : undefined;
+    if (isConfigurationFailure(error)) {
+        return new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+            ...(code === undefined ? {} : { hostCode: code }),
+            cause: error,
+        });
+    }
+    return new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', { cause: error });
+}
+/** Capacitor's answer for a plugin the native shell does not implement. */
+function isConfigurationFailure(error) {
+    const code = isRecord(error) ? error['code'] : undefined;
+    return code === 'UNIMPLEMENTED' || code === 'UNAVAILABLE';
+}
+function defaultTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultLocale() {
+    const language = globalThis
+        .navigator?.language;
+    return typeof language === 'string' ? language : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringOf(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}