@portalshq/monetization 0.2.0 → 0.2.2

package/README.md

@@ -1,182 +1,43 @@
 # @portalshq/monetization
 
-Audience-to-creator monetization for Portals. Stripe Connect destination
-charges, entitlements, a ledger, and a transactional outbox.
+**Reusable agent module:** [integration guide](../../docs/package-agents/monetization.md)
 
-Applications provide authorization, catalog configuration, persistence, and
-URLs. They never provide authoritative prices, fees, or destination account ids
-from a browser.
+Audience-to-creator payments: Stripe Connect destination charges, tenant payout readiness, a PostgreSQL ledger/outbox, and rule-based entitlements.
 
-## Credentials
+## Required setup
 
-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.
+1. Apply `sql/001_monetization.sql` to PostgreSQL.
+2. Create `PostgresBillingStore` and `PostgresEntitlementStore` from the same pool.
+3. Inject a server-side Stripe platform client, server-owned `BillingCatalog`, and `IdGenerator` into `Monetization`.
+4. Create/refresh the tenant profile and complete Stripe onboarding before checkout.
+5. Route the **raw, unparsed** Stripe webhook body to `handleWebhook`, then run `MonetizationDispatcher.drainOnce()` from a worker.
 
 ```ts
+const monetization = new Monetization({ stripe, store, catalog, ids });
 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);
-  },
+  purchaseId, tenantId, channelId, buyerId, productKey, successUrl, cancelUrl,
 });
-
-// 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
+## Core API
 
-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.
+- `ensureTenantProfile()`, `refreshTenantCapabilities()`, `createConnectOnboardingLink()`: provision and assess the tenant's Stripe Connect recipient account.
+- `ensureBillingCustomer()`, `createCheckout()`: create platform-held customer/payment flows. `purchaseId` is the idempotency key and cannot be reused for different purchase facts.
+- `handleWebhook(rawBody, signature, secret)`: atomically applies Stripe events to purchases, ledger, and outbox. Use `refundPurchase()` for refunds.
+- `MonetizationDispatcher`: drains the outbox, applies entitlements, and invokes optional application side effects. Monitor `isStale()`, `listParked()`, and requeue repaired events with `requeueParked()`.
+- `PostgresEntitlementStore.consume()` / `remaining()`: consume or inspect entitlement balances.
 
-**Accounts v2 replaced the deprecated v1 accounts API**, and destination charges
-were retained (see "Destination charges, and why"):
+## Safety and operations
 
-- `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`.
+- Keep Stripe keys, webhook secrets, catalog pricing, fee amounts, and destination account IDs server-side. The catalog is authoritative; browser inputs must never set price or fee.
+- Verify webhook signatures before responding; preserve the exact raw request body.
+- Destination charges make the platform the losses collector. Configure and review dispute reversal policy (`reverseTransferForDispute`) before production.
+- A settlement without `sessionId` cannot match session-scoped entitlement rules. Alert on a non-zero `withoutSession` drain result.
+- This package is tenant-keyed. It is not for platform B2B subscriptions; use `@portalshq/platform-billing` for those.
 
-`StripePlatformBilling` and `createStripePlatformBilling` moved to
-`@portalshq/platform-billing`; they serve the platform's own B2B flows, not
-audience monetization.
+### Lock ordering with interaction credit holds
 
+`PostgresEntitlementStore.consume` locks grants by ID and then consumes the oldest
+matching grants first. The interaction orchestrator uses the same grant lock order
+for reservations, captures and refunds. Deploy these package updates together when
+sharing a PostgreSQL entitlement database.

package/dist/postgres-store.js

@@ -231,11 +231,17 @@ export class PostgresEntitlementStore {
             // 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
+            const candidates = await client.query(`SELECT id, scope, remaining,
+           to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.US') AS created_order
+         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));
+         ORDER BY id FOR UPDATE`, [consumerId, kind]);
+            // Lock by id, as interaction credit holds/refunds do, then spend oldest first.
+            // Keeping lock acquisition separate from spend order avoids cross-module deadlocks.
+            const applicable = candidates.rows
+                .filter((row) => grantAppliesAt(row.scope, site))
+                .sort((a, b) => a.created_order < b.created_order ? -1 : a.created_order > b.created_order ? 1 : 0);
             const available = applicable.reduce((total, row) => total + Number(row.remaining), 0);
             if (available < n) {
                 await client.query("ROLLBACK");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portalshq/monetization",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Audience-to-creator monetization for Portals: Stripe Connect destination charges, entitlements, ledger, and transactional outbox. Keyed on tenant, not channel.",
   "repository": {
     "type": "git",