@mpgd/adapter-devvit 0.13.2 → 0.13.4

package/README.md

@@ -58,7 +58,14 @@ Reddit approves. The profile follows the
   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)`.
+  per app per day. Players' own calls take
+  `devvitNotificationSessionFromContext(context)` so the player is the
+  request's `context.userId`. `devvitNotificationSession(userId)` remains
+  for a caller that already holds that id.
+
+<!--
+@link ./src/server/notifications-delivery.ts#devvitNotificationSessionFromContext Builds the session from the request context user id.
+-->
   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

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

@@ -20,6 +20,12 @@ export declare const devvitCommerceV2MethodUnsupportedBridgeErrorCode: 'COMMERCE
 export declare const devvitCommerceCheckoutClientOnlyBridgeErrorCode: 'DEVVIT_COMMERCE_CHECKOUT_CLIENT_ONLY';
 /** Bridge error when the payments plugin fails; retryable. */
 export declare const devvitPaymentsUnavailableBridgeErrorCode: 'DEVVIT_PAYMENTS_UNAVAILABLE';
+/**
+* Bridge error when the paid-order scan hit its page cap with pages left.
+* Retryable. A caller must not treat orders absent from this scan as delivered:
+* the list was not finished.
+*/
+export declare const devvitOrderScanIncompleteBridgeErrorCode: 'DEVVIT_ORDER_SCAN_INCOMPLETE';
 /** `Order.status` as `@devvit/protos` encodes it (`OrderStatus` enum) or as the handler types spell it. */
 export type DevvitPaymentsOrderStatusLike = number | string;
 /** The fields of a `@devvit/payments` `Order` the handler reads. */
@@ -81,6 +87,17 @@ export interface DevvitCommerceV2BridgeHandler {
   request(input: BridgeRequest): Promise<BridgeResponse>;
 }
 /**
+* Hard cap on the pages scanned per listing. `@devvit/payments` 0.14 ignores
+* `status` and `buyer` (`GetOrdersRequest` marks both "currently does nothing";
+* an empty filter means every order), and `PaymentsClient` forwards the
+* request unchanged, so every status is scanned. Devvit serves this handler
+* inside a time-bounded HTTP request. Thirty-two serial plugin calls stay
+* inside that budget (the kit treats about 20 seconds as the practical limit
+* for a Devvit task). Hitting the cap with a next page fails the request
+* instead of returning a partial list: unseen orders are not delivered.
+*/
+export declare const maximumDevvitOrderScanPages = 32;
+/**
 * Serves `commerce.v2.*` from the payments plugin:
 *
 * - `getCapabilities` answers the Devvit profile (`createDevvitCommerceCapabilities`).
@@ -92,13 +109,10 @@ export interface DevvitCommerceV2BridgeHandler {
 *   `purchased` (the order id as `transactionId` and `token`,
 *   `devvit.order.v1` evidence whose `status` says which), bounded by
 *   `maximumDevvitAvailableOrders`. Reddit marks an order `DELIVERED` as soon
-*   as the fulfillment handler answered, so the delivered orders are the ones
-*   whose ledger entry exists; the webview provider lists only the `PAID`
-*   ones as available and reports both as events, so a session that lost its
-*   checkout result still finds the order. The scan reads pages of 64
-*   (newest first, as the Devvit docs describe) and stops after two
-*   consecutive pages without a paid or delivered order or after
-*   `maximumOrderPages`, warning when pages are left.
+*   as the fulfillment handler answered. The scan reads pages of 64 until the
+*   cursor ends, or until `maximumDevvitOrderScanPages`. A scan that still has
+*   a next page at that cap fails with `DEVVIT_ORDER_SCAN_INCOMPLETE` rather
+*   than returning a partial list: an order that was not read is not delivered.
 * - `requestPurchase` is refused with `DEVVIT_COMMERCE_CHECKOUT_CLIENT_ONLY`,
 *   `finishTransaction` with `COMMERCE_V2_METHOD_UNSUPPORTED`, and
 *   `restorePurchases` answers `{ restored: false }`: the webview provider

package/dist/server/commerce-bridge.js

@@ -22,6 +22,12 @@ export const devvitCommerceV2MethodUnsupportedBridgeErrorCode = 'COMMERCE_V2_MET
 export const devvitCommerceCheckoutClientOnlyBridgeErrorCode = 'DEVVIT_COMMERCE_CHECKOUT_CLIENT_ONLY';
 /** Bridge error when the payments plugin fails; retryable. */
 export const devvitPaymentsUnavailableBridgeErrorCode = 'DEVVIT_PAYMENTS_UNAVAILABLE';
+/**
+ * Bridge error when the paid-order scan hit its page cap with pages left.
+ * Retryable. A caller must not treat orders absent from this scan as delivered:
+ * the list was not finished.
+ */
+export const devvitOrderScanIncompleteBridgeErrorCode = 'DEVVIT_ORDER_SCAN_INCOMPLETE';
 /** `OrderStatus.ORDER_STATUS_PAID` of `@devvit/protos`, and its handler-type spelling. */
 const paidOrderStatuses = new Set([
     3,
@@ -61,17 +67,16 @@ const durableAccountingTypes = new Set([
 ]);
 const orderPageSize = maximumDevvitAvailableOrders;
 /**
- * Hard cap on the pages scanned per listing. The plugin's `status` filter
- * does nothing in `@devvit/payments` 0.14 (its proto marks it so, and the
- * `PaymentsClient` forwards it unchanged), so every status is scanned. The
- * Devvit docs describe the list as newest first ("Manage Payments", "Check
- * orders"); that is documentation, not a plugin guarantee, so the scan stops
- * early only after two consecutive pages without a paid or delivered order,
- * and warns when it stops with pages left.
+ * Hard cap on the pages scanned per listing. `@devvit/payments` 0.14 ignores
+ * `status` and `buyer` (`GetOrdersRequest` marks both "currently does nothing";
+ * an empty filter means every order), and `PaymentsClient` forwards the
+ * request unchanged, so every status is scanned. Devvit serves this handler
+ * inside a time-bounded HTTP request. Thirty-two serial plugin calls stay
+ * inside that budget (the kit treats about 20 seconds as the practical limit
+ * for a Devvit task). Hitting the cap with a next page fails the request
+ * instead of returning a partial list: unseen orders are not delivered.
  */
-const maximumOrderPages = 8;
-/** Consecutive pages without a paid or delivered order after which the scan stops early. */
-const settledPagesBeforeStop = 2;
+export const maximumDevvitOrderScanPages = 32;
 /**
  * Serves `commerce.v2.*` from the payments plugin:
  *
@@ -84,13 +89,10 @@ const settledPagesBeforeStop = 2;
  *   `purchased` (the order id as `transactionId` and `token`,
  *   `devvit.order.v1` evidence whose `status` says which), bounded by
  *   `maximumDevvitAvailableOrders`. Reddit marks an order `DELIVERED` as soon
- *   as the fulfillment handler answered, so the delivered orders are the ones
- *   whose ledger entry exists; the webview provider lists only the `PAID`
- *   ones as available and reports both as events, so a session that lost its
- *   checkout result still finds the order. The scan reads pages of 64
- *   (newest first, as the Devvit docs describe) and stops after two
- *   consecutive pages without a paid or delivered order or after
- *   `maximumOrderPages`, warning when pages are left.
+ *   as the fulfillment handler answered. The scan reads pages of 64 until the
+ *   cursor ends, or until `maximumDevvitOrderScanPages`. A scan that still has
+ *   a next page at that cap fails with `DEVVIT_ORDER_SCAN_INCOMPLETE` rather
+ *   than returning a partial list: an order that was not read is not delivered.
  * - `requestPurchase` is refused with `DEVVIT_COMMERCE_CHECKOUT_CLIENT_ONLY`,
  *   `finishTransaction` with `COMMERCE_V2_METHOD_UNSUPPORTED`, and
  *   `restorePurchases` answers `{ restored: false }`: the webview provider
@@ -113,19 +115,14 @@ export function createDevvitCommerceV2BridgeHandler(input) {
     const listPaidOrders = async () => {
         const orders = [];
         let cursor;
-        let settledPages = 0;
-        for (let page = 0; page < maximumOrderPages; page += 1) {
+        for (let page = 0; page < maximumDevvitOrderScanPages; page += 1) {
             const response = await input.payments.getOrders({
                 limit: orderPageSize,
                 ...(cursor === undefined ? {} : { cursor }),
             });
             const next = response.pageInfo;
             const hasNextPage = next !== undefined && next.hasNextPage && next.endCursor.length > 0;
-            let listableOnPage = 0;
             for (const [index, order] of response.orders.entries()) {
-                if (paidOrderStatuses.has(order.status) || deliveredOrderStatuses.has(order.status)) {
-                    listableOnPage += 1;
-                }
                 const paid = readListedOrder(order, productsBySku);
                 if (paid !== undefined) {
                     orders.push(paid);
@@ -138,21 +135,15 @@ export function createDevvitCommerceV2BridgeHandler(input) {
                 }
             }
             if (!hasNextPage || next === undefined) {
-                break;
+                return orders;
             }
-            settledPages = listableOnPage === 0 ? settledPages + 1 : 0;
-            if (settledPages >= settledPagesBeforeStop) {
-                // Newest first, as documented: the older pages left hold nothing to list.
-                warn(`Devvit order scan stopped after ${String(settledPagesBeforeStop)} pages without a `
-                    + 'paid or delivered order; older pages were not read.');
-                break;
-            }
-            if (page + 1 === maximumOrderPages) {
-                warn('Devvit order scan reached its page cap; older pages were not read.');
+            if (page + 1 === maximumDevvitOrderScanPages) {
+                // A partial list would look complete. Unseen orders are not delivered.
+                throw incompleteOrderScan();
             }
             cursor = next.endCursor;
         }
-        return orders;
+        throw incompleteOrderScan();
     };
     const serve = async (request) => {
         const { payload } = request;
@@ -343,6 +334,14 @@ function normalizeBridgeProducts(input) {
         return { productId: product.productId, sku: product.sku };
     });
 }
+function incompleteOrderScan() {
+    return new PlatformOperationError({
+        code: devvitOrderScanIncompleteBridgeErrorCode,
+        message: `Devvit order scan is incomplete: it reached ${String(maximumDevvitOrderScanPages)} `
+            + 'pages with pages left. Unseen orders were not read and are not delivered.',
+        retryable: true,
+    });
+}
 async function paymentsCall(call) {
     try {
         return await call();

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

@@ -68,7 +68,10 @@ export declare const devvitNotificationHostCodes: Readonly<{
 *   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
+*   (`success: false`) is re-read with `isOptedIn`. If that read is
+*   `granted`, a concurrent request already opted the user in and the
+*   observed state is returned (`already-granted`), not a permanent
+*   configuration error. If the user is still out, it 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
@@ -76,8 +79,10 @@ export declare const devvitNotificationHostCodes: Readonly<{
 * - **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.
+*   opt-out when none is mapped). A refused opt-out is re-read the same
+*   way: still opted in throws `DEVVIT_OPT_OUT_REFUSED`; already out returns
+*   the observed `prompt` state. A successful opt-out answers the state it
+*   produced (`prompt`), not a second read that could be stale.
 * - **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' }`;

package/dist/server/notifications-bridge.js

@@ -17,7 +17,10 @@ export const devvitNotificationHostCodes = Object.freeze({
  *   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
+ *   (`success: false`) is re-read with `isOptedIn`. If that read is
+ *   `granted`, a concurrent request already opted the user in and the
+ *   observed state is returned (`already-granted`), not a permanent
+ *   configuration error. If the user is still out, it 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
@@ -25,8 +28,10 @@ export const devvitNotificationHostCodes = Object.freeze({
  * - **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.
+ *   opt-out when none is mapped). A refused opt-out is re-read the same
+ *   way: still opted in throws `DEVVIT_OPT_OUT_REFUSED`; already out returns
+ *   the observed `prompt` state. A successful opt-out answers the state it
+ *   produced (`prompt`), not a second read that could be stale.
  * - **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' }`;
@@ -103,9 +108,17 @@ export function createDevvitServerNotificationProvider(input) {
                 const response = await plugin(() => input.notifications.optInCurrentUser(), 'optInCurrentUser');
                 const failure = refused(response, devvitNotificationHostCodes.optInRefused, 'the opt-in');
                 if (failure !== undefined) {
-                    throw failure;
+                    // Both of two concurrent requests can see not-granted and call
+                    // opt-in. The duplicate answers success:false. That is a permanent
+                    // configuration error only when a re-read still shows the user out.
+                    if ((await read(userId)) !== 'granted') {
+                        throw failure;
+                    }
+                    outcome = 'already-granted';
+                }
+                else {
+                    outcome = 'granted';
                 }
-                outcome = 'granted';
             }
             return { snapshot: snapshotOf(topics, 'granted'), outcomes: outcomesWith(topics, outcome) };
         },
@@ -123,7 +136,9 @@ export function createDevvitServerNotificationProvider(input) {
             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) {
+                if (failure !== undefined && (await read(userId)) === 'granted') {
+                    // Still opted in: the refusal stands. Already out: a concurrent
+                    // opt-out won, and the observed state is the one returned below.
                     throw failure;
                 }
             }

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

@@ -102,22 +102,28 @@ export declare const devvitNotificationProviderCodes: Readonly<{
 *   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.
+*   because the same send would fail again. An `enqueue` error that reads
+*   as a length or content refusal (a size or text word, and refusal
+*   evidence such as too long, exceeds, invalid, not allowed, or not found)
+*   is `rejected` with reason `configuration` once, not replayed. A field
+*   name alone stays ambiguous.
 * - **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.
+*   at most a day), one that reads as a length or content refusal is
+*   `rejected` with reason `configuration`, 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
@@ -159,7 +165,9 @@ export interface DevvitNotificationService {
 * (`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
+* Players' own calls take `devvitNotificationSessionFromContext(context)`
+* (the request's `context.userId`). `devvitNotificationSession(userId)` remains
+* for a caller that already holds that id. 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
@@ -171,8 +179,23 @@ export declare function createDevvitNotificationService(input: CreateDevvitNotif
 * 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.
+*
+* @deprecated Prefer `devvitNotificationSessionFromContext`. A caller-supplied
+* id can name a different player than the request.
 */
 export declare function devvitNotificationSession(userId: string): NotificationSession;
+/** The Devvit request context fields this session reads (`context` from `@devvit/web/server`). */
+export interface DevvitNotificationSessionContext {
+  /** The logged-in Reddit user of the current request (`context.userId`). */
+  readonly userId?: string | undefined;
+}
+/**
+* The notifications session of the current Devvit request. The player is
+* `context.userId`, not a string the caller supplies, so a handler cannot
+* record consent or set a reminder for a different user by passing one.
+* A missing or non-`t2_` id throws: a logged-out request has no session.
+*/
+export declare function devvitNotificationSessionFromContext(context: DevvitNotificationSessionContext): NotificationSession;
 /**
 * The Devvit scheduler tasks that keep the service's own work moving:
 * `dispatch` runs the service's scheduler (`runScheduler`) every minute,

package/dist/server/notifications-delivery.js

@@ -26,10 +26,13 @@ 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)) {
+    // A size or text word plus refusal evidence marks a length or content
+    // refusal, whatever period it names. Such a refusal is configuration: the
+    // same send fails again, so it must not be replayed as ambiguous. A field
+    // name alone ("payload service temporarily unavailable") is not evidence.
+    // "Message" may count sends ("daily message limit"), so it marks a rate
+    // limit only when the message names no period and no size or text refusal.
+    if (readsAsSizeOrTextRefusal(message)) {
         return false;
     }
     if (!dailyLimitWords.test(message) && /\bmessages?\b/iu.test(message)) {
@@ -47,6 +50,16 @@ function readsAsRateLimit(message) {
 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');
+/** Title, character, length, link, and the other size or text words a refusal names. */
+const sizeOrTextWords = /\b(?:characters?|length|long|size|bytes?|title|body|link|text|content|payload|template)\b/iu;
+/**
+ * Words that prove a deterministic refusal. A field name alone is not one:
+ * "payload service temporarily unavailable" stays ambiguous and is replayed.
+ */
+const refusalEvidence = /\b(?:too long|exceed(?:s|ed|ing)?|invalid|not allowed|not found|does not exist)\b/iu;
+function readsAsSizeOrTextRefusal(message) {
+    return sizeOrTextWords.test(message) && refusalEvidence.test(message);
+}
 /**
  * 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
@@ -86,22 +99,28 @@ function reasonOf(answer) {
  *   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.
+ *   because the same send would fail again. An `enqueue` error that reads
+ *   as a length or content refusal (a size or text word, and refusal
+ *   evidence such as too long, exceeds, invalid, not allowed, or not found)
+ *   is `rejected` with reason `configuration` once, not replayed. A field
+ *   name alone stays ambiguous.
  * - **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.
+ *   at most a day), one that reads as a length or content refusal is
+ *   `rejected` with reason `configuration`, 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
@@ -226,6 +245,9 @@ export function createDevvitNotificationDeliveryProvider(input) {
             if (readsAsRateLimit(message)) {
                 fallback = 'rate-limited';
             }
+            else if (readsAsSizeOrTextRefusal(message)) {
+                fallback = 'configuration';
+            }
             else if (ours?.userId === userId && readsAsUserRefusal(message)) {
                 // Only an error that names this recipient proves a refusal of the user.
                 fallback = 'recipient';
@@ -269,7 +291,9 @@ export function createDevvitNotificationProviderEntry() {
  * (`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
+ * Players' own calls take `devvitNotificationSessionFromContext(context)`
+ * (the request's `context.userId`). `devvitNotificationSession(userId)` remains
+ * for a caller that already holds that id. 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
@@ -336,6 +360,9 @@ export function createDevvitNotificationService(input) {
  * 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.
+ *
+ * @deprecated Prefer `devvitNotificationSessionFromContext`. A caller-supplied
+ * id can name a different player than the request.
  */
 export function devvitNotificationSession(userId) {
     if (!devvitUserIdPattern.test(userId)) {
@@ -343,6 +370,18 @@ export function devvitNotificationSession(userId) {
     }
     return { player: userId, sessionId: `devvit:${userId}`, installationId: `devvit:${userId}` };
 }
+/**
+ * The notifications session of the current Devvit request. The player is
+ * `context.userId`, not a string the caller supplies, so a handler cannot
+ * record consent or set a reminder for a different user by passing one.
+ * A missing or non-`t2_` id throws: a logged-out request has no session.
+ */
+export function devvitNotificationSessionFromContext(context) {
+    if (typeof context.userId !== 'string') {
+        throw new TypeError('A Devvit notifications session needs the request context user id.');
+    }
+    return devvitNotificationSession(context.userId);
+}
 /**
  * The Devvit scheduler tasks that keep the service's own work moving:
  * `dispatch` runs the service's scheduler (`runScheduler`) every minute,

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

@@ -29,7 +29,11 @@ import { type NotificationStore } from '@mpgd/game-services/notifications';
 *   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
+*   players (purge), and per provider. `listHistory` reads the hash with
+*   `hGetAll`, not `hMGet`: Devvit documents `hMGet` as an allowlisted
+*   command that may be disabled per app, and the gate calls `listHistory`
+*   before any write, so a disabled `hMGet` would fail every send.
+*   `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
@@ -59,7 +63,14 @@ import { type NotificationStore } from '@mpgd/game-services/notifications';
 * `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 allows 20 concurrent transactions per installation by default, and
+* a transaction still open after 5 seconds is aborted. A throw from WATCH
+* or the planning read that is transient, and an EXEC throw that proves the
+* transaction aborted before commit (that cap, that timeout), are retried
+* inside the same attempt budget with the step's backoff. A connection loss
+* thrown by EXEC is not: the reply may have been lost after commit, and
+* re-planning would report the landed write as contention. A non-transient
+* failure throws on the attempt that saw it.
 *
 * Devvit Redis: <https://developers.reddit.com/docs/versioned_docs/version-0.14/capabilities/server/redis>
 * (transactions: WATCH, MULTI, EXEC, DISCARD, UNWATCH).
@@ -88,7 +99,6 @@ export interface DevvitNotificationRedis {
   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';

package/dist/server/redis-notification-store.js

@@ -41,6 +41,10 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
         due: `${namespace}:sends:due`,
         changed: `${namespace}:sends:changed`,
         inFlight: (player) => `${namespace}:sends:in-flight:${enc(player)}`,
+        // The in-flight member is the send key, which does not name the player.
+        // This pointer is written in the same transaction, so purge can drop the
+        // member when the send value no longer parses.
+        inFlightOwner: (key) => `${namespace}:sends:in-flight-owner:${enc(key)}`,
         history: (player) => `${namespace}:history:${enc(player)}`,
         historyAt: (player) => `${namespace}:history-at:${enc(player)}`,
         historyAll: `${namespace}:history-all`,
@@ -76,11 +80,13 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
             if (attempt > 0) {
                 await backoff(attempt);
             }
-            const { watched, plan } = await prepare();
-            lastWatched = watched;
-            const transaction = await redis.watch(...watched);
+            let transaction;
             let multiStarted = false;
+            let execStarted = false;
             try {
+                const { watched, plan } = await prepare();
+                lastWatched = watched;
+                transaction = await redis.watch(...watched);
                 const planned = await plan();
                 if ('retry' in planned) {
                     await transaction.unwatch();
@@ -97,6 +103,7 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
                     await command(transaction);
                 }
                 await transaction.set(keys.commitMarker, commitMarkerValue);
+                execStarted = true;
                 const results = await transaction.exec();
                 if (results !== null && !Array.isArray(results)) {
                     throw new Error('Devvit Redis transaction returned an unsupported response.');
@@ -110,8 +117,22 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
                 return result;
             }
             catch (error) {
-                await bestEffortReset(transaction, multiStarted);
-                throw error;
+                if (transaction !== undefined) {
+                    await bestEffortReset(transaction, multiStarted);
+                }
+                // A nil EXEC retries above. A throw before EXEC (WATCH, the planning
+                // read, MULTI, or a queued command) retries when it is transient:
+                // EXEC did not run. A throw from EXEC retries only when it proves
+                // the transaction aborted before commit (the 20-transaction cap, the
+                // 5-second timeout). A connection loss on EXEC is not retried: the
+                // reply may have been lost after commit, and re-planning would
+                // report the landed write as contention.
+                const retryable = execStarted
+                    ? provesExecAbortedBeforeCommit(error)
+                    : isTransientDevvitRedisError(error);
+                if (!retryable || attempt + 1 >= attempts) {
+                    throw error;
+                }
             }
         }
         throw new Error(`Devvit Redis notification store: contention exceeded ${String(attempts)} attempts on ${String(lastWatched.length)} watched key(s).`);
@@ -278,12 +299,31 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
         const flying = (send) => send !== undefined && send.rows.some((row) => row.state.status === 'in-flight');
         if (before !== undefined && flying(before) && !flying(after)) {
             commands.push((transaction) => transaction.zRem(keys.inFlight(before.request.player), [key]));
+            commands.push((transaction) => transaction.del(keys.inFlightOwner(key)));
         }
         if (after !== undefined && flying(after)) {
             commands.push((transaction) => transaction.zAdd(keys.inFlight(after.request.player), { member: key, score: 0 }));
+            commands.push((transaction) => transaction.set(keys.inFlightOwner(key), after.request.player));
         }
         return commands;
     }
+    /**
+     * Commands that drop an in-flight index member whose send value no longer
+     * names the player. The owner pointer is written with the member. A row
+     * written before that pointer existed cannot be removed from a player
+     * index the value no longer tells; `listInFlightSends` skips the missing
+     * value.
+     */
+    async function inFlightCleanup(key) {
+        const owner = await redis.get(keys.inFlightOwner(key));
+        if (isMissing(owner) || owner.length === 0) {
+            return [];
+        }
+        return [
+            (transaction) => transaction.zRem(keys.inFlight(owner), [key]),
+            (transaction) => transaction.del(keys.inFlightOwner(key)),
+        ];
+    }
     /** A stored send value, or `'unreadable'` for one that is not a send. */
     function readSendValue(raw) {
         const value = tryParse(raw);
@@ -727,10 +767,12 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
                 return [];
             }
             const key = keys.history(player);
-            const values = await redis.hMGet(key, fields);
-            return values
-                .filter((value) => typeof value === 'string')
-                .map((value) => parse(value, key))
+            const stored = await redis.hGetAll(key);
+            return fields
+                .flatMap((field) => {
+                const value = stored[field];
+                return typeof value === 'string' ? [parse(value, key)] : [];
+            })
                 .sort((left, right) => Date.parse(left.at) - Date.parse(right.at));
         },
         async countHistory({ provider, since, until }) {
@@ -816,13 +858,14 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
                     const raw = await redis.get(valueKey);
                     const stored = isMissing(raw) ? undefined : readSendValue(raw);
                     if (stored === 'unreadable') {
-                        // Its in-flight index entry, if any, names a player the value no
-                        // longer tells; listInFlightSends skips the missing value.
+                        // The value no longer names the player. The owner pointer, written
+                        // with the in-flight member, is what makes that member cleanable.
                         return {
                             commands: [
                                 (transaction) => transaction.del(valueKey),
                                 (transaction) => transaction.zRem(keys.changed, [key]),
                                 (transaction) => transaction.zRem(keys.due, [key]),
+                                ...(await inFlightCleanup(key)),
                             ],
                             result: true,
                         };
@@ -833,6 +876,7 @@ export function createDevvitRedisNotificationStore(redis, options = {}) {
                             commands: [
                                 (transaction) => transaction.zRem(keys.changed, [key]),
                                 (transaction) => transaction.zRem(keys.due, [key]),
+                                ...(await inFlightCleanup(key)),
                             ],
                             result: false,
                         };
@@ -1018,6 +1062,59 @@ function defaultBackoff(attempt) {
         setTimeout(resolve, delayMs);
     });
 }
+/**
+ * Whether a Redis client throw is worth another attempt when EXEC has not
+ * run: the installation's 20-transaction cap, a transaction aborted after 5
+ * seconds, or another transient failure. A wrong type, a disabled command,
+ * or a value this store cannot parse is not transient.
+ */
+function isTransientDevvitRedisError(error) {
+    const kind = redisThrowKind(error);
+    return kind === 'aborted-before-commit' || kind === 'connection-loss';
+}
+/**
+ * Whether an EXEC throw proves the transaction aborted before commit. A
+ * connection loss does not: the server may have committed and dropped the
+ * reply, so the caller must see the error instead of a retried plan.
+ */
+function provesExecAbortedBeforeCommit(error) {
+    return redisThrowKind(error) === 'aborted-before-commit';
+}
+const permanentRedisError = /not allowed|allow-?list|unknown command|WRONGTYPE|unsupported response|is not JSON|NOAUTH/iu;
+const connectionLoss = /\b(?:econnreset|econnrefused|socket hang up|temporarily unavailable|resource[_ ]exhausted|try again later)\b/iu;
+const transactionAbort = /\b(?:timed?\s*out|timeout|deadline exceeded)\b/iu;
+function redisThrowKind(error) {
+    if (error instanceof TypeError || error instanceof RangeError || error instanceof SyntaxError) {
+        return 'permanent';
+    }
+    const text = redisErrorText(error);
+    if (text.length === 0 || permanentRedisError.test(text)) {
+        return 'permanent';
+    }
+    // A dropped connection can follow a commit whose reply never arrived, even
+    // when the message also names a timeout. That is not proof of an abort.
+    if (connectionLoss.test(text)) {
+        return 'connection-loss';
+    }
+    if ((/\btransactions?\b/iu.test(text)
+        && /\b(?:limit|cap|exceed\w*|too many|concurrent|timeout|timed out|deadline)\b/iu.test(text))
+        || transactionAbort.test(text)) {
+        return 'aborted-before-commit';
+    }
+    return 'other';
+}
+function redisErrorText(error) {
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (typeof error !== 'object' || error === null) {
+        return '';
+    }
+    const record = error;
+    return [record.message, record.code, record.msg]
+        .filter((part) => typeof part === 'string')
+        .join(' ');
+}
 /** A missing key, field, or member: `@devvit/redis` answers `undefined`, a classic client `null`. */
 function isMissing(value) {
     return value === undefined || value === null;

package/dist/server/redis-verified-leaderboard.js

@@ -4,6 +4,8 @@ const defaultSnapshotLimit = 10;
 const defaultTransactionAttempts = 3;
 const maximumTransactionAttempts = 32;
 const keyPrefixPattern = /^[A-Za-z0-9:_-]{1,128}$/;
+/** The commit marker's value; its SET replies `OK`, which `@devvit/redis` always maps. */
+const commitMarkerValue = '1';
 /**
  * Durable Devvit Redis provider for modest verified leaderboards. Writes are
  * fenced with WATCH/MULTI/EXEC and keep the original idempotency response.
@@ -66,13 +68,22 @@ export function createDevvitRedisVerifiedLeaderboardService(redis, options = {})
                     await transaction.hSet(keys.attempts, {
                         [attemptMember]: serializeAttemptDecision(request.attempt, response),
                     });
+                    // `@devvit/redis` `TxClient.exec()` resolves an aborted WATCH as `[]`
+                    // and drops zero or nil replies. The marker's `OK` always maps, so a
+                    // committed EXEC answers at least that reply even when the array is
+                    // shorter than the queued commands. Only an empty, `null`, or all-nil
+                    // result is an abort. Requiring `results.length === queued` would
+                    // retry a landed score whose zero replies Devvit dropped.
+                    await transaction.set(keys.commitMarker, commitMarkerValue);
                     const results = await transaction.exec();
-                    if (results === null || (Array.isArray(results) && results.length === 0)) {
-                        continue;
-                    }
-                    if (!Array.isArray(results)) {
+                    if (results !== null && !Array.isArray(results)) {
                         throw new Error('Devvit Redis transaction returned an unsupported response.');
                     }
+                    if (results === null
+                        || results.length === 0
+                        || results.every((reply) => reply === null || reply === undefined)) {
+                        continue;
+                    }
                     return response;
                 }
                 catch (error) {
@@ -136,6 +147,7 @@ async function createBoardKeys(keyPrefix, leaderboardId) {
         attempts: `${base}:attempts`,
         entries: `${base}:entries`,
         ranking: `${base}:ranking`,
+        commitMarker: `${keyPrefix}:commit`,
     };
     return {
         ...keys,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-devvit",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "description": "Reddit Devvit Web platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -55,9 +55,9 @@
   ],
   "dependencies": {
     "@devvit/web": "0.14.1",
-    "@mpgd/bridge": "0.14.1",
-    "@mpgd/platform": "0.26.0",
-    "@mpgd/game-services": "0.26.0"
+    "@mpgd/bridge": "0.14.3",
+    "@mpgd/platform": "0.27.1",
+    "@mpgd/game-services": "0.27.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",