@portalshq/monetization 0.2.2 → 0.3.0

package/README.md

@@ -4,6 +4,21 @@
 
 Audience-to-creator payments: Stripe Connect destination charges, tenant payout readiness, a PostgreSQL ledger/outbox, and rule-based entitlements.
 
+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.
+
+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.
+
 ## Required setup
 
 1. Apply `sql/001_monetization.sql` to PostgreSQL.
@@ -26,6 +41,7 @@ const { url } = await monetization.createCheckout({
 - `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`.
 
 ## Safety and operations
 

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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portalshq/monetization",
-  "version": "0.2.2",
+  "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()
+);