@portalshq/monetization 0.2.0 → 0.3.0

package/README.md

@@ -1,182 +1,59 @@
 # @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
+A **tenant** is a producer, independent of the audience users who are consumers.
+A **channel** is the producer venue; a **program** is the software experience
+owned by a channel. Attribute application activity and entitlement kinds to the
+program ID. A central `tenants` registry can identify producers without a user
+foreign key.
 
-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.
+The current package and vendored SQL still use `tenant_id` for payout profiles,
+purchases and entitlement records. It is a required package key, not a newly
+introduced `program_id` column. An integration that uses a program ID in this
+field must provision the corresponding payout profile and Stripe mapping and
+coordinate all purchase, rule and grant keys. Do not reassign existing tenant
+keys, Stripe accounts or grant kinds without an explicit data migration. A
+program-prefixed entitlement kind isolates a program because the entitlement
+store filters by consumer and kind.
 
-```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
+## Required setup
 
-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.
+- `debitCredits(input)` / `grantCredits(input)` (`CreditDebitStore` / `CreditGrantStore`): retry-safe credit operations keyed by an immutable `operationId`. The debit locks grants, verifies tenant/consumer/kind/scope, debits in deterministic order, and persists the outcome (including `insufficient`, so a later balance cannot charge a declined operation). The grant issues reward/courtesy credits as a non-purchase-backed grant under a `credit-grant:<kind>` rule and records it in `monetization_credit_grants`. Identical retries replay the stored result; a reused operation id with different facts is an idempotency conflict. Apply `sql/002_credit_debits.sql` and `sql/003_credit_grants.sql`.
 
-**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/entitlements.d.ts

@@ -85,6 +85,45 @@ export interface EntitlementGrant {
     createdAt: string;
     updatedAt: string;
 }
+/** Immutable facts for one retry-safe credit debit. */
+export interface CreditDebitInput {
+    operationId: string;
+    tenantId: string;
+    consumerId: string;
+    kind: string;
+    site: EntitlementScope;
+    amount: number;
+}
+export interface CreditDebitResult {
+    outcome: "debited" | "insufficient";
+    allocations: readonly {
+        grantId: string;
+        amount: number;
+    }[];
+}
+export interface CreditDebitStore {
+    debitCredits(input: CreditDebitInput): Promise<CreditDebitResult>;
+}
+/** Immutable facts for one retry-safe credit grant (reward or courtesy issue). */
+export interface CreditGrantInput {
+    operationId: string;
+    tenantId: string;
+    consumerId: string;
+    kind: string;
+    site: EntitlementScope;
+    amount: number;
+}
+export interface CreditGrantResult {
+    outcome: "granted";
+    grantId: string;
+}
+export interface CreditGrantStore {
+    grantCredits(input: CreditGrantInput): Promise<CreditGrantResult>;
+}
+export declare function normalizeCreditDebit(input: CreditDebitInput): CreditDebitInput;
+export declare function normalizeCreditGrant(input: CreditGrantInput): CreditGrantInput;
+/** The entitlement rule a `grantCredits` operation ensures before granting. */
+export declare function creditGrantRuleId(kind: string): string;
 export interface EntitlementStore {
     saveRule(rule: EntitlementRule): Promise<void>;
     getRule(id: string): Promise<EntitlementRule | undefined>;
@@ -120,10 +159,21 @@ export declare class InMemoryEntitlementStore implements EntitlementStore {
     private readonly rules;
     private readonly grants;
     private readonly granted;
+    private readonly creditDebits;
+    private readonly creditGrants;
     saveRule(rule: EntitlementRule): Promise<void>;
     getRule(id: string): Promise<EntitlementRule | undefined>;
     listRules(tenantId: string): Promise<readonly EntitlementRule[]>;
     grant(grants: readonly EntitlementGrant[]): Promise<void>;
+    debitCredits(input: CreditDebitInput): Promise<CreditDebitResult>;
+    /**
+     * Issue `amount` credits as a new grant, exactly once per `operationId`.
+     * The grant is not purchase-backed (`purchaseId` carries the operation id,
+     * never a real purchase), so refund flows can never revoke a reward.
+     * An identical retry returns the original result; a reused operation id
+     * carrying different facts fails.
+     */
+    grantCredits(input: CreditGrantInput): Promise<CreditGrantResult>;
     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>;

package/dist/entitlements.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 /**
  * Tenant-configured entitlements.
  *
@@ -64,6 +65,40 @@ export function resolveScope(scope, facts) {
     }
     return resolved;
 }
+/** Shared shape of a retry-safe credit operation's immutable facts. */
+function normalizeCreditOperation(input) {
+    for (const value of [input.operationId, input.tenantId, input.consumerId, input.kind]) {
+        if (typeof value !== "string" || !value.trim() || value.length > 512)
+            throw new TypeError("Invalid credit operation identifier");
+    }
+    if (!Number.isSafeInteger(input.amount) || input.amount < 1)
+        throw new TypeError("Invalid credit operation amount");
+    if (!input.site || typeof input.site !== "object" || Array.isArray(input.site))
+        throw new TypeError("Invalid credit operation scope");
+    const site = {};
+    for (const key of Object.keys(input.site))
+        if (!["channelId", "sessionId", "date"].includes(key))
+            throw new TypeError("Invalid credit operation scope");
+    for (const key of ["channelId", "sessionId", "date"]) {
+        const value = input.site[key];
+        if (value !== undefined) {
+            if (typeof value !== "string" || !value.trim() || value.length > 512)
+                throw new TypeError("Invalid credit operation scope");
+            site[key] = value;
+        }
+    }
+    return { operationId: input.operationId, tenantId: input.tenantId, consumerId: input.consumerId, kind: input.kind, site, amount: input.amount };
+}
+export function normalizeCreditDebit(input) {
+    return normalizeCreditOperation(input);
+}
+export function normalizeCreditGrant(input) {
+    return normalizeCreditOperation(input);
+}
+/** The entitlement rule a `grantCredits` operation ensures before granting. */
+export function creditGrantRuleId(kind) {
+    return `credit-grant:${kind}`;
+}
 /** End of the UTC day named by `scope.date`, or undefined when the rule is not date-bounded. */
 export function scopeExpiresAt(scope) {
     return scope.date ? `${utcDay(scope.date)}T23:59:59.999Z` : undefined;
@@ -155,6 +190,8 @@ export class InMemoryEntitlementStore {
     rules = new Map();
     grants = new Map();
     granted = new Set();
+    creditDebits = new Map();
+    creditGrants = new Map();
     async saveRule(rule) {
         validateRule(rule);
         this.rules.set(rule.id, rule);
@@ -174,6 +211,70 @@ export class InMemoryEntitlementStore {
             this.grants.set(grant.id, grant);
         }
     }
+    async debitCredits(input) {
+        const normalized = normalizeCreditDebit(input);
+        const existing = this.creditDebits.get(normalized.operationId);
+        if (existing) {
+            if (JSON.stringify(existing.input) !== JSON.stringify(normalized))
+                throw new Error("Credit debit idempotency conflict");
+            return structuredClone(existing.result);
+        }
+        const candidates = [...this.grants.values()].filter(g => g.tenantId === normalized.tenantId && g.consumerId === normalized.consumerId && g.kind === normalized.kind && g.remaining > 0 && grantAppliesAt(g.scope, normalized.site) && (g.expiresAt === undefined || Date.parse(g.expiresAt) >= Date.now())).sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        const enough = candidates.reduce((sum, g) => sum + g.remaining, 0) >= normalized.amount;
+        const allocations = [];
+        let owed = enough ? normalized.amount : 0;
+        for (const grant of candidates) {
+            const amount = Math.min(owed, grant.remaining);
+            if (amount) {
+                grant.remaining -= amount;
+                owed -= amount;
+                allocations.push({ grantId: grant.id, amount });
+            }
+        }
+        const result = { outcome: enough ? "debited" : "insufficient", allocations };
+        this.creditDebits.set(normalized.operationId, { input: normalized, result });
+        return structuredClone(result);
+    }
+    /**
+     * Issue `amount` credits as a new grant, exactly once per `operationId`.
+     * The grant is not purchase-backed (`purchaseId` carries the operation id,
+     * never a real purchase), so refund flows can never revoke a reward.
+     * An identical retry returns the original result; a reused operation id
+     * carrying different facts fails.
+     */
+    async grantCredits(input) {
+        const normalized = normalizeCreditGrant(input);
+        const existing = this.creditGrants.get(normalized.operationId);
+        if (existing) {
+            if (JSON.stringify(existing.input) !== JSON.stringify(normalized))
+                throw new Error("Credit grant idempotency conflict");
+            return structuredClone(existing.result);
+        }
+        const ruleId = creditGrantRuleId(normalized.kind);
+        if (!this.rules.has(ruleId)) {
+            this.rules.set(ruleId, { id: ruleId, tenantId: normalized.tenantId, kind: normalized.kind, scope: normalized.site, conditions: [], quantity: 1, createdAt: new Date().toISOString() });
+        }
+        const grantId = randomUUID();
+        const now = new Date().toISOString();
+        const expiresAt = scopeExpiresAt(normalized.site);
+        this.grants.set(grantId, {
+            id: grantId,
+            ruleId,
+            tenantId: normalized.tenantId,
+            consumerId: normalized.consumerId,
+            kind: normalized.kind,
+            scope: normalized.site,
+            quantity: normalized.amount,
+            remaining: normalized.amount,
+            purchaseId: normalized.operationId,
+            ...(expiresAt ? { expiresAt } : {}),
+            createdAt: now,
+            updatedAt: now,
+        });
+        const result = { outcome: "granted", grantId };
+        this.creditGrants.set(normalized.operationId, { input: normalized, result });
+        return structuredClone(result);
+    }
     async consume(consumerId, kind, site, n) {
         if (!Number.isInteger(n) || n < 1)
             throw new TypeError("consume count must be a positive integer");

package/dist/postgres-store.d.ts

@@ -1,7 +1,7 @@
 import type { Pool } from "pg";
 import type Stripe from "stripe";
 import type { BillingOutboxEvent, BillingStore, BillingTransaction, Purchase, TenantBillingProfile } from "./types.js";
-import type { EntitlementGrant, EntitlementRule, EntitlementScope, EntitlementStore } from "./entitlements.js";
+import type { EntitlementGrant, EntitlementRule, EntitlementScope, EntitlementStore, CreditDebitInput, CreditDebitResult, CreditGrantInput, CreditGrantResult } from "./entitlements.js";
 /** Durable PostgreSQL adapter. Apply sql/001_monetization.sql before use. */
 export declare class PostgresBillingStore implements BillingStore {
     private readonly pool;
@@ -39,6 +39,17 @@ export declare class PostgresEntitlementStore implements EntitlementStore {
     getRule(id: string): Promise<EntitlementRule | undefined>;
     listRules(tenantId: string): Promise<readonly EntitlementRule[]>;
     grant(grants: readonly EntitlementGrant[]): Promise<void>;
+    /** Debit and its idempotency record commit atomically in the billing database. */
+    debitCredits(input: CreditDebitInput): Promise<CreditDebitResult>;
+    /**
+     * Issue `amount` credits as a new grant, exactly once per `operationId`.
+     * The rule, grant and operation record commit atomically, so a crash
+     * leaves either nothing or a replayable record — replaying the operation
+     * id returns the stored grant rather than issuing twice. The grant's
+     * `purchase_id` is NULL: reward credits are not purchase-backed and a
+     * refund flow can never revoke them.
+     */
+    grantCredits(input: CreditGrantInput): Promise<CreditGrantResult>;
     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>;

package/dist/postgres-store.js

@@ -1,4 +1,5 @@
-import { grantAppliesAt, validateRule } from "./entitlements.js";
+import { randomUUID } from "node:crypto";
+import { grantAppliesAt, validateRule, normalizeCreditDebit, normalizeCreditGrant, creditGrantRuleId, scopeExpiresAt } from "./entitlements.js";
 /** Durable PostgreSQL adapter. Apply sql/001_monetization.sql before use. */
 export class PostgresBillingStore {
     pool;
@@ -221,6 +222,89 @@ export class PostgresEntitlementStore {
        VALUES ${tuples.join(",")}
        ON CONFLICT (rule_id, purchase_id) DO NOTHING`, values);
     }
+    /** Debit and its idempotency record commit atomically in the billing database. */
+    async debitCredits(input) {
+        const x = normalizeCreditDebit(input);
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`credit-debit:${x.operationId}`]);
+            const prior = (await client.query("SELECT * FROM monetization_credit_debits WHERE operation_id=$1", [x.operationId])).rows[0];
+            if (prior) {
+                const same = prior.tenant_id === x.tenantId && prior.consumer_id === x.consumerId && prior.kind === x.kind && Number(prior.amount) === x.amount && JSON.stringify(normalizeCreditDebit({ ...x, site: prior.scope }).site) === JSON.stringify(x.site);
+                if (!same)
+                    throw new Error("Credit debit idempotency conflict");
+                await client.query("COMMIT");
+                return { outcome: prior.outcome, allocations: prior.allocations };
+            }
+            const rows = (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 tenant_id=$1 AND consumer_id=$2 AND kind=$3 AND remaining>0 AND (expires_at IS NULL OR expires_at>=now()) ORDER BY id FOR UPDATE`, [x.tenantId, x.consumerId, x.kind])).rows;
+            const candidates = rows.filter(row => grantAppliesAt(row.scope, x.site)).sort((a, b) => a.created_order.localeCompare(b.created_order) || a.id.localeCompare(b.id));
+            const enough = candidates.reduce((sum, row) => sum + Number(row.remaining), 0) >= x.amount;
+            const allocations = [];
+            let owed = enough ? x.amount : 0;
+            for (const row of candidates) {
+                const amount = Math.min(owed, Number(row.remaining));
+                if (amount) {
+                    await client.query("UPDATE monetization_entitlements SET remaining=remaining-$2,updated_at=now() WHERE id=$1", [row.id, amount]);
+                    owed -= amount;
+                    allocations.push({ grantId: row.id, amount });
+                }
+            }
+            const outcome = enough ? "debited" : "insufficient";
+            await client.query("INSERT INTO monetization_credit_debits(operation_id,tenant_id,consumer_id,kind,scope,amount,outcome,allocations) VALUES($1,$2,$3,$4,$5,$6,$7,$8)", [x.operationId, x.tenantId, x.consumerId, x.kind, JSON.stringify(x.site), x.amount, outcome, JSON.stringify(allocations)]);
+            await client.query("COMMIT");
+            return { outcome, allocations };
+        }
+        catch (cause) {
+            await client.query("ROLLBACK");
+            throw cause;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Issue `amount` credits as a new grant, exactly once per `operationId`.
+     * The rule, grant and operation record commit atomically, so a crash
+     * leaves either nothing or a replayable record — replaying the operation
+     * id returns the stored grant rather than issuing twice. The grant's
+     * `purchase_id` is NULL: reward credits are not purchase-backed and a
+     * refund flow can never revoke them.
+     */
+    async grantCredits(input) {
+        const x = normalizeCreditGrant(input);
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`credit-grant:${x.operationId}`]);
+            const prior = (await client.query("SELECT * FROM monetization_credit_grants WHERE operation_id=$1", [x.operationId])).rows[0];
+            if (prior) {
+                const same = prior.tenant_id === x.tenantId && prior.consumer_id === x.consumerId && prior.kind === x.kind && Number(prior.amount) === x.amount && JSON.stringify(normalizeCreditGrant({ ...x, site: prior.scope }).site) === JSON.stringify(x.site);
+                if (!same)
+                    throw new Error("Credit grant idempotency conflict");
+                await client.query("COMMIT");
+                return { outcome: "granted", grantId: prior.grant_id };
+            }
+            const ruleId = creditGrantRuleId(x.kind);
+            await client.query(`INSERT INTO monetization_entitlement_rules(id,tenant_id,kind,scope,conditions,quantity,created_at)
+         VALUES($1,$2,$3,$4,'[]'::jsonb,1,now()) ON CONFLICT (id) DO NOTHING`, [ruleId, x.tenantId, x.kind, JSON.stringify(x.site)]);
+            const grantId = randomUUID();
+            const expiresAt = scopeExpiresAt(x.site) ?? null;
+            await client.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($1,$2,$3,$4,$5,$6,$7,$7,NULL,$8,now(),now())`, [grantId, ruleId, x.tenantId, x.consumerId, x.kind, JSON.stringify(x.site), x.amount, expiresAt]);
+            await client.query("INSERT INTO monetization_credit_grants(operation_id,tenant_id,consumer_id,kind,scope,amount,grant_id,outcome) VALUES($1,$2,$3,$4,$5,$6,$7,'granted')", [x.operationId, x.tenantId, x.consumerId, x.kind, JSON.stringify(x.site), x.amount, grantId]);
+            await client.query("COMMIT");
+            return { outcome: "granted", grantId };
+        }
+        catch (cause) {
+            await client.query("ROLLBACK");
+            throw cause;
+        }
+        finally {
+            client.release();
+        }
+    }
     async consume(consumerId, kind, site, n) {
         if (!Number.isInteger(n) || n < 1)
             throw new TypeError("consume count must be a positive integer");
@@ -231,11 +315,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.3.0",
   "description": "Audience-to-creator monetization for Portals: Stripe Connect destination charges, entitlements, ledger, and transactional outbox. Keyed on tenant, not channel.",
   "repository": {
     "type": "git",

package/sql/002_credit_debits.sql

@@ -0,0 +1,12 @@
+-- Idempotency records live in the same database and transaction as credit debits.
+CREATE TABLE IF NOT EXISTS monetization_credit_debits (
+  operation_id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  consumer_id text NOT NULL,
+  kind text NOT NULL,
+  scope jsonb NOT NULL,
+  amount integer NOT NULL CHECK (amount > 0),
+  outcome text NOT NULL CHECK (outcome IN ('debited', 'insufficient')),
+  allocations jsonb NOT NULL DEFAULT '[]'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now()
+);

package/sql/003_credit_grants.sql

@@ -0,0 +1,19 @@
+-- Idempotent platform-issued credit grants (rewards, courtesy credits).
+-- Apply after 001 and 002. Records live in the same database as grants and
+-- commit in the same transaction as the grant they create.
+
+-- Reward grants are not purchase-backed: purchase_id stays NULL so refund
+-- flows (revokeForPurchase) can never revoke them.
+ALTER TABLE monetization_entitlements ALTER COLUMN purchase_id DROP NOT NULL;
+
+CREATE TABLE IF NOT EXISTS monetization_credit_grants (
+  operation_id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  consumer_id text NOT NULL,
+  kind text NOT NULL,
+  scope jsonb NOT NULL,
+  amount integer NOT NULL CHECK (amount > 0),
+  outcome text NOT NULL CHECK (outcome IN ('granted')),
+  grant_id text,
+  created_at timestamptz NOT NULL DEFAULT now()
+);