@mpgd/adapter-devvit 0.9.19 → 0.10.0

package/dist/commerce-provider.js

@@ -0,0 +1,472 @@
+import { assertRequestPurchaseSupported, assertStoreProduct, CommerceError, createCommerceEventBuffer, isCommerceErrorCode, } from '@mpgd/platform/commerce';
+import { createDevvitCommerceCapabilities, createDevvitStorePurchase, devvitCommerceStoreId, maximumDevvitAvailableOrders, readDevvitIdentifier, } from './commerce-contract.js';
+import { normalizeDevvitCommerceProducts, } from './payments.js';
+/**
+ * Refreshes an order reported ahead of the list (by a checkout result or a
+ * signal) survives without a listing showing it; it is forgotten on the next
+ * one, so a re-listed order is reported again.
+ */
+export const unlistedOrderGraceRefreshes = 7;
+/** Store codes the provider attaches to failures of its own. */
+export const devvitCommerceStoreCodes = Object.freeze({
+    productNotConfigured: 'DEVVIT_PRODUCT_NOT_CONFIGURED',
+    checkoutFailed: 'DEVVIT_CHECKOUT_FAILED',
+    checkoutCancelled: 'DEVVIT_CHECKOUT_CANCELLED',
+    ordersUnavailable: 'DEVVIT_ORDERS_UNAVAILABLE',
+});
+/**
+ * Commerce v2 provider for Devvit (RFC profile `devvit`, see
+ * `createDevvitCommerceCapabilities`). Reddit's fulfillment handler settles a
+ * purchase on the server: it writes the backend ledger, and the client learns
+ * of the grant through the backend's server-push lookup verifier, which
+ * answers `pending` until that entry exists. The provider therefore never
+ * grants and has nothing to finish.
+ *
+ * - `requestPurchase` opens the Reddit checkout. A checkout that already
+ *   carries the created order id answers `purchased` with the order id as
+ *   `transactionId` and `token` and `devvit.order.v1` evidence; the backend
+ *   verify is what grants it. A checkout without an order id, or one that
+ *   ended `pending`, is `launched`: an order may exist, and the reconciler
+ *   resolves it from `getAvailablePurchases`. A dismissed checkout is
+ *   `cancelled`; a failed one is `failed` with the platform code as
+ *   `storeCode` (`OUTCOME_UNKNOWN` and `ALREADY_OWNED` classes stay open as
+ *   `launched`, as the RFC requires, and so does a `purchase()` call that
+ *   rejects, since a missing response does not prove a missing order).
+ * - `getAvailablePurchases` lists the paid orders whose delivery the server
+ *   has not acknowledged (the order source without its delivered entries),
+ *   bounded by `maximumDevvitAvailableOrders`; `includePending` adds nothing
+ *   because Devvit has no store-side pending order.
+ * - `restorePurchases` re-reads the order source and emits `purchaseUpdated`
+ *   once per order not reported before, delivered orders included: Reddit
+ *   marks an order delivered as soon as the fulfillment handler answered, so
+ *   a session that lost its checkout result finds the order this way and the
+ *   backend lookup answers `granted` for it. The first listener triggers the
+ *   same read. Events before the first `subscribe` are buffered.
+ * - The provider emits no `purchaseError`: every checkout outcome is a
+ *   synchronous result of the purchase call.
+ */
+export function createDevvitCommerceProvider(input) {
+    const store = input.store ?? devvitCommerceStoreId;
+    if (store.length === 0) {
+        throw new TypeError('A Devvit commerce provider requires a non-empty store id.');
+    }
+    const products = normalizeDevvitCommerceProducts(input.products);
+    const oneTimeProductCount = products.filter((product) => product.info.type !== 'subscription').length;
+    const productsById = new Map(products.map((product) => [product.info.id, product]));
+    const productsBySku = new Map(products.map((product) => [product.sku, product]));
+    const buffer = createCommerceEventBuffer();
+    const listeners = new Set();
+    /** Orders already reported, through a checkout result or a `purchaseUpdated` event. */
+    const reportedOrders = new Set();
+    /**
+     * Orders reported ahead of the list (a checkout result or a signal) that no
+     * listing has confirmed yet, with the unlisted refreshes left before one is
+     * forgotten: the server may list a just-created order a moment later, and
+     * it must not be reported twice.
+     */
+    const unlistedOrders = new Map();
+    /** Bounds the reported set (oldest first) and drops grace entries of evicted orders. */
+    const boundReported = () => {
+        for (const oldest of reportedOrders) {
+            if (reportedOrders.size <= maximumDevvitAvailableOrders) {
+                break;
+            }
+            reportedOrders.delete(oldest);
+        }
+        for (const tracked of [...unlistedOrders.keys()]) {
+            if (!reportedOrders.has(tracked)) {
+                unlistedOrders.delete(tracked);
+            }
+        }
+    };
+    const emit = (event) => {
+        if (listeners.size === 0) {
+            buffer.push(event);
+            return;
+        }
+        for (const listener of [...listeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                // One listener must not stop the others from receiving the event.
+                console.warn('Devvit commerce listener failed.', errorMessage(error));
+            }
+        }
+    };
+    const toPurchase = (order, source) => {
+        const product = productsBySku.get(order.sku);
+        if (product === undefined) {
+            // An order for a SKU this build does not sell is not this game's purchase.
+            return undefined;
+        }
+        return createDevvitStorePurchase({
+            store,
+            orderId: order.orderId,
+            sku: order.sku,
+            logicalId: product.info.id,
+            source,
+            paidAt: order.paidAt,
+            environment: order.environment,
+            delivered: order.delivered,
+        });
+    };
+    const readPaidOrders = async () => {
+        let orders;
+        try {
+            orders = await input.orders.listPaidOrders();
+        }
+        catch (error) {
+            throw toCommerceError(error);
+        }
+        if (orders.length > maximumDevvitAvailableOrders) {
+            console.warn('Devvit paid-order list exceeds the available-purchase bound.', {
+                limit: maximumDevvitAvailableOrders,
+                ignoredOrderCount: orders.length - maximumDevvitAvailableOrders,
+            });
+        }
+        return orders.slice(0, maximumDevvitAvailableOrders).filter((order) => readDevvitIdentifier(order.orderId) !== undefined
+            && readDevvitIdentifier(order.sku) !== undefined);
+    };
+    /**
+     * Reports a paid order once. The purchase is built before any bookkeeping,
+     * so an order the contract rejects is neither marked reported nor emitted.
+     */
+    const reportOrder = (order, aheadOfList = false) => {
+        if (reportedOrders.has(order.orderId)) {
+            return;
+        }
+        let purchase;
+        try {
+            purchase = toPurchase(order, 'order-list');
+        }
+        catch (error) {
+            // One invalid order must not hide the others.
+            console.warn('Devvit paid order was not reported.', errorMessage(error));
+            return;
+        }
+        if (purchase === undefined) {
+            return;
+        }
+        reportedOrders.add(order.orderId);
+        if (aheadOfList) {
+            unlistedOrders.set(order.orderId, unlistedOrderGraceRefreshes);
+        }
+        boundReported();
+        emit({ type: 'purchaseUpdated', purchase });
+    };
+    /** Re-reads the paid orders and reports the ones not reported yet. */
+    const refreshOrders = async () => {
+        const orders = await readPaidOrders();
+        const listed = new Set(orders.map((order) => order.orderId));
+        for (const order of orders) {
+            reportOrder(order);
+        }
+        for (const orderId of [...reportedOrders]) {
+            if (listed.has(orderId)) {
+                // A listing confirmed the order; it is a listed order now.
+                unlistedOrders.delete(orderId);
+                continue;
+            }
+            const remaining = unlistedOrders.get(orderId);
+            if (remaining !== undefined && remaining > 0) {
+                // Not listed yet: the server may still be catching up.
+                unlistedOrders.set(orderId, remaining - 1);
+                continue;
+            }
+            // An order the server stopped listing (or never listed within the grace)
+            // was delivered; it is forgotten so a re-listed order is reported again.
+            unlistedOrders.delete(orderId);
+            reportedOrders.delete(orderId);
+        }
+    };
+    const refreshInBackground = () => {
+        void refreshOrders().catch((error) => {
+            console.warn('Devvit paid-order refresh failed.', errorMessage(error));
+        });
+    };
+    /** Reports the orders a signal carries; the read that follows confirms the rest. */
+    const reportSignalledOrders = (orders) => {
+        for (const order of orders.slice(0, maximumDevvitAvailableOrders)) {
+            if (readDevvitIdentifier(order.orderId) === undefined
+                || readDevvitIdentifier(order.sku) === undefined) {
+                continue;
+            }
+            reportOrder(order, true);
+        }
+    };
+    let detachOrderSignal;
+    const attachOrderSignal = () => {
+        if (detachOrderSignal !== undefined || input.onOrdersChanged === undefined) {
+            return;
+        }
+        detachOrderSignal = input.onOrdersChanged((change) => {
+            if (change?.orders !== undefined && Array.isArray(change.orders)) {
+                reportSignalledOrders(change.orders);
+            }
+            refreshInBackground();
+        });
+    };
+    const detachOrderSignalIfIdle = () => {
+        if (listeners.size > 0 || detachOrderSignal === undefined) {
+            return;
+        }
+        const detach = detachOrderSignal;
+        detachOrderSignal = undefined;
+        detach();
+    };
+    const toRequestPurchaseResult = (product, result) => {
+        switch (result.status) {
+            case 'completed': {
+                const orderId = readDevvitIdentifier(result.orderId);
+                if (orderId === undefined) {
+                    // Reddit answered without an order id: an order may still exist.
+                    return { outcome: 'launched' };
+                }
+                const purchase = createDevvitStorePurchase({
+                    store,
+                    orderId,
+                    sku: product.sku,
+                    logicalId: product.info.id,
+                    source: 'checkout',
+                });
+                reportedOrders.add(orderId);
+                unlistedOrders.set(orderId, unlistedOrderGraceRefreshes);
+                boundReported();
+                return { outcome: 'purchased', purchase };
+            }
+            case 'pending':
+                return { outcome: 'launched' };
+            case 'cancelled':
+                return { outcome: 'cancelled', error: toCancelledErrorInfo(result.error) };
+            case 'failed': {
+                const error = toCheckoutErrorInfo(result.error);
+                if (error.code === 'OUTCOME_UNKNOWN' || error.code === 'ALREADY_OWNED') {
+                    // RFC "Errors": an unfinished order may exist, so the attempt stays
+                    // open for the reconciler instead of becoming terminal.
+                    return { outcome: 'launched' };
+                }
+                if (error.code === 'USER_CANCELLED') {
+                    return { outcome: 'cancelled', error };
+                }
+                return { outcome: 'failed', error };
+            }
+            default:
+                return {
+                    outcome: 'failed',
+                    error: new CommerceError('INVALID_RESPONSE', {
+                        message: `Devvit checkout answered an unknown status: ${String(result.status)}.`,
+                    }).toCommerceErrorInfo(),
+                };
+        }
+    };
+    const provider = {
+        store,
+        async getCapabilities() {
+            let availability = 'available';
+            if (oneTimeProductCount === 0) {
+                // A catalog without a consumable or durable product sells nothing here.
+                availability = 'configuration-required';
+            }
+            else if (input.orders.getAvailability !== undefined) {
+                try {
+                    availability = await input.orders.getAvailability();
+                }
+                catch (error) {
+                    console.warn('Devvit commerce availability read failed.', errorMessage(error));
+                    availability = 'temporarily-unavailable';
+                }
+            }
+            return createDevvitCommerceCapabilities(availability);
+        },
+        async fetchProducts(request = {}) {
+            if ((request.type ?? 'all') === 'subscription') {
+                return [];
+            }
+            const listed = [];
+            for (const product of products) {
+                if (request.logicalIds !== undefined && !request.logicalIds.includes(product.info.id)) {
+                    continue;
+                }
+                const storeProduct = toStoreProduct(store, product);
+                if (storeProduct !== undefined) {
+                    listed.push(storeProduct);
+                }
+            }
+            return listed;
+        },
+        async requestPurchase(request) {
+            const product = productsById.get(request.logicalId);
+            if (product === undefined) {
+                return {
+                    outcome: 'failed',
+                    error: new CommerceError('ITEM_UNAVAILABLE', {
+                        message: `Devvit product ${request.logicalId} is not configured.`,
+                        storeCode: devvitCommerceStoreCodes.productNotConfigured,
+                    }).toCommerceErrorInfo(),
+                };
+            }
+            // Both one-time kinds are sold; a subscription-typed product and a
+            // quantity above one are rejected before the checkout opens.
+            assertRequestPurchaseSupported(createDevvitCommerceCapabilities('available'), request, purchaseKindOf(product.info.type));
+            let result;
+            try {
+                // Reddit's order id is authoritative; no client metadata is attached.
+                result = await input.client.purchase(product.sku);
+            }
+            catch (error) {
+                // `purchase()` rejects when the checkout effect produced no usable
+                // response, which does not prove that no order was created: the
+                // outcome is unknown, so the attempt stays open (RFC "Errors") and
+                // the reconciler resolves it from the paid-order list.
+                input.onCheckoutError?.(error);
+                refreshInBackground();
+                return { outcome: 'launched' };
+            }
+            const outcome = toRequestPurchaseResult(product, result);
+            if (outcome.outcome === 'launched') {
+                // The order, if any, is in the server's list; report it without
+                // waiting for a signal.
+                refreshInBackground();
+            }
+            return outcome;
+        },
+        async getAvailablePurchases(_request = {}) {
+            const purchases = [];
+            for (const order of await readPaidOrders()) {
+                if (order.delivered === true) {
+                    // Delivered: the fulfillment handler settled it; it reaches the
+                    // reconciler as an event, not as an unfinished purchase.
+                    continue;
+                }
+                try {
+                    const purchase = toPurchase(order, 'order-list');
+                    if (purchase !== undefined) {
+                        purchases.push(purchase);
+                    }
+                }
+                catch (error) {
+                    // One invalid order must not hide the others, as on a refresh.
+                    console.warn('Devvit paid order was not listed.', errorMessage(error));
+                }
+            }
+            return purchases;
+        },
+        async restorePurchases() {
+            await refreshOrders();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            attachOrderSignal();
+            if (listeners.size === 1) {
+                buffer.drain((event) => {
+                    try {
+                        listener(event);
+                    }
+                    catch (error) {
+                        console.warn('Devvit commerce listener failed.', errorMessage(error));
+                    }
+                });
+                // A fresh listener (a new session, or a restart) learns of the recent
+                // orders, delivered ones included, so a checkout result lost to a
+                // restart still reaches the reconciler; it matches them to its
+                // records by store and transaction id.
+                refreshInBackground();
+            }
+            return () => {
+                listeners.delete(listener);
+                detachOrderSignalIfIdle();
+            };
+        },
+        dispose() {
+            listeners.clear();
+            detachOrderSignalIfIdle();
+        },
+    };
+    return provider;
+}
+function toStoreProduct(store, product) {
+    const { info } = product;
+    const kind = info.type === 'consumable'
+        ? 'consumable'
+        : info.type === 'non_consumable'
+            ? 'durable'
+            : undefined;
+    if (kind === undefined) {
+        return undefined;
+    }
+    try {
+        return assertStoreProduct({
+            logicalId: info.id,
+            store,
+            storeSku: product.sku,
+            kind,
+            title: info.title,
+            description: info.description,
+            price: { formatted: info.price.formatted, currencyCode: info.price.currencyCode },
+        });
+    }
+    catch (error) {
+        throw new CommerceError('INVALID_RESPONSE', {
+            message: `Devvit product ${product.sku} is configured with invalid product info.`,
+            cause: error,
+        });
+    }
+}
+function purchaseKindOf(type) {
+    switch (type) {
+        case 'consumable':
+            return 'consumable';
+        case 'non_consumable':
+            return 'durable';
+        case 'subscription':
+            return 'subscription';
+    }
+}
+/** A cancelled checkout: `USER_CANCELLED`, with the platform's own code kept as `storeCode`. */
+function toCancelledErrorInfo(failure) {
+    const storeCode = failure?.storeCode
+        ?? (failure !== undefined && !isCommerceErrorCode(failure.code) ? failure.code : undefined)
+        ?? devvitCommerceStoreCodes.checkoutCancelled;
+    return new CommerceError('USER_CANCELLED', {
+        message: failure?.message ?? 'Devvit checkout was cancelled.',
+        storeCode,
+        retryable: false,
+    }).toCommerceErrorInfo();
+}
+/**
+ * The normalized error of a failed checkout: a v2 code the client classified
+ * is kept with its own `storeCode`; any other code is `UNKNOWN` and travels
+ * as `storeCode`. `retryable` defaults from the normalized code.
+ */
+function toCheckoutErrorInfo(failure) {
+    if (failure === undefined) {
+        return new CommerceError('UNKNOWN', {
+            message: 'Devvit checkout failed.',
+            storeCode: devvitCommerceStoreCodes.checkoutFailed,
+            retryable: false,
+        }).toCommerceErrorInfo();
+    }
+    const normalized = isCommerceErrorCode(failure.code) ? failure.code : 'UNKNOWN';
+    const storeCode = failure.storeCode ?? (normalized === 'UNKNOWN' ? failure.code : undefined);
+    return new CommerceError(normalized, {
+        message: failure.message ?? `Devvit checkout failed: ${storeCode ?? normalized}.`,
+        ...(storeCode === undefined ? {} : { storeCode }),
+        ...(failure.retryable === undefined ? {} : { retryable: failure.retryable }),
+    }).toCommerceErrorInfo();
+}
+/** A thrown order-source failure as a retryable `STORE_UNAVAILABLE`, unless it already is a commerce error. */
+function toCommerceError(error) {
+    if (error instanceof CommerceError) {
+        return error;
+    }
+    return new CommerceError('STORE_UNAVAILABLE', {
+        message: `Devvit paid orders are unavailable: ${errorMessage(error)}`,
+        storeCode: devvitCommerceStoreCodes.ordersUnavailable,
+        retryable: true,
+        cause: error,
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -1,8 +1,13 @@
-import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
+import { type BridgeMethod, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import { type BridgeRpcClient, type BridgeRpcEndpoint } from '@mpgd/bridge/orpc';
-import type { PlatformGateway } from '@mpgd/platform';
+import { type PlatformGateway } from '@mpgd/platform';
+import { type CreateDevvitCommerceProviderInput, type DevvitOrderSource } from './commerce-provider.js';
+export * from './commerce-contract.js';
+export * from './commerce-provider.js';
 export * from './payments.js';
 export declare const defaultDevvitRpcEndpoint = "/api/mpgd/rpc";
+/** Bridge error of `createDevvitOrpcBridge` when the oRPC request itself failed. */
+export declare const devvitBridgeNetworkErrorCode: 'DEVVIT_BRIDGE_NETWORK_ERROR';
 type BridgeErrorResponse = Extract<BridgeResponse, {
   readonly ok: false;
 }>;
@@ -15,14 +20,48 @@ export declare class DevvitBridgeError extends Error {
   readonly retryable: boolean;
   constructor(response: BridgeErrorResponse);
 }
+/**
+* Webview side of commerce v2: the checkout client and the product catalog.
+* The paid-order list and the capability availability come from the server
+* bridge (`commerce.v2.getAvailablePurchases`, `commerce.v2.getCapabilities`),
+* which the server serves through `createDevvitCommerceV2BridgeHandler` from
+* `@mpgd/adapter-devvit/server`.
+*/
+export type DevvitGatewayCommerceOptions = Omit<CreateDevvitCommerceProviderInput, 'orders'>;
 export interface DevvitPlatformGatewayOptions {
   readonly appVersion: string;
   readonly buildId: string;
   readonly bridge?: DevvitBridge;
   readonly fallbackBridge?: DevvitBridge;
   readonly rpcEndpoint?: BridgeRpcEndpoint;
+  /**
+  * Installs the commerce v2 provider (`createDevvitCommerceProvider`) as
+  * `commerceV2`, with the `commerce` capability block and `nativeIap` and
+  * `subscriptionIap` derived from it. Absent, the gateway offers no
+  * `commerceV2`; the v1 `commerce` surface is the bridge's either way.
+  *
+  * Not yet usable in production before C2: the backend lookup verifier for
+  * `devvit.order.v1` does not exist yet, so a verify request for a Devvit
+  * purchase is refused today instead of answering `pending`, and no journal
+  * record can reach `granted`. Enable it once the backend can answer.
+  */
+  readonly commerce?: DevvitGatewayCommerceOptions;
 }
 export declare function createDevvitPlatformGateway(input: DevvitPlatformGatewayOptions): PlatformGateway;
+/**
+* The webview provider's order source over the server bridge: the paid orders
+* the server lists as available purchases, mapped back to orders (the
+* provider rebuilds the purchases under its own store id), and the
+* availability the server reports. `COMMERCE_V2_UNAVAILABLE` from a bridge
+* without the commerce handler is `configuration-required`; another bridge
+* failure that is retryable (or the transport failing) keeps the availability
+* the server last answered for the capability read (`temporarily-unavailable`
+* before any answer; a non-retryable failure or an invalid answer fails
+* closed) and is
+* a `CommerceError` for a list read (`NETWORK` for a transport failure,
+* otherwise `UNKNOWN` with the bridge code as `storeCode`).
+*/
+export declare function createDevvitBridgeOrderSource(request: <TData>(method: BridgeMethod, payload: unknown) => Promise<TData>): DevvitOrderSource;
 export declare function createDevvitOrpcBridge(input?: {
   readonly endpoint?: BridgeRpcEndpoint | undefined;
   readonly fetch?: typeof fetch | undefined;