@mpgd/adapter-capacitor 0.11.1 → 0.12.1

package/README.md

@@ -194,6 +194,7 @@ import { resolveNotificationTopicsForTarget } from '@mpgd/catalog';
 import {
   createCapacitorNotificationServiceProvider,
   loadCapacitorNotificationSdks,
+  openCapacitorNotificationSettings,
 } from '@mpgd/adapter-capacitor/notifications';
 
 const sdks = await loadCapacitorNotificationSdks();
@@ -201,12 +202,16 @@ const notifications = createCapacitorNotificationServiceProvider({
   platform: 'android',
   topics: resolveNotificationTopicsForTarget(catalog, 'android'),
   ...sdks,
-  // Optional: opens this app's notification settings (see below).
-  openSettings,
+  // Opens this app's notification settings (see below).
+  openSettings: openCapacitorNotificationSettings,
 });
 const gateway = createCapacitorPlatformGateway({ ..., providers: [notifications] });
 ```
 
+<!--
+@link src/notifications-provider.ts#createCapacitorNotificationProvider Android omits advertising from remote purposes, waits for channels before register, refuses a token when channels cannot be created, ignores a dismiss, confirms an iOS schedule by content, and keeps a Doze-deferred alarm visible to cancellation.
+@evidence ../../docs/specs/notifications/notifications-v2-rfc.md#profile-capacitor An Android FCM notification message cannot carry the opt-out action, and a killed-app tap is only in connectionOptions.notificationResponse.
+-->
 Create it once, early in startup: it registers its native listeners when it
 is created, which is how a cold-start open reaches it.
 
@@ -239,7 +244,12 @@ is created, which is how a cold-start open reaches it.
   `NOTIFICATIONS_V2_UNAVAILABLE` before it pauses the game.
 - **Permission.** One OS permission for the app. The provider reads it through
   the local plugin, which reflects the system setting on Android 12 and lower
-  where the push plugin answers `granted` regardless. The OS `denied` reads
+  where the push plugin answers `granted` regardless. On Android 13+ a granted
+  `POST_NOTIFICATIONS` with notifications turned off in settings
+  (`areNotificationsEnabled() == false`) reads `blocked`. iOS provisional and
+  ephemeral authorization, when a shell reports them instead of collapsing
+  them to `granted`, read `prompt` so a full prompt can still upgrade them.
+  The OS `denied` reads
   `blocked`: after one denial on iOS (`promptLimit` 1) and after the second on
   Android 13+ (`promptLimit` 2; pass `androidPromptLimit: 1` for an app that
   targets SDK 32 or lower). Only `requestPermission` shows the dialog, and a
@@ -251,6 +261,15 @@ is created, which is how a cold-start open reaches it.
   schedules locally. Otherwise it reads the permission first and answers
   `permission-required` without calling the plugin, whose own `schedule` would
   prompt on Android 13+.
+  iOS `schedule` resolves before `center.add` finishes, so the provider
+  checks `getPending` for the reminder's key, topic, `fireAt`, and route — not only
+  its id — and waits with a bounded backoff before it answers. An add still
+  missing when that wait ends is not a failure: `center.add` has no deadline,
+  and failing it would restore a reminder evicted to make room while the new
+  add may still be in flight. Android `listLocal` omits a stored row only
+  when `getDeliveredNotifications` shows it in the shade. A past `fireAt`
+  that is not delivered stays listed: Doze can defer an inexact alarm past
+  its time while it is still pending, and cancellation reads `listLocal`.
   - Reminders are inexact (`isExactNotification: false`; the plugin's default
     would open the exact-alarm settings screen) but may fire in Android's Doze
     mode (`allowWhileIdle: true`; Android lets such alarms fire about once per
@@ -260,15 +279,18 @@ is created, which is how a cold-start open reaches it.
     the topic's Android channel. Operations run one at a time, in call order.
   - iOS keeps at most 64 pending, so the provider keeps the nearest: at the
     ceiling it cancels the farthest of its reminders before it schedules a
-    nearer one, and puts the farthest back when that schedule fails. Android
-    declares no ceiling, but its alarm manager refuses an app with about 500
-    pending alarms.
+    nearer one, and puts the farthest back when that schedule is rejected.
+    An add the plugin accepted but that is not yet pending is not a rejection,
+    so the farthest is not put back then. Android declares no ceiling, but its
+    alarm manager refuses an app with about 500 pending alarms.
 - **Channels.** Each topic posts to its mapping's `channelId`, or to
   `mpgd-service`, `mpgd-requested`, or `mpgd-advertising` by purpose
   (`capacitorNotificationChannelId`). Creating the provider throws when a
   channel would mix advertising with other topics, so a player can always turn
   advertising off in system settings. Name the channels with the `channels`
-  option.
+  option. A push-only Android shell whose messaging plugin has no
+  `createChannel` is `configuration-required` when the catalog names a
+  channel: `register()` throws and a token is not announced.
 - **Topics.** Only topics this target maps count. A topic the catalog does
   not declare, or declares without a mapping for the target, reads
   `unsupported`, answers `unavailable` to a request and `unsupported` to
@@ -283,8 +305,12 @@ is created, which is how a cold-start open reaches it.
   the like), reach the game as untrusted `data`. A route is kept only when
   `isRootRelativeNotificationRoute` accepts it, and a topic only when the
   catalog declares it. Nothing is granted from an open. An open that arrives
-  before the first subscriber is marked `cold`; Capacitor replays a cold-start
-  tap asynchronously, so one replayed after the game subscribed reads `warm`.
+  before the first subscriber is marked `cold`. A killed-app tap on iOS is
+  only in `UIScene.ConnectionOptions.notificationResponse`. The reference
+  shell's `SceneDelegate` forwards it to the notification-center delegate
+  once the bridge has loaded plugins (`capacitorViewDidAppear`); Capacitor
+  8.5's scene proxy does not. Capacitor then replays that tap to the first
+  native listener, so one replayed after the game subscribed reads `warm`.
 - **Advertising opt-out.** For a catalog with an advertising topic, the
   provider registers the action type `mpgd-advertising`
   (`capacitorAdvertisingActionTypeId`) with the `advertising-opt-out` action
@@ -296,17 +322,34 @@ is created, which is how a cold-start open reaches it.
   - The action opens the `optOutRoute` of the advertising topic the push names
     in its `topic` data key; without that key it opens nothing.
   - An Android FCM notification message cannot carry actions, so an Android
-    advertising push needs the shell to render it natively with the action;
-    the template work for that is C1's.
-- **Settings.** Neither plugin opens the notification settings, so the shell
-  passes `openSettings` (for example a small native method); without it
-  `permission.settings` is `false` and `openSettings` answers `unavailable`.
+    advertising push needs the shell to render it natively with the action,
+    which is not built yet (a follow-up after C1). Android `remote.purposes`
+    still lists `advertising` so the provider pairs with the standard FCM
+    registry, but `validateNotificationTopicCatalog` refuses a catalog that
+    maps an advertising topic to `android`: the push would arrive without the
+    opt-out action the Korean rules require (see the RFC's advertising
+    rules). The kit's starter maps its sample advertising topic to iOS only.
+- **Settings.** Neither plugin opens the notification settings, so the
+  provider takes an `openSettings` opener; without one `permission.settings`
+  is `false` and `openSettings` answers `unavailable`.
+  `openCapacitorNotificationSettings` is the kit's opener: it calls
+  `openNotificationSettings` of `@mpgd/capacitor-game-services` (Android 8+
+  `Settings.ACTION_APP_NOTIFICATION_SETTINGS`, iOS 16+
+  `UIApplication.openNotificationSettingsURLString`, and each app's settings
+  page on older versions) and throws when the screen did not open. A shell
+  built with a plugin older than the method rejects the call, and the
+  provider then answers `unavailable` and reports the error.
   The provider resolves `openSettings` only once the app is back in the
   foreground, after at most two minutes (`settingsReturnTimeoutMs`), or after
   five seconds when the app never left.
 - **Endpoints.** `register()` answers the FCM token with the device
   permission, locale, and time zone, or `null` while Firebase cannot issue one
-  yet; a token Firebase issues later arrives as `endpoint-changed`. It
+  yet; a token Firebase issues later arrives as `endpoint-changed`. On
+  Android it waits until the topic channels exist, and does not return a
+  token if creating them failed: FCM sets `android.notification.channel_id`,
+  so a push that arrives before the channel exists is dropped. A rotated
+  token is announced at once with the last permission read, then replaced if
+  a fresh read differs (a settings change has no event). It
   registers FCM tokens only: `fcm-installation` addresses are reserved,
   because FCM HTTP v1 cannot send to a Firebase installation id and the
   game-services FCM sender refuses them.

package/dist/notifications-provider.d.ts

@@ -71,6 +71,18 @@ export interface CreateCapacitorNotificationProviderInput {
   readonly timeZone?: () => string | undefined;
   /** The device locale for registrations; defaults to `navigator.language`. */
   readonly locale?: () => string | undefined;
+  /**
+  * Scenario clock for whether a reminder is already due. A future reminder
+  * must be pending before `scheduleLocal` answers; an already-due one posts
+  * at once. Defaults to `Date.now`. The iOS confirm wait uses the wall
+  * clock instead, because conformance freezes this one.
+  */
+  readonly now?: () => number;
+  /**
+  * How long `scheduleLocal` waits for an iOS `center.add` that is still in
+  * flight before it treats the add as unconfirmed. Defaults to 2 seconds.
+  */
+  readonly scheduleConfirmBudgetMs?: number;
   readonly settingsLeaveTimeoutMs?: number;
   readonly settingsReturnTimeoutMs?: number;
   /** Reports a native listener or setup failure; defaults to `console.warn`. */
@@ -110,7 +122,7 @@ export declare function capacitorLocalNotificationId(key: string): number;
 * - **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.
+*   plugins do. Android `listLocal` omits a row only when it is in the shade.
 * - **Fails closed.** Without either SDK the provider is `unsupported`;
 *   without `push` it declares no remote delivery, without `local` no local
 *   reminders.

package/dist/notifications-provider.js

@@ -83,7 +83,7 @@ export function capacitorLocalNotificationId(key) {
  * - **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.
+ *   plugins do. Android `listLocal` omits a row only when it is in the shade.
  * - **Fails closed.** Without either SDK the provider is `unsupported`;
  *   without `push` it declares no remote delivery, without `local` no local
  *   reminders.
@@ -114,10 +114,18 @@ export function createCapacitorNotificationProvider(input) {
     // `configuration-required`, as a registry mismatch makes a provider.
     const optOutMissing = push !== undefined && local === undefined
         && mappedTopics.some((topic) => topic.purpose === 'advertising');
+    // A push-only shell whose messaging plugin cannot create channels would
+    // otherwise announce an FCM token for catalog channels that do not exist.
+    const channelsUncreatable = platform === 'android' && channels.length > 0
+        && push !== undefined && local === undefined && push.createChannel === undefined;
     const configurationIssue = optOutMissing
         ? 'Capacitor notifications: the catalog maps an advertising topic, whose opt-out action '
             + 'needs @capacitor/local-notifications; install both plugins.'
-        : undefined;
+        : channelsUncreatable
+            ? 'Capacitor notifications: Android pushes name a catalog channel, and this push-only '
+                + 'shell has no createChannel. Install @capacitor/local-notifications, or a messaging '
+                + 'plugin that creates channels, before registering a token.'
+            : undefined;
     const assertConfigured = () => {
         if (configurationIssue !== undefined) {
             throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
@@ -180,7 +188,20 @@ export function createCapacitorNotificationProvider(input) {
     // which also registers with APNs on iOS.
     let checkPermission;
     if (local !== undefined) {
-        checkPermission = async () => (await local.checkPermissions()).display;
+        checkPermission = async () => {
+            const display = (await local.checkPermissions()).display;
+            // Android 13+ `checkPermissions` reads POST_NOTIFICATIONS and can
+            // answer granted after the player turns notifications off in settings.
+            // `areNotificationsEnabled` is that switch. On older Android the
+            // permission read already uses it, so a false answer agrees.
+            if (platform === 'android' && display === 'granted' && local.areEnabled !== undefined) {
+                const enabled = await local.areEnabled();
+                if (enabled.value === false) {
+                    return 'denied';
+                }
+            }
+            return display;
+        };
     }
     else if (push !== undefined) {
         // Without the local plugin, Android 12 and lower read granted whatever
@@ -195,6 +216,8 @@ export function createCapacitorNotificationProvider(input) {
         askPermission = async () => (await local.requestPermissions()).display;
     }
     let tokenFailureReported = false;
+    /** Latest `tokenReceived`, so an older permission correction cannot publish last. */
+    let tokenGeneration = 0;
     let lastObserved;
     /**
      * The OS dialog in flight, whose answer settles `lastObserved`; a request
@@ -283,6 +306,12 @@ export function createCapacitorNotificationProvider(input) {
         return mappedTopic(stringOf(data[capacitorNotificationDataKeys.topic]));
     };
     const openedFromPush = (actionId, notification) => {
+        if (actionId === 'dismiss') {
+            // Firebase Messaging emits notificationActionPerformed for a swipe
+            // dismiss (`UNNotificationDismissActionIdentifier`) and retains it
+            // until a listener consumes it. That is not an open.
+            return;
+        }
         const data = isRecord(notification?.data) ? notification.data : {};
         const declared = declaredTopicOf(data);
         const topicId = declared?.id;
@@ -345,21 +374,60 @@ export function createCapacitorNotificationProvider(input) {
             }
             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;
+            const generation = tokenGeneration + 1;
+            tokenGeneration = generation;
+            // A rotation must reach the runtime before this listener returns: the
+            // conformance harness registers the address from that synchronous
+            // event. The permission on it is the last read. A change made in
+            // system settings has no event, so a fresh read follows and replaces
+            // the announcement when the permission differs. Channels are awaited
+            // on that read; `register()` does not return a token until they exist.
+            const announced = lastObserved !== undefined && requesting === undefined
+                ? lastObserved
+                : undefined;
+            const announcedNow = announced !== undefined && androidChannelsReady;
+            if (announcedNow && announced !== undefined) {
+                dispatch({
+                    type: 'endpoint-changed',
+                    registration: registrationWith(token, announced),
+                });
             }
             void (requesting ?? Promise.resolve())
                 .catch(() => undefined)
-                .then(() => (lastObserved === undefined
-                ? registrationOf(token)
-                : registrationWith(token, lastObserved)))
-                .then((registration) => dispatch({ type: 'endpoint-changed', registration }), reportError);
+                .then(async () => {
+                if (generation !== tokenGeneration) {
+                    return undefined;
+                }
+                await ensureChannels();
+                if (generation !== tokenGeneration) {
+                    return undefined;
+                }
+                return registrationOf(token);
+            })
+                .then((registration) => {
+                if (registration === undefined || generation !== tokenGeneration) {
+                    return;
+                }
+                const permission = registration.address.kind === 'fcm-token'
+                    ? registration.address.permission
+                    : undefined;
+                if (announcedNow && permission === announced) {
+                    return;
+                }
+                dispatch({ type: 'endpoint-changed', registration });
+            }, (error) => {
+                if (generation !== tokenGeneration) {
+                    return;
+                }
+                // Channel creation can fail transiently. Keep this token: the
+                // foreground retry of `ensureChannels` publishes it once the
+                // channels exist. Dropping it leaves the backend on the previous
+                // address until the next registration or the seven-day refresh.
+                if (!androidChannelsReady) {
+                    retainedToken = { token, generation };
+                }
+                reportError(error);
+            });
         }));
         listen(() => push.addListener('notificationReceived', (event) => {
             const data = isRecord(event?.notification?.data) ? event.notification.data : {};
@@ -402,6 +470,40 @@ export function createCapacitorNotificationProvider(input) {
         }
     };
     let channelsReady;
+    /** Android pushes name a channel; do not announce an address before it exists. */
+    let androidChannelsReady = platform !== 'android';
+    /**
+     * A `tokenReceived` whose publish failed because Android channels were not
+     * ready. Published once a later `ensureChannels` succeeds, so a transient
+     * channel failure does not leave the backend on the previous token.
+     */
+    let retainedToken;
+    const publishRetainedToken = () => {
+        const held = retainedToken;
+        if (held === undefined || !androidChannelsReady) {
+            return;
+        }
+        if (held.generation !== tokenGeneration) {
+            retainedToken = undefined;
+            return;
+        }
+        retainedToken = undefined;
+        void (async () => {
+            try {
+                const registration = await registrationOf(held.token);
+                if (held.generation !== tokenGeneration) {
+                    return;
+                }
+                dispatch({ type: 'endpoint-changed', registration });
+            }
+            catch (error) {
+                if (held.generation === tokenGeneration) {
+                    retainedToken = held;
+                    reportError(error);
+                }
+            }
+        })();
+    };
     const ensureChannels = () => {
         channelsReady ??= (async () => {
             if (platform !== 'android') {
@@ -416,9 +518,12 @@ export function createCapacitorNotificationProvider(input) {
             for (const channel of channels) {
                 await createChannel(channel);
             }
+            androidChannelsReady = true;
             setupFailureReported = false;
+            publishRetainedToken();
         })().catch((error) => {
             channelsReady = undefined;
+            androidChannelsReady = platform === 'android' ? false : androidChannelsReady;
             throw error;
         });
         return channelsReady;
@@ -488,6 +593,14 @@ export function createCapacitorNotificationProvider(input) {
             ? { supported: false, purposes: [], addressing: 'none', content: 'free-form' }
             : {
                 supported: true,
+                // Same purposes as `referenceNotificationProviders.fcm`, which
+                // `createFcmProviderRegistration` publishes for android and ios.
+                // `notificationRegistryMismatch` requires that list exactly; omitting
+                // `advertising` on Android makes every standard pairing
+                // `configuration-required`. An Android FCM notification message still
+                // cannot carry the opt-out action: the catalog validator refuses an
+                // advertising topic mapped to `android` until the shell renders it
+                // (RFC "Provider profiles", Capacitor).
                 purposes: ['service', 'requested', 'advertising'],
                 addressing: 'device',
                 content: 'free-form',
@@ -517,6 +630,66 @@ export function createCapacitorNotificationProvider(input) {
         }
         return { all, ours: sortEntries(ours) };
     };
+    /** Ids currently in the shade. Empty when the plugin cannot say, so a deferred alarm stays visible. */
+    const deliveredIds = async (sdk) => {
+        const read = sdk.getDeliveredNotifications;
+        if (read === undefined) {
+            return new Set();
+        }
+        try {
+            const result = await read();
+            const notifications = Array.isArray(result?.notifications) ? result.notifications : [];
+            const ids = new Set();
+            for (const notification of notifications) {
+                if (typeof notification?.id === 'number') {
+                    ids.add(notification.id);
+                }
+            }
+            return ids;
+        }
+        catch {
+            // A failed shade read cannot tell a fired row from a deferred alarm.
+            // Hide nothing, as when the method is absent, so cancellation still
+            // reaches every stored row.
+            return new Set();
+        }
+    };
+    /** How long to wait for an iOS `center.add` that the plugin already accepted. */
+    const scheduleConfirmBudgetMs = 2_000;
+    /** First pause after the immediate re-read; later pauses double up to the max. */
+    const scheduleConfirmInitialDelayMs = 25;
+    const scheduleConfirmMaxDelayMs = 250;
+    /**
+     * iOS `LocalNotifications.schedule` resolves before `center.add` completes.
+     * The pending row for this id can still be the reminder being replaced, so
+     * a match is the requested key, topic, `fireAt`, and route — not the id alone.
+     * Returns whether that row appeared before the wall-clock budget elapsed.
+     */
+    const confirmScheduled = async (sdk, expected) => {
+        const budget = input.scheduleConfirmBudgetMs ?? scheduleConfirmBudgetMs;
+        const started = Date.now();
+        let delay = 0;
+        for (;;) {
+            if (delay > 0) {
+                const remaining = budget - (Date.now() - started);
+                if (remaining <= 0) {
+                    return false;
+                }
+                await new Promise((resolve) => setTimeout(resolve, Math.min(delay, remaining)));
+            }
+            const pending = await callSdk(() => sdk.getPending());
+            const notifications = Array.isArray(pending?.notifications) ? pending.notifications : [];
+            if (notifications.some((entry) => matchesScheduled(entry, expected))) {
+                return true;
+            }
+            if (Date.now() - started >= budget) {
+                return false;
+            }
+            delay = delay === 0
+                ? scheduleConfirmInitialDelayMs
+                : Math.min(delay * 2, scheduleConfirmMaxDelayMs);
+        }
+    };
     /**
      * Schedules a validated, declared, non-advertising reminder once permission
      * and channels are in place; runs inside `serialized`.
@@ -546,18 +719,38 @@ export function createCapacitorNotificationProvider(input) {
         }
         const id = existing?.id ?? freeId(checked.key, pending.all);
         const route = checked.route ?? declared.route;
+        const expected = {
+            id,
+            key: checked.key,
+            topic: checked.topic,
+            fireAt,
+            title: checked.title,
+            body: checked.body,
+            ...(route === undefined ? {} : { 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.
+            // The plugin rejected the schedule after the farthest gave way: put that one back.
             if (evicted !== undefined) {
                 await restore(sdk, evicted);
             }
             throw error;
         }
+        // iOS `schedule` resolves before `center.add` finishes, and a full
+        // center silently drops one. A future reminder is confirmed when the
+        // pending row carries this key, topic, time, and route. An add still missing
+        // when the wait ends is unconfirmed, not a failure: `center.add` has no
+        // deadline, and throwing would restore the evicted reminder into a slot
+        // the add may still take. An already-due one posts at once and does not
+        // have to stay pending.
+        const nowMs = (input.now ?? Date.now)();
+        if (Date.parse(fireAt) > nowMs) {
+            await confirmScheduled(sdk, expected);
+        }
         return { status: existing === undefined ? 'scheduled' : 'replaced' };
     };
     /** One local notification as this provider writes it, for a new or a restored reminder. */
@@ -696,6 +889,9 @@ export function createCapacitorNotificationProvider(input) {
             : {
                 async register() {
                     assertConfigured();
+                    // Do not hand the backend a token until the Android channels
+                    // exist. A failed create is retryable and returns no token.
+                    await callSdk(ensureChannels);
                     let value;
                     try {
                         value = (await push.getToken()).token;
@@ -762,8 +958,24 @@ export function createCapacitorNotificationProvider(input) {
                     });
                 },
                 listLocal() {
-                    return serialized(async () => (await readPending(local)).ours
-                        .map(({ key, topic, fireAt }) => ({ key, topic, fireAt })));
+                    return serialized(async () => {
+                        const pending = await readPending(local);
+                        // Android `getPending` keeps fired one-shots in storage. A row
+                        // in the shade has fired. A past `fireAt` that is not there can
+                        // still be an alarm Doze has not delivered; cancellation reads
+                        // this list, so that row stays. Without the delivered read a
+                        // timestamp cannot tell those apart, so every stored row stays.
+                        // iOS removes a request from pending once it fires, and a
+                        // replacement reuses the stable id while the delivered copy can
+                        // still sit in Notification Center, so the shade filter is an
+                        // Android-only storage workaround.
+                        const delivered = platform === 'android'
+                            ? await deliveredIds(local)
+                            : new Set();
+                        return pending.ours
+                            .filter((entry) => !delivered.has(entry.id))
+                            .map(({ key, topic, fireAt }) => ({ key, topic, fireAt }));
+                    });
                 },
             }),
         async openSettings() {
@@ -912,6 +1124,11 @@ function toPermissionState(state) {
         case 'granted':
             return 'granted';
         case 'prompt':
+        case 'provisional':
+        case 'ephemeral':
+            // Provisional and ephemeral can still be upgraded by a prompt. The
+            // installed plugins collapse both to `granted`; a shell that reports
+            // the raw status is not treated as already granted.
             return 'prompt';
         case 'prompt-with-rationale':
             return 'prompt-with-rationale';
@@ -925,6 +1142,26 @@ function toPermissionState(state) {
             });
     }
 }
+/**
+ * Whether `getPending` is showing the reminder just scheduled, not an older
+ * request that still holds the same native id.
+ */
+function matchesScheduled(notification, expected) {
+    if (notification.id !== expected.id || !isRecord(notification.extra)) {
+        return false;
+    }
+    const { extra } = notification;
+    if (stringOf(extra[extraKeys.key]) !== expected.key
+        || stringOf(extra[extraKeys.topic]) !== expected.topic
+        || stringOf(extra[extraKeys.fireAt]) !== expected.fireAt
+        || safeRoute(extra[extraKeys.route]) !== expected.route) {
+        return false;
+    }
+    if (typeof notification.title === 'string' && notification.title !== expected.title) {
+        return false;
+    }
+    return typeof notification.body !== 'string' || notification.body === expected.body;
+}
 /** 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;

package/dist/notifications-sdk.d.ts

@@ -1,4 +1,11 @@
 import { type PermissionState, type PluginListenerHandle } from '@capacitor/core';
+/**
+* Permission strings the plugins report. The installed 8.x plugins collapse
+* iOS `.provisional` and `.ephemeral` to `granted`; a shell that reports the
+* raw status uses the extra values, which the provider treats as still
+* promptable.
+*/
+export type NotificationSdkPermissionState = PermissionState | 'provisional' | 'ephemeral';
 /** A notification as `@capacitor-firebase/messaging` reports it. */
 export interface PushSdkNotification {
   readonly id?: string;
@@ -29,11 +36,11 @@ export interface NotificationSdkChannel {
 export interface PushSdk {
   /** On Android 12 and lower the plugin answers `granted` whatever the system setting is. */
   checkPermissions(): Promise<{
-    readonly receive: PermissionState;
+    readonly receive: NotificationSdkPermissionState;
   }>;
   /** Shows the OS dialog when the OS still allows it; on iOS it also registers with APNs. */
   requestPermissions(): Promise<{
-    readonly receive: PermissionState;
+    readonly receive: NotificationSdkPermissionState;
   }>;
   /** Rejects while Firebase cannot issue a token yet (iOS before APNs registration, offline). */
   getToken(): Promise<{
@@ -95,10 +102,18 @@ export interface LocalNotificationSdkActionType {
 export interface LocalNotificationSdk {
   /** Reflects the system setting on every Android version, unlike the push plugin. */
   checkPermissions(): Promise<{
-    readonly display: PermissionState;
+    readonly display: NotificationSdkPermissionState;
   }>;
   requestPermissions(): Promise<{
-    readonly display: PermissionState;
+    readonly display: NotificationSdkPermissionState;
+  }>;
+  /**
+  * `NotificationManager.areNotificationsEnabled()`. Absent on a partial
+  * fake. On Android 13+ `checkPermissions` reads `POST_NOTIFICATIONS` and
+  * can answer `granted` while this is false.
+  */
+  areEnabled?(): Promise<{
+    readonly value: boolean;
   }>;
   schedule(options: {
     readonly notifications: LocalNotificationSdkSchema[];
@@ -111,6 +126,17 @@ export interface LocalNotificationSdk {
   getPending(): Promise<{
     readonly notifications: readonly LocalNotificationSdkEntry[];
   }>;
+  /**
+  * Notifications currently visible in the shade. Android `getPending` also
+  * keeps a fired one-shot in storage; a row here has fired. Absent on a
+  * partial fake, which then cannot tell that row from an alarm Doze has
+  * not delivered yet.
+  */
+  getDeliveredNotifications?(): Promise<{
+    readonly notifications: readonly {
+      readonly id: number;
+    }[];
+  }>;
   createChannel(channel: NotificationSdkChannel): Promise<void>;
   /**
   * On iOS this sets the app's notification categories, which remote

package/dist/notifications-settings.d.ts

@@ -0,0 +1,14 @@
+import { type CapacitorGameServicesPlugin } from '@mpgd/capacitor-game-services';
+/** The part of `@mpgd/capacitor-game-services` the settings opener calls. */
+export type CapacitorNotificationSettingsPlugin = Pick<CapacitorGameServicesPlugin, 'openNotificationSettings'>;
+/**
+* Opens this app's notification settings through
+* `@mpgd/capacitor-game-services` (Android 8+ app notification settings, iOS
+* 16+ notification settings, each app's settings page on older versions).
+* Pass it as the provider's `openSettings`, which then declares
+* `permission.settings: true` and waits for the player to come back. It
+* throws when the system could not open the screen, and the plugin rejects
+* it as unimplemented in a shell built with a plugin older than the method;
+* the provider reports either failure and answers `unavailable`.
+*/
+export declare function openCapacitorNotificationSettings(plugin?: CapacitorNotificationSettingsPlugin): Promise<void>;

package/dist/notifications-settings.js

@@ -0,0 +1,18 @@
+import { CapacitorGameServices, } from '@mpgd/capacitor-game-services';
+/**
+ * Opens this app's notification settings through
+ * `@mpgd/capacitor-game-services` (Android 8+ app notification settings, iOS
+ * 16+ notification settings, each app's settings page on older versions).
+ * Pass it as the provider's `openSettings`, which then declares
+ * `permission.settings: true` and waits for the player to come back. It
+ * throws when the system could not open the screen, and the plugin rejects
+ * it as unimplemented in a shell built with a plugin older than the method;
+ * the provider reports either failure and answers `unavailable`.
+ */
+export async function openCapacitorNotificationSettings(plugin = CapacitorGameServices) {
+    const result = await plugin.openNotificationSettings();
+    if (typeof result !== 'object' || result === null
+        || result.opened !== true) {
+        throw new Error('The notification settings screen could not be opened.');
+    }
+}

package/dist/notifications.d.ts

@@ -1,8 +1,9 @@
 import { type CreateCapacitorNotificationProviderInput } from './notifications-provider.js';
 import type { CapacitorNotificationServiceProvider } from './providers.js';
-export { capacitorNotificationPluginNames, loadCapacitorNotificationSdks, type CapacitorNotificationSdkRuntime, type CapacitorNotificationSdks, type LoadCapacitorNotificationSdksInput, type LocalNotificationSdk, type LocalNotificationSdkActionType, type LocalNotificationSdkEntry, type LocalNotificationSdkSchema, type NotificationSdkChannel, type PushSdk, type PushSdkActionEvent, type PushSdkNotification, } from './notifications-sdk.js';
+export { capacitorNotificationPluginNames, loadCapacitorNotificationSdks, type CapacitorNotificationSdkRuntime, type CapacitorNotificationSdks, type LoadCapacitorNotificationSdksInput, type LocalNotificationSdk, type LocalNotificationSdkActionType, type LocalNotificationSdkEntry, type LocalNotificationSdkSchema, type NotificationSdkChannel, type NotificationSdkPermissionState, type PushSdk, type PushSdkActionEvent, type PushSdkNotification, } from './notifications-sdk.js';
 export { capacitorAdvertisingActionTypeId, capacitorIosMaxPendingLocalNotifications, capacitorLocalNotificationId, capacitorNotificationChannelId, capacitorNotificationDataKeys, capacitorNotificationProviderId, capacitorSettingsLeaveTimeoutMs, capacitorSettingsReturnTimeoutMs, createCapacitorNotificationProvider, type CapacitorNotificationAppEvents, type CapacitorNotificationChannelSettings, type CapacitorNotificationProvider, type CreateCapacitorNotificationProviderInput, } from './notifications-provider.js';
 export { createBridgeNotificationProvider, createNotificationProviderBridge, createNotificationServiceProvider, createNotificationSubscriptionAdapter, type CreateBridgeNotificationProviderInput, type CreateNotificationProviderBridgeInput, type CreateNotificationServiceProviderInput, type NotificationProviderBridge, } from './notifications-bridge.js';
+export { openCapacitorNotificationSettings, type CapacitorNotificationSettingsPlugin, } from './notifications-settings.js';
 export type { CapacitorNotificationServiceProvider, CapacitorNotificationsV2Service, } from './providers.js';
 export interface CreateCapacitorNotificationServiceProviderInput extends CreateCapacitorNotificationProviderInput {
   /** The registry id; 'capacitor-notifications' when absent. */

package/dist/notifications.js

@@ -8,6 +8,7 @@ import { createCapacitorNotificationProvider, } from './notifications-provider.j
 export { capacitorNotificationPluginNames, loadCapacitorNotificationSdks, } from './notifications-sdk.js';
 export { capacitorAdvertisingActionTypeId, capacitorIosMaxPendingLocalNotifications, capacitorLocalNotificationId, capacitorNotificationChannelId, capacitorNotificationDataKeys, capacitorNotificationProviderId, capacitorSettingsLeaveTimeoutMs, capacitorSettingsReturnTimeoutMs, createCapacitorNotificationProvider, } from './notifications-provider.js';
 export { createBridgeNotificationProvider, createNotificationProviderBridge, createNotificationServiceProvider, createNotificationSubscriptionAdapter, } from './notifications-bridge.js';
+export { openCapacitorNotificationSettings, } from './notifications-settings.js';
 /**
  * The provider and its registry entry in one call, with the same topics, for
  * `createCapacitorPlatformGateway({ providers: [...] })`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-capacitor",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Capacitor platform adapter for mpgd Android and iOS shells.",
   "license": "MIT",
   "repository": {
@@ -43,11 +43,11 @@
   ],
   "dependencies": {
     "@capacitor/app": "8.1.1",
-    "@mpgd/platform": "0.25.0",
-    "@mpgd/bridge": "0.14.0",
-    "@mpgd/target-config": "0.23.3",
-    "@mpgd/capacitor-game-services": "0.7.3",
-    "@mpgd/game-services": "0.25.1"
+    "@mpgd/capacitor-game-services": "0.8.1",
+    "@mpgd/bridge": "0.14.2",
+    "@mpgd/game-services": "0.27.0",
+    "@mpgd/target-config": "0.23.5",
+    "@mpgd/platform": "0.27.0"
   },
   "peerDependencies": {
     "@capacitor-community/admob": "^8.1.0",
@@ -74,7 +74,7 @@
     "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vitest": "^4.0.0",
-    "@mpgd/game-runtime": "0.7.3"
+    "@mpgd/game-runtime": "0.7.5"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",