@mpgd/adapter-devvit 0.12.1 → 0.13.0

package/README.md

@@ -4,10 +4,10 @@ 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 |
+| `@mpgd/adapter-devvit` | `createDevvitPlatformGateway`, the oRPC bridge and sandbox bridge, the commerce provider and catalog helpers, the Devvit notifications profile values |
 | `@mpgd/adapter-devvit/payments` | `normalizeDevvitCommerceProducts` and the checkout types |
-| `@mpgd/adapter-devvit/server` | `createDevvitCommerceV2BridgeHandler`, payment-order normalizers, durable post operations, Redis stores |
-| `@mpgd/adapter-devvit/web` | Webview helpers, including `createDevvitWebPaymentsClient()` over `purchase()` from `@devvit/web/client` |
+| `@mpgd/adapter-devvit/server` | `createDevvitCommerceV2BridgeHandler`, `createDevvitNotificationsV2BridgeHandler`, 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 |
 
 ## Commerce
@@ -20,6 +20,58 @@ settles a purchase on the server, so only the backend ledger the fulfillment han
 anything. Games purchase through `@mpgd/game-services`; see the
 [Devvit commerce guide](../../docs/DEVVIT_COMMERCE.md).
 
+## Notifications
+
+Devvit push notifications are a gated beta: an app must
+[apply](https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/notifications/notifications-overview)
+and Devvit admins pre-approve every title and body. Until Reddit approves the
+app, keep `integrations.notifications` at `approval-required` (the default for
+`reddit`), which hides notifications from the game; set it to `available` once
+Reddit approves. The profile follows the
+[notifications v2 RFC](../../docs/specs/notifications/notifications-v2-rfc.md#profile-devvit):
+
+- **Consent the game renders.** Reddit shows no consent screen. The game draws
+  an on/off control with its current state and offers both directions.
+- **The server bridge.** Pass
+  `createDevvitNotificationsV2BridgeHandler({ notifications, currentUserId, topics })`
+  as the bridge's `notifications` dependency; it takes the Devvit plugin as
+  `notifications`. It opts the request's logged-in user in with
+  `optInCurrentUser` from `requestPermission`, out with `optOutCurrentUser`
+  from `revokePermission`, and reads `isOptedIn`.
+- **The gateway.** `createDevvitPlatformGateway({ notifications: { topics } })`
+  exposes `notificationsV2` over that bridge (its client loads in its own
+  chunk, starting with the gateway)
+  and serves the v1 `notifications` adapter from it. `topics` are the ids the
+  catalog maps for `reddit`.
+- **Login.** A logged-out viewer reads `action-required` with
+  `requiredAction: 'login'`. With `loginPrompt: createDevvitWebLoginPrompt()`
+  (from `@mpgd/adapter-devvit/web`), `identity.requestUpgrade` opens Reddit's
+  login and answers `reloadExpected: true`, since Reddit reloads the post after
+  login; set `integrations.identityUpgrade` to `available` in the game's target
+  config to expose it.
+- **No opt-out event.** Devvit reports no opt-out, and opt-out may move into
+  Reddit settings, so the backend reads `isOptedIn` at every send.
+- **Sending.** Remote delivery runs inside the Devvit server:
+  `createDevvitNotificationService({ redis, notifications, catalog })` is the
+  `@mpgd/game-services/notifications` service over a Redis store
+  (`createDevvitRedisNotificationStore`) with the Devvit delivery provider. Each
+  send needs a post (`t3_`) or comment (`t1_`) link, from the send or the
+  topic's mapping. Titles are at most 60 and bodies at most 100 Unicode code
+  points of the filled text. Devvit allows 2 sends per user per day and 25,000
+  per app per day. Players' own calls take `devvitNotificationSession(userId)`.
+  Two `devvit.json` scheduler tasks keep its work moving:
+  `mpgd-notifications-dispatch` (every minute, the service's `runScheduler`:
+  due server reminders and due sends, in rounds of 10, starting no round
+  after 20 seconds; Devvit carries no consent notices, since its entry fixes
+  the title and body per topic) and `mpgd-notifications-purge` (every
+  five minutes, at most 200 rows of each kind). Route their endpoints
+  (`devvitNotificationSchedulerTasks`) to
+  `runDevvitNotificationTask(service, task)`, as the kit's
+  `apps/target-devvit` server does. A player's `setReminder` fires through
+  the dispatch task.
+- **Opens.** A notification opens its post; the game routes from that post's
+  data.
+
 ## Migrating from v1
 
 | Removed | Replacement |

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './commerce-contract.js';
 export * from './commerce-provider.js';
 export * from './payments.js';
 export * from './catalog-products.js';
+export * from './notifications-contract.js';
 export declare const defaultDevvitRpcEndpoint = "/api/mpgd/rpc";
 /** Bridge error of `createDevvitOrpcBridge` when the oRPC request itself failed. */
 export declare const devvitBridgeNetworkErrorCode: 'DEVVIT_BRIDGE_NETWORK_ERROR';
@@ -49,6 +50,41 @@ export interface DevvitPlatformGatewayOptions {
   * from the payments client.
   */
   readonly commerce?: DevvitGatewayCommerceOptions;
+  /**
+  * Exposes notifications v2 (`notificationsV2`) over the server bridge,
+  * which serves the game-rendered opt-in from
+  * `createDevvitNotificationsV2BridgeHandler` (`@mpgd/adapter-devvit/server`),
+  * and serves the v1 `notifications` adapter from the same provider.
+  * Absent, the gateway offers no `notificationsV2` and keeps the server's
+  * v1 answers. Notifications are a gated beta: the target config keeps
+  * `integrations.notifications` at `approval-required` until Reddit
+  * approves the app, which hides both from the game.
+  */
+  readonly notifications?: DevvitGatewayNotificationsOptions;
+  /**
+  * The webview's Reddit login prompt (`createDevvitWebLoginPrompt()` from
+  * `@mpgd/adapter-devvit/web`). With it, `identity.requestUpgrade` shows the
+  * prompt to a logged-out viewer and answers `reloadExpected: true`, since
+  * Reddit reloads the post after login; a logged-in viewer gets the
+  * server's `completed` answer. Without it, the server answers alone.
+  */
+  readonly loginPrompt?: DevvitLoginPrompt;
+}
+export interface DevvitGatewayNotificationsOptions {
+  /** The topic ids the catalog maps for the `reddit` target; v1 reads any other as `configuration-required`. */
+  readonly topics: readonly string[];
+  /** The webview's IANA zone for the registration; `Intl` by default. */
+  readonly timeZone?: () => string | undefined;
+  /** The webview's locale for the registration; `navigator.language` by default. */
+  readonly locale?: () => string | undefined;
+  /** Loads the notifications client chunk, when the gateway is created; the dynamic import by default. Tests inject it. */
+  readonly load?: () => Promise<DevvitNotificationClientModule>;
+}
+/** What the gateway uses from the notifications client chunk. */
+export type DevvitNotificationClientModule = Pick<typeof import('./notifications-client.js'), 'createDevvitBridgeNotificationProvider' | 'createDevvitNotificationSubscriptionAdapter'>;
+/** Opens Reddit's login or sign-up flow (`showLoginPrompt` from `@devvit/web/client`). */
+export interface DevvitLoginPrompt {
+  showLoginPrompt(): void;
 }
 export declare function createDevvitPlatformGateway(input: DevvitPlatformGatewayOptions): PlatformGateway;
 /**

package/dist/index.js

@@ -4,11 +4,13 @@ import { createUnsupportedCommerceCapabilities, PlatformOperationError, } from '
 import { assertCommerceBridgeGetAvailablePurchasesResult, assertCommerceBridgeGetCapabilitiesResult, CommerceError, commerceProtocol, isCommerceErrorCode, } from '@mpgd/platform/commerce';
 import { withShareIntentCheck } from '@mpgd/platform/routes';
 import { assertDevvitOrderEvidence } from './commerce-contract.js';
+import { createDevvitDegradedNotificationCapabilities, devvitNotificationProviderId, } from './notifications-contract.js';
 import { createDevvitCommerceProvider, } from './commerce-provider.js';
 export * from './commerce-contract.js';
 export * from './commerce-provider.js';
 export * from './payments.js';
 export * from './catalog-products.js';
+export * from './notifications-contract.js';
 export const defaultDevvitRpcEndpoint = defaultBridgeRpcEndpoint;
 /** Bridge error of `createDevvitOrpcBridge` when the oRPC request itself failed. */
 export const devvitBridgeNetworkErrorCode = 'DEVVIT_BRIDGE_NETWORK_ERROR';
@@ -52,6 +54,10 @@ export function createDevvitPlatformGateway(input) {
             ...input.commerce,
             orders: createDevvitBridgeOrderSource(request),
         });
+    const notificationSurface = input.notifications === undefined
+        ? undefined
+        : createLazyDevvitNotificationSurface(input.notifications, (method, payload) => request(method, payload));
+    const notificationsV2 = notificationSurface?.notificationsV2;
     return {
         target: 'reddit',
         async getCapabilities() {
@@ -63,17 +69,45 @@ export function createDevvitPlatformGateway(input) {
             }
             // The webview provider owns the block: the server snapshot stays honest
             // about the server, and a gateway without a provider sells nothing.
+            // The two provider reads are independent bridge calls.
+            const [commerceBlock, notifications] = await Promise.all([
+                commerce === undefined ? createUnsupportedCommerceCapabilities() : commerce.getCapabilities(),
+                notificationsV2 === undefined ? undefined : readNotificationCapabilities(notificationsV2),
+            ]);
+            const { notifications: _serverNotifications, ...withCommerce } = { ...capabilities, commerce: commerceBlock };
+            if (notifications === undefined) {
+                return withCommerce;
+            }
+            // The block is present exactly when the gateway exposes notificationsV2,
+            // and the push readiness follows it.
             return {
-                ...capabilities,
-                commerce: commerce === undefined
-                    ? createUnsupportedCommerceCapabilities()
-                    : await commerce.getCapabilities(),
+                ...withCommerce,
+                providerAvailability: {
+                    ...withCommerce.providerAvailability,
+                    pushNotifications: notifications.availability,
+                },
+                notifications,
             };
         },
         identity: {
             getPlayer: () => request('identity.getPlayer', {}),
             getSession: () => request('identity.getSession', {}),
-            requestUpgrade: (payload) => request('identity.requestUpgrade', payload),
+            requestUpgrade: async (payload) => {
+                const answer = await request('identity.requestUpgrade', payload);
+                // The server answers `unavailable` for a logged-out viewer; any other
+                // answer is passed through.
+                if (input.loginPrompt === undefined || answer.status !== 'unavailable') {
+                    return answer;
+                }
+                // A logged-out viewer: Reddit's login flow reloads the post afterwards.
+                try {
+                    input.loginPrompt.showLoginPrompt();
+                }
+                catch {
+                    return { status: 'unavailable', reloadExpected: false };
+                }
+                return { status: 'completed', reloadExpected: true };
+            },
         },
         presentation: {
             getLaunchIntent: () => request('presentation.getLaunchIntent', {}),
@@ -85,11 +119,14 @@ export function createDevvitPlatformGateway(input) {
             share: (payload) => request('share.share', payload),
             readInboundShare: () => request('share.readInboundShare', {}),
         }),
-        notifications: {
+        // v1 is served from the v2 provider whenever the gateway exposes v2, so
+        // the two report the same readiness.
+        notifications: notificationSurface?.notifications ?? {
             getStatus: (topic) => request('notifications.getStatus', { topic }),
             requestSubscription: (topic) => request('notifications.requestSubscription', { topic }),
         },
         ...(commerce === undefined ? {} : { commerce }),
+        ...(notificationsV2 === undefined ? {} : { notificationsV2 }),
         ads: {
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
@@ -120,6 +157,128 @@ export function createDevvitPlatformGateway(input) {
         },
     };
 }
+/**
+ * Notifications v2 and the v1 adapter served from it, with the client chunk
+ * (the bridge provider and the `@mpgd/bridge/notifications` validators) in
+ * its own chunk, so a game that does not opt in carries none of it. A game
+ * that opts in starts loading it with the gateway. A
+ * chunk that fails to load rejects with a retryable
+ * `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`, and the next call loads again.
+ * Devvit pushes no notifications events, so `subscribe` attaches nothing.
+ */
+function createLazyDevvitNotificationSurface(options, request) {
+    const importClient = options.load ?? (() => import('./notifications-client.js'));
+    const topics = [...options.topics];
+    let loading;
+    const load = () => {
+        if (loading !== undefined) {
+            return loading;
+        }
+        // Any failure, a synchronous throw of the loader or one while the
+        // provider is built, is forgotten once settled, so the next call loads
+        // again; the reset runs after the attempt is stored, never before.
+        const attempt = (async () => {
+            try {
+                const module = await importClient();
+                const provider = module.createDevvitBridgeNotificationProvider({
+                    request,
+                    ...(options.timeZone === undefined ? {} : { timeZone: options.timeZone }),
+                    ...(options.locale === undefined ? {} : { locale: options.locale }),
+                });
+                return { provider, v1: module.createDevvitNotificationSubscriptionAdapter(provider, topics) };
+            }
+            catch (error) {
+                throw new PlatformOperationError({
+                    code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                    message: `The Devvit notifications client did not load: ${errorMessage(error)}`,
+                    retryable: true,
+                });
+            }
+        })();
+        loading = attempt;
+        attempt.catch(() => {
+            if (loading === attempt) {
+                loading = undefined;
+            }
+        });
+        return attempt;
+    };
+    // The game opted in, so the chunk is needed: load it now rather than on the
+    // first capability read, which is bounded in time.
+    void load().catch(() => { });
+    const provider = async () => (await load()).provider;
+    return {
+        notificationsV2: {
+            provider: devvitNotificationProviderId,
+            getCapabilities: async () => (await provider()).getCapabilities(),
+            getPermission: async (input) => (await provider()).getPermission(input),
+            requestPermission: async (input) => (await provider()).requestPermission(input),
+            revokePermission: async (input) => {
+                const loaded = await provider();
+                return loaded.revokePermission
+                    .call(loaded, input);
+            },
+            register: async () => (await (await provider()).register?.()) ?? null,
+            subscribe: () => () => { },
+        },
+        notifications: {
+            getStatus: async (topic) => (await load()).v1.getStatus(topic),
+            // As v1 answers any failed request: `unavailable`, also when the chunk did not load.
+            requestSubscription: async (topic) => {
+                let v1;
+                try {
+                    v1 = (await load()).v1;
+                }
+                catch {
+                    return 'unavailable';
+                }
+                return v1.requestSubscription(topic);
+            },
+        },
+    };
+}
+/** Bound on one notifications capability read, as `withTargetAvailability` bounds it. */
+const notificationCapabilityReadTimeoutMs = 3_000;
+/** Failures the same server answers the same way again; `@mpgd/target-config` reads them as unsupported. */
+const unsupportedNotificationReadCodes = new Set([
+    'NOTIFICATIONS_V2_UNAVAILABLE',
+    'NOTIFICATIONS_UNSUPPORTED',
+    'NOTIFICATIONS_HOST_VERSION_UNSUPPORTED',
+]);
+/**
+ * One bounded read of the provider's block. The provider validated it, so
+ * it is a fresh, exact block; a read that fails or stalls yields a block
+ * that offers nothing, with the availability that explains why.
+ */
+async function readNotificationCapabilities(provider) {
+    let timer;
+    try {
+        return await Promise.race([
+            provider.getCapabilities(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('Notification capabilities read timed out.')), notificationCapabilityReadTimeoutMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        const failure = typeof error === 'object' && error !== null
+            ? error
+            : {};
+        let availability = 'temporarily-unavailable';
+        if (failure.code === 'NOTIFICATIONS_CONFIGURATION_REQUIRED') {
+            availability = 'configuration-required';
+        }
+        else if (failure.retryable !== true && unsupportedNotificationReadCodes.has(failure.code)) {
+            availability = 'unsupported';
+        }
+        return createDevvitDegradedNotificationCapabilities(availability);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
 /**
  * The webview provider's order source over the server bridge: the paid orders
  * the server lists as available purchases, mapped back to orders (the
@@ -290,8 +449,8 @@ export function createDevvitSandboxBridge() {
     const storage = new Map();
     return {
         async request(input) {
-            // Notifications v2 arrives with the Devvit provider (P3); until then
-            // every v2 method answers the dedicated code.
+            // Only the Devvit server can opt a user in: the sandbox serves no
+            // notifications v2, and every v2 method answers the dedicated code.
             if (isBridgeNotificationsV2Method(input.method)) {
                 return createNotificationsV2UnavailableBridgeError(input, 'Devvit sandbox bridge');
             }

package/dist/notifications-client.d.ts

@@ -0,0 +1,44 @@
+import type { BridgeNotificationsV2Method } from '@mpgd/bridge';
+import type { NotificationSubscriptionAdapter } from '@mpgd/platform';
+import { type NotificationProvider } from '@mpgd/platform/notifications';
+/**
+* The webview side of notifications v2 on Devvit, loaded in its own chunk
+* by `createDevvitPlatformGateway({ notifications })`: a
+* `NotificationProvider` over the Devvit server bridge, which serves the
+* game-rendered opt-in from `createDevvitNotificationsV2BridgeHandler`
+* (`@mpgd/adapter-devvit/server`), and the v1 adapter served from it.
+*/
+export interface CreateDevvitBridgeNotificationProviderInput {
+  /** Sends one server bridge request and returns its data; bridge errors reject with their code. */
+  readonly request: (method: BridgeNotificationsV2Method, payload: unknown) => Promise<unknown>;
+  /** The webview's IANA zone, which the registration carries; `Intl` by default. */
+  readonly timeZone?: () => string | undefined;
+  /** The webview's locale, which the registration carries; `navigator.language` by default. */
+  readonly locale?: () => string | undefined;
+}
+/**
+* The Devvit profile's provider: reads, the opt-in request, the opt-out
+* (`revokePermission`, because the game renders the consent), and the
+* `platform-user` registration with the webview's locale and zone. No
+* local notifications and no settings link exist, and no event reaches the
+* webview: a notification opens its post, and the game routes from that
+* post's data. Answers are validated again here, so a server that skips
+* validation stays fail-closed.
+*
+* Errors: a bridge error with a `NOTIFICATIONS_*` code becomes a
+* `NotificationError` with that code (and the host code its message names);
+* `NOTIFICATIONS_V2_UNAVAILABLE` from a server without the handler stays
+* that; `UNSUPPORTED_METHOD` or `INVALID_BRIDGE_REQUEST` from a server that
+* predates the methods becomes `NOTIFICATIONS_V2_UNAVAILABLE`; anything else
+* (the oRPC transport failing) is `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`,
+* retryable unless the failure says otherwise.
+*/
+export declare function createDevvitBridgeNotificationProvider(input: CreateDevvitBridgeNotificationProviderInput): NotificationProvider;
+/**
+* The v1 `NotificationSubscriptionAdapter` served from the v2 provider (RFC
+* "Migration and PR plan", through `toNotificationSubscriptionAdapter`), so
+* v1 and v2 report the same readiness. Every state comes from the host
+* (Devvit `isOptedIn` through the server); a topic outside `topics` reads
+* `configuration-required` and requests `unavailable`.
+*/
+export declare function createDevvitNotificationSubscriptionAdapter(provider: Pick<NotificationProvider, 'getPermission' | 'requestPermission'>, topics: readonly string[]): NotificationSubscriptionAdapter;

package/dist/notifications-client.js

@@ -0,0 +1,141 @@
+import { assertBridgeNotificationsV2Result, } from '@mpgd/bridge/notifications';
+import { isNotificationErrorCode, isValidNotificationTimeZone, NotificationError, notificationsProtocol, toNotificationSubscriptionAdapter, } from '@mpgd/platform/notifications';
+import { devvitHostCodeCharacters, devvitNotificationProviderId, } from './notifications-contract.js';
+/**
+ * The Devvit profile's provider: reads, the opt-in request, the opt-out
+ * (`revokePermission`, because the game renders the consent), and the
+ * `platform-user` registration with the webview's locale and zone. No
+ * local notifications and no settings link exist, and no event reaches the
+ * webview: a notification opens its post, and the game routes from that
+ * post's data. Answers are validated again here, so a server that skips
+ * validation stays fail-closed.
+ *
+ * Errors: a bridge error with a `NOTIFICATIONS_*` code becomes a
+ * `NotificationError` with that code (and the host code its message names);
+ * `NOTIFICATIONS_V2_UNAVAILABLE` from a server without the handler stays
+ * that; `UNSUPPORTED_METHOD` or `INVALID_BRIDGE_REQUEST` from a server that
+ * predates the methods becomes `NOTIFICATIONS_V2_UNAVAILABLE`; anything else
+ * (the oRPC transport failing) is `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`,
+ * retryable unless the failure says otherwise.
+ */
+export function createDevvitBridgeNotificationProvider(input) {
+    const send = async (method, payload) => {
+        let data;
+        try {
+            data = await input.request(method, payload);
+        }
+        catch (error) {
+            throw toNotificationError(error);
+        }
+        try {
+            return assertBridgeNotificationsV2Result(method, data);
+        }
+        catch (error) {
+            throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+                message: `The Devvit server answered ${method} with invalid data.`,
+                cause: error,
+            });
+        }
+    };
+    const timeZone = input.timeZone ?? defaultTimeZone;
+    const locale = input.locale ?? defaultLocale;
+    return {
+        provider: devvitNotificationProviderId,
+        async getCapabilities() {
+            const answer = await send('notifications.v2.getCapabilities', { protocol: notificationsProtocol });
+            if (answer.provider !== devvitNotificationProviderId) {
+                throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+                    message: `The Devvit server serves notifications provider ${answer.provider}, not ${devvitNotificationProviderId}.`,
+                });
+            }
+            return answer.capabilities;
+        },
+        getPermission: (request) => send('notifications.v2.getPermission', request),
+        requestPermission: (request) => send('notifications.v2.requestPermission', request),
+        revokePermission: (request) => send('notifications.v2.revokePermission', request),
+        async register() {
+            const { registration } = await send('notifications.v2.register', { protocol: notificationsProtocol });
+            if (registration === null || registration.address.kind !== 'platform-user') {
+                return registration;
+            }
+            // The server knows the user; only the webview knows its locale and zone.
+            const zone = registration.timeZone ?? readOptional(timeZone);
+            const language = registration.locale ?? readOptional(locale);
+            return {
+                ...registration,
+                ...(language === undefined || language.length === 0 || language.length > 2048 ? {} : { locale: language }),
+                ...(zone === undefined || !isValidNotificationTimeZone(zone) ? {} : { timeZone: zone }),
+            };
+        },
+        subscribe() {
+            // Devvit has no server-to-webview notifications channel.
+            return () => { };
+        },
+    };
+}
+/**
+ * The v1 `NotificationSubscriptionAdapter` served from the v2 provider (RFC
+ * "Migration and PR plan", through `toNotificationSubscriptionAdapter`), so
+ * v1 and v2 report the same readiness. Every state comes from the host
+ * (Devvit `isOptedIn` through the server); a topic outside `topics` reads
+ * `configuration-required` and requests `unavailable`.
+ */
+export function createDevvitNotificationSubscriptionAdapter(provider, topics) {
+    return toNotificationSubscriptionAdapter({
+        async getPermission(request) {
+            const snapshot = await provider.getPermission(request);
+            return {
+                ...snapshot,
+                sources: Object.fromEntries(Object.keys(snapshot.topics).map((topic) => [topic, 'host'])),
+            };
+        },
+        requestPermission: ({ topics: requested }) => provider.requestPermission({ topics: requested }),
+    }, topics.map((id) => ({ id })));
+}
+function readOptional(read) {
+    try {
+        const value = read();
+        return typeof value === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+function defaultLocale() {
+    const navigatorLike = globalThis.navigator;
+    return typeof navigatorLike?.language === 'string' ? navigatorLike.language : undefined;
+}
+const hostCodePattern = new RegExp(`\\(host code (${devvitHostCodeCharacters})\\)$`, 'u');
+function toNotificationError(error) {
+    if (error instanceof NotificationError) {
+        return error;
+    }
+    const failure = typeof error === 'object' && error !== null
+        ? error
+        : {};
+    const message = typeof failure.message === 'string' ? failure.message : undefined;
+    const explicit = typeof failure.retryable === 'boolean' ? { retryable: failure.retryable } : {};
+    if (isNotificationErrorCode(failure.code)) {
+        const hostCode = message === undefined ? undefined : hostCodePattern.exec(message)?.[1];
+        return new NotificationError(failure.code, {
+            ...(message === undefined ? {} : { message }),
+            ...explicit,
+            ...(hostCode === undefined ? {} : { hostCode }),
+            cause: error,
+        });
+    }
+    if (failure.code === 'UNSUPPORTED_METHOD' || failure.code === 'INVALID_BRIDGE_REQUEST') {
+        return new NotificationError('NOTIFICATIONS_V2_UNAVAILABLE', {
+            ...(message === undefined ? {} : { message }),
+            cause: error,
+        });
+    }
+    return new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', {
+        ...(message === undefined ? {} : { message }),
+        ...explicit,
+        cause: error,
+    });
+}

package/dist/notifications-contract.d.ts

@@ -0,0 +1,71 @@
+/**
+* The Devvit notifications profile (notifications v2 RFC, "Provider
+* profiles", Devvit), shared by the webview gateway and the Devvit server.
+* Pure values: no Devvit SDK, no `@mpgd/platform/notifications` runtime code,
+* so the gateway's main entry can import it without pulling in validators.
+*
+* Sources (checked 2026-10-19 through the Devvit MCP `devvit_search`):
+* - <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/notifications/notifications-overview>:
+*   a gated beta that an app applies for.
+* - <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/notifications/pn-best-practices>:
+*   copy pre-approved by Devvit admins, "titles ≤ 60 characters, body ≤ 100
+*   characters", at most 2 per user per day and 25K per app per day once
+*   published, opt-in enforced at the API level, an in-game control for both
+*   directions, and opt-out controls planned for Reddit settings.
+* - <https://developers.reddit.com/docs/versioned_docs/version-0.14/guides/logged-out-users>:
+*   `showLoginPrompt()` reloads the page after the player logs in.
+*/
+import type { NotificationCapabilities } from '@mpgd/platform/notifications';
+/** The reference provider id of the Devvit profile. */
+export declare const devvitNotificationProviderId: 'devvit';
+/** The catalog target Devvit serves. */
+export declare const devvitNotificationTarget: 'reddit';
+/** Longest title Devvit accepts, in Unicode code points of the filled text as the kit counts them. */
+export declare const devvitNotificationTitleMaxLength = 60;
+/** Longest body Devvit accepts, in Unicode code points of the filled text as the kit counts them. */
+export declare const devvitNotificationBodyMaxLength = 100;
+/** Sends per Reddit user per rolling day (a provider limit). */
+export declare const devvitNotificationsPerUserPerDay = 2;
+/** Sends per app per day (the registry entry's `rate`). */
+export declare const devvitNotificationsPerAppPerDay = 25000;
+/**
+* Devvit's length unit, which the RFC left to P3. The docs give the limits
+* in "characters" without a unit, the SDK (`@devvit/notifications` 0.14.1)
+* checks nothing before `Enqueue`, and Devvit admins approve the copy
+* before a game may send it, so the limit is a copy-review rule more than an
+* API one. The kit counts Unicode code points, as the catalog validator
+* counts its mapping fields: an accented letter or an emoji counts once, as
+* a reader sees it, and a grapheme cluster of several code points (a flag, a
+* family emoji) counts more than once, which is stricter than a reader.
+* Devvit has not confirmed the unit; if its server counts UTF-16 units, a
+* text with astral characters (most emoji) that passes here could still be
+* refused there, and the refusal arrives as an `enqueue` error. It counts
+* the filled text, at send time, because `{{name}}` placeholders change the
+* length once template data fills them.
+*/
+export declare function devvitNotificationTextLength(text: string): number;
+/**
+* The characters of a Devvit host code. The server bridge names a host code
+* in an error message as `(host code <code>)`, and the webview reads it back.
+*/
+export declare const devvitHostCodeCharacters = "[A-Za-z0-9_.:-]{1,128}";
+/** A post (`t3_`) or comment (`t1_`) id, the only links `enqueue` accepts. */
+export declare const devvitNotificationLinkPattern: RegExp;
+/** A Reddit user id (`t2_`), the only recipient `enqueue` accepts. */
+export declare const devvitUserIdPattern: RegExp;
+/**
+* The Devvit capability block (RFC "Provider profiles"): app-scope consent
+* the game renders, readable through the server bridge and at send time,
+* persistent, behind a player gesture, revocable in the game, with no
+* settings link; platform-user, free-form (approved copy) remote delivery for
+* `service` and `requested` topics; no local notifications; opens through
+* the send's post or comment link. While the viewer is logged out the
+* availability is `action-required` (login). A fresh object on every call.
+*/
+export declare function createDevvitNotificationCapabilities(availability?: NotificationCapabilities['availability']): NotificationCapabilities;
+/**
+* A block that offers nothing, for a provider read that failed or stalled
+* (`createUnsupportedNotificationCapabilities()` of `@mpgd/platform/notifications`
+* with the given availability, kept equal by a test). A fresh object.
+*/
+export declare function createDevvitDegradedNotificationCapabilities(availability: NotificationCapabilities['availability']): NotificationCapabilities;