@portalshq/monetization 0.2.0

package/dist/postgres-store.js

@@ -0,0 +1,276 @@
+import { grantAppliesAt, validateRule } from "./entitlements.js";
+/** Durable PostgreSQL adapter. Apply sql/001_monetization.sql before use. */
+export class PostgresBillingStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async getTenantProfile(tenantId) {
+        const result = await this.pool.query("SELECT * FROM monetization_tenant_profiles WHERE tenant_id = $1", [tenantId]);
+        return result.rows[0] ? profileFromRow(result.rows[0]) : undefined;
+    }
+    async findTenantProfileByAccount(accountId) {
+        const result = await this.pool.query("SELECT * FROM monetization_tenant_profiles WHERE stripe_account_id = $1", [accountId]);
+        return result.rows[0] ? profileFromRow(result.rows[0]) : undefined;
+    }
+    async getBillingCustomer(buyerId) {
+        const { rows } = await this.pool.query(`SELECT stripe_customer_id FROM monetization_billing_customers WHERE buyer_id = $1`, [buyerId]);
+        return rows[0]?.stripe_customer_id;
+    }
+    async saveBillingCustomer(buyerId, stripeCustomerId, createdAt) {
+        await this.pool.query(`INSERT INTO monetization_billing_customers (buyer_id, stripe_customer_id, created_at)
+       VALUES ($1,$2,$3)
+       ON CONFLICT (buyer_id) DO UPDATE SET stripe_customer_id = EXCLUDED.stripe_customer_id`, [buyerId, stripeCustomerId, createdAt]);
+    }
+    async saveTenantProfile(profile) {
+        await saveProfile(this.pool, profile);
+    }
+    async createPurchase(purchase) {
+        await savePurchase(this.pool, purchase);
+        return purchase;
+    }
+    async getPurchase(id) {
+        const result = await this.pool.query("SELECT * FROM monetization_purchases WHERE id = $1", [id]);
+        return result.rows[0] ? purchaseFromRow(result.rows[0]) : undefined;
+    }
+    async findPurchaseByStripeReference(reference) {
+        if (!reference)
+            return undefined;
+        const result = await this.pool.query(`SELECT * FROM monetization_purchases
+       WHERE stripe_checkout_session_id = $1 OR stripe_payment_intent_id = $1
+          OR stripe_charge_id = $1 OR stripe_transfer_id = $1
+       LIMIT 1`, [reference]);
+        return result.rows[0] ? purchaseFromRow(result.rows[0]) : undefined;
+    }
+    async processStripeEvent(event, apply) {
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            const claimed = await client.query("INSERT INTO monetization_stripe_events (id, type, created_at) VALUES ($1, $2, to_timestamp($3)) ON CONFLICT DO NOTHING RETURNING id", [event.id, event.type, event.created]);
+            if (claimed.rowCount === 0) {
+                await client.query("ROLLBACK");
+                return "duplicate";
+            }
+            await apply(new PostgresBillingTransaction(client));
+            await client.query("UPDATE monetization_stripe_events SET processed_at = now() WHERE id = $1", [event.id]);
+            await client.query("COMMIT");
+            return "processed";
+        }
+        catch (cause) {
+            await client.query("ROLLBACK");
+            throw cause;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async claimOutbox(limit) {
+        const result = await this.pool.query(`UPDATE monetization_outbox SET claimed_at = now(), attempts = attempts + 1
+       WHERE id IN (
+         SELECT id FROM monetization_outbox
+         WHERE delivered_at IS NULL AND dead_at IS NULL
+           AND (claimed_at IS NULL OR claimed_at < now() - interval '5 minutes')
+         ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT $1
+       ) RETURNING *`, [limit]);
+        return result.rows.map(outboxFromRow);
+    }
+    async completeOutbox(id) {
+        await this.pool.query("UPDATE monetization_outbox SET delivered_at = now(), claimed_at = NULL, last_error = NULL WHERE id = $1", [id]);
+    }
+    async failOutbox(id, error) {
+        await this.pool.query("UPDATE monetization_outbox SET claimed_at = NULL, last_error = $2 WHERE id = $1", [id, error.slice(0, 2_000)]);
+    }
+    /**
+     * Parks the event rather than deleting it. `last_error` is kept and the claim
+     * is released, so an operator can see what failed and replay it once fixed.
+     */
+    async markOutboxDead(id, error) {
+        await this.pool.query("UPDATE monetization_outbox SET dead_at = now(), claimed_at = NULL, last_error = $2 WHERE id = $1", [id, error.slice(0, 2_000)]);
+    }
+    async listDeadOutbox(limit) {
+        const result = await this.pool.query("SELECT * FROM monetization_outbox WHERE dead_at IS NOT NULL ORDER BY created_at LIMIT $1", [limit]);
+        return result.rows.map(outboxFromRow);
+    }
+    async requeueDeadOutbox(limit) {
+        const result = await this.pool.query(`UPDATE monetization_outbox SET dead_at = NULL, attempts = 0, claimed_at = NULL
+       WHERE id IN (
+         SELECT id FROM monetization_outbox
+         WHERE dead_at IS NOT NULL
+         ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT $1
+       ) RETURNING id`, [limit]);
+        return result.rowCount ?? 0;
+    }
+}
+class PostgresBillingTransaction {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async getPurchase(id) {
+        const result = await this.client.query("SELECT * FROM monetization_purchases WHERE id = $1 FOR UPDATE", [id]);
+        return result.rows[0] ? purchaseFromRow(result.rows[0]) : undefined;
+    }
+    async findPurchaseByStripeReference(reference) {
+        if (!reference)
+            return undefined;
+        const result = await this.client.query(`SELECT * FROM monetization_purchases
+       WHERE stripe_checkout_session_id = $1 OR stripe_payment_intent_id = $1 OR stripe_charge_id = $1 OR stripe_transfer_id = $1
+       LIMIT 1 FOR UPDATE`, [reference]);
+        return result.rows[0] ? purchaseFromRow(result.rows[0]) : undefined;
+    }
+    async savePurchase(purchase) { await savePurchase(this.client, purchase); }
+    async saveTenantProfile(profile) { await saveProfile(this.client, profile); }
+    async appendLedger(entry) {
+        await this.client.query(`INSERT INTO monetization_ledger (id, purchase_id, stripe_event_id, kind, amount, currency, stripe_fee, net, metadata, created_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10) ON CONFLICT (id) DO NOTHING`, [entry.id, entry.purchaseId, entry.stripeEventId ?? null, entry.kind, entry.amount, entry.currency, entry.stripeFee ?? null, entry.net ?? null, entry.metadata ?? {}, entry.createdAt]);
+    }
+    async appendOutbox(event) {
+        await this.client.query(`INSERT INTO monetization_outbox (id, type, aggregate_id, payload, created_at) VALUES ($1,$2,$3,$4,$5) ON CONFLICT (id) DO NOTHING`, [event.id, event.type, event.aggregateId, event.payload, event.createdAt]);
+    }
+}
+async function saveProfile(db, profile) {
+    await db.query(`INSERT INTO monetization_tenant_profiles
+      (tenant_id, owner_id, stripe_account_id, transfers_status, default_currency, country, created_at, updated_at)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
+     ON CONFLICT (tenant_id) DO UPDATE SET owner_id=EXCLUDED.owner_id, stripe_account_id=EXCLUDED.stripe_account_id,
+       transfers_status=EXCLUDED.transfers_status, default_currency=EXCLUDED.default_currency,
+       country=EXCLUDED.country, updated_at=EXCLUDED.updated_at`, [profile.tenantId, profile.ownerId, profile.stripeAccountId, profile.transfersStatus,
+        profile.defaultCurrency, profile.country ?? null, profile.createdAt, profile.updatedAt]);
+}
+async function savePurchase(db, purchase) {
+    await db.query(`INSERT INTO monetization_purchases
+      (id, tenant_id, channel_id, session_id, buyer_id, customer_id, product_key, kind, amount, currency,
+       platform_fee_amount, state, stripe_checkout_session_id, stripe_payment_intent_id, stripe_charge_id,
+       stripe_transfer_id, stripe_application_fee_id, refunded_amount, settled_at, created_at, updated_at)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21)
+     ON CONFLICT (id) DO UPDATE SET state=EXCLUDED.state, stripe_checkout_session_id=EXCLUDED.stripe_checkout_session_id,
+       stripe_payment_intent_id=EXCLUDED.stripe_payment_intent_id, stripe_charge_id=EXCLUDED.stripe_charge_id,
+       stripe_transfer_id=EXCLUDED.stripe_transfer_id, stripe_application_fee_id=EXCLUDED.stripe_application_fee_id,
+       refunded_amount=EXCLUDED.refunded_amount, settled_at=EXCLUDED.settled_at, updated_at=EXCLUDED.updated_at`, [purchase.id, purchase.tenantId, purchase.channelId, purchase.sessionId ?? null, purchase.buyerId,
+        purchase.customerId ?? null, purchase.productKey, purchase.kind, purchase.amount, purchase.currency, purchase.platformFeeAmount, purchase.state,
+        purchase.stripeCheckoutSessionId ?? null, purchase.stripePaymentIntentId ?? null, purchase.stripeChargeId ?? null,
+        purchase.stripeTransferId ?? null, purchase.stripeApplicationFeeId ?? null, purchase.refundedAmount,
+        purchase.settledAt ?? null, purchase.createdAt, purchase.updatedAt]);
+}
+function profileFromRow(row) {
+    return { tenantId: row.tenant_id, ownerId: row.owner_id, stripeAccountId: row.stripe_account_id,
+        transfersStatus: row.transfers_status, defaultCurrency: row.default_currency,
+        ...(row.country ? { country: row.country } : {}), createdAt: iso(row.created_at), updatedAt: iso(row.updated_at) };
+}
+function purchaseFromRow(row) {
+    return { id: row.id, tenantId: row.tenant_id, channelId: row.channel_id,
+        ...(row.session_id ? { sessionId: row.session_id } : {}), buyerId: row.buyer_id,
+        ...(row.customer_id ? { customerId: row.customer_id } : {}),
+        productKey: row.product_key, kind: row.kind, amount: Number(row.amount), currency: row.currency,
+        platformFeeAmount: Number(row.platform_fee_amount), state: row.state,
+        ...(row.stripe_checkout_session_id ? { stripeCheckoutSessionId: row.stripe_checkout_session_id } : {}),
+        ...(row.stripe_payment_intent_id ? { stripePaymentIntentId: row.stripe_payment_intent_id } : {}),
+        ...(row.stripe_charge_id ? { stripeChargeId: row.stripe_charge_id } : {}),
+        ...(row.stripe_transfer_id ? { stripeTransferId: row.stripe_transfer_id } : {}),
+        ...(row.stripe_application_fee_id ? { stripeApplicationFeeId: row.stripe_application_fee_id } : {}),
+        refundedAmount: Number(row.refunded_amount), ...(row.settled_at ? { settledAt: iso(row.settled_at) } : {}),
+        createdAt: iso(row.created_at), updatedAt: iso(row.updated_at) };
+}
+function outboxFromRow(row) {
+    return {
+        id: row.id, type: row.type, aggregateId: row.aggregate_id, payload: row.payload,
+        createdAt: iso(row.created_at), attempts: Number(row.attempts ?? 0),
+        ...(row.last_error ? { lastError: row.last_error } : {}),
+        ...(row.dead_at ? { deadAt: iso(row.dead_at) } : {}),
+    };
+}
+function iso(value) { return value instanceof Date ? value.toISOString() : new Date(value).toISOString(); }
+/**
+ * Durable entitlement store. Grants are keyed `(rule_id, purchase_id)` so a
+ * redelivered settlement outbox event cannot double-grant, and `consume` takes
+ * a row lock per grant so two concurrent consumers cannot both spend the last
+ * unit.
+ */
+export class PostgresEntitlementStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async saveRule(rule) {
+        validateRule(rule);
+        await this.pool.query(`INSERT INTO monetization_entitlement_rules
+        (id, tenant_id, kind, scope, conditions, quantity, created_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7)
+       ON CONFLICT (id) DO UPDATE SET kind=EXCLUDED.kind, scope=EXCLUDED.scope,
+         conditions=EXCLUDED.conditions, quantity=EXCLUDED.quantity`, [rule.id, rule.tenantId, rule.kind, rule.scope, rule.conditions, rule.quantity, rule.createdAt]);
+    }
+    async getRule(id) {
+        const result = await this.pool.query("SELECT * FROM monetization_entitlement_rules WHERE id = $1", [id]);
+        return result.rows[0] ? ruleFromRow(result.rows[0]) : undefined;
+    }
+    async listRules(tenantId) {
+        const result = await this.pool.query("SELECT * FROM monetization_entitlement_rules WHERE tenant_id = $1 ORDER BY created_at", [tenantId]);
+        return result.rows.map(ruleFromRow);
+    }
+    async grant(grants) {
+        if (grants.length === 0)
+            return;
+        const values = [];
+        const tuples = grants.map((grant, index) => {
+            const at = index * 10;
+            values.push(grant.id, grant.ruleId, grant.tenantId, grant.consumerId, grant.kind, grant.scope, grant.quantity, grant.remaining, grant.purchaseId, grant.expiresAt ?? null);
+            return `($${at + 1},$${at + 2},$${at + 3},$${at + 4},$${at + 5},$${at + 6},$${at + 7},$${at + 8},$${at + 9},$${at + 10}, now(), now())`;
+        });
+        await this.pool.query(`INSERT INTO monetization_entitlements
+        (id, rule_id, tenant_id, consumer_id, kind, scope, quantity, remaining, purchase_id, expires_at, created_at, updated_at)
+       VALUES ${tuples.join(",")}
+       ON CONFLICT (rule_id, purchase_id) DO NOTHING`, values);
+    }
+    async consume(consumerId, kind, site, n) {
+        if (!Number.isInteger(n) || n < 1)
+            throw new TypeError("consume count must be a positive integer");
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            // Plain FOR UPDATE, not SKIP LOCKED: skipping locked rows would let two
+            // concurrent consumers each see a partial balance, both conclude there is
+            // enough, and both commit — spending the last unit twice. Serializing here
+            // costs throughput on a low-frequency path and buys correctness.
+            const candidates = await client.query(`SELECT id, scope, remaining FROM monetization_entitlements
+         WHERE consumer_id = $1 AND kind = $2 AND remaining > 0
+           AND (expires_at IS NULL OR expires_at >= now())
+         ORDER BY created_at FOR UPDATE`, [consumerId, kind]);
+            const applicable = candidates.rows.filter((row) => grantAppliesAt(row.scope, site));
+            const available = applicable.reduce((total, row) => total + Number(row.remaining), 0);
+            if (available < n) {
+                await client.query("ROLLBACK");
+                return false;
+            }
+            let owed = n;
+            for (const row of applicable) {
+                if (owed === 0)
+                    break;
+                const taken = Math.min(owed, Number(row.remaining));
+                await client.query("UPDATE monetization_entitlements SET remaining = remaining - $2, updated_at = now() WHERE id = $1", [row.id, taken]);
+                owed -= taken;
+            }
+            await client.query("COMMIT");
+            return true;
+        }
+        catch (cause) {
+            await client.query("ROLLBACK");
+            throw cause;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async remaining(consumerId, kind, site) {
+        const result = await this.pool.query(`SELECT scope, remaining FROM monetization_entitlements
+       WHERE consumer_id = $1 AND kind = $2 AND (expires_at IS NULL OR expires_at >= now())`, [consumerId, kind]);
+        return result.rows
+            .filter((row) => grantAppliesAt(row.scope, site))
+            .reduce((total, row) => total + Number(row.remaining), 0);
+    }
+    async revokeForPurchase(purchaseId) {
+        await this.pool.query("DELETE FROM monetization_entitlements WHERE purchase_id = $1", [purchaseId]);
+    }
+}
+function ruleFromRow(row) {
+    return { id: row.id, tenantId: row.tenant_id, kind: row.kind, scope: row.scope, conditions: row.conditions, quantity: Number(row.quantity), createdAt: iso(row.created_at) };
+}

package/dist/stripe-client.d.ts

@@ -0,0 +1,9 @@
+import Stripe from "stripe";
+/**
+ * Minimal Stripe client factory.
+ *
+ * `platform-billing` carries its own equivalent for the platform B2B paths.
+ * The duplication is deliberate: it is three validated lines, and sharing it
+ * would force one of the two sibling packages to depend on the other.
+ */
+export declare function createStripePlatformClient(secretKey: string): Stripe;

package/dist/stripe-client.js

@@ -0,0 +1,14 @@
+import Stripe from "stripe";
+/**
+ * Minimal Stripe client factory.
+ *
+ * `platform-billing` carries its own equivalent for the platform B2B paths.
+ * The duplication is deliberate: it is three validated lines, and sharing it
+ * would force one of the two sibling packages to depend on the other.
+ */
+export function createStripePlatformClient(secretKey) {
+    const normalized = secretKey.trim();
+    if (!normalized)
+        throw new TypeError("Stripe secret key is required");
+    return new Stripe(normalized);
+}

package/dist/stripe-connect-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Stripe Connect wrapper for marketplace provider payouts.
+ * Uses Stripe Connect's Transfers API, not Payouts — Transfers go to
+ * connected accounts (your providers), not to external bank accounts.
+ * That distinction matters: Transfers happen instantly within Stripe;
+ * Payouts (connected account → bank) happen on the provider's schedule.
+ *
+ * STRIPE_SECRET_KEY is resolved at the application boundary and injected via
+ * the constructor. The platform's own Stripe account holds the credential; each
+ * *tenant's* destination account is a Connect account id held in
+ * `monetization_tenant_profiles`, not a separate secret. Never hardcode either.
+ */
+export interface ConnectTransfer {
+    amount: number;
+    currency: string;
+    destination: string;
+    transferGroup?: string;
+    metadata?: Record<string, string>;
+}
+export declare class StripeConnectClient {
+    private secretKey;
+    /**
+     * The secret key is required by injection. This package never reads the
+     * environment: the application boundary resolves the credential and hands it
+     * over, so a library can never quietly pick up an ambient key, and tests
+     * cannot be influenced by one.
+     */
+    constructor(secretKey: string);
+    /**
+     * Transfer provider payout to their connected Stripe account.
+     * Call AFTER the platform has collected the gross amount from the buyer —
+     * transfer only the net after rake and Stripe Connect fee.
+     */
+    transferToProvider(transfer: ConnectTransfer): Promise<{
+        transferId: string;
+    }>;
+    /**
+     * Execute all royalty splits from calculateRoyaltySplits() as a single
+     * transfer group so they're traceable together in the Stripe dashboard.
+     */
+    executeRoyaltySplits(splits: Array<{
+        stripeAccountId: string;
+        amountCents: number;
+    }>, currency: string, groupId: string): Promise<string[]>;
+}

package/dist/stripe-connect-client.js

@@ -0,0 +1,75 @@
+/**
+ * Stripe Connect wrapper for marketplace provider payouts.
+ * Uses Stripe Connect's Transfers API, not Payouts — Transfers go to
+ * connected accounts (your providers), not to external bank accounts.
+ * That distinction matters: Transfers happen instantly within Stripe;
+ * Payouts (connected account → bank) happen on the provider's schedule.
+ *
+ * STRIPE_SECRET_KEY is resolved at the application boundary and injected via
+ * the constructor. The platform's own Stripe account holds the credential; each
+ * *tenant's* destination account is a Connect account id held in
+ * `monetization_tenant_profiles`, not a separate secret. Never hardcode either.
+ */
+export class StripeConnectClient {
+    secretKey;
+    /**
+     * The secret key is required by injection. This package never reads the
+     * environment: the application boundary resolves the credential and hands it
+     * over, so a library can never quietly pick up an ambient key, and tests
+     * cannot be influenced by one.
+     */
+    constructor(secretKey) {
+        const normalized = secretKey.trim();
+        if (!normalized)
+            throw new TypeError("Stripe secret key is required");
+        this.secretKey = normalized;
+    }
+    /**
+     * Transfer provider payout to their connected Stripe account.
+     * Call AFTER the platform has collected the gross amount from the buyer —
+     * transfer only the net after rake and Stripe Connect fee.
+     */
+    async transferToProvider(transfer) {
+        const res = await fetch("https://api.stripe.com/v1/transfers", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.secretKey}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: new URLSearchParams({
+                amount: String(transfer.amount),
+                currency: transfer.currency,
+                destination: transfer.destination,
+                ...(transfer.transferGroup ? { transfer_group: transfer.transferGroup } : {}),
+                ...(transfer.metadata
+                    ? Object.fromEntries(Object.entries(transfer.metadata).map(([k, v]) => [`metadata[${k}]`, v]))
+                    : {}),
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`Stripe Connect transfer failed: ${await res.text()}`);
+        }
+        const data = (await res.json());
+        return { transferId: data.id };
+    }
+    /**
+     * Execute all royalty splits from calculateRoyaltySplits() as a single
+     * transfer group so they're traceable together in the Stripe dashboard.
+     */
+    async executeRoyaltySplits(splits, currency, groupId) {
+        const transferIds = [];
+        for (const split of splits) {
+            if (split.amountCents <= 0)
+                continue;
+            const { transferId } = await this.transferToProvider({
+                amount: split.amountCents,
+                currency,
+                destination: split.stripeAccountId,
+                transferGroup: groupId,
+                metadata: { royaltyGroup: groupId },
+            });
+            transferIds.push(transferId);
+        }
+        return transferIds;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,225 @@
+import type Stripe from "stripe";
+export type PurchaseKind = "super_chat" | "tip" | "channel_product" | (string & {});
+export type PurchaseState = "pending" | "checkout_created" | "settled" | "failed" | "partially_refunded" | "refunded" | "disputed";
+/**
+ * v2 capability status for the tenant's recipient configuration. Read from
+ * `account.configuration.recipient.capabilities.stripe_balance.stripe_transfers.status`.
+ * The v1 fields `payouts_enabled` / `charges_enabled` are deprecated and unused.
+ */
+export type TransfersStatus = "active" | "inactive" | "pending";
+/**
+ * One Connect account per tenant, created via Accounts v2 as a **recipient**
+ * for destination charges.
+ *
+ * The end user's `Customer` and payment method live on the **platform** account,
+ * not the tenant's. A consumer provides payment details once and the same
+ * payment method is reused for every tenant they pay, which is the reason
+ * destination charges are used rather than direct charges. Funds transfer to the
+ * tenant on payment success; `application_fee_amount` is the platform's rake.
+ *
+ * `losses_collector: "application"` is required here — it is what makes dispute
+ * transfer reversals possible — so the platform is merchant of record and
+ * carries negative-balance and dispute liability across tenant volume.
+ */
+export interface TenantBillingProfile {
+    tenantId: string;
+    ownerId: string;
+    /** The tenant's connected account, the destination for transfers. */
+    stripeAccountId: string;
+    transfersStatus: TransfersStatus;
+    defaultCurrency: string;
+    country?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Something a tenant sells.
+ *
+ * Named `Product` rather than `BillingCatalogItem` because it is the tenant's
+ * product, not a billing implementation detail: the catalog is just where the
+ * platform looks it up by key. `key` is the tenant-local identifier the buyer
+ * and the purchase record refer to; it need not be globally unique.
+ */
+export interface Product {
+    /** Tenant-local identifier. What `CreateCheckoutInput.productKey` names. */
+    key: string;
+    purchaseKind: PurchaseKind;
+    name: string;
+    /**
+     * Tenant-authored copy for this product, e.g. what the buyer gets. Carried so
+     * a catalog can be rendered to a buyer without a second parallel map. The
+     * platform does not interpret it.
+     */
+    description?: string;
+    unitAmount: number;
+    currency: string;
+    /**
+     * Rake withheld via `application_fee_amount`. On direct charges the tenant
+     * creates the charge, so it chooses this value; `verifySettlement` checks
+     * what Stripe actually recorded before anything is granted or settled.
+     */
+    platformFeeAmount: number;
+    stripePriceId?: string;
+    refundApplicationFee?: boolean;
+}
+/** Where the platform looks up the tenant's products by key. */
+export interface BillingCatalog {
+    resolve(productKey: string): Product;
+}
+/**
+ * @deprecated Use {@link Product}. Retained so existing catalogs keep compiling.
+ */
+export type BillingCatalogItem = Product;
+/**
+ * One audience payment. `tenantId` decides where the money goes; `channelId`
+ * is attribution only. Both are kept because a tenant's revenue rollup is
+ * reported per channel but paid per tenant.
+ */
+export interface Purchase {
+    id: string;
+    tenantId: string;
+    channelId: string;
+    /** Fact for session-scoped entitlement rules. Absent when the purchase did not occur in a session. */
+    sessionId?: string;
+    /** The end user who paid. Distinct from `tenantId`, which receives the money. */
+    buyerId: string;
+    /**
+     * The platform-account `Customer` for this end user. Customers and payment
+     * methods live on the platform, not per tenant, so one payment method is
+     * reused across every tenant this consumer pays.
+     */
+    customerId?: string;
+    productKey: string;
+    kind: PurchaseKind;
+    amount: number;
+    currency: string;
+    platformFeeAmount: number;
+    state: PurchaseState;
+    stripeCheckoutSessionId?: string;
+    stripePaymentIntentId?: string;
+    stripeChargeId?: string;
+    /** The Connect transfer to the tenant. Reversed on dispute, per Connect's model. */
+    stripeTransferId?: string;
+    stripeApplicationFeeId?: string;
+    refundedAmount: number;
+    /** Set when the purchase reaches `settled`. Fact for date-scoped entitlement rules. */
+    settledAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BillingLedgerEntry {
+    id: string;
+    purchaseId: string;
+    stripeEventId?: string;
+    kind: "settlement" | "refund" | "dispute" | "transfer_reversal";
+    amount: number;
+    currency: string;
+    stripeFee?: number;
+    net?: number;
+    metadata?: Readonly<Record<string, string>>;
+    createdAt: string;
+}
+export type BillingOutboxEventType = "billing.purchase_settled" | "billing.purchase_refunded" | "billing.purchase_disputed";
+export interface BillingOutboxEvent {
+    id: string;
+    type: BillingOutboxEventType;
+    aggregateId: string;
+    payload: Readonly<Record<string, unknown>>;
+    createdAt: string;
+    /** How many times this event has been claimed for delivery. */
+    attempts: number;
+    /** Why the last delivery attempt failed, truncated by the store. */
+    lastError?: string;
+    /** Set when the event exceeded its attempt budget and was parked for an operator. */
+    deadAt?: string;
+}
+/** Every fact an outbox payload must carry for entitlement rules to be evaluable. */
+export interface PurchaseSettledFacts {
+    purchaseId: string;
+    tenantId: string;
+    channelId: string;
+    sessionId: string | null;
+    buyerId: string;
+    kind: string;
+    productKey: string;
+    amount: number;
+    currency: string;
+    settledAt: string;
+}
+export interface BillingTransaction {
+    getPurchase(id: string): Promise<Purchase | undefined>;
+    findPurchaseByStripeReference(reference: string): Promise<Purchase | undefined>;
+    savePurchase(purchase: Purchase): Promise<void>;
+    saveTenantProfile(profile: TenantBillingProfile): Promise<void>;
+    appendLedger(entry: BillingLedgerEntry): Promise<void>;
+    appendOutbox(event: BillingOutboxEvent): Promise<void>;
+}
+export interface BillingStore {
+    /**
+     * Returns this consumer's platform-held Customer id, or undefined if they have
+     * never checked out. Consumers are platform-scoped, not tenant-scoped.
+     */
+    getBillingCustomer(buyerId: string): Promise<string | undefined>;
+    /** Records the Customer created for a consumer. Idempotent per buyer. */
+    saveBillingCustomer(buyerId: string, stripeCustomerId: string, createdAt: string): Promise<void>;
+    getTenantProfile(tenantId: string): Promise<TenantBillingProfile | undefined>;
+    findTenantProfileByAccount(accountId: string): Promise<TenantBillingProfile | undefined>;
+    saveTenantProfile(profile: TenantBillingProfile): Promise<void>;
+    createPurchase(purchase: Purchase): Promise<Purchase>;
+    getPurchase(id: string): Promise<Purchase | undefined>;
+    /**
+     * Resolves a purchase by any recorded Stripe reference (checkout session,
+     * payment intent, charge, or transfer). Available on the store as well as the
+     * transaction because work that must happen outside a webhook transaction —
+     * such as reversing a Connect transfer — still needs to find its purchase.
+     */
+    findPurchaseByStripeReference(reference: string): Promise<Purchase | undefined>;
+    /** Must atomically claim event.id and commit all callback writes. */
+    processStripeEvent(event: Stripe.Event, apply: (transaction: BillingTransaction) => Promise<void>): Promise<"processed" | "duplicate">;
+    /** Claims pending events. Dead events are never claimed. */
+    claimOutbox(limit: number): Promise<readonly BillingOutboxEvent[]>;
+    completeOutbox(id: string): Promise<void>;
+    failOutbox(id: string, error: string): Promise<void>;
+    /**
+     * Parks an event that exceeded its attempt budget. The row is **retained**
+     * with its payload and error so nothing is lost: a customer who paid still has
+     * a settlement event on record, and it can be replayed.
+     */
+    markOutboxDead(id: string, error: string): Promise<void>;
+    /** Dead events awaiting attention, newest last. For an operator view. */
+    listDeadOutbox(limit: number): Promise<readonly BillingOutboxEvent[]>;
+    /**
+     * Returns dead events to the pending queue with a fresh attempt budget. This
+     * is how a fixed rule or a repaired payload is replayed rather than lost.
+     */
+    requeueDeadOutbox(limit: number): Promise<number>;
+}
+export interface IdGenerator {
+    next(): string;
+}
+export interface CreateCheckoutInput {
+    /** Stable application order id. Reuse it when retrying the same checkout. */
+    purchaseId: string;
+    tenantId: string;
+    channelId: string;
+    sessionId?: string;
+    buyerId: string;
+    /**
+     * The platform-account `Customer` holding this end user's saved payment
+     * method. Omit to let Stripe create one for the session; supply it to reuse
+     * payment details the consumer already provided for another tenant.
+     */
+    customerId?: string;
+    productKey: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+export interface CreateCheckoutResult {
+    purchase: Purchase;
+    sessionId: string;
+    url: string | null;
+}
+export interface BillingWebhookResult {
+    eventId: string;
+    status: "processed" | "duplicate";
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};