@mpgd/adapter-devvit 0.12.1 → 0.13.0

package/dist/server/notifications-delivery.js

@@ -0,0 +1,431 @@
+import { createNotificationProviderRegistry, createNotificationService, createNotificationServiceCatalog, } from '@mpgd/game-services/notifications';
+import { referenceNotificationProviders, } from '@mpgd/platform/notifications';
+import { devvitNotificationBodyMaxLength, devvitNotificationLinkPattern, devvitNotificationProviderId, devvitNotificationsPerAppPerDay, devvitNotificationsPerUserPerDay, devvitNotificationTarget, devvitNotificationTextLength, devvitNotificationTitleMaxLength, devvitUserIdPattern, } from '../notifications-contract.js';
+import { createDevvitRedisNotificationStore, } from './redis-notification-store.js';
+/** Provider codes of the answers this provider gives without calling `enqueue`. */
+export const devvitNotificationProviderCodes = Object.freeze({
+    deviceRecipient: 'DEVVIT_DEVICE_RECIPIENT',
+    recipientInvalid: 'DEVVIT_RECIPIENT_INVALID',
+    linkInvalid: 'DEVVIT_LINK_INVALID',
+    textMissing: 'DEVVIT_TEXT_MISSING',
+    titleTooLong: 'DEVVIT_TITLE_TOO_LONG',
+    bodyTooLong: 'DEVVIT_BODY_TOO_LONG',
+    templateSyntax: 'DEVVIT_TEMPLATE_SYNTAX',
+    enqueueFailed: 'DEVVIT_ENQUEUE_FAILED',
+    enqueueRejected: 'DEVVIT_ENQUEUE_REJECTED',
+    enqueueUnanswered: 'DEVVIT_ENQUEUE_UNANSWERED',
+    enqueueUnclassified: 'DEVVIT_ENQUEUE_UNCLASSIFIED',
+});
+/**
+ * Whether a message reads as a rate limit: per user (2 a day) or per app
+ * (25,000 a day). A limit counts only next to a word about sending and
+ * never next to one about the text, so "character limit exceeded" stays a
+ * configuration refusal.
+ */
+function readsAsRateLimit(message) {
+    if (/rate[ -]?limit|too many (?:requests|notifications)|quota|throttl/iu.test(message)) {
+        return true;
+    }
+    // A word about size or about the text marks a length or content refusal,
+    // whatever period it names. "Message" may count sends ("daily message
+    // limit"), so it marks one only when the message names no period.
+    if (/\b(?:characters?|length|long|size|bytes?|title|body|link|text|content|payload|template)\b/iu.test(message)) {
+        return false;
+    }
+    if (!dailyLimitWords.test(message) && /\bmessages?\b/iu.test(message)) {
+        return false;
+    }
+    // "Daily send limit", "per-user limits": the limit names what it counts.
+    if (adjacentCountedLimit.test(message)) {
+        return true;
+    }
+    return /\blimits?\b/iu.test(message)
+        && /\b(?:exceed(?:s|ed)?|reach(?:es|ed)?|hit)\b/iu.test(message)
+        && (dailyLimitWords.test(message) || /\b(?:notifications?|user|app|send(?:s|ing)?)\b/iu.test(message));
+}
+/** The words that name a daily period, once: Devvit's limits are per user per day and per app per day. */
+const dailyPeriodSource = String.raw `daily|per[- ]?(?:day|user|app)|today'?s?`;
+const dailyLimitWords = new RegExp(String.raw `\b(?:${dailyPeriodSource})\b`, 'iu');
+const adjacentCountedLimit = new RegExp(String.raw `\b(?:${dailyPeriodSource}|send(?:ing)?|notifications?) limits?\b`, 'iu');
+/**
+ * A message that reads as this user's refusal: not opted in, opted out, no
+ * such user or account. It counts only for an error that names this
+ * recipient.
+ */
+function readsAsUserRefusal(message) {
+    // A message about the link, the post, or the comment is not the user's.
+    if (/\b(?:perma)?(?:link|post|comment)(?:s|_?ids?)?\b|\bt[13]_/iu.test(message)) {
+        return false;
+    }
+    return /\bopt(?:ed|ing)?[ -]?(?:in|out)\b|\bnot subscribed\b|\bnotifications? (?:are )?disabled\b/iu.test(message)
+        || /\b(?:user|account|recipient)(?:\s+(?:with\s+)?(?:id\s+)?t2_\w+)?\s+(?:is\s+|was\s+|has\s+been\s+)?(?:not found|does not exist|deleted|suspended|banned)\b/iu
+            .test(message);
+}
+/** The reason a report names: only the two reasons this provider answers. */
+function reasonOf(answer) {
+    if (answer.status !== 'rejected') {
+        return {};
+    }
+    if (answer.reason === 'recipient' || answer.reason === 'configuration') {
+        return { reason: answer.reason };
+    }
+    return {};
+}
+/**
+ * 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 function createDevvitNotificationDeliveryProvider(input) {
+    const userIdOf = input.userIdOf ?? ((player) => player);
+    const rejected = (reason, providerCode) => ({ status: 'rejected', reason, providerCode });
+    return {
+        id: devvitNotificationProviderId,
+        async send(request) {
+            if (request.recipient.kind !== 'platform-user') {
+                return rejected('configuration', devvitNotificationProviderCodes.deviceRecipient);
+            }
+            const userId = request.recipient.id;
+            if (!devvitUserIdPattern.test(userId)) {
+                return rejected('recipient', devvitNotificationProviderCodes.recipientInvalid);
+            }
+            const link = request.link;
+            if (link === undefined || !devvitNotificationLinkPattern.test(link)) {
+                return rejected('configuration', devvitNotificationProviderCodes.linkInvalid);
+            }
+            const { title, body } = request.content;
+            if (title === undefined || body === undefined || title.trim() === '' || body.trim() === '') {
+                // A host template or an empty text: Devvit sends the title and body it is given.
+                return rejected('configuration', devvitNotificationProviderCodes.textMissing);
+            }
+            if (devvitNotificationTextLength(title) > devvitNotificationTitleMaxLength) {
+                return rejected('configuration', devvitNotificationProviderCodes.titleTooLong);
+            }
+            if (devvitNotificationTextLength(body) > devvitNotificationBodyMaxLength) {
+                return rejected('configuration', devvitNotificationProviderCodes.bodyTooLong);
+            }
+            if (title.includes('{{') || body.includes('{{')) {
+                // From template data or from a catalog brace outside a `{{name}}`
+                // placeholder: either way the operator should see it.
+                return rejected('configuration', devvitNotificationProviderCodes.templateSyntax);
+            }
+            const report = (source, message, answer) => {
+                try {
+                    input.onEnqueueError?.({
+                        sendKey: request.sendKey,
+                        source,
+                        message,
+                        answer: answer.status,
+                        ...reasonOf(answer),
+                    });
+                }
+                catch {
+                    // A failing log never changes the answer.
+                }
+                return answer;
+            };
+            const failure = (source, message, fallback) => {
+                let kind = fallback;
+                let note = '';
+                try {
+                    kind = input.classifyEnqueueError?.(message, source) ?? fallback;
+                }
+                catch (error) {
+                    // A failing classifier keeps the default answer; the report says so.
+                    note = ` (classifyEnqueueError threw: ${error instanceof Error ? error.message : String(error)})`;
+                }
+                // The provider code follows the final answer, after any override; a
+                // thrown call keeps DEVVIT_ENQUEUE_FAILED, which names its source.
+                let providerCode = devvitNotificationProviderCodes.enqueueRejected;
+                if (source === 'thrown') {
+                    providerCode = devvitNotificationProviderCodes.enqueueFailed;
+                }
+                else if (kind === 'ambiguous') {
+                    providerCode = devvitNotificationProviderCodes.enqueueUnclassified;
+                }
+                let answer;
+                if (kind === 'rate-limited') {
+                    // A daily limit lifts no sooner than an hour from now; any other
+                    // waits the service's default first delay.
+                    answer = dailyLimitWords.test(message)
+                        ? { status: 'rate-limited', retryAfterSeconds: 3600 }
+                        : { status: 'rate-limited' };
+                }
+                else if (kind === 'ambiguous') {
+                    answer = { status: 'ambiguous', providerCode };
+                }
+                else {
+                    answer = rejected(kind === 'recipient' ? 'recipient' : 'configuration', providerCode);
+                }
+                return report(source, `${message}${note}`, answer);
+            };
+            let response;
+            try {
+                response = await input.notifications.enqueue({
+                    title,
+                    body,
+                    recipients: [{
+                            userId: userId,
+                            link: link,
+                            data: {},
+                        }],
+                });
+            }
+            catch (error) {
+                return failure('thrown', error instanceof Error ? error.message : String(error), 'ambiguous');
+            }
+            if (typeof response?.successCount === 'number' && response.successCount > 0) {
+                return { status: 'accepted' };
+            }
+            const errors = Array.isArray(response?.errors) ? response.errors : [];
+            const ours = errors.find((error) => error?.userId === userId)
+                ?? errors.find((error) => error?.userId === undefined);
+            const failed = typeof response?.failureCount === 'number' && response.failureCount > 0;
+            if (ours === undefined && !failed) {
+                // Neither queued nor refused: Devvit may still have queued it. No
+                // error exists to classify, so the answer stays ambiguous.
+                return report('answer', '(no success and no error in the answer)', {
+                    status: 'ambiguous',
+                    providerCode: devvitNotificationProviderCodes.enqueueUnanswered,
+                });
+            }
+            const message = typeof ours?.message === 'string' ? ours.message : '';
+            let fallback = 'ambiguous';
+            if (readsAsRateLimit(message)) {
+                fallback = 'rate-limited';
+            }
+            else if (ours?.userId === userId && readsAsUserRefusal(message)) {
+                // Only an error that names this recipient proves a refusal of the user.
+                fallback = 'recipient';
+            }
+            return failure('answer', message, fallback);
+        },
+        async readPermission({ player }) {
+            const userId = userIdOf(player);
+            if (userId === undefined || !devvitUserIdPattern.test(userId)) {
+                return 'unknown';
+            }
+            return (await input.notifications.isOptedIn(userId)) ? 'granted' : 'prompt';
+        },
+    };
+}
+/**
+ * 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 function createDevvitNotificationProviderEntry() {
+    const entry = structuredClone(referenceNotificationProviders.devvit);
+    return {
+        ...entry,
+        limits: [{ count: devvitNotificationsPerUserPerDay, windowSeconds: 86_400 }],
+        rate: { count: devvitNotificationsPerAppPerDay, windowSeconds: 86_400 },
+        mapping: {
+            ...entry.mapping,
+            title: { required: true, maxLength: devvitNotificationTitleMaxLength },
+            body: { required: true, maxLength: devvitNotificationBodyMaxLength },
+        },
+    };
+}
+/**
+ * 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 function createDevvitNotificationService(input) {
+    const { redis, notifications, catalog: catalogFile, deployment, store: givenStore, storeOptions, classifyEnqueueError, ...options } = input;
+    if (givenStore !== undefined && (redis !== undefined || storeOptions !== undefined)) {
+        throw new TypeError('Pass either a notification store or Redis with its store options, not both.');
+    }
+    let store;
+    if (givenStore !== undefined) {
+        store = givenStore;
+    }
+    else if (redis === undefined) {
+        throw new TypeError('The Devvit notifications service needs Redis or a notification store.');
+    }
+    else {
+        // A scheduled purge runs in a time-bounded Devvit task: bound each call.
+        store = createDevvitRedisNotificationStore(redis, {
+            ...storeOptions,
+            purgeLimit: storeOptions?.purgeLimit ?? devvitNotificationPurgeBatch,
+        });
+    }
+    const registry = createNotificationProviderRegistry([
+        {
+            entry: createDevvitNotificationProviderEntry(),
+            delivery: createDevvitNotificationDeliveryProvider({
+                notifications,
+                ...(classifyEnqueueError === undefined ? {} : { classifyEnqueueError }),
+                onEnqueueError: (report) => {
+                    // Routine answers (a rate limit, a user's refusal) are not errors.
+                    if (report.answer !== 'ambiguous' && report.reason !== 'configuration') {
+                        return;
+                    }
+                    options.onError?.(new Error(`Devvit enqueue failed (${report.source}): ${report.message}`), {
+                        operation: 'devvit.enqueue',
+                        sendKey: report.sendKey,
+                        provider: devvitNotificationProviderId,
+                    });
+                },
+            }),
+            targets: [devvitNotificationTarget],
+        },
+    ]);
+    const catalog = createNotificationServiceCatalog(catalogFile, {
+        registry,
+        ...(deployment === undefined ? {} : { deployment }),
+    });
+    const service = createNotificationService({
+        ...options,
+        store,
+        registry,
+        catalog,
+        ...(deployment === undefined ? {} : { deployment }),
+        resolvePlatformRecipient: ({ provider, player }) => provider === devvitNotificationProviderId && devvitUserIdPattern.test(player)
+            ? player
+            : undefined,
+    });
+    return { service, store, registry, catalog };
+}
+/**
+ * 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 function devvitNotificationSession(userId) {
+    if (!devvitUserIdPattern.test(userId)) {
+        throw new TypeError('A Devvit notifications session needs a t2_ Reddit user id.');
+    }
+    return { player: userId, sessionId: `devvit:${userId}`, installationId: `devvit:${userId}` };
+}
+/**
+ * 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 const devvitNotificationSchedulerTasks = Object.freeze({
+    dispatch: Object.freeze({
+        name: 'mpgd-notifications-dispatch',
+        endpoint: '/internal/scheduler/mpgd-notifications-dispatch',
+        cron: '* * * * *',
+    }),
+    purge: Object.freeze({
+        name: 'mpgd-notifications-purge',
+        endpoint: '/internal/scheduler/mpgd-notifications-purge',
+        cron: '*/5 * * * *',
+    }),
+});
+/**
+ * Due schedule entries, and due sends, one scheduler round of a dispatch
+ * task takes at most (`runScheduler`'s `limit`).
+ */
+export 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 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 const devvitNotificationDispatchBudgetMs = 20_000;
+/** The task an internal scheduler endpoint names, or `undefined` for any other path. */
+export function devvitNotificationTaskForEndpoint(pathname) {
+    for (const [task, declared] of Object.entries(devvitNotificationSchedulerTasks)) {
+        if (declared.endpoint === pathname) {
+            return task;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 async function runDevvitNotificationTask(service, task, options = {}) {
+    if (task === 'dispatch') {
+        const limit = options.dispatchLimit ?? devvitNotificationDispatchBatch;
+        const budgetMs = options.budgetMs ?? devvitNotificationDispatchBudgetMs;
+        if (!Number.isSafeInteger(limit) || limit < 1) {
+            throw new RangeError('dispatchLimit must be a positive integer');
+        }
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0) {
+            throw new RangeError('budgetMs must be a positive number of milliseconds');
+        }
+        const run = await service.runScheduler({ limit, budgetMs });
+        return { task, touched: run.results.length, failed: run.failed };
+    }
+    const counts = await service.purge();
+    return { task, ...counts };
+}

package/dist/server/redis-notification-store.d.ts

@@ -0,0 +1,130 @@
+import { type NotificationStore } from '@mpgd/game-services/notifications';
+/**
+* A `NotificationStore` over Devvit Redis (notifications v2 RFC, "Delivery
+* providers", Devvit: "The same delivery module and policy gate run there
+* with a Redis-backed ledger"). The notifications service of
+* `@mpgd/game-services/notifications` keeps every rule; this store keeps the
+* rows and answers each atomic step with one WATCH/MULTI/EXEC transaction.
+*
+* - **Sends** (the claim/lease ledger) are one JSON value per key with a
+*   version token. `updateSend` writes only while the stored version is the
+*   one the caller read, inside a transaction that watches the key, so a
+*   holder whose lease another worker took over cannot write its answer
+*   back. The due, in-flight, and retention indexes are sorted sets written
+*   in the same transaction as the value, so they never disagree with it.
+* - **Consent records** are a sorted set per player scored by the record's
+*   millisecond; an append watches it, so parallel appends each take their
+*   own millisecond. `pruneConsent` deletes records and the notices given
+*   about them in one transaction over the player's two keys.
+* - **Device endpoints** are one JSON value per provider and installation,
+*   with an address pointer per provider and address (the uniqueness check)
+*   and sorted-set indexes per player, session, and installation, all
+*   written in the endpoint's own transaction. A call reads and watches only
+*   the keys of the endpoints it touches, so reads and contention scale with
+*   one player's endpoints. `purge` reads, per cutoff, only the endpoints
+*   past it from a time index. The address pointer's key holds a hash of
+*   the address, so a device token never appears in a key name. Updates
+*   to several endpoints (a session's) commit one endpoint at a time. A
+*   Devvit server serves only platform-user
+*   providers, so it stores none in practice.
+* - **History** is a hash per player (one field per send and provider, so a
+*   repeat is ignored) with sorted sets by time: per player, for all
+*   players (purge), and per provider. `countHistory` counts the provider's
+*   set by rank (`@devvit/redis` has no ZCOUNT): a few reads, not a
+*   snapshot, which the scheduler's approximate pacing allows.
+* - **Schedule entries** (server reminders, and notice checks for a
+*   provider that carries notices) are one JSON
+*   value per player and id with a version token, written as sends are.
+*   The due index is one sorted set by `dueAt` whose member encodes the
+*   player and id with fixed-width code points, so Redis's byte order of
+*   equal scores is code-point order by player, then id. A sorted set per
+*   player holds the ids of pending reminders, so `countPendingReminders`
+*   is one ZCARD.
+* - **Times.** A time the service passes to a schedule step, a due or
+*   history listing, a history write or count, a pruning, or a purge is
+*   refused with a `TypeError` when it does not parse, before anything is
+*   read or written, as in the in-memory store. Other writes take the
+*   service's times as given.
+* - **Order.** Lists come sorted (by time, then by key or installation),
+*   not in insertion order as in the in-memory store; the interface promises
+*   only "oldest first" and "earliest first", and the service sorts where
+*   it needs more.
+* - **Purge** deletes every row past its cutoff, as the interface says; a
+*   deployment that bounds each call sets `purgeLimit`, and the next
+*   scheduled purge continues.
+*
+* The Devvit Redis client (`@devvit/redis` `TxClient.exec()`) resolves an
+* aborted transaction as an empty array, never `null`, so a result shorter
+* than the commands queued would be a conflict in
+* `createDevvitRedisPostOperationStore`. Here every transaction ends with a
+* commit marker whose reply always maps, so only an empty or all-nil result
+* is an abort, and a committed write is never retried as if it were lost.
+* Devvit allows 20 concurrent transactions per installation by default.
+*
+* Devvit Redis: <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/server/redis>
+* (transactions: WATCH, MULTI, EXEC, DISCARD, UNWATCH).
+*/
+/** The member and score of a sorted-set entry, as `@devvit/redis` reads and writes them. */
+export interface DevvitNotificationRedisMember {
+  readonly member: string;
+  readonly score: number;
+}
+/** The commands this store queues inside a transaction (`@devvit/redis` `TxClientLike`). */
+export interface DevvitNotificationRedisTransaction {
+  multi(): Promise<unknown>;
+  exec(): Promise<readonly unknown[] | null>;
+  discard(): Promise<unknown>;
+  unwatch(): Promise<unknown>;
+  set(key: string, value: string): Promise<unknown>;
+  del(...keys: string[]): Promise<unknown>;
+  hSet(key: string, fieldValues: Record<string, string>): Promise<unknown>;
+  hDel(key: string, fields: string[]): Promise<unknown>;
+  zAdd(key: string, ...members: DevvitNotificationRedisMember[]): Promise<unknown>;
+  zRem(key: string, members: string[]): Promise<unknown>;
+}
+/** The subset of the Devvit server Redis client (`redis` from `@devvit/web/server`) this store reads. */
+export interface DevvitNotificationRedis {
+  get(key: string): Promise<string | undefined>;
+  mGet(keys: string[]): Promise<(string | null)[]>;
+  hGet(key: string, field: string): Promise<string | undefined>;
+  hGetAll(key: string): Promise<Record<string, string>>;
+  hMGet(key: string, fields: string[]): Promise<(string | null)[]>;
+  hSet(key: string, fieldValues: Record<string, string>): Promise<unknown>;
+  zRange(key: string, start: number | string, stop: number | string, options?: {
+    readonly by: 'score' | 'lex' | 'rank';
+    readonly limit?: {
+      readonly offset: number;
+      readonly count: number;
+    };
+  }): Promise<{
+    member: string;
+    score: number;
+  }[]>;
+  zRank(key: string, member: string): Promise<number | undefined>;
+  zCard(key: string): Promise<number>;
+  watch(...keys: string[]): Promise<DevvitNotificationRedisTransaction>;
+}
+export interface CreateDevvitRedisNotificationStoreOptions {
+  /** Prefix of every key; generated games pass their game name. Default `mpgd:notifications`. */
+  readonly namespace?: string;
+  /** Attempts of one atomic step before it fails as contended; 16 by default, at most 64. */
+  readonly transactionAttempts?: number;
+  /** A fresh send version token; random by default. */
+  readonly newVersion?: () => string;
+  /**
+  * Waits before an aborted step is planned again, `attempt` from 1; a
+  * short jittered backoff by default, so contending writers spread out
+  * instead of retrying in lockstep.
+  */
+  readonly backoff?: (attempt: number) => Promise<void>;
+  /**
+  * Sends, history rows, and endpoints (per cutoff) one `purge` call deletes at most, each; unbounded
+  * by default, as `NotificationStore.purge` deletes every row past its
+  * cutoff. Each row costs a few Redis round trips, so a deployment whose
+  * purge runs in a time-bounded Devvit request or scheduler job sets it
+  * (say 500) and runs the purge again while a count equals it.
+  */
+  readonly purgeLimit?: number | undefined;
+}
+export declare const defaultDevvitNotificationNamespace = "mpgd:notifications";
+export declare function createDevvitRedisNotificationStore(redis: DevvitNotificationRedis, options?: CreateDevvitRedisNotificationStoreOptions): NotificationStore;