@mpgd/adapter-devvit 0.13.5 → 0.14.0

package/README.md

@@ -4,9 +4,9 @@ Reddit Devvit Web platform adapter for mpgd games.
 
 | Entry point | Purpose |
 | --- | --- |
-| `@mpgd/adapter-devvit` | `createDevvitPlatformGateway`, the oRPC bridge and sandbox bridge, the commerce provider and catalog helpers, the Devvit notifications profile values |
+| `@mpgd/adapter-devvit` | `createDevvitPlatformGateway`, the oRPC bridge and sandbox bridge, the commerce provider and catalog helpers, the Devvit notifications profile values, `createDevvitNotificationsBackend` (the notifications runtime's backend) |
 | `@mpgd/adapter-devvit/payments` | `normalizeDevvitCommerceProducts` and the checkout types |
-| `@mpgd/adapter-devvit/server` | `createDevvitCommerceV2BridgeHandler`, `createDevvitNotificationsV2BridgeHandler`, the notifications service and delivery provider, payment-order normalizers, durable post operations, Redis stores |
+| `@mpgd/adapter-devvit/server` | `createDevvitCommerceV2BridgeHandler`, `createDevvitNotificationsV2BridgeHandler`, `createDevvitNotificationsBackendBridgeHandler`, the notifications service and delivery provider, payment-order normalizers, durable post operations, Redis stores |
 | `@mpgd/adapter-devvit/web` | Webview helpers, including `createDevvitWebPaymentsClient()` over `purchase()` and `createDevvitWebLoginPrompt()` over `showLoginPrompt()` from `@devvit/web/client` |
 | `@mpgd/adapter-devvit/surface`, `/view-mode` | Inline and expanded view-mode helpers |
 
@@ -76,6 +76,38 @@ Reddit approves. The profile follows the
   `runDevvitNotificationTask(service, task)`, as the kit's
   `apps/target-devvit` server does. A player's `setReminder` fires through
   the dispatch task.
+- **The runtime's backend.** The game's notifications runtime
+  (`createNotificationRuntime` from `@mpgd/platform/notifications-runtime`)
+  keeps consent records, the player's registration (locale and zone),
+  server reminders, and notices in that same service:
+  - The server passes
+    `createDevvitNotificationsBackendBridgeHandler({ service, context: () => context })`
+    as the bridge's `notificationsBackend` dependency. It serves the nine
+    `notifications.backend.*` methods for `devvitNotificationSessionFromContext(context())`,
+    the request's logged-in user, never a payload field; a call that names
+    another player (`expectedPlayer`) or comes from a logged-out viewer is
+    refused before the service. Without the dependency the bridge answers
+    `NOTIFICATIONS_CONFIGURATION_REQUIRED`.
+  - The webview passes `createDevvitNotificationsBackend({ appVersion, buildId })`
+    as the runtime's `backend`. Its client loads in its own chunk and reads
+    the session the server answers (`getSession`), so the game sets no session
+    of its own; it announces the player to the runtime, reads again when the
+    server refuses a call for another user, and retries a failed read at most
+    every 5 seconds when the runtime next reads the session. Requests time
+    out after 15 seconds. While the server answers signed out, the client
+    keeps reading the session at most every 5 seconds as the runtime reads
+    it, so a login is picked up whether or not Reddit reloads the post after
+    `showLoginPrompt()`. The runtime's
+    `unregister()` call removes this installation's endpoint record for the
+    user and provider; the platform-user
+    registration (locale and zone) is not an endpoint and stays, and sends
+    still need the user's opt-in.
+  - A reminder set through the runtime (`runtime.reminders.set`) is stored
+    by the service and fired by the `dispatch` task through `enqueue`, with
+    the reminder's `link` (a post or comment id such as `context.postId` from
+    `@devvit/web/client`) or the topic mapping's default `link`. Notices stay empty unless the deployment applies the Korean
+    rules, and Devvit carries no advertising topic, so the starter shows no
+    advertising or night consent on Reddit.
 - **Opens.** A notification opens its post; the game routes from that post's
   data.
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { type BridgeMethod, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import { type BridgeRpcClient, type BridgeRpcEndpoint } from '@mpgd/bridge/orpc';
 import { type PlatformGateway } from '@mpgd/platform';
+import type { NotificationRuntimeBackend, NotificationRuntimeSession } from '@mpgd/platform/notifications-runtime';
 import { type CreateDevvitCommerceProviderInput, type DevvitOrderSource } from './commerce-provider.js';
 export * from './commerce-contract.js';
 export * from './commerce-provider.js';
@@ -86,6 +87,62 @@ export type DevvitNotificationClientModule = Pick<typeof import('./notifications
 export interface DevvitLoginPrompt {
   showLoginPrompt(): void;
 }
+/** Where a request goes: the injected bridge, the host's global bridge, the fallback, or the oRPC bridge. */
+type DevvitBridgeTarget = Pick<DevvitPlatformGatewayOptions, 'appVersion' | 'buildId' | 'bridge' | 'fallbackBridge' | 'rpcEndpoint'>;
+export interface DevvitNotificationsBackendOptions extends DevvitBridgeTarget {
+  /** How long one backend request may take; 15 seconds by default (see `createDevvitNotificationsBackendClient`). */
+  readonly timeoutMs?: number;
+  /**
+  * While the client chunk has not loaded, or no session read has settled
+  * (none answered a signed-in player, and none failed in a way a retry
+  * cannot change), `session()` tries again at most this
+  * often; 5 seconds by default. After a
+  * load the client refuses (options out of range), `session()` does not try
+  * again; the other calls answer `NOTIFICATIONS_INVALID_INPUT`, except
+  * `unregisterEndpoint`, which has nothing to unbind and resolves.
+  */
+  readonly retryIntervalMs?: number;
+  /** The clock the retry interval reads, in milliseconds; `Date.now` by default. */
+  readonly now?: () => number;
+  /** Loads the backend client chunk, when the backend is created; the dynamic import by default. Tests inject it. */
+  readonly load?: () => Promise<DevvitNotificationsBackendClientModule>;
+}
+/** What `createDevvitNotificationsBackend` uses from the backend client chunk. */
+export type DevvitNotificationsBackendClientModule = Pick<typeof import('./notifications-backend-client.js'), 'createDevvitNotificationsBackendClient'>;
+/** The notifications runtime's backend on Devvit, with the session read the server answers. */
+export interface DevvitNotificationsBackend extends NotificationRuntimeBackend {
+  /**
+  * Reads the session the Devvit server answers for the request's logged-in
+  * user and announces a new one through `onAuthenticated`; the backend
+  * starts one read when it is created.
+  */
+  refreshSession(): Promise<NotificationRuntimeSession | undefined>;
+}
+/**
+* The notifications runtime's backend for a Reddit game
+* (`NotificationRuntimeBackend` for `createNotificationRuntime` from
+* `@mpgd/platform/notifications-runtime`): the Devvit server's notifications
+* service over the same server bridge as `createDevvitPlatformGateway`,
+* served by `createDevvitNotificationsBackendBridgeHandler` from
+* `@mpgd/adapter-devvit/server`.
+*
+* Its client and validators load in their own chunk, starting now, and the
+* backend reads the session as soon as they have loaded. Until the server
+* has answered for a logged-in user, `session()` is `undefined` and calls
+* answer `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`; the runtime hears of the
+* user through `onAuthenticated`. A chunk that fails to load is
+* `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` too; the next call, or a
+* `session()` read at most once per `retryIntervalMs`, loads again, and a
+* session read that failed is retried the same way. Options the client
+* refuses are not retried from `session()`: calls answer
+* `NOTIFICATIONS_INVALID_INPUT`, and the refusal is logged once. While the
+* server answers signed out, `session()` reads again at most once per
+* `retryIntervalMs`, so a login is picked up whether or not Reddit reloads
+* the post.
+* The player is always the one the server answers for; the webview never
+* names one it chose.
+*/
+export declare function createDevvitNotificationsBackend(options: DevvitNotificationsBackendOptions): DevvitNotificationsBackend;
 export declare function createDevvitPlatformGateway(input: DevvitPlatformGatewayOptions): PlatformGateway;
 /**
 * The webview provider's order source over the server bridge: the paid orders

package/dist/index.js

@@ -26,8 +26,9 @@ export class DevvitBridgeError extends Error {
         this.retryable = response.error.retryable;
     }
 }
-export function createDevvitPlatformGateway(input) {
-    async function request(method, payload) {
+/** Sends one request over the bridge the gateway uses; a bridge error rejects as a `DevvitBridgeError`. */
+function createDevvitBridgeRequest(input) {
+    return async function request(method, payload) {
         const bridge = input.bridge ??
             getBridge() ??
             input.fallbackBridge ??
@@ -47,7 +48,139 @@ export function createDevvitPlatformGateway(input) {
             throw new DevvitBridgeError(response);
         }
         return response.data;
-    }
+    };
+}
+/**
+ * The notifications runtime's backend for a Reddit game
+ * (`NotificationRuntimeBackend` for `createNotificationRuntime` from
+ * `@mpgd/platform/notifications-runtime`): the Devvit server's notifications
+ * service over the same server bridge as `createDevvitPlatformGateway`,
+ * served by `createDevvitNotificationsBackendBridgeHandler` from
+ * `@mpgd/adapter-devvit/server`.
+ *
+ * Its client and validators load in their own chunk, starting now, and the
+ * backend reads the session as soon as they have loaded. Until the server
+ * has answered for a logged-in user, `session()` is `undefined` and calls
+ * answer `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`; the runtime hears of the
+ * user through `onAuthenticated`. A chunk that fails to load is
+ * `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` too; the next call, or a
+ * `session()` read at most once per `retryIntervalMs`, loads again, and a
+ * session read that failed is retried the same way. Options the client
+ * refuses are not retried from `session()`: calls answer
+ * `NOTIFICATIONS_INVALID_INPUT`, and the refusal is logged once. While the
+ * server answers signed out, `session()` reads again at most once per
+ * `retryIntervalMs`, so a login is picked up whether or not Reddit reloads
+ * the post.
+ * The player is always the one the server answers for; the webview never
+ * names one it chose.
+ */
+export function createDevvitNotificationsBackend(options) {
+    const request = createDevvitBridgeRequest(options);
+    const importClient = options.load ?? (() => import('./notifications-backend-client.js'));
+    // `defaultDevvitNotificationsBackendRetryIntervalMs` of the client chunk, which this entry does not import.
+    const retryIntervalMs = options.retryIntervalMs ?? 5_000;
+    const now = options.now ?? Date.now;
+    const listeners = new Set();
+    let client;
+    let loading;
+    /** When the last chunk load started or failed, whichever is later. */
+    let lastLoadAt;
+    /** A load failed in a way another load cannot change (options the client refuses). */
+    let loadRefused = false;
+    const load = () => {
+        if (client !== undefined) {
+            return Promise.resolve(client);
+        }
+        if (loading !== undefined) {
+            return loading;
+        }
+        lastLoadAt = now();
+        const attempt = (async () => {
+            let module;
+            try {
+                module = await importClient();
+            }
+            catch (error) {
+                throw new PlatformOperationError({
+                    code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                    message: `The Devvit notifications backend client did not load: ${errorMessage(error)}`,
+                    retryable: true,
+                });
+            }
+            // Options the client refuses (a timeoutMs out of range) fail as they are, not as a load to retry.
+            const created = module.createDevvitNotificationsBackendClient({
+                request: (method, payload) => request(method, payload),
+                retryIntervalMs,
+                now,
+                ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            });
+            created.onAuthenticated((session) => {
+                for (const listener of [...listeners]) {
+                    try {
+                        listener(session);
+                    }
+                    catch {
+                        // One listener failing never keeps the session from the others.
+                    }
+                }
+            });
+            client = created;
+            // Read the session now, so the runtime hears of a logged-in user.
+            void created.refreshSession().catch(() => { });
+            return created;
+        })();
+        loading = attempt;
+        attempt.then(() => {
+            loading = undefined;
+        }, (error) => {
+            loading = undefined;
+            lastLoadAt = now();
+            const refused = !(typeof error === 'object' && error !== null
+                && error.retryable === true);
+            if (refused && !loadRefused) {
+                console.error('[notifications] the Devvit notifications backend refused its options.', error);
+            }
+            loadRefused = loadRefused || refused;
+        });
+        return attempt;
+    };
+    void load().catch(() => { });
+    return {
+        session() {
+            if (client !== undefined) {
+                return client.session();
+            }
+            // The runtime makes no backend call while it sees no session, so a
+            // chunk that failed to load is loaded again from here.
+            // A load another load cannot fix is not retried from here; calls still report it.
+            if (loading === undefined
+                && !loadRefused
+                && (lastLoadAt === undefined || !withinBackendRetryInterval(now() - lastLoadAt, retryIntervalMs))) {
+                void load().catch(() => { });
+            }
+            return undefined;
+        },
+        onAuthenticated(listener) {
+            const entry = (session) => listener(session);
+            listeners.add(entry);
+            return () => {
+                listeners.delete(entry);
+            };
+        },
+        refreshSession: async () => (await load()).refreshSession(),
+        recordConsent: async (record) => (await load()).recordConsent(record),
+        listConsent: async () => (await load()).listConsent(),
+        registerEndpoint: async (registration) => (await load()).registerEndpoint(registration),
+        // Nothing was registered before the client loaded, and no session is signed in.
+        unregisterEndpoint: async (input) => client?.unregisterEndpoint(input),
+        setReminder: async (reminder) => (await load()).setReminder(reminder),
+        cancelReminder: async (input) => (await load()).cancelReminder(input),
+        listNotices: async () => (await load()).listNotices(),
+        recordNotice: async (input) => (await load()).recordNotice(input),
+    };
+}
+export function createDevvitPlatformGateway(input) {
+    const request = createDevvitBridgeRequest(input);
     const commerce = input.commerce === undefined
         ? undefined
         : createDevvitCommerceProvider({
@@ -442,6 +575,15 @@ function generateRequestId() {
     }
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+/**
+ * Whether `elapsed` milliseconds are still inside the retry interval; a
+ * clock that went backwards (a negative or non-finite difference) counts as
+ * past it. The same rule as the client chunk's `withinRetryInterval`, which
+ * this entry does not import.
+ */
+function withinBackendRetryInterval(elapsed, retryIntervalMs) {
+    return elapsed >= 0 && elapsed < retryIntervalMs;
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/notifications-backend-client.d.ts

@@ -0,0 +1,67 @@
+import type { BridgeNotificationsBackendMethod } from '@mpgd/bridge';
+import type { NotificationRuntimeBackend, NotificationRuntimeSession } from '@mpgd/platform/notifications-runtime';
+/**
+* The webview side of the notifications runtime's backend on Devvit
+* (notifications v2 RFC, "Bridge and versioning", "Backend methods"): a
+* `NotificationRuntimeBackend` over the Devvit server bridge, which serves
+* the Devvit notifications service from
+* `createDevvitNotificationsBackendBridgeHandler`
+* (`@mpgd/adapter-devvit/server`). Loaded in its own chunk.
+*
+* - **Session.** The client never chooses a player. It reads the session
+*   the server answers for the request's logged-in user (`getSession`,
+*   through `refreshSession()`), and `session()` answers the last one read.
+*   Every call names that player as `expectedPlayer`; the server acts for
+*   its own user and refuses a call whose player is not it. A refusal for a
+*   logged-out or changed user makes the client read the session again
+*   (announcing a new one through `onAuthenticated`) and answers
+*   `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`, which the runtime retries at
+*   its next trigger.
+* - **Errors.** A bridge error with a `NOTIFICATIONS_*` code keeps its code,
+*   retryable flag, and host code. `UNSUPPORTED_METHOD`,
+*   `INVALID_BRIDGE_REQUEST`, and `NOTIFICATIONS_V2_UNAVAILABLE` from a
+*   server that serves no backend are `NOTIFICATIONS_CONFIGURATION_REQUIRED`
+*   (not retryable), as the game-services client reads a Worker without the
+*   session routes. An answer outside the method's contract is
+*   `NOTIFICATIONS_CONFIGURATION_REQUIRED`. Anything else (the transport
+*   failing) and a request with no answer within `timeoutMs` is a retryable
+*   `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`; a request that timed out may
+*   still have reached the server. A payload the bridge contract refuses is
+*   `NOTIFICATIONS_INVALID_INPUT` and is not sent.
+*/
+export interface CreateDevvitNotificationsBackendClientInput {
+  /** Sends one server bridge request and returns its data; a bridge error rejects with its `code`, `message`, and `retryable`. */
+  readonly request: (method: BridgeNotificationsBackendMethod, payload: unknown) => Promise<unknown>;
+  /**
+  * How long one request may take before the client stops waiting and
+  * answers `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`; 15 seconds by default,
+  * at most 2147483647. Devvit ends a server request after 30 seconds.
+  */
+  readonly timeoutMs?: number;
+  /**
+  * While no session read has settled (none was made, the last one answered
+  * signed out, or it failed in a way a retry may fix), `session()` and a
+  * call that finds no session start another read, at most one this often;
+  * 5 seconds by default. 0 reads again on every such call, one at a time.
+  */
+  readonly retryIntervalMs?: number;
+  /** The clock the retry interval reads, in milliseconds; `Date.now` by default. */
+  readonly now?: () => number;
+}
+export interface DevvitNotificationsBackendClient extends NotificationRuntimeBackend {
+  /**
+  * Reads the session the server answers for the request's user, keeps it
+  * for `session()`, and announces it through `onAuthenticated` when it is a
+  * new one (a first sign-in, or another user). A logged-out answer clears
+  * it, and `session()` keeps reading at `retryIntervalMs` until a player
+  * signs in. Concurrent reads share one request. A read that fails keeps the
+  * session as it was and rejects.
+  */
+  refreshSession(): Promise<NotificationRuntimeSession | undefined>;
+}
+/** The default `timeoutMs`: a request still unanswered after this is no longer awaited. */
+export declare const defaultDevvitNotificationsBackendTimeoutMs = 15000;
+/** The default `retryIntervalMs` between session reads while none has settled. */
+export declare const defaultDevvitNotificationsBackendRetryIntervalMs = 5000;
+/** Creates the client. It holds no session until `refreshSession()` has read one. */
+export declare function createDevvitNotificationsBackendClient(input: CreateDevvitNotificationsBackendClientInput): DevvitNotificationsBackendClient;

package/dist/notifications-backend-client.js

@@ -0,0 +1,319 @@
+import { assertBridgeNotificationsBackendPayload, assertBridgeNotificationsBackendResult, notificationsBackendBridgeHostCodes, readBridgeNotificationsHostCode, } from '@mpgd/bridge/notifications';
+import { isNotificationErrorCode, NotificationError, notificationsProtocol, } from '@mpgd/platform/notifications';
+/** The default `timeoutMs`: a request still unanswered after this is no longer awaited. */
+export const defaultDevvitNotificationsBackendTimeoutMs = 15_000;
+/** The default `retryIntervalMs` between session reads while none has settled. */
+export const defaultDevvitNotificationsBackendRetryIntervalMs = 5_000;
+/** Bridge codes a server that serves no notifications backend answers with. */
+const backendUnavailableCodes = new Set([
+    'UNSUPPORTED_METHOD',
+    'INVALID_BRIDGE_REQUEST',
+    'NOTIFICATIONS_V2_UNAVAILABLE',
+]);
+/** Host codes of a call the server refused for its session; nothing was read or changed. */
+const sessionRefusalHostCodes = new Set([
+    notificationsBackendBridgeHostCodes.signedOut,
+    notificationsBackendBridgeHostCodes.sessionChanged,
+]);
+/** Creates the client. It holds no session until `refreshSession()` has read one. */
+export function createDevvitNotificationsBackendClient(input) {
+    const timeoutMs = input.timeoutMs ?? defaultDevvitNotificationsBackendTimeoutMs;
+    // setTimeout takes at most 2^31 - 1 ms; a longer delay would fire at once.
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'The Devvit notifications backend timeoutMs must be a positive number of milliseconds, at most 2147483647.',
+        });
+    }
+    const retryIntervalMs = input.retryIntervalMs ?? defaultDevvitNotificationsBackendRetryIntervalMs;
+    if (!Number.isFinite(retryIntervalMs) || retryIntervalMs < 0) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'The Devvit notifications backend retryIntervalMs must be a non-negative number of milliseconds.',
+        });
+    }
+    const now = input.now ?? Date.now;
+    let current;
+    let refreshing;
+    /** When the last session read started or settled, whichever is later. */
+    let lastReadAt;
+    /**
+     * Whether the session read settled: the server answered a
+     * signed-in player, or a read failed in a way a retry cannot change (a
+     * server without the backend, or an answer outside the contract, which
+     * only a fixed server or a reload changes). Until then `session()` and a
+     * call that finds no session start a read (`retryIfUnsettled`): a first
+     * read that failed (offline, timed out) is tried again, and so is a
+     * signed-out answer, so a login is picked up whether or not Reddit
+     * reloads the post, even though the runtime makes no backend call while
+     * it sees no session. A later signed-out answer (an explicit
+     * `refreshSession()`, or the read after a refusal) unsettles it again.
+     */
+    let sessionSettled = false;
+    const listeners = new Set();
+    const send = async (method, payload) => {
+        try {
+            assertBridgeNotificationsBackendPayload(method, payload);
+        }
+        catch (error) {
+            throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+                message: `${method}: the request is outside the bridge contract; it was not sent.`,
+                cause: error,
+            });
+        }
+        let timer;
+        let data;
+        try {
+            data = await Promise.race([
+                input.request(method, payload),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => {
+                        reject(new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', {
+                            message: `${method}: the Devvit server did not answer within ${timeoutMs} ms; the client stopped `
+                                + 'waiting, and the server may still have handled it.',
+                        }));
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        catch (error) {
+            throw toNotificationError(method, error);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        try {
+            return assertBridgeNotificationsBackendResult(method, data);
+        }
+        catch (error) {
+            throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+                message: `The Devvit server answered ${method} outside the notifications backend contract.`,
+                cause: error,
+            });
+        }
+    };
+    const announce = (session) => {
+        for (const listener of [...listeners]) {
+            try {
+                listener(session);
+            }
+            catch {
+                // One listener failing never keeps the session from the others.
+            }
+        }
+    };
+    const refreshSession = () => {
+        if (refreshing !== undefined) {
+            return refreshing;
+        }
+        lastReadAt = now();
+        const attempt = (async () => {
+            let session;
+            try {
+                ({ session } = await send('notifications.backend.getSession', { protocol: notificationsProtocol }));
+            }
+            catch (error) {
+                if (error instanceof NotificationError && !error.retryable) {
+                    sessionSettled = true;
+                }
+                throw error;
+            }
+            // A signed-out answer leaves the read unsettled: the player may log in
+            // without the post being reloaded, so the next read asks again.
+            sessionSettled = session !== null;
+            if (session === null) {
+                current = undefined;
+                return undefined;
+            }
+            const previous = current;
+            const next = { id: session.id, player: session.player };
+            if (previous?.id === next.id && previous.player === next.player) {
+                return previous;
+            }
+            current = next;
+            announce(next);
+            return next;
+        })();
+        refreshing = attempt;
+        // The next read asks again once this one settles, whatever it answered;
+        // a retry waits the interval from the settle, so a read that timed out
+        // is not followed by another at once.
+        void attempt.then(() => {
+            refreshing = undefined;
+            lastReadAt = now();
+        }, () => {
+            refreshing = undefined;
+            lastReadAt = now();
+        });
+        return attempt;
+    };
+    const requireSession = (method) => {
+        if (current === undefined) {
+            retryIfUnsettled();
+            throw new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', {
+                message: `${method} needs a signed-in player; no request was sent.`,
+            });
+        }
+        return current;
+    };
+    /**
+     * While no session is known and no read has settled (none was made, the
+     * last one answered signed out, or it failed in a way a retry may fix),
+     * starts a read in the
+     * background, at most one at a time and one per `retryIntervalMs`, so the
+     * runtime hears of a signed-in player through onAuthenticated instead of
+     * waiting forever.
+     */
+    const retryIfUnsettled = () => {
+        if (current !== undefined
+            || sessionSettled
+            || refreshing !== undefined
+            || (lastReadAt !== undefined && withinRetryInterval(now() - lastReadAt, retryIntervalMs))) {
+            return;
+        }
+        void refreshSession().catch(() => undefined);
+    };
+    /**
+     * Reads the session again after the server refused a call for `refused`.
+     * A read already in flight may have been answered before the user
+     * changed. When its answer contradicts the refusal, one more read asks the
+     * server again: the refused session itself, or, after a refusal that said
+     * another user is signed in, no user. A failed read leaves the session as
+     * it was; the next refusal reads again.
+     */
+    const rereadAfterRefusal = async (refused, hostCode) => {
+        const contradicts = (read) => read === undefined
+            ? hostCode === notificationsBackendBridgeHostCodes.sessionChanged
+            : read.id === refused.id && read.player === refused.player;
+        try {
+            if (contradicts(await refreshSession())) {
+                await refreshSession();
+            }
+        }
+        catch (error) {
+            // A read failed in a way a retry may fix after a stale answer cleared
+            // the session: read again later rather than wait for a refusal that
+            // cannot come.
+            if (current === undefined && error instanceof NotificationError && error.retryable) {
+                sessionSettled = false;
+            }
+            // The refusal is what the caller needs to see.
+        }
+    };
+    /**
+     * One call for the current session's player. A refusal for its session
+     * reads the session again before it answers, so the runtime sees the
+     * player the server serves now when it reacts.
+     */
+    const call = async (method, body, session = requireSession(method)) => {
+        try {
+            return await send(method, {
+                ...body,
+                expectedPlayer: session.player,
+            });
+        }
+        catch (error) {
+            if (error instanceof NotificationError && sessionRefusalHostCodes.has(error.hostCode)) {
+                await rereadAfterRefusal(session, error.hostCode);
+            }
+            throw error;
+        }
+    };
+    return {
+        session() {
+            retryIfUnsettled();
+            return current;
+        },
+        onAuthenticated(listener) {
+            // The session already read when the runtime subscribes is not a new one.
+            const entry = (session) => listener(session);
+            listeners.add(entry);
+            return () => {
+                listeners.delete(entry);
+            };
+        },
+        refreshSession,
+        async recordConsent(record) {
+            await call('notifications.backend.recordConsent', { record });
+        },
+        async listConsent() {
+            return (await call('notifications.backend.listConsent', {})).records;
+        },
+        async registerEndpoint(registration) {
+            await call('notifications.backend.registerEndpoint', { registration });
+        },
+        async unregisterEndpoint({ provider, player }) {
+            const session = current;
+            if (session === undefined || session.player !== player) {
+                // A Devvit registration belongs to the Reddit user, not to a device,
+                // and another user's request cannot reach it.
+                return;
+            }
+            try {
+                await call('notifications.backend.unregisterEndpoint', { provider }, session);
+            }
+            catch (error) {
+                // The user left before the call reached the server: nothing on this
+                // webview belongs to that user any more. (On Devvit the service keeps
+                // the user's platform-user locale and zone; sends still need the
+                // user's opt-in.)
+                if (error instanceof NotificationError && sessionRefusalHostCodes.has(error.hostCode)) {
+                    return;
+                }
+                throw error;
+            }
+        },
+        async setReminder(reminder) {
+            return (await call('notifications.backend.setReminder', { reminder })).status;
+        },
+        async cancelReminder({ key }) {
+            return (await call('notifications.backend.cancelReminder', { key })).cancelled;
+        },
+        async listNotices() {
+            return (await call('notifications.backend.listNotices', {})).notices;
+        },
+        async recordNotice({ channel, kind, record, dueBy }) {
+            await call('notifications.backend.recordNotice', {
+                notice: { kind, record: { kind: record.kind, at: record.at }, dueBy },
+                channel,
+            });
+        },
+    };
+}
+function toNotificationError(method, error) {
+    if (error instanceof NotificationError) {
+        return error;
+    }
+    const failure = typeof error === 'object' && error !== null
+        ? error
+        : {};
+    const message = typeof failure.message === 'string' ? failure.message : undefined;
+    if (backendUnavailableCodes.has(failure.code)) {
+        return new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+            message: `${method}: the Devvit server serves no notifications backend (wire `
+                + 'createDevvitNotificationsBackendBridgeHandler into its bridge).',
+            cause: error,
+        });
+    }
+    const explicit = typeof failure.retryable === 'boolean' ? { retryable: failure.retryable } : {};
+    if (isNotificationErrorCode(failure.code)) {
+        const hostCode = message === undefined ? undefined : readBridgeNotificationsHostCode(message);
+        return new NotificationError(failure.code, {
+            ...(message === undefined ? {} : { message }),
+            ...explicit,
+            ...(hostCode === undefined ? {} : { hostCode }),
+            cause: error,
+        });
+    }
+    return new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', {
+        message: `${method}: the Devvit server could not be reached.`,
+        ...explicit,
+        cause: error,
+    });
+}
+/**
+ * Whether `elapsed` milliseconds are still inside the retry interval. A
+ * clock that went backwards (a negative or non-finite difference) counts
+ * as past it, so a clock change never holds a retry back.
+ */
+function withinRetryInterval(elapsed, retryIntervalMs) {
+    return elapsed >= 0 && elapsed < retryIntervalMs;
+}

package/dist/server/index.d.ts

@@ -7,3 +7,4 @@ export * from './redis-verified-leaderboard.js';
 export * from './redis-notification-store.js';
 export * from './notifications-delivery.js';
 export * from './notifications-bridge.js';
+export * from './notifications-backend-bridge.js';

package/dist/server/index.js

@@ -7,3 +7,4 @@ export * from './redis-verified-leaderboard.js';
 export * from './redis-notification-store.js';
 export * from './notifications-delivery.js';
 export * from './notifications-bridge.js';
+export * from './notifications-backend-bridge.js';

package/dist/server/notifications-backend-bridge.d.ts

@@ -0,0 +1,67 @@
+import type { BridgeRequest, BridgeResponse } from '@mpgd/bridge';
+import { type NotificationService } from '@mpgd/game-services/notifications';
+import { type DevvitNotificationSessionContext } from './notifications-delivery.js';
+/**
+* The notifications runtime's backend on Devvit (notifications v2 RFC,
+* "Bridge and versioning", "Backend methods", and "Provider profiles",
+* Devvit): the Devvit server's notifications service
+* (`createDevvitNotificationService`) served over the server bridge for the
+* request's logged-in user, so the webview's runtime keeps consent records,
+* the platform-user registration, server reminders, and notices there.
+*
+* The player is always the request's `context.userId`, read through
+* `devvitNotificationSessionFromContext`, never a payload field: the payload
+* only names the player its call began for, and a call for another player
+* is refused before the service.
+*/
+/** The parts of the notifications service the backend bridge serves. */
+export type DevvitNotificationsBackendService = Pick<NotificationService, 'recordConsent' | 'listConsent' | 'registerEndpoint' | 'unregisterEndpoint' | 'setReminder' | 'cancelReminder' | 'listNotices' | 'recordNoticeShown'>;
+export interface CreateDevvitNotificationsBackendBridgeHandlerInput {
+  /** `createDevvitNotificationService(...).service`. */
+  readonly service: DevvitNotificationsBackendService;
+  /** The current Devvit request's context (`context` from `@devvit/web/server`). */
+  readonly context: () => DevvitNotificationSessionContext;
+  /**
+  * Every failure the handler answers with an error, except an invalid
+  * payload and a logged-out or changed session, with its cause (the
+  * service's or Redis's own text, which the webview never sees).
+  * Synchronous; a hook that throws or rejects changes nothing. By default
+  * `console.warn`, which skips a player's own consent write cap and an
+  * input the service refuses as invalid.
+  */
+  readonly onError?: ((error: unknown, context: {
+    readonly method: string;
+  }) => void) | undefined;
+}
+/**
+* Serves the nine `notifications.backend.*` methods; the handler a Devvit
+* server bridge routes them to (the `notificationsBackend` dependency of the
+* kit's and the CLI template's `createDevvitBridgeHandler`).
+*/
+export interface DevvitNotificationsBackendBridgeHandler {
+  request(input: BridgeRequest): Promise<BridgeResponse>;
+}
+/**
+* The server bridge side of the runtime's backend on Devvit:
+* `createNotificationsBackendBridgeHandler` from `@mpgd/bridge/notifications`
+* over the Devvit notifications service.
+*
+* - **Session.** `getSession` answers the request's user as
+*   `{ player: 't2_…', id: 'devvit:t2_…' }`, or `null` for a logged-out
+*   viewer. Every other call needs that user: a logged-out request answers
+*   `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` (host code
+*   `NOTIFICATIONS_SIGNED_OUT`), which the runtime reads as "not signed in",
+*   and a call that began for another user answers the same code with
+*   `NOTIFICATIONS_SESSION_CHANGED`.
+* - **Calls.** Each method is the service's, for
+*   `devvitNotificationSessionFromContext(context())`: records (the service
+*   dates them and caps a player's writes per day), the `platform-user`
+*   registration's locale and zone, server reminders (which the `dispatch`
+*   scheduler task fires through `enqueue`), and notices, which stay empty
+*   unless the deployment applies the Korean rules.
+* - **Failures.** A service `NotificationError` crosses with its code (an
+*   invalid record or reminder is `NOTIFICATIONS_INVALID_INPUT`); any other
+*   failure is a retryable `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` with a
+*   fixed message, and its text stays on the server (`onError`).
+*/
+export declare function createDevvitNotificationsBackendBridgeHandler(input: CreateDevvitNotificationsBackendBridgeHandlerInput): DevvitNotificationsBackendBridgeHandler;

package/dist/server/notifications-backend-bridge.js

@@ -0,0 +1,73 @@
+import { createNotificationsBackendBridgeHandler } from '@mpgd/bridge/notifications';
+import { NotificationError } from '@mpgd/platform/notifications';
+import { NotificationConsentRateLimitError, } from '@mpgd/game-services/notifications';
+import { devvitUserIdPattern } from '../notifications-contract.js';
+import { devvitNotificationSessionFromContext, } from './notifications-delivery.js';
+/**
+ * The server bridge side of the runtime's backend on Devvit:
+ * `createNotificationsBackendBridgeHandler` from `@mpgd/bridge/notifications`
+ * over the Devvit notifications service.
+ *
+ * - **Session.** `getSession` answers the request's user as
+ *   `{ player: 't2_…', id: 'devvit:t2_…' }`, or `null` for a logged-out
+ *   viewer. Every other call needs that user: a logged-out request answers
+ *   `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` (host code
+ *   `NOTIFICATIONS_SIGNED_OUT`), which the runtime reads as "not signed in",
+ *   and a call that began for another user answers the same code with
+ *   `NOTIFICATIONS_SESSION_CHANGED`.
+ * - **Calls.** Each method is the service's, for
+ *   `devvitNotificationSessionFromContext(context())`: records (the service
+ *   dates them and caps a player's writes per day), the `platform-user`
+ *   registration's locale and zone, server reminders (which the `dispatch`
+ *   scheduler task fires through `enqueue`), and notices, which stay empty
+ *   unless the deployment applies the Korean rules.
+ * - **Failures.** A service `NotificationError` crosses with its code (an
+ *   invalid record or reminder is `NOTIFICATIONS_INVALID_INPUT`); any other
+ *   failure is a retryable `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` with a
+ *   fixed message, and its text stays on the server (`onError`).
+ */
+export function createDevvitNotificationsBackendBridgeHandler(input) {
+    const { service } = input;
+    const handler = createNotificationsBackendBridgeHandler({
+        label: 'Devvit',
+        unexpectedFailureMessage: (method) => `${method} failed on the Devvit server.`,
+        onError: (error, context) => {
+            (input.onError ?? warnBackendFailure)(error, context);
+        },
+        backend: {
+            session() {
+                const context = input.context();
+                // A request without a Devvit user id (missing, `null`, or not a t2_
+                // id) has no signed-in player, as the provider side reads it. A
+                // context that cannot be read at all is the server's failure and
+                // reaches onError.
+                const userId = context.userId;
+                if (typeof userId !== 'string' || !devvitUserIdPattern.test(userId)) {
+                    return undefined;
+                }
+                // The id checked above, so the session cannot fail on a second read of the context.
+                const notifications = devvitNotificationSessionFromContext({ userId });
+                return { id: notifications.sessionId, player: notifications.player, notifications };
+            },
+            recordConsent: (session, record) => service.recordConsent(session.notifications, record),
+            listConsent: (session) => service.listConsent(session.notifications),
+            registerEndpoint: (session, registration) => service.registerEndpoint(session.notifications, { registration }),
+            unregisterEndpoint: (session, { provider }) => service.unregisterEndpoint(session.notifications, { provider }),
+            setReminder: async (session, reminder) => (await service.setReminder(session.notifications, reminder)).status,
+            cancelReminder: async (session, { key }) => (await service.cancelReminder(session.notifications, { key })).cancelled,
+            listNotices: (session) => service.listNotices(session.notifications),
+            recordNotice: (session, notice, { channel }) => service.recordNoticeShown(session.notifications, notice, { channel }),
+        },
+    });
+    return { request: (request) => handler.request(request) };
+}
+function warnBackendFailure(error, context) {
+    // A throttled consent write is the player's own cap, and an input the
+    // service refuses is the caller's: neither is a server failure, and a
+    // webview could otherwise fill the log with them.
+    if (error instanceof NotificationConsentRateLimitError
+        || (error instanceof NotificationError && error.code === 'NOTIFICATIONS_INVALID_INPUT')) {
+        return;
+    }
+    console.warn(`devvit notifications ${context.method} failed`, error);
+}

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

@@ -186,8 +186,8 @@ export declare function createDevvitNotificationService(input: CreateDevvitNotif
 export declare function devvitNotificationSession(userId: string): NotificationSession;
 /** The Devvit request context fields this session reads (`context` from `@devvit/web/server`). */
 export interface DevvitNotificationSessionContext {
-  /** The logged-in Reddit user of the current request (`context.userId`). */
-  readonly userId?: string | undefined;
+  /** The logged-in Reddit user of the current request (`context.userId`); absent or `null` when logged out. */
+  readonly userId?: string | null | undefined;
 }
 /**
 * The notifications session of the current Devvit request. The player is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-devvit",
-  "version": "0.13.5",
+  "version": "0.14.0",
   "description": "Reddit Devvit Web platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -55,9 +55,9 @@
   ],
   "dependencies": {
     "@devvit/web": "0.15.0",
-    "@mpgd/bridge": "0.15.0",
-    "@mpgd/game-services": "0.27.2",
-    "@mpgd/platform": "0.27.2"
+    "@mpgd/bridge": "0.16.0",
+    "@mpgd/platform": "0.28.0",
+    "@mpgd/game-services": "0.28.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",