@mpgd/adapter-devvit 0.12.1 → 0.13.0

package/dist/notifications-contract.js

@@ -0,0 +1,109 @@
+/**
+ * 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.
+ */
+/** The reference provider id of the Devvit profile. */
+export const devvitNotificationProviderId = 'devvit';
+/** The catalog target Devvit serves. */
+export const devvitNotificationTarget = 'reddit';
+/** Longest title Devvit accepts, in Unicode code points of the filled text as the kit counts them. */
+export const devvitNotificationTitleMaxLength = 60;
+/** Longest body Devvit accepts, in Unicode code points of the filled text as the kit counts them. */
+export const devvitNotificationBodyMaxLength = 100;
+/** Sends per Reddit user per rolling day (a provider limit). */
+export const devvitNotificationsPerUserPerDay = 2;
+/** Sends per app per day (the registry entry's `rate`). */
+export const devvitNotificationsPerAppPerDay = 25_000;
+/**
+ * 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 function devvitNotificationTextLength(text) {
+    return [...text].length;
+}
+/**
+ * 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 const devvitHostCodeCharacters = '[A-Za-z0-9_.:-]{1,128}';
+/** A post (`t3_`) or comment (`t1_`) id, the only links `enqueue` accepts. */
+export const devvitNotificationLinkPattern = /^t[13]_[A-Za-z0-9]+$/u;
+/** A Reddit user id (`t2_`), the only recipient `enqueue` accepts. */
+export const devvitUserIdPattern = /^t2_[A-Za-z0-9]+$/u;
+/**
+ * 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 function createDevvitNotificationCapabilities(availability = 'available') {
+    return {
+        availability,
+        permission: {
+            scope: 'app',
+            prompt: 'game',
+            readable: true,
+            serverReadable: true,
+            allowance: 'persistent',
+            userGesture: true,
+            settings: false,
+        },
+        remote: {
+            supported: true,
+            purposes: ['service', 'requested'],
+            addressing: 'platform-user',
+            content: 'free-form',
+        },
+        local: { supported: false },
+        open: 'host-link',
+    };
+}
+/**
+ * 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 function createDevvitDegradedNotificationCapabilities(availability) {
+    return {
+        availability,
+        permission: {
+            scope: 'app',
+            prompt: 'os',
+            readable: true,
+            serverReadable: false,
+            allowance: 'persistent',
+            userGesture: false,
+            settings: false,
+        },
+        remote: { supported: false, purposes: [], addressing: 'none', content: 'free-form' },
+        local: { supported: false },
+        open: 'none',
+    };
+}

package/dist/server/index.d.ts

@@ -4,3 +4,6 @@ export * from './payment-order.js';
 export * from './post-operation.js';
 export * from './redis-post-operation-store.js';
 export * from './redis-verified-leaderboard.js';
+export * from './redis-notification-store.js';
+export * from './notifications-delivery.js';
+export * from './notifications-bridge.js';

package/dist/server/index.js

@@ -4,3 +4,6 @@ export * from './payment-order.js';
 export * from './post-operation.js';
 export * from './redis-post-operation-store.js';
 export * from './redis-verified-leaderboard.js';
+export * from './redis-notification-store.js';
+export * from './notifications-delivery.js';
+export * from './notifications-bridge.js';

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

@@ -0,0 +1,103 @@
+import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
+import { type NotificationProvider } from '@mpgd/platform/notifications';
+/**
+* The game-rendered consent of the Devvit profile (notifications v2 RFC,
+* "Provider profiles", Devvit), served from the Devvit server bridge. Reddit
+* shows no consent screen: the game draws its own on/off control, and the
+* server opts the requesting user in or out with `optInCurrentUser` and
+* `optOutCurrentUser` and reads `isOptedIn` (`notifications` from
+* `@devvit/web/server`; <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/notifications/pn-best-practices>).
+*
+* The user is the Devvit request context's (`context.userId`), never a
+* payload field. A logged-out viewer has none: reads answer
+* `action-required` with `requiredAction: 'login'`, and requests answer the
+* `action-required` outcome (`unavailable` for an unmapped topic) without
+* reaching the plugin; the game then calls
+* `identity.requestUpgrade({ reason: 'notifications' })`.
+*
+* Notifications are a gated beta: an app Reddit has not approved is kept
+* `approval-required` by the target config, which hides the provider from
+* the game. No opt-out event exists, so nothing here pushes events; the
+* backend reads `isOptedIn` at send time instead.
+*/
+/** The server side of the Devvit notifications plugin that opts the current user in and out. */
+export interface DevvitNotificationsConsentClient {
+  optInCurrentUser(): Promise<{
+    readonly success: boolean;
+    readonly message?: string | undefined;
+  }>;
+  optOutCurrentUser(): Promise<{
+    readonly success: boolean;
+    readonly message?: string | undefined;
+  }>;
+  isOptedIn(userId: `t2_${string}`): Promise<boolean>;
+}
+export interface CreateDevvitServerNotificationProviderInput {
+  readonly notifications: DevvitNotificationsConsentClient;
+  /** The logged-in Reddit user of the current Devvit request (`context.userId`). */
+  readonly currentUserId: () => string | undefined;
+  /**
+  * The topic ids the game's catalog maps for the `reddit` target. A request
+  * for a topic outside them answers `unavailable` without opting in.
+  */
+  readonly topics: readonly string[];
+}
+export interface CreateDevvitNotificationsV2BridgeHandlerInput extends CreateDevvitServerNotificationProviderInput {
+  /**
+  * Every failure of a notifications method the handler answers with an
+  * error, except an invalid payload (the caller's), with its cause (the
+  * plugin's own text, which the webview never sees). Synchronous; a hook
+  * that throws or rejects changes nothing. By default `console.warn`, which
+  * skips the expected `NOTIFICATIONS_UNSUPPORTED` of the local methods.
+  */
+  readonly onError?: ((error: unknown, context: {
+    readonly method: string;
+  }) => void) | undefined;
+}
+/** Host codes of the failures this provider normalizes. */
+export declare const devvitNotificationHostCodes: Readonly<{
+  readonly optInRefused: 'DEVVIT_OPT_IN_REFUSED';
+  readonly optOutRefused: 'DEVVIT_OPT_OUT_REFUSED';
+  readonly pluginFailed: 'DEVVIT_NOTIFICATIONS_PLUGIN_FAILED';
+}>;
+/**
+* The Devvit server's `NotificationProvider`, for one request at a time: the
+* bridge handler calls it inside the request whose user it reads.
+*
+* - **Reads.** Opted in reads `granted`, otherwise `prompt` (the runtime
+*   turns `prompt` into `denied` once a decision is recorded).
+* - **Requests.** Already opted in is `already-granted` without a second
+*   opt-in; otherwise `optInCurrentUser` answers `granted`. A refused opt-in
+*   (`success: false`, such as an app not yet approved) throws
+*   `NOTIFICATIONS_CONFIGURATION_REQUIRED` with host code
+*   `DEVVIT_OPT_IN_REFUSED`, which is not retryable: Devvit documents no
+*   transient refusal, and a refusal the game retried would loop. A plugin
+*   call that throws is `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`.
+* - **Revocation.** `optOutCurrentUser` for a user who is opted in (one who
+*   is already out needs none, which Devvit might refuse), the `denied`
+*   outcome for every mapped topic (`unavailable` for the others, and no
+*   opt-out when none is mapped), and the state the opt-out produced:
+*   `prompt`, not opted in.
+* - **Unmapped topics.** A topic the catalog does not map for `reddit`
+*   reads `unsupported` in every snapshot.
+* - **Registration.** A logged-in user registers `{ kind: 'platform-user' }`;
+*   the webview adds its locale and zone. No device address exists.
+*/
+export declare function createDevvitServerNotificationProvider(input: CreateDevvitServerNotificationProviderInput): NotificationProvider;
+/** Serves the nine `notifications.v2.*` bridge methods; the Devvit server bridge's `notifications` dependency. */
+export interface DevvitNotificationsV2BridgeHandler {
+  request(input: BridgeRequest): Promise<BridgeResponse>;
+}
+/**
+* The server bridge side of notifications v2 on Devvit (RFC "Bridge and
+* versioning"): each method's payload and answer are checked with the
+* `@mpgd/bridge/notifications` validators. A payload the validator rejects
+* answers `NOTIFICATIONS_INVALID_INPUT`; a method the profile lacks (the
+* local-notification methods) `NOTIFICATIONS_UNSUPPORTED`; `openSettings`
+* answers `unavailable`, because Devvit has no settings link; an answer the
+* contract rejects `NOTIFICATIONS_CONFIGURATION_REQUIRED`. A thrown
+* `NotificationError` crosses as `{ code, message, retryable }` with its host
+* code named in the message. Devvit has no server-to-webview event channel,
+* so the bridge carries no notifications events.
+*/
+export declare function createDevvitNotificationsV2BridgeHandler(input: CreateDevvitNotificationsV2BridgeHandlerInput): DevvitNotificationsV2BridgeHandler;

package/dist/server/notifications-bridge.js

@@ -0,0 +1,262 @@
+import { createBridgeError, isBridgeNotificationsV2Method, } from '@mpgd/bridge';
+import { assertBridgeNotificationsV2Payload, assertBridgeNotificationsV2Result, } from '@mpgd/bridge/notifications';
+import { PlatformOperationError } from '@mpgd/platform';
+import { isNotificationErrorCode, NotificationError, notificationsProtocolVersion, } from '@mpgd/platform/notifications';
+import { createDevvitNotificationCapabilities, devvitHostCodeCharacters, devvitNotificationProviderId, devvitUserIdPattern, } from '../notifications-contract.js';
+/** Host codes of the failures this provider normalizes. */
+export const devvitNotificationHostCodes = Object.freeze({
+    optInRefused: 'DEVVIT_OPT_IN_REFUSED',
+    optOutRefused: 'DEVVIT_OPT_OUT_REFUSED',
+    pluginFailed: 'DEVVIT_NOTIFICATIONS_PLUGIN_FAILED',
+});
+/**
+ * The Devvit server's `NotificationProvider`, for one request at a time: the
+ * bridge handler calls it inside the request whose user it reads.
+ *
+ * - **Reads.** Opted in reads `granted`, otherwise `prompt` (the runtime
+ *   turns `prompt` into `denied` once a decision is recorded).
+ * - **Requests.** Already opted in is `already-granted` without a second
+ *   opt-in; otherwise `optInCurrentUser` answers `granted`. A refused opt-in
+ *   (`success: false`, such as an app not yet approved) throws
+ *   `NOTIFICATIONS_CONFIGURATION_REQUIRED` with host code
+ *   `DEVVIT_OPT_IN_REFUSED`, which is not retryable: Devvit documents no
+ *   transient refusal, and a refusal the game retried would loop. A plugin
+ *   call that throws is `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`.
+ * - **Revocation.** `optOutCurrentUser` for a user who is opted in (one who
+ *   is already out needs none, which Devvit might refuse), the `denied`
+ *   outcome for every mapped topic (`unavailable` for the others, and no
+ *   opt-out when none is mapped), and the state the opt-out produced:
+ *   `prompt`, not opted in.
+ * - **Unmapped topics.** A topic the catalog does not map for `reddit`
+ *   reads `unsupported` in every snapshot.
+ * - **Registration.** A logged-in user registers `{ kind: 'platform-user' }`;
+ *   the webview adds its locale and zone. No device address exists.
+ */
+export function createDevvitServerNotificationProvider(input) {
+    const mapped = new Set(input.topics);
+    const user = () => {
+        const id = input.currentUserId();
+        return typeof id === 'string' && devvitUserIdPattern.test(id)
+            ? id
+            : undefined;
+    };
+    const plugin = async (call, what) => {
+        try {
+            return await call();
+        }
+        catch (error) {
+            // The plugin's own text stays on the server (as the cause); the
+            // webview gets a fixed message.
+            throw new NotificationError('NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', {
+                message: `Devvit notifications ${what} failed.`,
+                hostCode: devvitNotificationHostCodes.pluginFailed,
+                cause: error,
+            });
+        }
+    };
+    /** The app's state for each mapped topic; a topic the catalog does not map for `reddit` reads `unsupported`. */
+    const snapshotOf = (topics, state) => ({
+        app: state,
+        topics: Object.fromEntries(topics.map((topic) => [topic, mapped.has(topic) ? state : 'unsupported'])),
+        ...(state === 'action-required' ? { requiredAction: 'login' } : {}),
+    });
+    const read = async (userId) => (await plugin(() => input.notifications.isOptedIn(userId), 'isOptedIn')) ? 'granted' : 'prompt';
+    /** `forMapped` for each mapped topic, `unavailable` for the others. */
+    const outcomesWith = (topics, forMapped) => Object.fromEntries(topics.map((topic) => [topic, mapped.has(topic) ? forMapped : 'unavailable']));
+    const loginRequired = (topics) => ({
+        snapshot: snapshotOf(topics, 'action-required'),
+        outcomes: outcomesWith(topics, 'action-required'),
+        // Logging in could not enable a topic the catalog does not map.
+        ...(topics.some((topic) => mapped.has(topic)) ? { requiredAction: 'login' } : {}),
+    });
+    const refused = (response, hostCode, what) => {
+        if (response?.success === true) {
+            return undefined;
+        }
+        // Devvit's own message stays on the server (as the cause).
+        return new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+            message: `Devvit refused ${what}.`,
+            hostCode,
+            cause: new Error(typeof response?.message === 'string' ? response.message : 'no message'),
+        });
+    };
+    return {
+        provider: devvitNotificationProviderId,
+        async getCapabilities() {
+            return createDevvitNotificationCapabilities(user() === undefined ? 'action-required' : 'available');
+        },
+        async getPermission({ topics }) {
+            const userId = user();
+            return snapshotOf(topics, userId === undefined ? 'action-required' : await read(userId));
+        },
+        async requestPermission({ topics }) {
+            const userId = user();
+            if (userId === undefined) {
+                return loginRequired(topics);
+            }
+            const askable = topics.filter((topic) => mapped.has(topic));
+            if (askable.length === 0) {
+                return { snapshot: snapshotOf(topics, await read(userId)), outcomes: outcomesWith(topics, 'unavailable') };
+            }
+            let outcome = 'already-granted';
+            if ((await read(userId)) !== 'granted') {
+                const response = await plugin(() => input.notifications.optInCurrentUser(), 'optInCurrentUser');
+                const failure = refused(response, devvitNotificationHostCodes.optInRefused, 'the opt-in');
+                if (failure !== undefined) {
+                    throw failure;
+                }
+                outcome = 'granted';
+            }
+            return { snapshot: snapshotOf(topics, 'granted'), outcomes: outcomesWith(topics, outcome) };
+        },
+        async revokePermission({ topics }) {
+            const userId = user();
+            if (userId === undefined) {
+                return loginRequired(topics);
+            }
+            const outcomes = outcomesWith(topics, 'denied');
+            if (!topics.some((topic) => mapped.has(topic))) {
+                // Nothing this provider maps: no opt-out, as a request opts nothing in.
+                return { snapshot: snapshotOf(topics, await read(userId)), outcomes };
+            }
+            // A user who is already out needs no opt-out, which Devvit might refuse.
+            if ((await read(userId)) === 'granted') {
+                const response = await plugin(() => input.notifications.optOutCurrentUser(), 'optOutCurrentUser');
+                const failure = refused(response, devvitNotificationHostCodes.optOutRefused, 'the opt-out');
+                if (failure !== undefined) {
+                    throw failure;
+                }
+            }
+            // The opt-out (or the read that found the user out) decided the state:
+            // not opted in, which reads `prompt`. A second read could be stale.
+            return { snapshot: snapshotOf(topics, 'prompt'), outcomes };
+        },
+        async register() {
+            return user() === undefined
+                ? null
+                : { provider: devvitNotificationProviderId, address: { kind: 'platform-user' } };
+        },
+        subscribe() {
+            // No opt-out event exists, and opens arrive as post links.
+            return () => { };
+        },
+    };
+}
+/**
+ * The server bridge side of notifications v2 on Devvit (RFC "Bridge and
+ * versioning"): each method's payload and answer are checked with the
+ * `@mpgd/bridge/notifications` validators. A payload the validator rejects
+ * answers `NOTIFICATIONS_INVALID_INPUT`; a method the profile lacks (the
+ * local-notification methods) `NOTIFICATIONS_UNSUPPORTED`; `openSettings`
+ * answers `unavailable`, because Devvit has no settings link; an answer the
+ * contract rejects `NOTIFICATIONS_CONFIGURATION_REQUIRED`. A thrown
+ * `NotificationError` crosses as `{ code, message, retryable }` with its host
+ * code named in the message. Devvit has no server-to-webview event channel,
+ * so the bridge carries no notifications events.
+ */
+export function createDevvitNotificationsV2BridgeHandler(input) {
+    const provider = createDevvitServerNotificationProvider(input);
+    const onError = input.onError ?? ((error, context) => {
+        if (error instanceof NotificationError && error.code === 'NOTIFICATIONS_UNSUPPORTED') {
+            return;
+        }
+        console.warn(`devvit notifications ${context.method} failed`, error);
+    });
+    const serve = async (method, payload) => {
+        switch (method) {
+            case 'notifications.v2.getCapabilities':
+                validPayload(method, payload);
+                return {
+                    protocolVersion: notificationsProtocolVersion,
+                    provider: provider.provider,
+                    capabilities: await provider.getCapabilities(),
+                };
+            case 'notifications.v2.getPermission':
+                return provider.getPermission(validPayload(method, payload));
+            case 'notifications.v2.requestPermission':
+                return provider.requestPermission(validPayload(method, payload));
+            case 'notifications.v2.revokePermission':
+                return provider.revokePermission
+                    .call(provider, validPayload(method, payload));
+            case 'notifications.v2.register':
+                validPayload(method, payload);
+                return { registration: (await provider.register?.()) ?? null };
+            case 'notifications.v2.openSettings':
+                validPayload(method, payload);
+                return { status: 'unavailable' };
+            case 'notifications.v2.scheduleLocal':
+            case 'notifications.v2.cancelLocal':
+            case 'notifications.v2.listLocal':
+                validPayload(method, payload);
+                throw new NotificationError('NOTIFICATIONS_UNSUPPORTED', {
+                    message: `Devvit has no local notifications (${method}).`,
+                });
+        }
+    };
+    return {
+        async request(request) {
+            if (!isBridgeNotificationsV2Method(request.method)) {
+                return createBridgeError(request.id, 'UNSUPPORTED_METHOD', `${request.method} is not a notifications v2 method.`);
+            }
+            const method = request.method;
+            try {
+                const data = await serve(method, request.payload);
+                return { id: request.id, ok: true, data: validResult(method, data) };
+            }
+            catch (error) {
+                if (!(error instanceof InvalidPayloadError)) {
+                    try {
+                        const logged = onError(error, { method });
+                        if (logged instanceof Promise) {
+                            logged.catch(() => { });
+                        }
+                    }
+                    catch {
+                        // A failing log never changes the answer.
+                    }
+                }
+                return toBridgeError(request, error);
+            }
+        },
+    };
+}
+class InvalidPayloadError extends Error {
+    name = 'InvalidPayloadError';
+}
+function validPayload(method, payload) {
+    try {
+        return assertBridgeNotificationsV2Payload(method, payload);
+    }
+    catch (error) {
+        throw new InvalidPayloadError(`${method} payload is invalid: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+function validResult(method, data) {
+    try {
+        return assertBridgeNotificationsV2Result(method, data);
+    }
+    catch (error) {
+        throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+            message: `The Devvit notifications provider answered ${method} with invalid data: ${error instanceof Error ? error.message : String(error)}`,
+            cause: error,
+        });
+    }
+}
+const hostCodeValue = new RegExp(`^${devvitHostCodeCharacters}$`, 'u');
+function toBridgeError(request, error) {
+    if (error instanceof InvalidPayloadError) {
+        return createBridgeError(request.id, 'NOTIFICATIONS_INVALID_INPUT', error.message);
+    }
+    if (error instanceof NotificationError) {
+        return createBridgeError(request.id, error.code, error.hostCode === undefined || !hostCodeValue.test(error.hostCode)
+            ? error.message
+            : `${error.message} (host code ${error.hostCode})`, error.retryable);
+    }
+    if (error instanceof PlatformOperationError) {
+        return isNotificationErrorCode(error.code)
+            ? createBridgeError(request.id, error.code, error.message, error.retryable)
+            : createBridgeError(request.id, 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', `${request.method} failed: ${error.message}`, error.retryable);
+    }
+    // An unexpected failure's text stays on the server.
+    return createBridgeError(request.id, 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE', `${request.method} failed on the Devvit server.`, true);
+}