@mpgd/adapter-devvit 0.12.1 → 0.13.1

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

@@ -0,0 +1,257 @@
+import { type CreateNotificationServiceInput, type NotificationProviderRegistry, type NotificationRemoteDeliveryAnswer, type NotificationRemoteDeliveryProvider, type NotificationService, type NotificationServiceCatalog, type NotificationSession, type NotificationStore } from '@mpgd/game-services/notifications';
+import { type NotificationDeployment, type NotificationProviderRegistryEntry } from '@mpgd/platform/notifications';
+import { type CreateDevvitRedisNotificationStoreOptions, type DevvitNotificationRedis } from './redis-notification-store.js';
+/**
+* Remote delivery on Devvit (notifications v2 RFC, "Delivery providers",
+* Devvit). It runs inside the Devvit server, not the game-services Worker,
+* because only that runtime can call the notifications plugin: the same
+* `@mpgd/game-services/notifications` service, policy gate, and delivery
+* module, over a Redis-backed store.
+*
+* `enqueue` and `isOptedIn` are `notifications` from `@devvit/web/server`
+* (`@devvit/notifications` 0.14.1): <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/notifications/pn-best-practices>.
+*/
+/** One recipient of `notifications.enqueue` (`EnqueueOptions['recipients'][number]`). */
+export interface DevvitEnqueueRecipient {
+  readonly userId: `t2_${string}`;
+  readonly link: `t1_${string}` | `t3_${string}`;
+  readonly data: Record<string, string>;
+}
+/** What `notifications.enqueue` answers (`EnqueueResponse`). */
+export interface DevvitEnqueueResponse {
+  readonly successCount: number;
+  readonly failureCount: number;
+  readonly errors: readonly {
+    readonly userId: string | undefined;
+    readonly message: string;
+  }[];
+}
+/** The server side of the Devvit notifications plugin that sends and reads opt-in. */
+export interface DevvitNotificationsDeliveryClient {
+  enqueue(options: {
+    title: string;
+    body: string;
+    recipients: DevvitEnqueueRecipient[];
+  }): Promise<DevvitEnqueueResponse>;
+  isOptedIn(userId: `t2_${string}`): Promise<boolean>;
+}
+/**
+* How an `enqueue` failure is answered: a per-recipient error of the answer
+* (`source: 'answer'`: Devvit counted a failure for the user, but an error
+* the defaults cannot read is still `ambiguous`) or a call that threw
+* (`source: 'thrown'`, Devvit may have queued it, so `ambiguous` is the
+* default and the only safe answer unless the error proves nothing was
+* sent: a classifier must answer `undefined` or `ambiguous` for a thrown
+* error it does not know). An answer that counts neither a success nor a
+* failure is not classified. Devvit documents no error messages (checked
+* 2026-10-19); a deployment that observes one (through `onEnqueueError`)
+* names it here. `undefined` keeps the default.
+*/
+export type DevvitEnqueueErrorClassifier = (message: string, source: 'answer' | 'thrown') => 'rate-limited' | 'recipient' | 'configuration' | 'ambiguous' | undefined;
+/** An `enqueue` failure, for the operator's log; the message is Devvit's and may name the user. */
+export interface DevvitEnqueueErrorReport {
+  readonly sendKey: string;
+  readonly source: 'answer' | 'thrown';
+  readonly message: string;
+  readonly answer: NotificationRemoteDeliveryAnswer['status'];
+  /** The reason of a `rejected` answer. */
+  readonly reason?: 'configuration' | 'recipient';
+}
+export interface CreateDevvitNotificationDeliveryProviderInput {
+  readonly notifications: DevvitNotificationsDeliveryClient;
+  /**
+  * The Reddit user id of a player, for the send-time opt-in read. By
+  * default a player id that is a `t2_` id (the Devvit server bridge's
+  * `context.userId`) is its own Reddit id.
+  */
+  readonly userIdOf?: (player: string) => string | undefined;
+  readonly classifyEnqueueError?: DevvitEnqueueErrorClassifier;
+  /**
+  * Every `enqueue` failure and how it was answered, so an operator learns
+  * Devvit's messages. `createDevvitNotificationService` forwards the
+  * `ambiguous` ones and the `configuration` rejections to `onError`.
+  */
+  readonly onEnqueueError?: (report: DevvitEnqueueErrorReport) => void;
+}
+/** Provider codes of the answers this provider gives without calling `enqueue`. */
+export declare const devvitNotificationProviderCodes: Readonly<{
+  readonly deviceRecipient: 'DEVVIT_DEVICE_RECIPIENT';
+  readonly recipientInvalid: 'DEVVIT_RECIPIENT_INVALID';
+  readonly linkInvalid: 'DEVVIT_LINK_INVALID';
+  readonly textMissing: 'DEVVIT_TEXT_MISSING';
+  readonly titleTooLong: 'DEVVIT_TITLE_TOO_LONG';
+  readonly bodyTooLong: 'DEVVIT_BODY_TOO_LONG';
+  readonly templateSyntax: 'DEVVIT_TEMPLATE_SYNTAX';
+  readonly enqueueFailed: 'DEVVIT_ENQUEUE_FAILED';
+  readonly enqueueRejected: 'DEVVIT_ENQUEUE_REJECTED';
+  readonly enqueueUnanswered: 'DEVVIT_ENQUEUE_UNANSWERED';
+  readonly enqueueUnclassified: 'DEVVIT_ENQUEUE_UNCLASSIFIED';
+}>;
+/**
+* The Devvit delivery provider (`{ id: 'devvit', send, readPermission }`).
+* One recipient per `enqueue` call in the first wave (RFC "Open questions",
+* bulk sends).
+*
+* - **What it sends.** The gate's title and body as they are, with the
+*   send's `link` (else the mapping's) and no template data. Every Mustache
+*   tag starts with `{{`, so a filled text that still holds one (from
+*   template data such as a player name, or a catalog brace outside a
+*   `{{name}}` placeholder) is refused (`rejected`, `configuration`, provider
+*   code `DEVVIT_TEMPLATE_SYNTAX`) before anything is sent.
+* - **Limits it checks first.** A missing or blank title or body, a title over 60 or a body over 100 code
+*   points of the filled text (see `devvitNotificationTextLength`), a link
+*   that is not a `t3_` or `t1_` id, and a recipient that is not a `t2_` id
+*   are `rejected` with reason `configuration` (the recipient: `recipient`),
+*   because the same send would fail again.
+* - **Answers.** `successCount` above 0 is `accepted`. Otherwise an error for
+*   this recipient (or for no named user) is a failure Devvit counted:
+*   a message that reads as a rate limit is `rate-limited` (deferred, for
+*   at most a day), one that reads as the user's refusal (not opted in, no
+*   such user) in an error that names this recipient is `rejected` with
+*   reason `recipient`. Any other error is `ambiguous` (provider code
+*   `DEVVIT_ENQUEUE_UNCLASSIFIED`): Devvit documents no error messages, so
+*   an unknown one is neither proof of a setup error nor of a refusal. The
+*   service reports it to the operator and replays it after each lease,
+*   which doubles from the claim lease up to an hour, for at most 24 hours
+*   after the first attempt (`notificationAmbiguousReplayHours`): with the
+*   default 300-second lease, at most 27 calls. A call that throws,
+*   or an answer that counts neither a success nor a failure, is
+*   `ambiguous` too: Devvit may have queued it, and `enqueue` takes no
+*   idempotency key, so a replay may show twice.
+*   `classifyEnqueueError` overrides each default, and `onEnqueueError`
+*   sees every failure with Devvit's message.
+* - **Opt-in at send time.** `readPermission` reads `isOptedIn`, since no
+*   opt-out event exists and opt-out may move into Reddit settings: opted in
+*   is `granted`, otherwise `prompt`.
+*/
+export declare function createDevvitNotificationDeliveryProvider(input: CreateDevvitNotificationDeliveryProviderInput): NotificationRemoteDeliveryProvider;
+/**
+* The Devvit registry entry: the reference `devvit` entry of
+* `@mpgd/platform/notifications`, whose values this provider owns. 2 sends
+* per user per day is a provider limit (a day-long window suppresses), and
+* 25,000 per app per day is the `rate` the scheduler keeps to. A fresh copy
+* on every call.
+*/
+export declare function createDevvitNotificationProviderEntry(): NotificationProviderRegistryEntry;
+export interface CreateDevvitNotificationServiceInput extends Omit<CreateNotificationServiceInput, 'store' | 'registry' | 'catalog' | 'resolvePlatformRecipient' | 'deployment'> {
+  /** `redis` from `@devvit/web/server`, for the Redis store; not needed with `store`. */
+  readonly redis?: DevvitNotificationRedis;
+  /** `notifications` from `@devvit/web/server`. */
+  readonly notifications: DevvitNotificationsDeliveryClient;
+  /** The game's topic catalog file, validated against the Devvit entry for the `reddit` target. */
+  readonly catalog: unknown;
+  readonly deployment?: NotificationDeployment;
+  readonly store?: NotificationStore;
+  readonly storeOptions?: CreateDevvitRedisNotificationStoreOptions;
+  readonly classifyEnqueueError?: DevvitEnqueueErrorClassifier;
+}
+export interface DevvitNotificationService {
+  readonly service: NotificationService;
+  readonly store: NotificationStore;
+  readonly registry: NotificationProviderRegistry;
+  readonly catalog: NotificationServiceCatalog;
+}
+/**
+* The notifications v2 service as the Devvit server runs it: the Redis
+* store, the Devvit provider for the `reddit` target, and the catalog
+* checked against the Devvit entry (title ≤ 60 and body ≤ 100 code points,
+* an optional `t3_`/`t1_` default link). A player is a Reddit user id
+* (`context.userId`), which is also the recipient; any other player id has
+* no Devvit recipient (`unavailable: no-endpoint`).
+*
+* Players' own calls take a `devvitNotificationSession(userId)`. Server
+* reminders (`setReminder`) fire through the `dispatch` scheduler task
+* (`runDevvitNotificationTask`). The scheduler pushes no consent notices
+* through Devvit: its entry fixes the title and body per topic, so it does
+* not carry notices (`notificationProviderCarriesNotices`).
+*/
+export declare function createDevvitNotificationService(input: CreateDevvitNotificationServiceInput): DevvitNotificationService;
+/**
+* The notifications session of a Devvit request's logged-in user. A Devvit
+* player has no game-services session: the user id is the player, and one
+* session and installation per user, which no endpoint uses because Devvit
+* registers no device address.
+*/
+export declare function devvitNotificationSession(userId: string): NotificationSession;
+/**
+* The Devvit scheduler tasks that keep the service's own work moving:
+* `dispatch` runs the service's scheduler (`runScheduler`) every minute,
+* which turns due server reminders into sends and replays due rows
+* (deferred sends, rate-limited ones, and ambiguous answers once their
+* lease ends), and `purge` forgets old keys,
+* history, and dead endpoints every five minutes. They run, and use two of
+* the installation's recurring tasks, even while the game has no
+* notifications service; such a run does no work. A game declares both in
+* `devvit.json` (`scheduler.tasks`, each with its `endpoint` and `cron`)
+* and routes each endpoint to `runDevvitNotificationTask`.
+*
+* Devvit scheduler: <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/server/scheduler>
+* (a recurring task is a `devvit.json` `scheduler.tasks` entry whose
+* endpoint matches `/internal/.+`, answered with a `TaskResponse`, `{}`).
+*/
+export declare const devvitNotificationSchedulerTasks: Readonly<{
+  readonly dispatch: Readonly<{
+    name: "mpgd-notifications-dispatch";
+    endpoint: "/internal/scheduler/mpgd-notifications-dispatch";
+    cron: "* * * * *";
+  }>;
+  readonly purge: Readonly<{
+    name: "mpgd-notifications-purge";
+    endpoint: "/internal/scheduler/mpgd-notifications-purge";
+    cron: "*/5 * * * *";
+  }>;
+}>;
+export type DevvitNotificationTask = keyof typeof devvitNotificationSchedulerTasks;
+/**
+* Due schedule entries, and due sends, one scheduler round of a dispatch
+* task takes at most (`runScheduler`'s `limit`).
+*/
+export declare const devvitNotificationDispatchBatch = 10;
+/**
+* Rows of each kind one purge task deletes at most (the Redis store's
+* `purgeLimit`). Every five minutes that is 57,600 a day of each kind,
+* above the 25,000 sends a day Devvit allows an app.
+*/
+export declare const devvitNotificationPurgeBatch = 200;
+/**
+* A dispatch task starts no scheduler round after this long
+* (`runScheduler`'s `budgetMs`), so a run lasts the budget plus at most one
+* round. Devvit documents no time limit for a scheduler task; this keeps a
+* run well inside the next minute's.
+*/
+export declare const devvitNotificationDispatchBudgetMs = 20000;
+/** The task an internal scheduler endpoint names, or `undefined` for any other path. */
+export declare function devvitNotificationTaskForEndpoint(pathname: string): DevvitNotificationTask | undefined;
+export type DevvitNotificationTaskResult = {
+  readonly task: 'dispatch';
+  /**
+  * The sends the run touched, whatever their outcome (delivered, in
+  * flight, deferred, or refused by the gate): fired reminders and due rows.
+  */
+  readonly touched: number;
+  readonly failed: number;
+} | {
+  readonly task: 'purge';
+  readonly sends: number;
+  readonly history: number;
+  readonly endpoints: number;
+};
+/**
+* Runs one scheduler task.
+*
+* `dispatch` is one `runScheduler` run, bounded by time: rounds of at most
+* `dispatchLimit` (10, a positive integer) due schedule entries and due
+* sends, which go on while a round filled its batch and got somewhere, and
+* start no round after `budgetMs` (20 seconds), so a run lasts the budget
+* plus at most one round; the sends of a run are not otherwise capped. Due
+* rows count against the Devvit entry's `rate`, 25,000 a day, a daily cap
+* rather than a spread. One failing send never stops the others.
+*
+* `purge` deletes at most the store's `purgeLimit` rows of each kind (200
+* for the store `createDevvitNotificationService` builds). A backlog
+* drains over the following runs.
+*/
+export declare function runDevvitNotificationTask(service: Pick<NotificationService, 'runScheduler' | 'purge'>, task: DevvitNotificationTask, options?: {
+  readonly dispatchLimit?: number;
+  readonly budgetMs?: number;
+}): Promise<DevvitNotificationTaskResult>;