@portalshq/monetization 0.2.0

package/README.md

@@ -0,0 +1,182 @@
+# @portalshq/monetization
+
+Audience-to-creator monetization for Portals. Stripe Connect destination
+charges, entitlements, a ledger, and a transactional outbox.
+
+Applications provide authorization, catalog configuration, persistence, and
+URLs. They never provide authoritative prices, fees, or destination account ids
+from a browser.
+
+## Credentials
+
+No package here reads `process.env` for a secret. The application boundary
+resolves the credential and injects it, so a library can never quietly pick up
+an ambient key and tests cannot be influenced by one.
+
+```ts
+// application boundary — the only place env is read
+const secretKey = process.env.STRIPE_SECRET_KEY?.trim();
+if (!secretKey) throw new Error("STRIPE_SECRET_KEY is not configured");
+
+const monetization = new Monetization({
+  stripe: createStripePlatformClient(secretKey),
+  store, ids, catalog,
+});
+const transfers = new StripeConnectClient(secretKey);
+```
+
+Store it in the deploy platform's secrets vault (AWS Secrets Manager, GCP Secret
+Manager, Azure Key Vault), or a write-only environment variable where no vault
+exists — Vercel, for instance, has no built-in vault. Never in source.
+
+### Credentials
+
+`stripe` is the platform's charge-capable key: it creates charges and transfers
+them to tenants, and it holds the end users' payment methods. Use a **restricted
+key** scoped to only the endpoints used, plus an IP access policy. Prefer the
+deploy platform's secrets vault over a plain environment variable.
+
+| Credential | Acts on | Purpose |
+|---|---|---|
+| **Platform RAK** (`rk_`) | Platform account, all connected accounts | Creates charges and transfers; provisions tenant accounts; reads capabilities; creates onboarding links |
+| **Platform-sales RAK** (`rk_`) | Platform account | Enterprise and B2B sales, no Connect involved. Served by `StripePlatformBilling` in `@portalshq/platform-billing` |
+
+End users never hold a Stripe credential, and neither do tenants. Tenants get
+Stripe-hosted onboarding plus dashboard access via account links the platform
+creates.
+
+## Checkout
+
+Pass a stable application order id as `purchaseId`. Retrying that id returns the
+existing Stripe Checkout Session; reusing it for different purchase data is
+rejected. Checkout is refused until the tenant can receive payouts.
+
+```ts
+const { url } = await monetization.createCheckout({
+  purchaseId, tenantId, channelId, sessionId, buyerId, productKey,
+  successUrl, cancelUrl,
+});
+```
+
+`sessionId` is optional. When present it becomes a fact that session-scoped
+entitlement rules can match on.
+
+## Webhooks, refunds, disputes
+
+`handleWebhook` processes signed events transactionally: the event is claimed
+atomically, so a redelivered event is a no-op and a settlement can never be
+applied twice. Refund webhooks are applied as cumulative Stripe state and
+ledger only the new delta. To recover tenant funds after a dispute, provide
+`reverseTransferForDispute`; an approved reversal uses the recorded Connect
+transfer and a stable Stripe idempotency key. Webhook effects and outbox writes
+commit in one `BillingStore` transaction.
+
+## Entitlements
+
+An entitlement is a grant made to a paying end user, configured by the tenant.
+The scope is an arbitrary subset of dimensions, and **the dimensions present are
+both the matcher and the lifetime**:
+
+| Scope | Meaning |
+|---|---|
+| `{ channelId }` | valid for the life of the channel |
+| `{ channelId, sessionId }` | valid only during that session |
+| `{ channelId, date }` | only for purchases settling that day; expires at end of it |
+| `{ channelId, sessionId, date }` | the narrowest form |
+
+Every dimension a rule names must match for the grant to be made. A grant is
+always made to a consumer, so a rule never grants "the channel" anything.
+
+## Wiring: one construction, nothing to remember
+
+`MonetizationDispatcher` is the intended entry point for outbox delivery, and it
+wires entitlement handling for you:
+
+```ts
+const dispatcher = new MonetizationDispatcher({
+  store: new PostgresBillingStore(pool),
+  entitlements: new PostgresEntitlementStore(pool),   // required
+  ids: { next: () => randomUUID() },
+  onEvent: (event, applied) => {
+    // your own side effects, e.g. publish a settled superchat to the live chat
+    if (event.type === "billing.purchase_settled") publishToChat(event.payload);
+  },
+});
+
+// on a schedule — a worker, a cron, or a loop
+const { delivered, failed, granted, revoked, withoutSession } = await dispatcher.drainOnce();
+```
+
+**Entitlement handling is unconditional.** `onEvent` is the optional part. There
+is no configuration in which a settled purchase silently fails to grant, because
+the alternative — constructing a `BillingOutboxDispatcher` and pointing its
+`publish` at `applySettlementEvent` — is a step whose omission produces no error.
+Use that path only if you are deliberately building your own delivery loop.
+
+`drainOnce` returns per-drain counters, not a running total. `withoutSession`
+counts settlements that arrived with no `sessionId`: a purchase with no session
+cannot match a session-scoped rule, so a non-zero count means either
+`sessionId` is not being passed at checkout, or sessions are unused. Both are
+worth seeing rather than inferring from a rule that never matches.
+
+A worker that stops is indistinguishable from a quiet platform, so:
+
+```ts
+if (dispatcher.isStale()) alert("monetization outbox is not draining");
+```
+
+Grants are **balances, not flags**. A rule nothing ever consumes stays
+permanently available, which is how a standing membership is expressed; a rule
+the application spends one unit at a time is how a single-use unlock is
+expressed. Both use the same primitive:
+
+```ts
+const store = new PostgresEntitlementStore(pool);
+
+await store.consume(consumerId, "prompt_influence", { channelId, sessionId }, 1);
+await store.remaining(consumerId, "founding_member", { channelId });
+```
+
+Rules are evaluated off the settlement outbox, so `billing.purchase_settled`
+carries every fact a rule can match on. Grants are keyed `(rule_id, purchase_id)`,
+so a redelivered event cannot double-grant. `purchase_refunded` and
+`purchase_disputed` revoke what a purchase created.
+
+## Persistence
+
+`PostgresBillingStore` (purchases, ledger, outbox) and
+`PostgresEntitlementStore` (rules, grants) are the provided adapters. Apply
+`sql/001_monetization.sql` first. Both sit behind small ports, so an application
+already using an ORM can implement them without `pg`.
+
+## Breaking changes in 0.2.0
+
+Renamed from `@portalshq/billing`. Money is now keyed on `tenantId` rather than
+`channelId`, so the `billing_*` tables are replaced rather than migrated —
+`sql/001_monetization.sql` is the new baseline. `ChannelBillingProfile` is now
+`TenantBillingProfile`, `createChannelCheckout` is `createCheckout`, and
+`ChannelPurchase` is `Purchase`. No production data was written against the
+Connect path before this release, so nothing required migrating.
+
+**Accounts v2 replaced the deprecated v1 accounts API**, and destination charges
+were retained (see "Destination charges, and why"):
+
+- `ensureTenantProfile` calls `stripe.v2.core.accounts.create` with a merchant
+  configuration. The deprecated `stripe.accounts.create({ type: "express" })`
+  form is not used anywhere.
+- Capability state is read from
+  `configuration.recipient.capabilities.stripe_balance.stripe_transfers.status`.
+  The v1 fields `charges_enabled`, `payouts_enabled`, and `details_submitted` are
+  gone, as are their columns.
+- `TenantBillingProfile` drops `stripeCustomerId` and the three v1 booleans,
+  gaining `stripeAccountId` and `transfersStatus`.
+- `createConnectOnboardingLink` uses the v2 `accountLinks` resource.
+- `createCheckout` sets `transfer_data.destination` and `integration_identifier`,
+  and accepts an optional `customerId` for the platform-held end user.
+- New: `verifySettlement`, `refreshTenantCapabilities`, `SettlementVerification`.
+- Checkout metadata `schemaVersion` is `3`.
+
+`StripePlatformBilling` and `createStripePlatformBilling` moved to
+`@portalshq/platform-billing`; they serve the platform's own B2B flows, not
+audience monetization.
+

package/dist/dispatcher.d.ts

@@ -0,0 +1,105 @@
+import type { BillingOutboxEvent, BillingStore, IdGenerator } from "./types.js";
+import { type EntitlementStore } from "./entitlements.js";
+/** What entitlement handling did to one outbox event. */
+export interface SettlementApplication {
+    granted: number;
+    revoked: number;
+    /**
+     * Set when the settlement carried no `sessionId`. A purchase with no session
+     * cannot match a session-scoped rule, so a non-zero count here means either
+     * the integration passes no `sessionId` at checkout, or sessions are not in
+     * use. Both are worth seeing rather than inferring.
+     */
+    withoutSession: boolean;
+}
+export interface MonetizationDispatcherOptions {
+    store: BillingStore;
+    /**
+     * Required. Entitlement handling is not optional: a paid purchase that never
+     * grants anything is a silent failure, not a configuration choice. Supply the
+     * store even if you have no rules yet — an empty rule set is a valid state and
+     * is recorded as such.
+     */
+    entitlements: EntitlementStore;
+    ids: IdGenerator;
+    /**
+     * Your own side effects, for example publishing a settled superchat to the
+     * live chat. Runs after entitlement handling, inside the same delivery, so a
+     * failure marks the event undelivered and it is retried. Never required.
+     */
+    onEvent?: (event: BillingOutboxEvent, applied: SettlementApplication) => void | Promise<void>;
+    now?: () => Date;
+    batchSize?: number;
+    /**
+     * Delivery attempts before an event is parked for an operator. Defaults to 10.
+     *
+     * A permanently-failing event would otherwise be re-claimed on every drain
+     * forever, and because `claimOutbox` orders by `created_at` it would occupy
+     * the first slots of every batch — so a few poison events degrade throughput
+     * and eventually stall the queue. Parking bounds that.
+     *
+     * Parking is not deletion: the row is retained with its payload and error, and
+     * `requeueDeadOutbox` replays it once the cause is fixed. Set this to a large
+     * number to prefer blocking-and-alerting over parking.
+     */
+    maxAttempts?: number;
+    logger?: (message: string, meta: Record<string, unknown>) => void;
+}
+export interface DrainResult {
+    delivered: number;
+    failed: number;
+    granted: number;
+    revoked: number;
+    /** Events parked this pass for an operator. Retained, not dropped. */
+    parked: number;
+    /** Events already past the attempt budget when claimed; parked without an attempt. */
+    exhausted: number;
+    /** Settlements that arrived without a `sessionId`. See `SettlementApplication`. */
+    withoutSession: number;
+}
+/**
+ * Outbox delivery with entitlement handling already wired in.
+ *
+ * This exists so that the correct wiring is the shortest path. Constructing a
+ * `BillingOutboxDispatcher` directly and pointing its `publish` at
+ * `applySettlementEvent` is possible but is the footgun that motivated this class:
+ * nothing failed when it was forgotten, entitlements simply never granted.
+ *
+ * Entitlement handling here is unconditional. `onEvent` is the optional part.
+ *
+ * Run `drainOnce` on a schedule. A worker that stops is indistinguishable from a
+ * quiet platform, so `isStale` is provided for a health check.
+ */
+export declare class MonetizationDispatcher {
+    private readonly options;
+    private readonly dispatcher;
+    private readonly now;
+    private readonly logger?;
+    private readonly maxAttempts;
+    private lastDrainAtMs;
+    private granted;
+    private revoked;
+    private withoutSession;
+    private parked;
+    private exhausted;
+    constructor(options: MonetizationDispatcherOptions);
+    /** @returns a sentinel so an unparseable payload fails delivery and is retried, not silently skipped. */
+    private applyToEntitlements;
+    drainOnce(): Promise<DrainResult>;
+    /**
+     * Returns parked events to the queue with a fresh attempt budget. Call this
+     * once the cause is fixed — a corrected rule, a repaired payload, a restored
+     * dependency. Without it, parking would be silent data loss.
+     */
+    requeueParked(limit?: number): Promise<number>;
+    /** Parked events awaiting an operator, with the error that parked them. */
+    listParked(limit?: number): Promise<readonly BillingOutboxEvent[]>;
+    /** ISO timestamp of the last drain, or undefined if it has never run. */
+    lastDrainAt(): string | undefined;
+    /**
+     * True when the dispatcher has never run, or has not run within `maxAgeMs`
+     * (default 10 minutes). A stopped worker and a quiet platform look identical
+     * from the outside; this is how they are told apart.
+     */
+    isStale(maxAgeMs?: number): boolean;
+}

package/dist/dispatcher.js

@@ -0,0 +1,138 @@
+import { BillingOutboxDispatcher } from "./outbox-dispatcher.js";
+import { applySettlementEvent, readSettlementFacts, } from "./entitlements.js";
+/**
+ * Outbox delivery with entitlement handling already wired in.
+ *
+ * This exists so that the correct wiring is the shortest path. Constructing a
+ * `BillingOutboxDispatcher` directly and pointing its `publish` at
+ * `applySettlementEvent` is possible but is the footgun that motivated this class:
+ * nothing failed when it was forgotten, entitlements simply never granted.
+ *
+ * Entitlement handling here is unconditional. `onEvent` is the optional part.
+ *
+ * Run `drainOnce` on a schedule. A worker that stops is indistinguishable from a
+ * quiet platform, so `isStale` is provided for a health check.
+ */
+export class MonetizationDispatcher {
+    options;
+    dispatcher;
+    now;
+    logger;
+    maxAttempts;
+    lastDrainAtMs;
+    granted = 0;
+    revoked = 0;
+    withoutSession = 0;
+    parked = 0;
+    exhausted = 0;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        this.logger = options.logger;
+        this.maxAttempts = options.maxAttempts ?? 10;
+        if (!Number.isInteger(this.maxAttempts) || this.maxAttempts < 1) {
+            throw new TypeError("maxAttempts must be a positive integer");
+        }
+        this.dispatcher = new BillingOutboxDispatcher({
+            store: options.store,
+            batchSize: options.batchSize,
+            // An event that is already past its budget is parked before any attempt,
+            // so it cannot consume a delivery slot and then fail again.
+            publish: async (event) => {
+                if (event.attempts > this.maxAttempts) {
+                    await options.store.markOutboxDead(event.id, `exceeded maxAttempts (${this.maxAttempts})`);
+                    this.exhausted += 1;
+                    this.logger?.("outbox event parked: attempts exhausted", {
+                        eventId: event.id, type: event.type, attempts: event.attempts,
+                    });
+                    return;
+                }
+                const applied = await this.applyToEntitlements(event);
+                this.granted += applied.granted;
+                this.revoked += applied.revoked;
+                if (applied.withoutSession)
+                    this.withoutSession += 1;
+                if (this.options.onEvent)
+                    await this.options.onEvent(event, applied);
+                if (applied.withoutSession) {
+                    this.logger?.("settlement arrived without a sessionId", {
+                        eventId: event.id, purchaseId: event.payload.purchaseId, type: event.type,
+                    });
+                }
+            },
+        });
+    }
+    /** @returns a sentinel so an unparseable payload fails delivery and is retried, not silently skipped. */
+    async applyToEntitlements(event) {
+        const base = { granted: 0, revoked: 0, withoutSession: false };
+        if (event.type !== "billing.purchase_settled"
+            && event.type !== "billing.purchase_refunded"
+            && event.type !== "billing.purchase_disputed") {
+            return base;
+        }
+        // Surface a malformed payload as a delivery failure rather than letting it
+        // pass: an event that cannot be evaluated must be retried and alerted, not
+        // marked delivered.
+        const withoutSession = event.type === "billing.purchase_settled"
+            && readSettlementFacts(event.payload).sessionId === null;
+        const result = await applySettlementEvent(this.options.entitlements, event, this.options.ids, this.now().toISOString());
+        return { ...base, ...result, withoutSession };
+    }
+    async drainOnce() {
+        // Counters are per-drain, not cumulative: a caller reading the result wants
+        // what this pass did, not a running total.
+        this.granted = 0;
+        this.revoked = 0;
+        this.withoutSession = 0;
+        this.parked = 0;
+        this.exhausted = 0;
+        const result = await this.dispatcher.drainOnce();
+        this.lastDrainAtMs = this.now().getTime();
+        if (this.parked > 0 || this.exhausted > 0) {
+            this.logger?.("outbox events parked for an operator", {
+                parked: this.parked, exhausted: this.exhausted, maxAttempts: this.maxAttempts,
+            });
+        }
+        if (result.failed > 0) {
+            this.logger?.("outbox delivery had failures", { failed: result.failed, delivered: result.delivered });
+        }
+        return {
+            delivered: result.delivered,
+            failed: result.failed,
+            granted: this.granted,
+            revoked: this.revoked,
+            parked: this.parked,
+            exhausted: this.exhausted,
+            withoutSession: this.withoutSession,
+        };
+    }
+    /**
+     * Returns parked events to the queue with a fresh attempt budget. Call this
+     * once the cause is fixed — a corrected rule, a repaired payload, a restored
+     * dependency. Without it, parking would be silent data loss.
+     */
+    async requeueParked(limit = 100) {
+        const requeued = await this.options.store.requeueDeadOutbox(limit);
+        if (requeued > 0)
+            this.logger?.("requeued parked outbox events", { requeued });
+        return requeued;
+    }
+    /** Parked events awaiting an operator, with the error that parked them. */
+    async listParked(limit = 100) {
+        return this.options.store.listDeadOutbox(limit);
+    }
+    /** ISO timestamp of the last drain, or undefined if it has never run. */
+    lastDrainAt() {
+        return this.lastDrainAtMs === undefined ? undefined : new Date(this.lastDrainAtMs).toISOString();
+    }
+    /**
+     * True when the dispatcher has never run, or has not run within `maxAgeMs`
+     * (default 10 minutes). A stopped worker and a quiet platform look identical
+     * from the outside; this is how they are told apart.
+     */
+    isStale(maxAgeMs = 10 * 60_000) {
+        if (this.lastDrainAtMs === undefined)
+            return true;
+        return this.now().getTime() - this.lastDrainAtMs > maxAgeMs;
+    }
+}

package/dist/entitlements.d.ts

@@ -0,0 +1,155 @@
+import type { IdGenerator, PurchaseSettledFacts } from "./types.js";
+/**
+ * Tenant-configured entitlements.
+ *
+ * An entitlement is a grant made to a paying end user ("consumer"), scoped by
+ * a set of dimensions. A rule is owned and configured by the tenant, not the
+ * platform: the channel owner decides what a purchase unlocks and for how long.
+ *
+ * The scope is an arbitrary subset of dimensions, and **the dimensions present
+ * are both the matcher and the lifetime**:
+ *
+ *   { channelId }                  → valid for the life of the channel
+ *   { channelId, sessionId }       → valid only during that session
+ *   { channelId, date }            → valid only for purchases settling that day,
+ *                                    and expires at the end of it
+ *   { channelId, sessionId, date } → the narrowest form
+ *
+ * Every dimension a rule names must match for the grant to be made. A grant
+ * is always made to a consumer, so a rule never grants "the channel" anything.
+ *
+ * Grants are balances, not flags. A rule that nothing ever consumes stays
+ * permanently available, which is how a standing membership is expressed, and
+ * a rule the application consumes one unit at a time is how a single-use
+ * unlock is expressed. Both use the same primitive.
+ */
+/**
+ * A scope dimension whose value is this token binds to the matching fact of the
+ * purchase at grant time, instead of being compared literally.
+ *
+ * A superchat grants influence over the story turn it was bought for, so its
+ * rule must be scoped to "whichever session this purchase happened in" — a
+ * fixed session id could never match. `"$self"` says bind; the grant then carries
+ * the concrete value and normal equality applies at consumption.
+ */
+export declare const SELF_BIND = "$self";
+export interface EntitlementScope {
+    channelId?: string;
+    sessionId?: string;
+    /** ISO `yyyy-mm-dd` (UTC). Restricts the rule to purchases settling that day. */
+    date?: string;
+}
+/**
+ * Replaces self-binding dimensions with the concrete facts, producing the scope
+ * the grant is actually scoped to. A binding dimension with no corresponding
+ * fact is dropped, so a purchase with no session yields an unscoped grant rather
+ * than a permanently unsatisfiable one.
+ */
+export declare function resolveScope(scope: EntitlementScope, facts: PurchaseSettledFacts): EntitlementScope;
+export type EntitlementCondition = {
+    fact: "purchaseKind";
+    equals: string;
+} | {
+    fact: "productKey";
+    equals: string;
+} | {
+    fact: "amount";
+    gte: number;
+};
+export interface EntitlementRule {
+    id: string;
+    tenantId: string;
+    /** What is granted, e.g. "prompt_influence" or "founding_member". */
+    kind: string;
+    scope: EntitlementScope;
+    /** All must match. Empty means the rule matches any settled purchase. */
+    conditions: readonly EntitlementCondition[];
+    /** Units granted per qualifying purchase. Must be >= 1. */
+    quantity: number;
+    createdAt: string;
+}
+export interface EntitlementGrant {
+    id: string;
+    ruleId: string;
+    tenantId: string;
+    /** The end user who paid. */
+    consumerId: string;
+    kind: string;
+    scope: EntitlementScope;
+    quantity: number;
+    remaining: number;
+    /** The purchase that created this grant, so a refund can revoke it. */
+    purchaseId: string;
+    /** End of `scope.date` when the rule named one, else undefined. */
+    expiresAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EntitlementStore {
+    saveRule(rule: EntitlementRule): Promise<void>;
+    getRule(id: string): Promise<EntitlementRule | undefined>;
+    listRules(tenantId: string): Promise<readonly EntitlementRule[]>;
+    /** Idempotent per `(ruleId, purchaseId)` so a redelivered outbox event cannot double-grant. */
+    grant(grants: readonly EntitlementGrant[]): Promise<void>;
+    /**
+     * Spend `n` units at a site. Consumes the oldest applicable grant with
+     * units remaining. Returns false when nothing is available.
+     */
+    consume(consumerId: string, kind: string, site: EntitlementScope, n: number): Promise<boolean>;
+    /** Units available at a site. */
+    remaining(consumerId: string, kind: string, site: EntitlementScope): Promise<number>;
+    /** Revoke everything a purchase created, for refunds and disputes. */
+    revokeForPurchase(purchaseId: string): Promise<void>;
+}
+/** End of the UTC day named by `scope.date`, or undefined when the rule is not date-bounded. */
+export declare function scopeExpiresAt(scope: EntitlementScope): string | undefined;
+/**
+ * A grant is usable at a site when every dimension it names matches the site's
+ * facts. A channel-scoped grant is therefore valid anywhere in that channel,
+ * and a session-scoped grant only inside that session.
+ */
+export declare function grantAppliesAt(grantScope: EntitlementScope, site: EntitlementScope): boolean;
+/** Every dimension named by the rule and every condition must match. */
+export declare function ruleMatches(rule: EntitlementRule, facts: PurchaseSettledFacts): boolean;
+/** Grants a settled purchase should create, one per matching rule for that tenant. */
+export declare function grantsForSettlement(rules: readonly EntitlementRule[], facts: PurchaseSettledFacts, ids: IdGenerator, now: string): EntitlementGrant[];
+/** Rejects rules the engine cannot honour, so a bad rule fails at configuration time. */
+export declare function validateRule(rule: EntitlementRule): void;
+/** Reference store for tests and single-process deployments. */
+export declare class InMemoryEntitlementStore implements EntitlementStore {
+    private readonly rules;
+    private readonly grants;
+    private readonly granted;
+    saveRule(rule: EntitlementRule): Promise<void>;
+    getRule(id: string): Promise<EntitlementRule | undefined>;
+    listRules(tenantId: string): Promise<readonly EntitlementRule[]>;
+    grant(grants: readonly EntitlementGrant[]): Promise<void>;
+    consume(consumerId: string, kind: string, site: EntitlementScope, n: number): Promise<boolean>;
+    remaining(consumerId: string, kind: string, site: EntitlementScope): Promise<number>;
+    revokeForPurchase(purchaseId: string): Promise<void>;
+}
+/**
+ * Applies a settlement outbox event to the entitlement store.
+ *
+ * This is the piece that makes entitlements actually run. `BillingOutboxDispatcher`
+ * delivers each committed event to a `publish` callback; wiring that callback to
+ * this function is what grants on settlement and revokes on refund or dispute.
+ *
+ * Returns the grants created, or the number revoked, so a caller can log or
+ * assert. Safe to call twice for the same event: grants are keyed
+ * `(ruleId, purchaseId)` and revocation is idempotent.
+ */
+export declare function applySettlementEvent(store: EntitlementStore, event: {
+    type: string;
+    payload: Readonly<Record<string, unknown>>;
+}, ids: IdGenerator, now: string): Promise<{
+    granted: number;
+    revoked: number;
+}>;
+/**
+ * Narrows an outbox payload to settlement facts, rejecting a payload that cannot
+ * support rule evaluation. The payload carries `schemaVersion: "2"` in its
+ * checkout metadata; a payload without the newer fields predates entitlements
+ * and is rejected rather than silently matched against missing values.
+ */
+export declare function readSettlementFacts(payload: Readonly<Record<string, unknown>>): PurchaseSettledFacts;