@mpgd/adapter-devvit 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import { type BridgeRpcClient, type BridgeRpcEndpoint } from '@mpgd/bridge/orpc';
 import type { PlatformGateway } from '@mpgd/platform';
+export * from './payments.js';
 export declare const defaultDevvitRpcEndpoint = "/api/mpgd/rpc";
 type BridgeErrorResponse = Extract<BridgeResponse, {
   readonly ok: false;
@@ -28,4 +29,3 @@ export declare function createDevvitOrpcBridge(input?: {
   readonly client?: BridgeRpcClient | undefined;
 }): DevvitBridge;
 export declare function createDevvitSandboxBridge(): DevvitBridge;
-export {};

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createBridgeError, } from '@mpgd/bridge';
 import { createBridgeOrpcClient, defaultBridgeRpcEndpoint, } from '@mpgd/bridge/orpc';
+export * from './payments.js';
 export const defaultDevvitRpcEndpoint = defaultBridgeRpcEndpoint;
 const devvitFallbackStoragePrefix = 'mpgd:devvit:fallback:';
 export class DevvitBridgeError extends Error {
@@ -233,7 +234,7 @@ export function createDevvitSandboxBridge() {
                         nativeAds: false,
                         rewardedAds: false,
                         interstitialAds: false,
-                        nativeLeaderboard: true,
+                        nativeLeaderboard: false,
                         achievements: false,
                         cloudSave: true,
                         socialShare: false,
@@ -299,7 +300,7 @@ export function createDevvitSandboxBridge() {
                     });
                 case 'leaderboard.submitScore':
                     return ok(input, {
-                        submitted: true,
+                        submitted: false,
                     });
                 case 'storage.load': {
                     const payload = optionalObjectPayload(input.payload);

package/dist/payments.d.ts

@@ -0,0 +1,21 @@
+import type { CommerceAdapter, Entitlement, PlatformEvidenceEnvelope, PlatformGateway, ProductInfo, PurchaseResult } from '@mpgd/platform';
+export interface DevvitCheckoutResult {
+  readonly status: PurchaseResult['status'];
+  readonly orderId?: string;
+  readonly evidence?: PlatformEvidenceEnvelope;
+}
+export interface DevvitPaymentsClient {
+  purchase(sku: string): Promise<DevvitCheckoutResult>;
+  getEntitlements(): Promise<readonly Entitlement[]>;
+}
+export interface DevvitCommerceProduct {
+  readonly info: ProductInfo;
+  readonly sku: string;
+}
+export interface CreateDevvitCommerceAdapterInput {
+  readonly products: readonly DevvitCommerceProduct[];
+  readonly client: DevvitPaymentsClient;
+  readonly onCheckoutError?: (error: unknown) => void;
+}
+export declare function createDevvitCommerceAdapter(input: CreateDevvitCommerceAdapterInput): CommerceAdapter;
+export declare function withDevvitCommerceAdapter(gateway: PlatformGateway, commerce: CommerceAdapter): PlatformGateway;

package/dist/payments.js

@@ -0,0 +1,82 @@
+export function createDevvitCommerceAdapter(input) {
+    const products = normalizeProducts(input.products);
+    const productsById = new Map(products.map((product) => [product.info.id, product]));
+    return {
+        async getProducts() {
+            return products.map((product) => product.info);
+        },
+        async purchase(request) {
+            const product = productsById.get(request.productId);
+            if (product === undefined) {
+                return failedPurchase();
+            }
+            try {
+                // Reddit's platform order ID is authoritative. Do not attach client operation
+                // metadata whose identifiers can exceed Devvit's metadata constraints.
+                const result = await input.client.purchase(product.sku);
+                return {
+                    status: result.status,
+                    ...(result.orderId === undefined ? {} : { transactionId: result.orderId }),
+                    // Devvit server fulfillment and a subsequent entitlement read are authoritative.
+                    entitlementIds: [],
+                    ...(result.evidence === undefined ? {} : { evidence: result.evidence }),
+                };
+            }
+            catch (error) {
+                input.onCheckoutError?.(error);
+                return failedPurchase();
+            }
+        },
+        async restore() {
+            return { restoredEntitlements: await input.client.getEntitlements() };
+        },
+        async getEntitlements() {
+            return input.client.getEntitlements();
+        },
+    };
+}
+export function withDevvitCommerceAdapter(gateway, commerce) {
+    if (gateway.target !== 'reddit') {
+        throw new TypeError('Devvit commerce can only be installed on a reddit gateway.');
+    }
+    if ('getTargetRuntime' in gateway && typeof gateway.getTargetRuntime === 'function') {
+        throw new TypeError('Devvit commerce must be installed before target availability is applied.');
+    }
+    return {
+        ...gateway,
+        async getCapabilities() {
+            return {
+                ...await gateway.getCapabilities(),
+                nativeIap: true,
+            };
+        },
+        commerce,
+    };
+}
+function normalizeProducts(input) {
+    const productIds = new Set();
+    const skus = new Set();
+    return Object.freeze(input.map((product) => {
+        if (productIds.has(product.info.id)) {
+            throw new TypeError(`Duplicate Devvit logical product ID: ${product.info.id}`);
+        }
+        if (skus.has(product.sku)) {
+            throw new TypeError(`Duplicate Devvit product SKU: ${product.sku}`);
+        }
+        if (product.sku.length === 0 || product.sku.trim() !== product.sku) {
+            throw new TypeError('Devvit product SKU must be a non-empty identifier.');
+        }
+        productIds.add(product.info.id);
+        skus.add(product.sku);
+        return Object.freeze({
+            info: Object.freeze({ ...product.info }),
+            sku: product.sku,
+        });
+    }));
+}
+function failedPurchase() {
+    return Object.freeze({
+        status: 'failed',
+        entitlementIds: [],
+    });
+}

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
+export * from './payment-order.js';
 export * from './post-operation.js';
 export * from './redis-post-operation-store.js';
 export * from './redis-verified-leaderboard.js';

package/dist/server/index.js

@@ -1,3 +1,4 @@
+export * from './payment-order.js';
 export * from './post-operation.js';
 export * from './redis-post-operation-store.js';
 export * from './redis-verified-leaderboard.js';

package/dist/server/payment-order.d.ts

@@ -0,0 +1,8 @@
+import { type FulfillPlatformOrderInput, type RefundPlatformOrderInput } from '@mpgd/game-services/platform-order';
+export interface NormalizeDevvitPaymentOrderInput {
+  readonly order: unknown;
+  /** Authenticated player ID supplied by the Devvit server request context. */
+  readonly playerId: string;
+}
+export declare function normalizeDevvitFulfillmentOrder(input: NormalizeDevvitPaymentOrderInput): FulfillPlatformOrderInput;
+export declare function normalizeDevvitRefundOrder(input: NormalizeDevvitPaymentOrderInput): RefundPlatformOrderInput;

package/dist/server/payment-order.js

@@ -0,0 +1,80 @@
+import { assertFulfillPlatformOrderInput, assertRefundPlatformOrderInput, } from '@mpgd/game-services/platform-order';
+const devvitPaymentOrderEvidenceSchema = 'devvit.payment-order.v1';
+export function normalizeDevvitFulfillmentOrder(input) {
+    const order = normalizeDevvitOrder(input, 'PAID');
+    const normalized = Object.freeze({
+        target: 'reddit',
+        orderId: order.orderId,
+        playerId: order.playerId,
+        platformSku: order.platformSku,
+        paidAt: order.occurredAt,
+        evidence: order.evidence,
+    });
+    return assertFulfillPlatformOrderInput(normalized);
+}
+export function normalizeDevvitRefundOrder(input) {
+    const order = normalizeDevvitOrder(input, 'REVERTED');
+    const normalized = Object.freeze({
+        target: 'reddit',
+        orderId: order.orderId,
+        playerId: order.playerId,
+        platformSku: order.platformSku,
+        refundedAt: order.occurredAt,
+        evidence: order.evidence,
+    });
+    return assertRefundPlatformOrderInput(normalized);
+}
+function normalizeDevvitOrder(input, expectedStatus) {
+    const playerId = requireString(input.playerId, 'Devvit payment context playerId');
+    const record = requireRecord(input.order, 'Devvit payment order');
+    if (record.status !== expectedStatus) {
+        throw new TypeError(`Devvit payment order status must be ${expectedStatus}.`);
+    }
+    if (!Array.isArray(record.products) || record.products.length !== 1) {
+        throw new TypeError('Devvit payment order must contain exactly one product.');
+    }
+    const product = requireRecord(record.products[0], 'Devvit payment product');
+    const orderId = requireString(record.id, 'order.id');
+    if (record.userId !== undefined
+        && requireString(record.userId, 'order.userId') !== playerId) {
+        throw new TypeError('Devvit payment order userId must match the authenticated context playerId.');
+    }
+    const platformSku = requireString(product.sku, 'order.products[0].sku');
+    const occurredAt = requireString(record.updatedAt ?? record.createdAt, 'order.updatedAt');
+    const evidencePayload = {
+        orderId,
+        status: expectedStatus,
+        occurredAt,
+        playerIdSource: 'devvit-context',
+    };
+    copyOptionalEvidenceField(record, evidencePayload, 'postId');
+    copyOptionalEvidenceField(record, evidencePayload, 'environment');
+    return Object.freeze({
+        orderId,
+        playerId,
+        platformSku,
+        occurredAt,
+        evidence: Object.freeze({
+            schema: devvitPaymentOrderEvidenceSchema,
+            payload: Object.freeze(evidencePayload),
+        }),
+    });
+}
+function copyOptionalEvidenceField(source, target, key) {
+    const value = source[key];
+    if (value !== undefined) {
+        target[key] = requireString(value, `order.${key}`);
+    }
+}
+function requireString(input, label) {
+    if (typeof input !== 'string') {
+        throw new TypeError(`${label} must be a string.`);
+    }
+    return input;
+}
+function requireRecord(input, label) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+    return input;
+}

package/dist/server/post-operation.d.ts

@@ -1,4 +1,5 @@
 declare const operationSchemaVersion: 1;
+export declare const devvitPostOperationMaximumPendingPageLimit = 100;
 export type DevvitJsonValue = null | boolean | number | string | readonly DevvitJsonValue[] | DevvitJsonObject;
 export interface DevvitJsonObject {
   readonly [key: string]: DevvitJsonValue;
@@ -15,6 +16,24 @@ export interface DevvitDurableOperationStore {
   /** Deletes a lease only when the current token matches. */
   releaseLease(key: string, token: string): Promise<void>;
 }
+export interface DevvitDurableOperationIndexEntry {
+  readonly indexKey: string;
+  readonly member: string;
+}
+/**
+* Optional durable-store capability used to discover pending operations without
+* scanning the Redis keyspace. Implementations must establish stable registry
+* membership before creating durable state and retain it for the record's
+* lifetime. A failed state creation can leave a safe stale member, but a live
+* operation must never be absent from its registry.
+*/
+export interface DevvitIndexedDurableOperationStore extends DevvitDurableOperationStore {
+  /** Idempotently establishes stable registry membership for an existing record. */
+  ensureIndexed(index: DevvitDurableOperationIndexEntry): Promise<void>;
+  createIndexed(key: string, value: string, index: DevvitDurableOperationIndexEntry): Promise<boolean>;
+  compareAndSetIndexed(key: string, expectedValue: string, nextValue: string, index: DevvitDurableOperationIndexEntry): Promise<boolean>;
+  listIndex(key: string, startExclusive: string | undefined, limit: number): Promise<readonly string[]>;
+}
 export interface DevvitPostOperationScope {
   readonly appScope: string;
   /** Use the canonical subreddit identifier, not a display name. */
@@ -106,10 +125,41 @@ export interface ExecuteDevvitPostOperationInput<TPayload extends DevvitJsonObje
 export interface ReconcileDevvitPostOperationInput<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> extends DevvitPostOperationDescriptorInput<TPayload, TLaunchParams> {
   readonly findCandidates: (input: DevvitPostPublishInput<TPayload, TLaunchParams>) => Promise<readonly DevvitPostReconciliationCandidate[]>;
 }
+export interface ListPendingDevvitPostOperationsInput {
+  readonly scope: DevvitPostOperationScope;
+  /** Opaque continuation returned by the previous page for the same scope. */
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+export type DevvitPendingPostOperation<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> = {
+  readonly status: 'prepared';
+  readonly operationId: string;
+  readonly updatedAt: number;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'reconciliation-required';
+  readonly operationId: string;
+  readonly reason: 'submission-attempted';
+  readonly updatedAt: number;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+} | {
+  readonly status: 'terminal-unresolved';
+  readonly operationId: string;
+  readonly reason: 'multiple-exact-matches' | 'published-receipt-conflict';
+  readonly postIds: readonly string[];
+  readonly updatedAt: number;
+  readonly postData: DevvitCanonicalPostData<TPayload, TLaunchParams>;
+};
+export interface DevvitPendingPostOperationPage<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
+  readonly operations: readonly DevvitPendingPostOperation<TPayload, TLaunchParams>[];
+  readonly nextCursor?: string;
+}
 export interface DevvitPostOperationCoordinator<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
   execute(input: ExecuteDevvitPostOperationInput<TPayload, TLaunchParams>): Promise<DevvitPostOperationResult<TPayload, TLaunchParams>>;
   read(input: DevvitPostOperationDescriptorInput<TPayload, TLaunchParams>): Promise<DevvitPostOperationResult<TPayload, TLaunchParams>>;
   reconcile(input: ReconcileDevvitPostOperationInput<TPayload, TLaunchParams>): Promise<DevvitPostOperationResult<TPayload, TLaunchParams>>;
+  /** Lists durable work only; it never invokes a Reddit API or reconciliation callback. */
+  listPending(input: ListPendingDevvitPostOperationsInput): Promise<DevvitPendingPostOperationPage<TPayload, TLaunchParams>>;
 }
 export interface CreateDevvitPostOperationCoordinatorOptions<TPayload extends DevvitJsonObject, TLaunchParams extends DevvitJsonObject> {
   readonly definition: DevvitPostOperationDefinition<TPayload, TLaunchParams>;

package/dist/server/post-operation.js

@@ -3,6 +3,8 @@ const defaultLeaseTtlMs = 30000;
 const defaultMaxPostDataBytes = 2048;
 const defaultStoreAttempts = 8;
 const maximumStoreAttempts = 32;
+const defaultPendingPageLimit = 20;
+export const devvitPostOperationMaximumPendingPageLimit = 100;
 const maximumIdentifierLength = 128;
 const maximumOperationTypeLength = 64;
 const maximumLeaseTtlMs = 60 * 60 * 1000;
@@ -39,6 +41,7 @@ export function createDevvitPostOperationCoordinator(input) {
     const createToken = input.createToken ?? defaultTokenFactory;
     const leaseTtlMs = input.leaseTtlMs ?? defaultLeaseTtlMs;
     const storeAttempts = input.storeAttempts ?? defaultStoreAttempts;
+    const indexedStore = readIndexedStore(input.store);
     assertPositiveSafeInteger(leaseTtlMs, 'leaseTtlMs');
     if (leaseTtlMs > maximumLeaseTtlMs) {
         throw new DevvitPostOperationValidationError(`leaseTtlMs must not exceed ${String(maximumLeaseTtlMs)}.`);
@@ -51,6 +54,7 @@ export function createDevvitPostOperationCoordinator(input) {
         execute,
         read,
         reconcile,
+        listPending,
     };
     async function execute(request) {
         if (typeof request.publish !== 'function') {
@@ -63,7 +67,7 @@ export function createDevvitPostOperationCoordinator(input) {
             operationId: request.operationId,
         });
         for (let attempt = 0; attempt < storeAttempts; attempt += 1) {
-            let current = await readOperation(operationKey, descriptor, definition, input.store);
+            let current = await readStoredOperation(operationKey, descriptor);
             if (current.kind === 'missing') {
                 const timestamp = readTimestamp(now);
                 const prepared = {
@@ -76,7 +80,7 @@ export function createDevvitPostOperationCoordinator(input) {
                     updatedAt: timestamp,
                 };
                 const preparedRaw = serializeRecord(prepared);
-                if (!await input.store.create(operationKey, preparedRaw)) {
+                if (!await createStoredRecord(operationKey, preparedRaw, prepared)) {
                     continue;
                 }
                 current = { kind: 'record', raw: preparedRaw, record: prepared };
@@ -96,7 +100,7 @@ export function createDevvitPostOperationCoordinator(input) {
                         updatedAt: timestamp,
                     };
                     const attemptedRaw = serializeRecord(attempted);
-                    if (!await input.store.compareAndSet(operationKey, current.raw, attemptedRaw)) {
+                    if (!await compareAndSetStoredRecord(operationKey, current.raw, attemptedRaw, current.record, attempted)) {
                         continue;
                     }
                     return submitOnce(attempted, attemptedRaw, request.publish);
@@ -118,7 +122,7 @@ export function createDevvitPostOperationCoordinator(input) {
             operationType: definition.operationType,
             operationId: request.operationId,
         });
-        const current = await readOperation(operationKey, descriptor, definition, input.store);
+        const current = await readStoredOperation(operationKey, descriptor);
         if (current.kind === 'missing') {
             return missingResult(descriptor);
         }
@@ -146,7 +150,7 @@ export function createDevvitPostOperationCoordinator(input) {
             operationType: definition.operationType,
             operationId: request.operationId,
         });
-        const current = await readOperation(operationKey, descriptor, definition, input.store);
+        const current = await readStoredOperation(operationKey, descriptor);
         if (current.kind === 'missing') {
             return missingResult(descriptor);
         }
@@ -214,6 +218,56 @@ export function createDevvitPostOperationCoordinator(input) {
             }
         }
     }
+    async function listPending(request) {
+        if (indexedStore === undefined) {
+            throw new DevvitPostOperationStateError('The durable post operation store does not support operation registries.');
+        }
+        const scope = normalizeScope(request.scope);
+        const limit = normalizePendingPageLimit(request.limit);
+        const indexKey = createDevvitPostOperationIndexKey({
+            scope,
+            operationType: definition.operationType,
+        });
+        const cursor = normalizePendingCursor(request.cursor, scope, definition.operationType);
+        const members = await indexedStore.listIndex(indexKey, cursor, limit + 1);
+        const pageMembers = members.slice(0, limit);
+        const indexedOperations = await Promise.all(pageMembers.map(async (member) => {
+            const indexed = parsePendingIndexMember(member, scope, definition.operationType);
+            const raw = await indexedStore.read(indexed.operationKey);
+            if (raw === undefined) {
+                // Index-first creation can leave a conservative stale member if the
+                // following state write fails. It is safe to skip and advance the cursor.
+                return undefined;
+            }
+            const record = parseStoredRecord(raw, indexed.operationKey, definition);
+            const expectedOperationKey = createDevvitPostOperationKey({
+                scope: record.descriptor.mpgd,
+                operationType: record.descriptor.mpgd.operationType,
+                operationId: record.descriptor.mpgd.operationId,
+            });
+            const recordIndexKey = createDevvitPostOperationIndexKey({
+                scope: record.descriptor.mpgd,
+                operationType: record.descriptor.mpgd.operationType,
+            });
+            if (expectedOperationKey !== indexed.operationKey || recordIndexKey !== indexKey) {
+                throw new DevvitPostOperationStateError(`Pending operation index scope is inconsistent for state: ${indexed.operationKey}`);
+            }
+            const expectedMember = operationIndexMember(record);
+            if (record.phase === 'published') {
+                return undefined;
+            }
+            if (expectedMember !== member) {
+                throw new DevvitPostOperationStateError(`Pending operation index is inconsistent for state: ${indexed.operationKey}`);
+            }
+            return pendingOperationResult(record);
+        }));
+        const operations = indexedOperations.filter((operation) => operation !== undefined);
+        const nextCursor = members.length > limit ? pageMembers.at(-1) : undefined;
+        return Object.freeze({
+            operations: Object.freeze(operations),
+            ...(nextCursor === undefined ? {} : { nextCursor }),
+        });
+    }
     async function submitOnce(record, raw, publish) {
         let receipt;
         try {
@@ -251,10 +305,10 @@ export function createDevvitPostOperationCoordinator(input) {
                 publishedAt: timestamp,
                 recovered,
             };
-            if (await input.store.compareAndSet(source.operationKey, expectedRaw, serializeRecord(published))) {
+            if (await compareAndSetStoredRecord(source.operationKey, expectedRaw, serializeRecord(published), expectedRecord, published)) {
                 return publishedResult(published, successStatus);
             }
-            const reread = await readOperation(source.operationKey, source.descriptor, definition, input.store);
+            const reread = await readStoredOperation(source.operationKey, source.descriptor);
             if (reread.kind === 'missing' || reread.kind === 'conflict') {
                 throw new DevvitPostOperationStateError(`Durable post operation changed incompatibly while recording post ${postId}.`);
             }
@@ -302,10 +356,10 @@ export function createDevvitPostOperationCoordinator(input) {
                 postIds: expectedPostIds,
                 unresolvedAt: timestamp,
             };
-            if (await input.store.compareAndSet(source.operationKey, expectedRaw, serializeRecord(terminal))) {
+            if (await compareAndSetStoredRecord(source.operationKey, expectedRaw, serializeRecord(terminal), expectedRecord, terminal)) {
                 return terminalResult(terminal);
             }
-            const current = await readOperation(source.operationKey, source.descriptor, definition, input.store);
+            const current = await readStoredOperation(source.operationKey, source.descriptor);
             if (current.kind !== 'record') {
                 throw new DevvitPostOperationStateError('Durable post operation changed incompatibly while recording a terminal outcome.');
             }
@@ -324,6 +378,32 @@ export function createDevvitPostOperationCoordinator(input) {
         }
         return busyResult(source.descriptor, 'store-contention');
     }
+    function createStoredRecord(operationKey, raw, record) {
+        if (indexedStore === undefined) {
+            return input.store.create(operationKey, raw);
+        }
+        return indexedStore.createIndexed(operationKey, raw, createOperationIndexEntry(undefined, record));
+    }
+    async function readStoredOperation(operationKey, descriptor) {
+        const current = await readOperation(operationKey, descriptor, definition, input.store);
+        if (indexedStore !== undefined && current.kind !== 'missing') {
+            try {
+                await indexedStore.ensureIndexed(createOperationIndexEntry(undefined, current.record));
+            }
+            catch {
+                // A best-effort migration write must not hide an already-readable exact
+                // result. Indexed creation and every state CAS still require registry
+                // membership before mutating durable state.
+            }
+        }
+        return current;
+    }
+    function compareAndSetStoredRecord(operationKey, expectedRaw, nextRaw, previous, next) {
+        if (indexedStore === undefined) {
+            return input.store.compareAndSet(operationKey, expectedRaw, nextRaw);
+        }
+        return indexedStore.compareAndSetIndexed(operationKey, expectedRaw, nextRaw, createOperationIndexEntry(previous, next));
+    }
 }
 export function createDevvitPostOperationKey(input) {
     const appScope = assertIdentifier(input.scope.appScope, 'appScope');
@@ -339,6 +419,128 @@ export function createDevvitPostOperationKey(input) {
         'state',
     ].join(':');
 }
+function createDevvitPostOperationIndexKey(input) {
+    const scope = normalizeScope(input.scope);
+    assertOperationType(input.operationType);
+    return [
+        'mpgd:devvit:post-operation-index:v1',
+        encodeKeyComponent(scope.appScope),
+        encodeKeyComponent(scope.subredditId),
+        encodeKeyComponent(input.operationType),
+        'operations',
+    ].join(':');
+}
+function readIndexedStore(store) {
+    const candidate = store;
+    const capabilities = [
+        candidate.createIndexed,
+        candidate.compareAndSetIndexed,
+        candidate.listIndex,
+        candidate.ensureIndexed,
+    ];
+    const supportedCapabilities = capabilities.filter((capability) => typeof capability === 'function').length;
+    if (supportedCapabilities === 0) {
+        return undefined;
+    }
+    if (supportedCapabilities !== capabilities.length) {
+        throw new DevvitPostOperationValidationError('Indexed durable operation stores must implement createIndexed, '
+            + 'compareAndSetIndexed, ensureIndexed, and listIndex together.');
+    }
+    return candidate;
+}
+function createOperationIndexEntry(previous, next) {
+    const indexKey = createDevvitPostOperationIndexKey({
+        scope: next.descriptor.mpgd,
+        operationType: next.descriptor.mpgd.operationType,
+    });
+    if (previous !== undefined) {
+        const previousIndexKey = createDevvitPostOperationIndexKey({
+            scope: previous.descriptor.mpgd,
+            operationType: previous.descriptor.mpgd.operationType,
+        });
+        if (previousIndexKey !== indexKey) {
+            throw new DevvitPostOperationStateError('A durable post operation cannot move between operation registries.');
+        }
+    }
+    return {
+        indexKey,
+        member: operationIndexMember(next),
+    };
+}
+function operationIndexMember(record) {
+    return record.operationKey;
+}
+function parsePendingIndexMember(member, scope, operationType) {
+    if (typeof member !== 'string' || member.length > 8192) {
+        throw new DevvitPostOperationStateError('Pending operation index member is invalid.');
+    }
+    const operationKey = member;
+    const operationKeyPrefix = [
+        'mpgd:devvit:post-operation:v1',
+        encodeKeyComponent(scope.appScope),
+        encodeKeyComponent(scope.subredditId),
+        encodeKeyComponent(operationType),
+        '',
+    ].join(':');
+    if (!operationKey.startsWith(operationKeyPrefix)
+        || !operationKey.endsWith(':state')) {
+        throw new DevvitPostOperationStateError('Pending operation index member is invalid.');
+    }
+    return { operationKey };
+}
+function normalizePendingCursor(cursor, scope, operationType) {
+    if (cursor === undefined) {
+        return undefined;
+    }
+    parsePendingIndexMember(cursor, scope, operationType);
+    return cursor;
+}
+function normalizePendingPageLimit(limit) {
+    const normalized = limit ?? defaultPendingPageLimit;
+    if (!Number.isSafeInteger(normalized)
+        || normalized < 1
+        || normalized > devvitPostOperationMaximumPendingPageLimit) {
+        throw new DevvitPostOperationValidationError('limit must be a safe integer from 1 to '
+            + `${String(devvitPostOperationMaximumPendingPageLimit)}.`);
+    }
+    return normalized;
+}
+function normalizeScope(scope) {
+    return Object.freeze({
+        appScope: assertIdentifier(scope.appScope, 'appScope'),
+        subredditId: assertSubredditId(scope.subredditId),
+    });
+}
+function pendingOperationResult(record) {
+    switch (record.phase) {
+        case 'prepared':
+            return Object.freeze({
+                status: 'prepared',
+                operationId: record.descriptor.mpgd.operationId,
+                updatedAt: record.updatedAt,
+                postData: record.descriptor,
+            });
+        case 'attempted':
+            return Object.freeze({
+                status: 'reconciliation-required',
+                operationId: record.descriptor.mpgd.operationId,
+                reason: 'submission-attempted',
+                updatedAt: record.updatedAt,
+                postData: record.descriptor,
+            });
+        case 'terminal-unresolved':
+            return Object.freeze({
+                status: 'terminal-unresolved',
+                operationId: record.descriptor.mpgd.operationId,
+                reason: record.reason,
+                postIds: record.postIds,
+                updatedAt: record.updatedAt,
+                postData: record.descriptor,
+            });
+        case 'published':
+            throw new DevvitPostOperationStateError('Published post operation cannot be returned as pending work.');
+    }
+}
 function createDescriptor(definition, input) {
     const scope = {
         appScope: assertIdentifier(input.scope.appScope, 'appScope'),
@@ -373,7 +575,7 @@ async function readOperation(operationKey, descriptor, definition, store) {
     }
     const record = parseStoredRecord(raw, operationKey, definition);
     if (canonicalJson(record.descriptor) !== canonicalJson(descriptor)) {
-        return { kind: 'conflict' };
+        return { kind: 'conflict', raw, record };
     }
     return { kind: 'record', raw, record };
 }

package/dist/server/redis-post-operation-store.d.ts

@@ -1,9 +1,20 @@
-import type { DevvitDurableOperationStore } from './post-operation.js';
+import { type DevvitIndexedDurableOperationStore } from './post-operation.js';
 export interface DevvitRedisSetOptions {
   readonly nx?: boolean;
   readonly xx?: boolean;
   readonly expiration?: Date;
 }
+export interface DevvitRedisSortedSetMember {
+  readonly member: string;
+  readonly score: number;
+}
+export interface DevvitRedisRangeOptions {
+  readonly by: 'lex';
+  readonly limit: {
+    readonly offset: number;
+    readonly count: number;
+  };
+}
 export interface DevvitRedisTransactionLike {
   multi(): Promise<void>;
   discard(): Promise<unknown>;
@@ -15,9 +26,11 @@ export interface DevvitRedisTransactionLike {
 export interface DevvitRedisLike {
   get(key: string): Promise<string | undefined>;
   set(key: string, value: string, options?: DevvitRedisSetOptions): Promise<string | undefined | null>;
+  zAdd(key: string, ...members: readonly DevvitRedisSortedSetMember[]): Promise<unknown>;
+  zRange(key: string, start: string, stop: string, options: DevvitRedisRangeOptions): Promise<readonly DevvitRedisSortedSetMember[]>;
   watch(...keys: readonly string[]): Promise<DevvitRedisTransactionLike>;
 }
 export interface DevvitRedisPostOperationStoreOptions {
   readonly transactionAttempts?: number;
 }
-export declare function createDevvitRedisPostOperationStore(redis: DevvitRedisLike, options?: DevvitRedisPostOperationStoreOptions): DevvitDurableOperationStore;
+export declare function createDevvitRedisPostOperationStore(redis: DevvitRedisLike, options?: DevvitRedisPostOperationStoreOptions): DevvitIndexedDurableOperationStore;

package/dist/server/redis-post-operation-store.js

@@ -1,3 +1,4 @@
+import { devvitPostOperationMaximumPendingPageLimit, } from './post-operation.js';
 const defaultTransactionAttempts = 3;
 const maximumTransactionAttempts = 32;
 export function createDevvitRedisPostOperationStore(redis, options = {}) {
@@ -6,9 +7,21 @@ export function createDevvitRedisPostOperationStore(redis, options = {}) {
         read(key) {
             return redis.get(key);
         },
+        async ensureIndexed(index) {
+            await redis.zAdd(index.indexKey, { member: index.member, score: 0 });
+        },
         async create(key, value) {
             return setIfAbsent(redis, key, value);
         },
+        async createIndexed(key, value, index) {
+            if (index.member !== key) {
+                throw new TypeError('Indexed creation member must equal the durable state key.');
+            }
+            // Membership is intentionally established first. If the following state
+            // write fails, listing may see a stale member but cannot miss live work.
+            await redis.zAdd(index.indexKey, { member: index.member, score: 0 });
+            return setIfAbsent(redis, key, value);
+        },
         async compareAndSet(key, expectedValue, nextValue) {
             return mutateIfValue({
                 redis,
@@ -18,6 +31,32 @@ export function createDevvitRedisPostOperationStore(redis, options = {}) {
                 queueMutation: (transaction) => transaction.set(key, nextValue),
             });
         },
+        async compareAndSetIndexed(key, expectedValue, nextValue, index) {
+            if (index.member !== key) {
+                throw new TypeError('Indexed CAS member must equal the durable state key.');
+            }
+            // Stable registry membership was established before state creation and
+            // does not change across prepared, attempted, published, or terminal state.
+            // Re-adding it backfills records created before indexed stores existed.
+            await redis.zAdd(index.indexKey, { member: index.member, score: 0 });
+            return mutateIfValue({
+                redis,
+                key,
+                expectedValue,
+                transactionAttempts,
+                queueMutation: (transaction) => transaction.set(key, nextValue),
+            });
+        },
+        async listIndex(key, startExclusive, limit) {
+            assertIndexPageLimit(limit);
+            const members = await redis.zRange(key, startExclusive === undefined ? '-' : `(${startExclusive}`, '+', { by: 'lex', limit: { offset: 0, count: limit } });
+            return members.map((member) => {
+                if (member.score !== 0 || typeof member.member !== 'string') {
+                    throw new Error(`Devvit Redis operation registry is invalid for key: ${key}`);
+                }
+                return member.member;
+            });
+        },
         async createLease(key, token, expiresAt) {
             assertExpirationDate(expiresAt);
             return setIfAbsent(redis, key, token, { expiration: expiresAt });
@@ -100,6 +139,12 @@ function normalizeTransactionAttempts(value) {
     }
     return transactionAttempts;
 }
+function assertIndexPageLimit(value) {
+    const maximum = devvitPostOperationMaximumPendingPageLimit + 1;
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+        throw new TypeError(`Devvit Redis index page limit must be a safe integer from 1 to ${String(maximum)}.`);
+    }
+}
 function assertExpirationDate(value) {
     if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
         throw new TypeError('Devvit Redis lease expiration must be a valid Date.');

package/dist/view-mode.d.ts

@@ -0,0 +1,31 @@
+export type DevvitViewMode = 'inline' | 'expanded';
+export interface DevvitViewModeClient {
+  getWebViewMode(): DevvitViewMode;
+}
+export interface DevvitInlineModeContext {
+  /**
+  * Loads gameplay in the current inline mode. Call this only from an explicit
+  * user action so the initial post entry can remain a lightweight launch screen.
+  */
+  readonly startGameplay: () => Promise<void>;
+}
+export type DevvitViewModeResult = {
+  readonly mode: 'inline';
+  readonly startGameplay: () => Promise<void>;
+} | {
+  readonly mode: 'expanded';
+};
+export interface DevvitViewModeOptions {
+  readonly client: DevvitViewModeClient;
+  readonly mountInlineMode: (context: DevvitInlineModeContext) => void | Promise<void>;
+  readonly loadGameplay: (mode: DevvitViewMode) => void | Promise<void>;
+  readonly onModeUnavailable?: (error: unknown) => void;
+}
+/**
+* Starts a Devvit web view using Reddit's official inline and expanded mode
+* terminology. Inline mode mounts lightweight content first and exposes a
+* retryable, concurrency-safe gameplay loader for a later user action.
+* Expanded mode loads gameplay immediately. Outside a Devvit host, expanded
+* mode is used as the local-browser fallback.
+*/
+export declare function startDevvitViewMode(options: DevvitViewModeOptions): Promise<DevvitViewModeResult>;

package/dist/view-mode.js

@@ -0,0 +1,45 @@
+/**
+ * Starts a Devvit web view using Reddit's official inline and expanded mode
+ * terminology. Inline mode mounts lightweight content first and exposes a
+ * retryable, concurrency-safe gameplay loader for a later user action.
+ * Expanded mode loads gameplay immediately. Outside a Devvit host, expanded
+ * mode is used as the local-browser fallback.
+ */
+export async function startDevvitViewMode(options) {
+    let mode;
+    try {
+        mode = options.client.getWebViewMode();
+    }
+    catch (error) {
+        options.onModeUnavailable?.(error);
+        await options.loadGameplay('expanded');
+        return { mode: 'expanded' };
+    }
+    if (mode === 'expanded') {
+        await options.loadGameplay('expanded');
+        return { mode: 'expanded' };
+    }
+    const startGameplay = createInlineModeGameplayStarter(options.loadGameplay);
+    await options.mountInlineMode({ startGameplay });
+    return {
+        mode: 'inline',
+        startGameplay,
+    };
+}
+function createInlineModeGameplayStarter(loadGameplay) {
+    let activeLoad;
+    return () => {
+        if (activeLoad !== undefined) {
+            return activeLoad.promise;
+        }
+        const pendingLoad = Promise.resolve().then(() => loadGameplay('inline'));
+        const loadState = { promise: pendingLoad };
+        activeLoad = loadState;
+        void pendingLoad.catch(() => {
+            if (activeLoad === loadState) {
+                activeLoad = undefined;
+            }
+        });
+        return pendingLoad;
+    };
+}

package/dist/web.d.ts

@@ -1,13 +1,21 @@
 import type { ShareResult } from '@mpgd/platform';
 import { type DevvitSurfaceOptions, type DevvitSurfaceResult } from './surface.js';
+import { type DevvitViewModeOptions, type DevvitViewModeResult } from './view-mode.js';
 export type { DevvitSurfaceClient, DevvitSurfaceMode, DevvitSurfaceOptions, DevvitSurfaceResult, } from './surface.js';
+export type { DevvitInlineModeContext, DevvitViewMode, DevvitViewModeClient, DevvitViewModeOptions, DevvitViewModeResult, } from './view-mode.js';
 export type DevvitWebSurfaceOptions = Omit<DevvitSurfaceOptions, 'client'>;
+export type DevvitWebViewOptions = Omit<DevvitViewModeOptions, 'client'>;
 export interface DevvitShareSheetOptions {
   readonly data?: string;
   readonly title?: string;
   readonly text?: string;
 }
 export declare function startDevvitWebSurface(options: DevvitWebSurfaceOptions): Promise<DevvitSurfaceResult>;
+/**
+* Starts a Devvit web view in inline or expanded mode. Inline mode can defer
+* gameplay until an explicit user action while remaining inside the post.
+*/
+export declare function startDevvitWebView(options: DevvitWebViewOptions): Promise<DevvitViewModeResult>;
 export declare function requestDevvitExpandedMode(event: MouseEvent, entry: string): Promise<void>;
 /**
 * Presents Devvit's native share surface without claiming that the user

package/dist/web.js

@@ -1,5 +1,6 @@
 import * as devvitWebClient from '@devvit/web/client';
 import { startDevvitSurface, } from './surface.js';
+import { startDevvitViewMode, } from './view-mode.js';
 // The Devvit package publishes browser implementations behind an export
 // condition while its default declaration is a server-side panic module.
 // Keep the narrow browser contract explicit until its default types expose it.
@@ -10,6 +11,16 @@ export function startDevvitWebSurface(options) {
         client: { getWebViewMode: browserClient.getWebViewMode },
     });
 }
+/**
+ * Starts a Devvit web view in inline or expanded mode. Inline mode can defer
+ * gameplay until an explicit user action while remaining inside the post.
+ */
+export function startDevvitWebView(options) {
+    return startDevvitViewMode({
+        ...options,
+        client: { getWebViewMode: browserClient.getWebViewMode },
+    });
+}
 export async function requestDevvitExpandedMode(event, entry) {
     await browserClient.requestExpandedMode(event, entry);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-devvit",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Reddit Devvit Web platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./payments": {
+      "types": "./dist/payments.d.ts",
+      "default": "./dist/payments.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -37,6 +41,10 @@
       "types": "./dist/surface.d.ts",
       "default": "./dist/surface.js"
     },
+    "./view-mode": {
+      "types": "./dist/view-mode.d.ts",
+      "default": "./dist/view-mode.js"
+    },
     "./web": {
       "types": "./dist/web.d.ts",
       "default": "./dist/web.js"
@@ -47,9 +55,9 @@
   ],
   "dependencies": {
     "@devvit/web": "0.13.8",
+    "@mpgd/game-services": "0.8.1",
     "@mpgd/bridge": "0.6.0",
-    "@mpgd/game-services": "0.7.0",
-    "@mpgd/platform": "0.5.1"
+    "@mpgd/platform": "0.6.0"
   },
   "devDependencies": {
     "ttsc": "0.18.4",
@@ -66,6 +74,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "vitest run && node test/server-dist-import.mjs && node --conditions=browser test/web-dist-import.mjs"
+    "test": "vitest run && node test/payments-dist-import.mjs && node test/server-dist-import.mjs && node --conditions=browser test/web-dist-import.mjs"
   }
 }