@mpgd/adapter-devvit 0.9.20 → 0.10.0

package/dist/commerce-contract.d.ts

@@ -0,0 +1,85 @@
+import type { PlatformEvidenceEnvelope, PlatformProviderAvailability } from '@mpgd/platform';
+import { type CommerceCapabilities, type StoreId, type StorePurchase } from '@mpgd/platform/commerce';
+/**
+* Commerce v2 contract pieces shared by the Devvit webview provider and the
+* Devvit server bridge handler: the store id, the RFC profile, the
+* `devvit.order.v1` evidence envelope, and the order-to-purchase mapping.
+* This module imports no Devvit SDK.
+*/
+/** The open store id of the Devvit provider (RFC "Capabilities"). */
+export declare const devvitCommerceStoreId: 'devvit';
+/**
+* Evidence schema of a Devvit order reported by the client (a checkout result
+* or the server's paid-order list). It names the order; the backend's
+* server-push lookup decides from the ledger the fulfillment handler wrote
+* (`devvit.payment-order.v1`), never from this envelope alone.
+*/
+export declare const devvitOrderEvidenceSchema: 'devvit.order.v1';
+/** Bounds what one order list can turn into available purchases. */
+export declare const maximumDevvitAvailableOrders = 64;
+export type DevvitOrderEvidenceSource = 'checkout' | 'order-list';
+export type DevvitOrderEnvironment = 'sandbox' | 'production';
+/** The Reddit order status an order-list envelope reports: paid and awaiting delivery, or delivered. */
+export type DevvitOrderEvidenceStatus = 'PAID' | 'DELIVERED';
+export interface DevvitOrderEvidencePayload {
+  readonly orderId: string;
+  readonly sku: string;
+  readonly source: DevvitOrderEvidenceSource;
+  readonly environment?: DevvitOrderEnvironment;
+  readonly status?: DevvitOrderEvidenceStatus;
+}
+/**
+* A paid Devvit order as the order list reports it: `delivered` says whether
+* Reddit already acknowledged its delivery (`DELIVERED`), which it does as
+* soon as the fulfillment handler answered; absent, the order is `PAID` and
+* the handler has not settled it yet.
+*/
+export interface DevvitPaidOrder {
+  readonly orderId: string;
+  readonly sku: string;
+  /** ISO timestamp of the payment (`Order.updatedAt`, else `createdAt`). */
+  readonly paidAt?: string;
+  readonly environment?: DevvitOrderEnvironment;
+  readonly delivered?: boolean;
+}
+/**
+* The RFC profile row for `devvit`: consumable and durable one-time products,
+* no subscription, no quantity, `lifecycle.finish: 'none'` (the fulfillment
+* handler settles on the server; the client has nothing to finish),
+* `authority.evidence: 'server-push'`, and `accountBinding: 'host'` (the
+* purchasing Reddit account comes from the server request context).
+* `lifecycle.pending` covers the server-side pending of a server-push store:
+* verify answers `pending` until the fulfillment push wrote the ledger; Devvit
+* reports no store-side pending purchase.
+*/
+export declare function createDevvitCommerceCapabilities(availability: PlatformProviderAvailability): CommerceCapabilities;
+export declare function createDevvitOrderEvidence(payload: DevvitOrderEvidencePayload): PlatformEvidenceEnvelope;
+/**
+* Validates a `devvit.order.v1` envelope the way a server registry entry must
+* before it looks the order up: the schema, a bounded order id and SKU, a
+* known source, and optional environment and status. Throws `TypeError`
+* otherwise.
+*/
+export declare function assertDevvitOrderEvidence(envelope: PlatformEvidenceEnvelope): DevvitOrderEvidencePayload;
+/** A bounded, trimmed, control-character-free identifier, or nothing. */
+export declare function readDevvitIdentifier(value: unknown): string | undefined;
+/** An ISO timestamp for a Devvit order time, or nothing when it is absent or unparseable. */
+export declare function readDevvitOrderTime(value: unknown): string | undefined;
+export interface DevvitStorePurchaseInput {
+  readonly store: StoreId;
+  readonly orderId: string;
+  readonly sku: string;
+  readonly logicalId: string;
+  readonly source: DevvitOrderEvidenceSource;
+  readonly paidAt?: string | undefined;
+  readonly environment?: DevvitOrderEnvironment | undefined;
+  /** Known from the order list only; a checkout result carries no status. */
+  readonly delivered?: boolean | undefined;
+}
+/**
+* A paid Devvit order as a `purchased` store purchase: the order id is both
+* `transactionId` and `token` (RFC "Client contract": host order id), the
+* evidence is the `devvit.order.v1` envelope, and the account binding is the
+* host identity. An order the contract rejects throws `INVALID_RESPONSE`.
+*/
+export declare function createDevvitStorePurchase(input: DevvitStorePurchaseInput): StorePurchase;

package/dist/commerce-contract.js

@@ -0,0 +1,145 @@
+import { assertStorePurchase, CommerceError, } from '@mpgd/platform/commerce';
+/**
+ * Commerce v2 contract pieces shared by the Devvit webview provider and the
+ * Devvit server bridge handler: the store id, the RFC profile, the
+ * `devvit.order.v1` evidence envelope, and the order-to-purchase mapping.
+ * This module imports no Devvit SDK.
+ */
+/** The open store id of the Devvit provider (RFC "Capabilities"). */
+export const devvitCommerceStoreId = 'devvit';
+/**
+ * Evidence schema of a Devvit order reported by the client (a checkout result
+ * or the server's paid-order list). It names the order; the backend's
+ * server-push lookup decides from the ledger the fulfillment handler wrote
+ * (`devvit.payment-order.v1`), never from this envelope alone.
+ */
+export const devvitOrderEvidenceSchema = 'devvit.order.v1';
+/** Bounds what one order list can turn into available purchases. */
+export const maximumDevvitAvailableOrders = 64;
+/**
+ * The RFC profile row for `devvit`: consumable and durable one-time products,
+ * no subscription, no quantity, `lifecycle.finish: 'none'` (the fulfillment
+ * handler settles on the server; the client has nothing to finish),
+ * `authority.evidence: 'server-push'`, and `accountBinding: 'host'` (the
+ * purchasing Reddit account comes from the server request context).
+ * `lifecycle.pending` covers the server-side pending of a server-push store:
+ * verify answers `pending` until the fulfillment push wrote the ledger; Devvit
+ * reports no store-side pending purchase.
+ */
+export function createDevvitCommerceCapabilities(availability) {
+    return {
+        purchase: { consumable: true, durable: true, subscription: false, quantity: false },
+        catalog: { products: true, offers: false, localizedPrice: false },
+        lifecycle: {
+            availablePurchases: true,
+            pending: true,
+            restore: true,
+            events: true,
+            finish: 'none',
+        },
+        authority: { evidence: 'server-push', accountBinding: 'host' },
+        availability,
+    };
+}
+export function createDevvitOrderEvidence(payload) {
+    return {
+        schema: devvitOrderEvidenceSchema,
+        payload: {
+            orderId: payload.orderId,
+            sku: payload.sku,
+            source: payload.source,
+            ...(payload.environment === undefined ? {} : { environment: payload.environment }),
+            ...(payload.status === undefined ? {} : { status: payload.status }),
+        },
+    };
+}
+/**
+ * Validates a `devvit.order.v1` envelope the way a server registry entry must
+ * before it looks the order up: the schema, a bounded order id and SKU, a
+ * known source, and optional environment and status. Throws `TypeError`
+ * otherwise.
+ */
+export function assertDevvitOrderEvidence(envelope) {
+    if (envelope.schema !== devvitOrderEvidenceSchema) {
+        throw new TypeError(`Devvit order evidence schema must be ${devvitOrderEvidenceSchema}.`);
+    }
+    const { payload } = envelope;
+    const orderId = readDevvitIdentifier(payload.orderId);
+    const sku = readDevvitIdentifier(payload.sku);
+    if (orderId === undefined) {
+        throw new TypeError('Devvit order evidence must carry an orderId.');
+    }
+    if (sku === undefined) {
+        throw new TypeError('Devvit order evidence must carry a sku.');
+    }
+    const { source, environment, status } = payload;
+    if (source !== 'checkout' && source !== 'order-list') {
+        throw new TypeError('Devvit order evidence source must be checkout or order-list.');
+    }
+    if (environment !== undefined && environment !== 'sandbox' && environment !== 'production') {
+        throw new TypeError('Devvit order evidence environment must be sandbox or production.');
+    }
+    if (status !== undefined && status !== 'PAID' && status !== 'DELIVERED') {
+        throw new TypeError('Devvit order evidence status must be PAID or DELIVERED.');
+    }
+    return {
+        orderId,
+        sku,
+        source,
+        ...(environment === undefined ? {} : { environment }),
+        ...(status === undefined ? {} : { status }),
+    };
+}
+/** A bounded, trimmed, control-character-free identifier, or nothing. */
+export function readDevvitIdentifier(value) {
+    if (typeof value !== 'string'
+        || value.length === 0
+        || value.length > 256
+        || value.trim() !== value
+        || /[\p{Cc}\p{Cf}]/u.test(value)) {
+        return undefined;
+    }
+    return value;
+}
+/** An ISO timestamp for a Devvit order time, or nothing when it is absent or unparseable. */
+export function readDevvitOrderTime(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 64) {
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
+}
+/**
+ * A paid Devvit order as a `purchased` store purchase: the order id is both
+ * `transactionId` and `token` (RFC "Client contract": host order id), the
+ * evidence is the `devvit.order.v1` envelope, and the account binding is the
+ * host identity. An order the contract rejects throws `INVALID_RESPONSE`.
+ */
+export function createDevvitStorePurchase(input) {
+    try {
+        return assertStorePurchase({
+            store: input.store,
+            transactionId: input.orderId,
+            storeSku: input.sku,
+            logicalId: input.logicalId,
+            quantity: 1,
+            state: 'purchased',
+            ...(input.paidAt === undefined ? {} : { purchasedAt: input.paidAt }),
+            token: input.orderId,
+            evidence: createDevvitOrderEvidence({
+                orderId: input.orderId,
+                sku: input.sku,
+                source: input.source,
+                ...(input.environment === undefined ? {} : { environment: input.environment }),
+                ...(input.delivered === undefined ? {} : { status: input.delivered ? 'DELIVERED' : 'PAID' }),
+            }),
+            accountBinding: { kind: 'host-identity' },
+        });
+    }
+    catch (error) {
+        throw new CommerceError('INVALID_RESPONSE', {
+            message: 'Devvit reported an invalid order.',
+            cause: error,
+        });
+    }
+}

package/dist/commerce-provider.d.ts

@@ -0,0 +1,93 @@
+import type { PlatformProviderAvailability } from '@mpgd/platform';
+import { type CommerceProvider, type StoreId } from '@mpgd/platform/commerce';
+import { type DevvitPaidOrder } from './commerce-contract.js';
+import { type DevvitCommerceProduct, type DevvitPaymentsClient } 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 declare const unlistedOrderGraceRefreshes = 7;
+/** Store codes the provider attaches to failures of its own. */
+export declare const devvitCommerceStoreCodes: Readonly<{
+  readonly productNotConfigured: 'DEVVIT_PRODUCT_NOT_CONFIGURED';
+  readonly checkoutFailed: 'DEVVIT_CHECKOUT_FAILED';
+  readonly checkoutCancelled: 'DEVVIT_CHECKOUT_CANCELLED';
+  readonly ordersUnavailable: 'DEVVIT_ORDERS_UNAVAILABLE';
+}>;
+/**
+* The server-push lookup of the Devvit provider: the user's recent paid
+* orders, each marked `delivered` once Reddit acknowledged its delivery
+* (which happens as soon as the fulfillment handler answered). The order
+* list is server-only in Devvit (`payments.getOrders`), so the webview reads
+* it through the server bridge (`commerce.v2.getAvailablePurchases`); the
+* conformance harness reads it from its fake payments plugin.
+*/
+export interface DevvitOrderSource {
+  listPaidOrders(): Promise<readonly DevvitPaidOrder[]>;
+  /** Whether the server side serves commerce v2; defaults to `available`. */
+  getAvailability?(): Promise<PlatformProviderAvailability>;
+}
+export interface DevvitOrdersChange {
+  /**
+  * Paid orders the signaller already knows, for example the order a
+  * realtime message named. The provider reports them at once and still
+  * re-reads the order source; an order for an unconfigured SKU is ignored.
+  */
+  readonly orders?: readonly DevvitPaidOrder[];
+}
+export type DevvitOrdersChangeListener = (change?: DevvitOrdersChange) => void;
+export interface CreateDevvitCommerceProviderInput {
+  readonly products: readonly DevvitCommerceProduct[];
+  /** Opens the Reddit checkout (`purchase()` from `@devvit/payments/client`). */
+  readonly client: Pick<DevvitPaymentsClient, 'purchase'>;
+  readonly orders: DevvitOrderSource;
+  /** Defaults to `devvit`; conformance vectors name their fixture store. */
+  readonly store?: StoreId;
+  /**
+  * Signals that the paid-order list may have changed, for example because the
+  * webview became visible again. The provider reports the orders the signal
+  * carries at once, then re-reads the list and emits `purchaseUpdated` for
+  * paid orders it has not reported yet. Observed only while a listener
+  * exists. Absent, orders are read on demand only.
+  */
+  readonly onOrdersChanged?: (listener: DevvitOrdersChangeListener) => () => void;
+  readonly onCheckoutError?: (error: unknown) => void;
+}
+export interface DevvitCommerceProvider extends CommerceProvider {
+  restorePurchases(): Promise<void>;
+  /** Stops observing the order signal; the provider answers no further events. */
+  dispose(): void;
+}
+/**
+* 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 declare function createDevvitCommerceProvider(input: CreateDevvitCommerceProviderInput): DevvitCommerceProvider;