@mpgd/game-services 0.28.1 → 0.29.0

package/dist/guest-session.d.ts

@@ -75,13 +75,50 @@ export interface GuestSessionBackend {
     readonly externalProof: string;
     readonly idempotencyKey: string;
   }): Promise<AccountBindingOutcome>;
+  /**
+  * A short-lived, single-use account deletion confirmation for the refresh
+  * token's player, which the game-services deletion route requires besides
+  * the access token (`accountDeletionConfirmationHeader`). It must
+  * authenticate the refresh token like `refresh`, without rotating it, and
+  * throw `GuestSessionRejectedError` for one refused for good. Optional: a
+  * backend without it cannot delete accounts through the starter.
+  */
+  requestAccountDeletionConfirmation?(input: {
+    readonly refreshToken: string;
+  }): Promise<AccountDeletionConfirmationGrant>;
 }
-export type GuestSessionCoordinatorErrorCode = 'GUEST_SESSION_CLOSED' | 'GUEST_SESSION_NOT_READY' | 'GUEST_SESSION_INVALID_INPUT' | 'GUEST_SESSION_INVALID_RESPONSE' | 'GUEST_SESSION_OWNERSHIP_CONFLICT' | 'GUEST_SESSION_BACKEND_FAILED' | 'GUEST_SESSION_CREDENTIAL_LOAD_FAILED' | 'GUEST_SESSION_CREDENTIAL_SAVE_FAILED' | 'GUEST_SESSION_LOGOUT_UNCERTAIN';
+/** A deletion confirmation, as the identity service answers it. */
+export interface AccountDeletionConfirmationGrant {
+  /** Opaque; sent once, in `accountDeletionConfirmationHeader`. */
+  readonly confirmation: string;
+  /** When it stops being accepted (ISO 8601). */
+  readonly expiresAt: string;
+}
+export type GuestSessionCoordinatorErrorCode = 'GUEST_SESSION_CLOSED' | 'GUEST_SESSION_NOT_READY' | 'GUEST_SESSION_INVALID_INPUT' | 'GUEST_SESSION_INVALID_RESPONSE' | 'GUEST_SESSION_OWNERSHIP_CONFLICT' | 'GUEST_SESSION_BACKEND_FAILED'
+/**
+* The identity service refused the refresh token: revoked (logout,
+* replay), expired after inactivity, or unknown. That session cannot come
+* back: the coordinator stops using it (`current()` is `undefined`, and
+* `start()`, `refresh()` and `getHeaders()` fail with
+* `GUEST_SESSION_NOT_READY` without calling the backend). Log out (which
+* removes the stored token) and start a new coordinator for a new guest.
+*/
+| 'GUEST_SESSION_REJECTED' | 'GUEST_SESSION_CREDENTIAL_LOAD_FAILED' | 'GUEST_SESSION_CREDENTIAL_SAVE_FAILED' | 'GUEST_SESSION_LOGOUT_UNCERTAIN'
+/** The backend has no `requestAccountDeletionConfirmation`. */
+| 'GUEST_SESSION_UNSUPPORTED';
 /** Error messages intentionally contain no token, proof, or installation ID. */
 export declare class GuestSessionCoordinatorError extends Error {
   readonly code: GuestSessionCoordinatorErrorCode;
   constructor(code: GuestSessionCoordinatorErrorCode);
 }
+/**
+* A `GuestSessionBackend` throws this when the identity service refused the
+* refresh token for good (revoked, expired, replayed, or unknown), as
+* opposed to an outage. The coordinator reports it as `GUEST_SESSION_REJECTED`.
+*/
+export declare class GuestSessionRejectedError extends Error {
+  constructor();
+}
 export interface GuestSessionCoordinator {
   start(): Promise<ServerGuestSessionView>;
   /** The active session's view, or `undefined` before `start()` settles, after a failure, and after logout. */
@@ -103,6 +140,18 @@ export interface GuestSessionCoordinator {
     readonly status: 'bound' | 'already-bound' | 'conflict';
   }>;
   getHeaders(): Readonly<Record<'authorization', string>>;
+  /**
+  * Asks the backend for an account deletion confirmation with the active
+  * session's refresh token (queued with refreshes, so it never presents a
+  * token a rotation in flight replaces). Fails with
+  * `GUEST_SESSION_REJECTED` when the service refused the session for good,
+  * now or in an earlier refresh (as `refresh` does, the coordinator then
+  * stops using it), `GUEST_SESSION_NOT_READY` without an active session for
+  * any other reason (not started, a failed credential save),
+  * `GUEST_SESSION_CLOSED` after logout, and `GUEST_SESSION_UNSUPPORTED`
+  * when the backend cannot issue one.
+  */
+  requestAccountDeletionConfirmation(): Promise<string>;
   logout(): Promise<void>;
 }
 /**
@@ -165,7 +214,7 @@ export interface GuestServerSession {
   /**
   * The `Authorization` header. An expired access token is refreshed first,
   * and a failed refresh throws its error (`GUEST_SESSION_BACKEND_FAILED`,
-  * `GUEST_SESSION_OWNERSHIP_CONFLICT`, ...). A token that expires within
+  * `GUEST_SESSION_REJECTED`, `GUEST_SESSION_OWNERSHIP_CONFLICT`, ...). A token that expires within
   * `refreshAheadMs` is answered at once while a refresh runs in the
   * background: once per token, and at most once per
   * `guestServerSessionRefreshAheadIntervalMs`, so a backend whose tokens
@@ -173,6 +222,13 @@ export interface GuestServerSession {
   * background refresh is retried when the token has expired.
   */
   getHeaders(): Promise<Readonly<Record<'authorization', string>>>;
+  /**
+  * An account deletion confirmation for the current session
+  * (`GuestSessionCoordinator.requestAccountDeletionConfirmation`), which the
+  * game-services deletion route requires. Optional, so another session
+  * holder (a development session) may leave it out.
+  */
+  requestAccountDeletionConfirmation?(): Promise<string>;
 }
 /** How long before its access token expires `createGuestServerSession` refreshes a session: one minute. */
 export declare const defaultGuestServerSessionRefreshAheadMs = 60000;
@@ -190,3 +246,57 @@ export declare function createGuestServerSession(coordinator: GuestSessionCoordi
   readonly refreshAheadMs?: number;
   readonly now?: () => number;
 }): GuestServerSession;
+/**
+* The HTTP routes of a guest identity service, relative to its base URL:
+* the contract between `createGuestSessionHttpBackend` and the reference
+* identity Worker (`apps/game-identity-worker`). Every route takes a JSON
+* `POST` body. `issueGuest` and `refresh` answer `200` with
+* `ServerGuestSessionCredentials`; `revoke` answers `200` with `{}`, also for
+* a token it does not know (RFC 7009 section 2.2); a refusal answers
+* `{ error: GuestIdentityHttpErrorCode }`. `bindAccount` answers `200` with
+* an `AccountBindingOutcome` (a `conflict` too), or a refusal; the reference
+* Worker binds nothing yet and answers `ACCOUNT_BINDING_UNSUPPORTED`.
+* `requestAccountDeletionConfirmation` takes `{ refreshToken }` and answers
+* `200` with an `AccountDeletionConfirmationGrant`. A refresh token any
+* route refuses for good is `GUEST_SESSION_REJECTED`.
+*/
+export declare const guestIdentityHttpRoutes: Readonly<{
+  readonly issueGuest: '/identity/v1/guest';
+  readonly refresh: '/identity/v1/refresh';
+  readonly revoke: '/identity/v1/revoke';
+  readonly bindAccount: '/identity/v1/bind-account';
+  readonly requestAccountDeletionConfirmation: '/identity/v1/account-deletion-confirmation';
+}>;
+/**
+* - `INVALID_REQUEST` (400): a body the route does not take.
+* - `GUEST_SESSION_REJECTED` (401): the refresh token is revoked, expired,
+*   replayed, or unknown; the session cannot come back.
+* - `RATE_LIMITED` (429): too many guests for this installation or address.
+* - `ACCOUNT_BINDING_UNSUPPORTED` (501): the service binds no external account.
+* - `UNAVAILABLE` (503): the service could not answer; retry later.
+*/
+export type GuestIdentityHttpErrorCode = 'INVALID_REQUEST' | 'GUEST_SESSION_REJECTED' | 'RATE_LIMITED' | 'ACCOUNT_BINDING_UNSUPPORTED' | 'UNAVAILABLE';
+/** A failed identity request. The message names the route and the code, never a token. */
+export declare class GuestSessionHttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(route: string, status: number, code: string);
+}
+/** How long one identity request may take by default: 15 seconds. */
+export declare const defaultGuestSessionHttpTimeoutMs = 15000;
+/**
+* A `GuestSessionBackend` over a guest identity service's HTTP routes
+* (`guestIdentityHttpRoutes`). A `refresh` the service refuses with
+* `GUEST_SESSION_REJECTED` throws `GuestSessionRejectedError` (the
+* coordinator's `GUEST_SESSION_REJECTED`); any other failure throws
+* `GuestSessionHttpError` or the fetch error, which the coordinator reports
+* as `GUEST_SESSION_BACKEND_FAILED`. `baseUrl` must be `https:`, except on a
+* local development host (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`,
+* `10.0.2.2`). Requests never follow a redirect, so a token is only ever sent
+* to `baseUrl`'s origin.
+*/
+export declare function createGuestSessionHttpBackend(input: {
+  readonly baseUrl: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly timeoutMs?: number;
+}): GuestSessionBackend;

package/dist/guest-session.js

@@ -7,6 +7,17 @@ export class GuestSessionCoordinatorError extends Error {
         this.code = code;
     }
 }
+/**
+ * A `GuestSessionBackend` throws this when the identity service refused the
+ * refresh token for good (revoked, expired, replayed, or unknown), as
+ * opposed to an outage. The coordinator reports it as `GUEST_SESSION_REJECTED`.
+ */
+export class GuestSessionRejectedError extends Error {
+    constructor() {
+        super('The identity service rejected the guest session.');
+        this.name = 'GuestSessionRejectedError';
+    }
+}
 const defaultCredentialKey = 'mpgd.guest.refresh';
 /**
  * Serializes token mutation and closes synchronously on logout. Native secure
@@ -49,6 +60,8 @@ export function createGuestSessionCoordinator(input) {
     let savedFamily;
     const listeners = new Set();
     let status = 'idle';
+    /** The identity service refused the session for good (as opposed to a failed save). */
+    let rejected = false;
     let tail = Promise.resolve();
     let startInFlight;
     let refreshInFlight;
@@ -85,7 +98,16 @@ export function createGuestSessionCoordinator(input) {
         try {
             return await operation();
         }
-        catch {
+        catch (error) {
+            if (error instanceof GuestSessionRejectedError) {
+                // The session can never come back: stop using it (current() is
+                // undefined, start() and getHeaders() fail fast) until logout.
+                if (status !== 'closed') {
+                    status = 'failed';
+                }
+                rejected = true;
+                throw new GuestSessionCoordinatorError('GUEST_SESSION_REJECTED');
+            }
             // Backend exceptions can contain URLs, proofs, or tokens. The public
             // coordinator surface intentionally exposes only a stable error code.
             throw new GuestSessionCoordinatorError('GUEST_SESSION_BACKEND_FAILED');
@@ -247,6 +269,30 @@ export function createGuestSessionCoordinator(input) {
                 return { status: result.status };
             });
         },
+        async requestAccountDeletionConfirmation() {
+            assertOpen();
+            const request = input.backend.requestAccountDeletionConfirmation?.bind(input.backend);
+            if (request === undefined) {
+                throw new GuestSessionCoordinatorError('GUEST_SESSION_UNSUPPORTED');
+            }
+            return enqueue(async () => {
+                assertOpen();
+                // Refused earlier (a refresh): say so, not merely "not ready", so the
+                // caller can tell a session that ended on the server from a failed save.
+                if (rejected) {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_REJECTED');
+                }
+                const active = requireCurrent();
+                const grant = await fromBackend(() => request({ refreshToken: active.refreshToken }));
+                // Logged out meanwhile: no confirmation for a closed session.
+                assertOpen();
+                if (!isRecord(grant) || typeof grant.confirmation !== 'string' || grant.confirmation.trim() === ''
+                    || typeof grant.expiresAt !== 'string' || !Number.isFinite(Date.parse(grant.expiresAt))) {
+                    throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_RESPONSE');
+                }
+                return grant.confirmation;
+            });
+        },
         current() {
             return status === 'active' && current !== undefined ? view(current) : undefined;
         },
@@ -396,6 +442,7 @@ export function createGuestServerSession(coordinator, options = {}) {
                 listener(next);
             });
         },
+        requestAccountDeletionConfirmation: () => coordinator.requestAccountDeletionConfirmation(),
         async getHeaders() {
             const active = coordinator.current();
             if (active !== undefined) {
@@ -421,3 +468,151 @@ export function createGuestServerSession(coordinator, options = {}) {
         },
     };
 }
+/**
+ * The HTTP routes of a guest identity service, relative to its base URL:
+ * the contract between `createGuestSessionHttpBackend` and the reference
+ * identity Worker (`apps/game-identity-worker`). Every route takes a JSON
+ * `POST` body. `issueGuest` and `refresh` answer `200` with
+ * `ServerGuestSessionCredentials`; `revoke` answers `200` with `{}`, also for
+ * a token it does not know (RFC 7009 section 2.2); a refusal answers
+ * `{ error: GuestIdentityHttpErrorCode }`. `bindAccount` answers `200` with
+ * an `AccountBindingOutcome` (a `conflict` too), or a refusal; the reference
+ * Worker binds nothing yet and answers `ACCOUNT_BINDING_UNSUPPORTED`.
+ * `requestAccountDeletionConfirmation` takes `{ refreshToken }` and answers
+ * `200` with an `AccountDeletionConfirmationGrant`. A refresh token any
+ * route refuses for good is `GUEST_SESSION_REJECTED`.
+ */
+export const guestIdentityHttpRoutes = Object.freeze({
+    issueGuest: '/identity/v1/guest',
+    refresh: '/identity/v1/refresh',
+    revoke: '/identity/v1/revoke',
+    bindAccount: '/identity/v1/bind-account',
+    requestAccountDeletionConfirmation: '/identity/v1/account-deletion-confirmation',
+});
+/** A failed identity request. The message names the route and the code, never a token. */
+export class GuestSessionHttpError extends Error {
+    status;
+    code;
+    constructor(route, status, code) {
+        super(`Guest identity request ${route} failed: ${status} ${code}.`);
+        this.name = 'GuestSessionHttpError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** How long one identity request may take by default: 15 seconds. */
+export const defaultGuestSessionHttpTimeoutMs = 15_000;
+/**
+ * A `GuestSessionBackend` over a guest identity service's HTTP routes
+ * (`guestIdentityHttpRoutes`). A `refresh` the service refuses with
+ * `GUEST_SESSION_REJECTED` throws `GuestSessionRejectedError` (the
+ * coordinator's `GUEST_SESSION_REJECTED`); any other failure throws
+ * `GuestSessionHttpError` or the fetch error, which the coordinator reports
+ * as `GUEST_SESSION_BACKEND_FAILED`. `baseUrl` must be `https:`, except on a
+ * local development host (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`,
+ * `10.0.2.2`). Requests never follow a redirect, so a token is only ever sent
+ * to `baseUrl`'s origin.
+ */
+export function createGuestSessionHttpBackend(input) {
+    const base = parseGuestIdentityBaseUrl(input.baseUrl);
+    const timeoutMs = input.timeoutMs ?? defaultGuestSessionHttpTimeoutMs;
+    // setTimeout fires at once past a signed 32-bit delay.
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const fetchImpl = input.fetch ?? ((request) => globalThis.fetch(request));
+    async function post(route, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetchImpl(new Request(new URL(route.slice(1), base), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', accept: 'application/json' },
+                body: JSON.stringify(body),
+                redirect: 'manual',
+                signal: controller.signal,
+            }));
+            // A fetch that followed a redirect anyway (some polyfills ignore
+            // `manual`) answered from another origin: never trust that answer.
+            if (response.redirected) {
+                throw new GuestSessionHttpError(route, response.status, 'REDIRECTED');
+            }
+            let payload;
+            try {
+                payload = await response.json();
+            }
+            catch {
+                payload = undefined;
+            }
+            if (response.status !== 200) {
+                const code = isRecord(payload) && typeof payload.error === 'string' && /^[A-Z_]{1,64}$/u.test(payload.error)
+                    ? payload.error
+                    : 'UNKNOWN';
+                throw new GuestSessionHttpError(route, response.status, code);
+            }
+            // A 200 that is not a JSON object (a captive portal's page, a body cut
+            // off by the timeout) is a failure, so a revoke is never assumed done.
+            if (!isRecord(payload)) {
+                throw new GuestSessionHttpError(route, response.status, 'INVALID_BODY');
+            }
+            return payload;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        async issueGuest({ installationId }) {
+            return await post(guestIdentityHttpRoutes.issueGuest, { installationId });
+        },
+        async refresh({ refreshToken }) {
+            return await withRejection(post(guestIdentityHttpRoutes.refresh, { refreshToken }));
+        },
+        async revoke({ refreshToken }) {
+            await post(guestIdentityHttpRoutes.revoke, { refreshToken });
+        },
+        async bindAccount({ refreshToken, externalProof, idempotencyKey }) {
+            return await withRejection(post(guestIdentityHttpRoutes.bindAccount, {
+                refreshToken,
+                externalProof,
+                idempotencyKey,
+            }));
+        },
+        async requestAccountDeletionConfirmation({ refreshToken }) {
+            return await withRejection(post(guestIdentityHttpRoutes.requestAccountDeletionConfirmation, { refreshToken }));
+        },
+    };
+}
+/** The service's `401 GUEST_SESSION_REJECTED` as `GuestSessionRejectedError`; other failures unchanged. */
+async function withRejection(request) {
+    try {
+        return await request;
+    }
+    catch (error) {
+        if (error instanceof GuestSessionHttpError && error.status === 401 && error.code === 'GUEST_SESSION_REJECTED') {
+            throw new GuestSessionRejectedError();
+        }
+        throw error;
+    }
+}
+function parseGuestIdentityBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    const host = url.hostname.toLowerCase();
+    const local = host === 'localhost' || host.endsWith('.localhost') || host === '127.0.0.1'
+        || host === '[::1]' || host === '10.0.2.2';
+    if (!(url.protocol === 'https:' || (url.protocol === 'http:' && local))
+        || url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') {
+        throw new GuestSessionCoordinatorError('GUEST_SESSION_INVALID_INPUT');
+    }
+    // Routes resolve under the base path, so `https://host/api` serves `/api/identity/v1/...`.
+    if (!url.pathname.endsWith('/')) {
+        url.pathname = `${url.pathname}/`;
+    }
+    return url;
+}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
+export * from './account-deletion.js';
 export * from './admob-ssv.js';
 export * from './ad-reward-verifier-registry.js';
 export * from './app-store-verifier.js';
 export * from './app-store-recovery.js';
+export * from './app-store-server-notifications.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
@@ -17,6 +19,7 @@ export * from './evidence-verification.js';
 export * from './guest-session.js';
 export * from './google-play-purchase.js';
 export * from './google-play-publisher-client.js';
+export * from './google-play-store-server.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
 export * from './monetization-operation-store.js';
@@ -24,6 +27,7 @@ export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';
 export * from './progress-link.js';
+export * from './purchase-sharing.js';
 export * from './runtime.js';
 export * from './server.js';
 export * from './types.js';

package/dist/index.js

@@ -1,7 +1,9 @@
+export * from './account-deletion.js';
 export * from './admob-ssv.js';
 export * from './ad-reward-verifier-registry.js';
 export * from './app-store-verifier.js';
 export * from './app-store-recovery.js';
+export * from './app-store-server-notifications.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
@@ -17,6 +19,7 @@ export * from './evidence-verification.js';
 export * from './guest-session.js';
 export * from './google-play-purchase.js';
 export * from './google-play-publisher-client.js';
+export * from './google-play-store-server.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
 export * from './monetization-operation-store.js';
@@ -24,6 +27,7 @@ export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';
 export * from './progress-link.js';
+export * from './purchase-sharing.js';
 export * from './runtime.js';
 export * from './server.js';
 export * from './types.js';

package/dist/notifications/delivery-provider.d.ts

@@ -22,6 +22,13 @@ export interface NotificationDeviceAddress {
   readonly kind: 'fcm-token' | 'fcm-installation';
   readonly value: string;
   readonly environment?: 'production' | 'sandbox';
+  /**
+  * The installation's shell renders advertising pushes itself, with the
+  * opt-out action (an Android shell with the kit's renderer). The backend
+  * keeps it only for a target whose pushes need it, and the FCM provider
+  * then sends advertising as a data message the shell renders.
+  */
+  readonly rendersAdvertising?: boolean;
 }
 /** Who one delivery goes to: a device endpoint, or a resolved platform identity. */
 export type NotificationRemoteRecipient = {

package/dist/notifications/fcm.d.ts

@@ -14,9 +14,11 @@ import type { NotificationProviderRegistration } from './registry.js';
 * Android posts to the mapping's `channelId`, else to `mpgd-service`,
 * `mpgd-requested`, or `mpgd-advertising` by purpose. An advertising send
 * names the iOS category `mpgd-advertising`, whose opt-out action the app
-* registers; an Android FCM notification message cannot carry actions, and
-* the Capacitor shell does not render advertising natively yet. An expiry
-* becomes `android.ttl` and the `apns-expiration` header. A replay of the
+* registers. An Android FCM notification message cannot carry actions, so an
+* advertising send to an endpoint whose registration says its shell renders
+* advertising (`rendersAdvertising`) is a data message the shell renders
+* with the action (`fcmShellRenderedDataKeys`). An expiry becomes
+* `android.ttl` and the `apns-expiration` header. A replay of the
 * same send key sets `android.collapse_key` and `apns-collapse-id` so a
 * crash after HTTP 200, before the ledger write, does not show a second
 * notification.
@@ -35,6 +37,31 @@ export declare const fcmReservedDataKeys: readonly ["topic", "route"];
 /** The iOS notification category of advertising, which carries the opt-out action. */
 export declare const fcmAdvertisingCategory = "mpgd-advertising";
 /**
+* The data keys of an advertising push the Android shell renders itself
+* (RFC "Delivery providers"). An Android FCM notification message cannot
+* carry actions, so such a push has no `notification` block: the app's
+* messaging service receives it in the background too and posts it with the
+* opt-out action. `render` is `fcmShellRenderedAdvertising`; `title` and
+* `body` are the gate's rendered text, `channel` the Android channel,
+* `actionTitle` and `optOutRoute` the opt-out action's title and route (the
+* topic's declared opt-out route) when the content carries the action, and
+* `expiresAt` the expiry in epoch milliseconds, after which the
+* shell does not show it. The send's `topic` and `route` stay in their own
+* keys, as on every push. A send's routing data may not use the `mpgd.`
+* prefix.
+*/
+export declare const fcmShellRenderedDataKeys: Readonly<{
+  readonly render: 'mpgd.render';
+  readonly title: 'mpgd.title';
+  readonly body: 'mpgd.body';
+  readonly channel: 'mpgd.channel';
+  readonly actionTitle: 'mpgd.actionTitle';
+  readonly optOutRoute: 'mpgd.optOutRoute';
+  readonly expiresAt: 'mpgd.expiresAt';
+}>;
+/** The `mpgd.render` value of an advertising push the shell renders. */
+export declare const fcmShellRenderedAdvertising = "advertising";
+/**
 * `android.collapse_key` and `apns-collapse-id` are at most 64 bytes. The
 * id is the SHA-256 of the send key, which is 64 hex characters.
 */

package/dist/notifications/fcm.js

@@ -1,4 +1,4 @@
-import { referenceNotificationProviders } from '@mpgd/platform/notifications';
+import { notificationAdvertisingOptOutActionId, referenceNotificationProviders, } from '@mpgd/platform/notifications';
 import { fcmInstallationIdRefusal, } from './delivery-provider.js';
 /**
  * The FCM remote delivery provider (notifications v2 RFC, "Delivery
@@ -14,9 +14,11 @@ import { fcmInstallationIdRefusal, } from './delivery-provider.js';
  * Android posts to the mapping's `channelId`, else to `mpgd-service`,
  * `mpgd-requested`, or `mpgd-advertising` by purpose. An advertising send
  * names the iOS category `mpgd-advertising`, whose opt-out action the app
- * registers; an Android FCM notification message cannot carry actions, and
- * the Capacitor shell does not render advertising natively yet. An expiry
- * becomes `android.ttl` and the `apns-expiration` header. A replay of the
+ * registers. An Android FCM notification message cannot carry actions, so an
+ * advertising send to an endpoint whose registration says its shell renders
+ * advertising (`rendersAdvertising`) is a data message the shell renders
+ * with the action (`fcmShellRenderedDataKeys`). An expiry becomes
+ * `android.ttl` and the `apns-expiration` header. A replay of the
  * same send key sets `android.collapse_key` and `apns-collapse-id` so a
  * crash after HTTP 200, before the ledger write, does not show a second
  * notification.
@@ -34,6 +36,31 @@ export const fcmAddressKinds = Object.freeze(['fcm-token']);
 export const fcmReservedDataKeys = Object.freeze(['topic', 'route']);
 /** The iOS notification category of advertising, which carries the opt-out action. */
 export const fcmAdvertisingCategory = 'mpgd-advertising';
+/**
+ * The data keys of an advertising push the Android shell renders itself
+ * (RFC "Delivery providers"). An Android FCM notification message cannot
+ * carry actions, so such a push has no `notification` block: the app's
+ * messaging service receives it in the background too and posts it with the
+ * opt-out action. `render` is `fcmShellRenderedAdvertising`; `title` and
+ * `body` are the gate's rendered text, `channel` the Android channel,
+ * `actionTitle` and `optOutRoute` the opt-out action's title and route (the
+ * topic's declared opt-out route) when the content carries the action, and
+ * `expiresAt` the expiry in epoch milliseconds, after which the
+ * shell does not show it. The send's `topic` and `route` stay in their own
+ * keys, as on every push. A send's routing data may not use the `mpgd.`
+ * prefix.
+ */
+export const fcmShellRenderedDataKeys = Object.freeze({
+    render: 'mpgd.render',
+    title: 'mpgd.title',
+    body: 'mpgd.body',
+    channel: 'mpgd.channel',
+    actionTitle: 'mpgd.actionTitle',
+    optOutRoute: 'mpgd.optOutRoute',
+    expiresAt: 'mpgd.expiresAt',
+});
+/** The `mpgd.render` value of an advertising push the shell renders. */
+export const fcmShellRenderedAdvertising = 'advertising';
 /**
  * FCM's 4,096-byte limit, less room for what FCM and APNs add on the way
  * (the `aps` wrapper and FCM's own keys), so a message this check passes is
@@ -319,9 +346,38 @@ export function buildFcmMessage(request) {
     // instead of showing beside it. Collapse is per token, so two devices of
     // one send do not hide each other.
     const collapseId = fcmCollapseId(request.sendKey);
+    const ttl = expiresAt === undefined ? {} : { ttl: `${Math.floor((expiresAt - at) / 1000)}s` };
+    if (request.topic.purpose === 'advertising' && recipient.address.rendersAdvertising === true) {
+        // A data message without a `notification` block reaches the shell's
+        // messaging service in the background too, which renders it with the
+        // opt-out action. Normal priority, FCM's default for data and
+        // notification messages alike: FCM keeps high priority for urgent,
+        // time-sensitive messages, and advertising is not one. The shell's
+        // renderer checks the expiry again, since arrival decides.
+        const optOut = content.actions
+            ?.find((action) => action.id === notificationAdvertisingOptOutActionId);
+        const rendered = Object.create(null);
+        Object.assign(rendered, data, {
+            [fcmShellRenderedDataKeys.render]: fcmShellRenderedAdvertising,
+            [fcmShellRenderedDataKeys.title]: content.title,
+            [fcmShellRenderedDataKeys.body]: content.body,
+            [fcmShellRenderedDataKeys.channel]: channelId,
+            ...(optOut === undefined
+                ? {}
+                : {
+                    [fcmShellRenderedDataKeys.actionTitle]: optOut.title,
+                    [fcmShellRenderedDataKeys.optOutRoute]: optOut.route,
+                }),
+            ...(expiresAt === undefined ? {} : { [fcmShellRenderedDataKeys.expiresAt]: String(expiresAt) }),
+        });
+        return sizedMessage(recipient.address.value, {
+            data: { ...rendered },
+            android: { collapse_key: collapseId, ...ttl },
+        });
+    }
     const android = {
         collapse_key: collapseId,
-        ...(expiresAt === undefined ? {} : { ttl: `${Math.floor((expiresAt - at) / 1000)}s` }),
+        ...ttl,
         notification: { channel_id: channelId },
     };
     const category = request.topic.purpose === 'advertising' ? fcmAdvertisingCategory : undefined;
@@ -332,12 +388,15 @@ export function buildFcmMessage(request) {
         },
         ...(category === undefined ? {} : { payload: { aps: { category } } }),
     };
-    const payload = {
+    return sizedMessage(recipient.address.value, {
         notification,
         data: { ...data },
         android,
         apns,
-    };
+    });
+}
+/** The message for `token`, unless its payload is over the size this provider sends. */
+function sizedMessage(token, payload) {
     // Everything but the token counts toward the size FCM and APNs carry.
     const payloadBytes = new TextEncoder().encode(JSON.stringify(payload)).length;
     if (payloadBytes > maxPayloadBytes) {
@@ -347,10 +406,7 @@ export function buildFcmMessage(request) {
             code: 'INVALID_MESSAGE',
         };
     }
-    return {
-        status: 'ready',
-        message: { token: recipient.address.value, ...payload },
-    };
+    return { status: 'ready', message: { token, ...payload } };
 }
 /**
  * Maps an FCM error answer to the provider answer kinds (RFC "Delivery
@@ -518,7 +574,7 @@ function isFirebaseProjectId(id) {
         && id.length <= 100
         && new RegExp(`^(?:${label}(?:\\.${label})*:)?${label}$`, 'u').test(id);
 }
-/** FCM's reserved data keys (`from`, `message_type`, and any `google` or `gcm` prefix), `topic` and `route`, and keys a plain object cannot hold. */
+/** FCM's reserved data keys (`from`, `message_type`, and any `google` or `gcm` prefix), `topic` and `route`, the shell renderer's `mpgd.` keys, and keys a plain object cannot hold. */
 function isReservedDataKey(key) {
     const lower = key.toLowerCase();
     return key === ''
@@ -532,7 +588,10 @@ function isReservedDataKey(key) {
         || key === 'aps'
         || key === 'fcm_options'
         || lower.startsWith('google')
-        || lower.startsWith('gcm');
+        || lower.startsWith('gcm')
+        // The shell renderer's keys (`fcmShellRenderedDataKeys`) and the keys it
+        // adds to an open.
+        || lower.startsWith('mpgd.');
 }
 /** The `details` of an FCM error answer. */
 function errorDetailsOf(body) {