@mpgd/adapter-capacitor 0.10.1 → 0.11.0

package/dist/notifications-bridge.js

@@ -0,0 +1,333 @@
+import { bridgeNotificationsEventProtocol, createBridgeError, createBridgeEventSource, isBridgeNotificationsV2Method, } from '@mpgd/bridge';
+import { assertBridgeNotificationsV2Payload, assertBridgeNotificationsV2Result, } from '@mpgd/bridge/notifications';
+import { PlatformOperationError } from '@mpgd/platform';
+import { assertNotificationEventEnvelope, isNotificationErrorCode, NotificationError, notificationsProtocol, notificationsProtocolVersion, toNotificationSubscriptionAdapter, } from '@mpgd/platform/notifications';
+import { namesOtherProtocol } from './bridge-events.js';
+/**
+ * In-process `NativeBridge` over a notifications v2 provider. Each
+ * `notifications.v2.*` request validates its payload (a payload the contract
+ * rejects answers `NOTIFICATIONS_INVALID_INPUT`) and its answer (one the
+ * contract rejects answers `NOTIFICATIONS_CONFIGURATION_REQUIRED`, because the
+ * provider broke it). A method the
+ * provider does not implement answers `NOTIFICATIONS_UNSUPPORTED`, except
+ * `openSettings`, which answers `unavailable`. Events go out through
+ * `createBridgeEventSource`, which attaches to the provider only for the
+ * first listener, so events the provider buffered reach it. Any other method
+ * answers `UNSUPPORTED_METHOD`.
+ */
+export function createNotificationProviderBridge(input) {
+    const { provider } = input;
+    const events = createBridgeEventSource(bridgeNotificationsEventProtocol, provider);
+    const serve = async (method, payload) => {
+        const checked = checkedPayload(method, payload);
+        switch (method) {
+            case 'notifications.v2.getCapabilities':
+                return {
+                    protocolVersion: notificationsProtocolVersion,
+                    provider: provider.provider,
+                    capabilities: await provider.getCapabilities(),
+                };
+            case 'notifications.v2.getPermission':
+                return provider.getPermission(checked);
+            case 'notifications.v2.requestPermission':
+                return provider.requestPermission(checked);
+            case 'notifications.v2.revokePermission':
+                return implemented(provider.revokePermission, method).call(provider, checked);
+            case 'notifications.v2.register':
+                return { registration: await implemented(provider.register, method).call(provider) };
+            case 'notifications.v2.scheduleLocal':
+                return implemented(provider.scheduleLocal, method).call(provider, checked);
+            case 'notifications.v2.cancelLocal':
+                await implemented(provider.cancelLocal, method).call(provider, checked);
+                return { cancelled: true };
+            case 'notifications.v2.listLocal':
+                return { pending: await implemented(provider.listLocal, method).call(provider) };
+            case 'notifications.v2.openSettings':
+                return {
+                    status: provider.openSettings === undefined
+                        ? 'unavailable'
+                        : await provider.openSettings(),
+                };
+            default: {
+                // A method added to the list without a case here fails to compile.
+                const unhandled = method;
+                throw new NotificationError('NOTIFICATIONS_UNSUPPORTED', {
+                    message: `The notifications bridge does not serve ${String(unhandled)}.`,
+                });
+            }
+        }
+    };
+    return {
+        async request(request) {
+            if (!isBridgeNotificationsV2Method(request.method)) {
+                return createBridgeError(request.id, 'UNSUPPORTED_METHOD', `${request.method} is not a notifications v2 method.`);
+            }
+            const method = request.method;
+            let data;
+            try {
+                data = await serve(method, request.payload);
+            }
+            catch (error) {
+                return toBridgeError(request, error);
+            }
+            try {
+                return { id: request.id, ok: true, data: assertBridgeNotificationsV2Result(method, data) };
+            }
+            catch (error) {
+                return createBridgeError(request.id, 'NOTIFICATIONS_CONFIGURATION_REQUIRED', `Notifications provider returned invalid data for ${method}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        subscribe: (listener) => events.subscribe(listener),
+    };
+}
+/** The payload as the contract reads it, or `NOTIFICATIONS_INVALID_INPUT`; both sides of the bridge use it. */
+function checkedPayload(method, payload) {
+    try {
+        return assertBridgeNotificationsV2Payload(method, payload);
+    }
+    catch (error) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: `${method} payload is invalid: ${error instanceof Error ? error.message : String(error)}`,
+            cause: error,
+        });
+    }
+}
+function implemented(method, name) {
+    if (method === undefined) {
+        throw new NotificationError('NOTIFICATIONS_UNSUPPORTED', {
+            message: `The notifications provider does not implement ${name}.`,
+        });
+    }
+    return method;
+}
+function toBridgeError(request, error) {
+    if (error instanceof PlatformOperationError) {
+        // A host code kept with `NOTIFICATIONS_CONFIGURATION_REQUIRED` crosses in
+        // the message: the bridge error has no field for it.
+        const hostCode = error instanceof NotificationError ? error.hostCode : undefined;
+        return createBridgeError(request.id, error.code, hostCode === undefined ? error.message : `${error.message} (host code ${hostCode})`, error.retryable);
+    }
+    return createBridgeError(request.id, 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', `${request.method} failed: ${error instanceof Error ? error.message : String(error)}`, true);
+}
+/**
+ * Registry entry for a notifications v2 provider, as
+ * `createCommerceServiceProvider` is for commerce: it declares no feature and
+ * no method, the nine `notifications.v2.*` methods are implied and served in
+ * process by `createNotificationProviderBridge`, and the gateway exposes
+ * `notificationsV2` and a v1 `notifications` adapter served from it.
+ */
+export function createNotificationServiceProvider(input) {
+    const { notifications } = input;
+    // Copied entry by entry, `targets` included: an entry that still carries
+    // one names no single target, and the v1 adapter counts it as outside.
+    const topics = input.topics.map((topic) => ({ ...topic }));
+    const service = {
+        async getCapabilities() {
+            return copyCapabilities(assertBridgeNotificationsV2Result('notifications.v2.getCapabilities', {
+                protocolVersion: notificationsProtocolVersion,
+                provider: notifications.provider,
+                capabilities: await notifications.getCapabilities(),
+            }).capabilities);
+        },
+        assertResult(method, data) {
+            assertBridgeNotificationsV2Result(method, data);
+        },
+        createGatewaySurface({ request, subscribe }) {
+            const client = createBridgeNotificationProvider({
+                provider: notifications.provider,
+                serves: {
+                    revokePermission: notifications.revokePermission !== undefined,
+                    register: notifications.register !== undefined,
+                    local: notifications.scheduleLocal !== undefined
+                        && notifications.cancelLocal !== undefined
+                        && notifications.listLocal !== undefined,
+                },
+                request,
+                subscribe,
+            });
+            return {
+                notificationsV2: client,
+                notifications: createNotificationSubscriptionAdapter(client, topics),
+            };
+        },
+    };
+    return {
+        id: input.id,
+        features: [],
+        methods: [],
+        notificationsV2: service,
+        bridge: createNotificationProviderBridge({ provider: notifications }),
+        async getAvailability() {
+            return {};
+        },
+    };
+}
+/**
+ * The v1 `NotificationSubscriptionAdapter` served from a v2 provider whose
+ * host is readable (RFC "Migration and PR plan" table, through
+ * `toNotificationSubscriptionAdapter`): every state comes from the host, a
+ * topic outside `topics` reads `configuration-required` and requests
+ * `unavailable`.
+ */
+export function createNotificationSubscriptionAdapter(provider, topics) {
+    return toNotificationSubscriptionAdapter({
+        async getPermission(input) {
+            const snapshot = await provider.getPermission(input);
+            return {
+                ...snapshot,
+                sources: Object.fromEntries(Object.keys(snapshot.topics).map((topic) => [topic, 'host'])),
+            };
+        },
+        requestPermission: ({ topics: requested }) => provider.requestPermission({ topics: requested }),
+    }, topics);
+}
+/**
+ * `NotificationProvider` over a bridge that serves the `notifications.v2.*`
+ * methods and the event envelope. Answers are validated again on this side,
+ * so a transport that forgets to stays fail-closed. A bridge failure becomes
+ * a `NotificationError`: one with a notifications code keeps it, anything
+ * else is `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` with the failure's
+ * retryable flag. An answer the contract rejects is
+ * `NOTIFICATIONS_CONFIGURATION_REQUIRED`, which is not retryable, because the
+ * provider broke the contract. An event envelope that
+ * names another protocol is skipped; a malformed one is dropped with a
+ * warning, because it carries nothing the game could route.
+ *
+ * Events reach the listeners subscribed when they arrive. The Capacitor
+ * provider keeps events that arrive while no listener is attached for the
+ * next subscriber, so a game that subscribes per scene loses no open.
+ */
+export function createBridgeNotificationProvider(input) {
+    const send = async (method, payload) => {
+        // Checked here too, so a payload the contract rejects never pauses the
+        // game for a request that cannot succeed.
+        checkedPayload(method, payload);
+        let data;
+        try {
+            data = await input.request(method, payload);
+        }
+        catch (error) {
+            throw toNotificationError(error);
+        }
+        try {
+            return assertBridgeNotificationsV2Result(method, data);
+        }
+        catch (error) {
+            // The provider broke the contract; a retry would not change that.
+            throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+                message: `Bridge returned invalid data for ${method}.`,
+                cause: error,
+            });
+        }
+    };
+    const protocol = { protocol: notificationsProtocol };
+    return {
+        provider: input.provider,
+        async getCapabilities() {
+            return (await send('notifications.v2.getCapabilities', protocol)).capabilities;
+        },
+        // Async, so wrong input from a caller outside TypeScript rejects instead
+        // of throwing synchronously.
+        getPermission: async (request) => send('notifications.v2.getPermission', topicsPayload(request)),
+        requestPermission: async (request) => send('notifications.v2.requestPermission', topicsPayload(request)),
+        ...(input.serves.revokePermission
+            ? {
+                revokePermission: async (request) => send('notifications.v2.revokePermission', topicsPayload(request)),
+            }
+            : {}),
+        ...(input.serves.register
+            ? {
+                async register() {
+                    return (await send('notifications.v2.register', protocol)).registration;
+                },
+            }
+            : {}),
+        ...(input.serves.local
+            ? {
+                scheduleLocal: (request) => send('notifications.v2.scheduleLocal', request),
+                async cancelLocal(request) {
+                    // A missing list stays missing, so the payload check rejects it.
+                    await send('notifications.v2.cancelLocal', {
+                        keys: request?.keys,
+                    });
+                },
+                async listLocal() {
+                    return (await send('notifications.v2.listLocal', protocol)).pending;
+                },
+            }
+            : {}),
+        async openSettings() {
+            return (await send('notifications.v2.openSettings', protocol)).status;
+        },
+        subscribe(listener) {
+            return input.subscribe((envelope) => {
+                if (namesOtherProtocol(envelope, bridgeNotificationsEventProtocol)) {
+                    return;
+                }
+                let event;
+                try {
+                    event = assertNotificationEventEnvelope(envelope).event;
+                }
+                catch (error) {
+                    console.warn('Dropped an invalid notifications event from the bridge.', error);
+                    return;
+                }
+                listener(event);
+            });
+        },
+    };
+}
+/**
+ * Only `topics` crosses, since the payload validator refuses unknown keys. A
+ * missing request or list stays missing on purpose: the cast lets `send`'s
+ * payload validator reject it as `NOTIFICATIONS_INVALID_INPUT`.
+ */
+function topicsPayload(request) {
+    return { topics: request?.topics };
+}
+function toNotificationError(error) {
+    if (error instanceof NotificationError) {
+        return error;
+    }
+    const code = typeof error === 'object' && error !== null
+        ? error.code
+        : undefined;
+    const options = {
+        ...(error instanceof Error ? { message: error.message } : {}),
+        // A transport failure keeps its retryability.
+        ...(error instanceof PlatformOperationError ? { retryable: error.retryable } : {}),
+        cause: error,
+    };
+    return new NotificationError(isNotificationErrorCode(code) ? code : 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', options);
+}
+/** A field-by-field copy, so the gateway never hands out a provider-owned block. */
+function copyCapabilities(capabilities) {
+    const { permission, remote, local } = capabilities;
+    return {
+        availability: capabilities.availability,
+        permission: {
+            scope: permission.scope,
+            prompt: permission.prompt,
+            readable: permission.readable,
+            serverReadable: permission.serverReadable,
+            allowance: permission.allowance,
+            userGesture: permission.userGesture,
+            ...(permission.promptLimit === undefined ? {} : { promptLimit: permission.promptLimit }),
+            ...(permission.maxTopicsPerPrompt === undefined
+                ? {}
+                : { maxTopicsPerPrompt: permission.maxTopicsPerPrompt }),
+            settings: permission.settings,
+        },
+        remote: {
+            supported: remote.supported,
+            purposes: [...remote.purposes],
+            addressing: remote.addressing,
+            content: remote.content,
+        },
+        local: {
+            supported: local.supported,
+            ...(local.maxPending === undefined ? {} : { maxPending: local.maxPending }),
+        },
+        open: capabilities.open,
+    };
+}

package/dist/notifications-provider.d.ts

@@ -0,0 +1,118 @@
+import { type AppPlugin } from '@capacitor/app';
+import { type NotificationProvider, type NotificationProviderId, type NotificationTopicDeclaration } from '@mpgd/platform/notifications';
+import type { LocalNotificationSdk, PushSdk } from './notifications-sdk.js';
+/** The reference provider id the backend's FCM registry entry uses. */
+export declare 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 declare 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 declare const capacitorNotificationDataKeys: Readonly<{
+  readonly topic: 'topic';
+  readonly route: 'route';
+}>;
+/** iOS keeps at most 64 pending local notifications per app. */
+export declare const capacitorIosMaxPendingLocalNotifications = 64;
+/** How long `openSettings` waits for the app to leave for the settings screen. */
+export declare const capacitorSettingsLeaveTimeoutMs = 5000;
+/** How long `openSettings` waits for the player to come back from settings. */
+export declare const capacitorSettingsReturnTimeoutMs = 120000;
+export type CapacitorNotificationAppEvents = Pick<AppPlugin, 'addListener'>;
+export interface CapacitorNotificationChannelSettings {
+  readonly name: string;
+  readonly description?: string;
+  /** Android importance, 1 (min) to 5 (max); 3 when absent. */
+  readonly importance?: 1 | 2 | 3 | 4 | 5;
+}
+export interface CreateCapacitorNotificationProviderInput {
+  readonly platform: 'android' | 'ios';
+  /**
+  * The topics resolved for this target, as the runtime reads them
+  * (`resolveNotificationTopicsForTarget(catalog, 'android')` from
+  * `@mpgd/catalog`). A topic outside them answers `unavailable` to a request.
+  */
+  readonly topics: readonly NotificationTopicDeclaration[];
+  /** Remote delivery; absent means the provider declares none. */
+  readonly push?: PushSdk;
+  /** Local reminders and the permission read; absent means no local reminders. */
+  readonly local?: LocalNotificationSdk;
+  /** Defaults to `capacitorNotificationProviderId` ('fcm'). */
+  readonly provider?: NotificationProviderId;
+  /**
+  * Denials Android accepts before only settings can change the answer: 2 for
+  * a target SDK of 33 or later (Capacitor 8 projects target 36), 1 for an
+  * app that targets 32 or lower. iOS always declares 1.
+  */
+  readonly androidPromptLimit?: 1 | 2;
+  /**
+  * Names of the Android channels, by channel id. A topic uses its mapping's
+  * `channelId`, or the default channel of its purpose
+  * (`capacitorNotificationChannelId`).
+  */
+  readonly channels?: Readonly<Record<string, CapacitorNotificationChannelSettings>>;
+  /** The title of the advertising opt-out action; '수신거부' when absent. */
+  readonly advertisingOptOutTitle?: string;
+  /**
+  * Opens the OS notification settings for this app. Neither plugin can, so
+  * the shell supplies it (for example a small native method). Without it
+  * `permission.settings` is false and `openSettings` answers 'unavailable'.
+  */
+  readonly openSettings?: () => Promise<void>;
+  /** App state events; defaults to `App` from `@capacitor/app`. */
+  readonly app?: CapacitorNotificationAppEvents | null;
+  /** The device's IANA zone for registrations; defaults to `Intl`. */
+  readonly timeZone?: () => string | undefined;
+  /** The device locale for registrations; defaults to `navigator.language`. */
+  readonly locale?: () => string | undefined;
+  readonly settingsLeaveTimeoutMs?: number;
+  readonly settingsReturnTimeoutMs?: number;
+  /** Reports a native listener or setup failure; defaults to `console.warn`. */
+  readonly onError?: (error: unknown) => void;
+}
+/** The provider, with the topics it was created for (the v1 surface reads them). */
+export interface CapacitorNotificationProvider extends NotificationProvider {
+  readonly topics: readonly NotificationTopicDeclaration[];
+}
+/**
+* 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 declare function capacitorNotificationChannelId(topic: Pick<NotificationTopicDeclaration, 'purpose' | 'mapping'>): string;
+/**
+* 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 declare function capacitorLocalNotificationId(key: string): number;
+/**
+* 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 declare function createCapacitorNotificationProvider(input: CreateCapacitorNotificationProviderInput): CapacitorNotificationProvider;