@portalshq/monetization 0.2.0

package/dist/entitlements.js

@@ -0,0 +1,275 @@
+/**
+ * Tenant-configured entitlements.
+ *
+ * An entitlement is a grant made to a paying end user ("consumer"), scoped by
+ * a set of dimensions. A rule is owned and configured by the tenant, not the
+ * platform: the channel owner decides what a purchase unlocks and for how long.
+ *
+ * The scope is an arbitrary subset of dimensions, and **the dimensions present
+ * are both the matcher and the lifetime**:
+ *
+ *   { channelId }                  → valid for the life of the channel
+ *   { channelId, sessionId }       → valid only during that session
+ *   { channelId, date }            → valid only for purchases settling that day,
+ *                                    and expires at the end of it
+ *   { channelId, sessionId, date } → the narrowest form
+ *
+ * Every dimension a rule names must match for the grant to be made. A grant
+ * is always made to a consumer, so a rule never grants "the channel" anything.
+ *
+ * Grants are balances, not flags. A rule that nothing ever consumes stays
+ * permanently available, which is how a standing membership is expressed, and
+ * a rule the application consumes one unit at a time is how a single-use
+ * unlock is expressed. Both use the same primitive.
+ */
+/**
+ * A scope dimension whose value is this token binds to the matching fact of the
+ * purchase at grant time, instead of being compared literally.
+ *
+ * A superchat grants influence over the story turn it was bought for, so its
+ * rule must be scoped to "whichever session this purchase happened in" — a
+ * fixed session id could never match. `"$self"` says bind; the grant then carries
+ * the concrete value and normal equality applies at consumption.
+ */
+export const SELF_BIND = "$self";
+/** True when a scope dimension binds to the purchase rather than comparing. */
+function isSelfBind(value) {
+    return value === SELF_BIND;
+}
+/**
+ * Replaces self-binding dimensions with the concrete facts, producing the scope
+ * the grant is actually scoped to. A binding dimension with no corresponding
+ * fact is dropped, so a purchase with no session yields an unscoped grant rather
+ * than a permanently unsatisfiable one.
+ */
+export function resolveScope(scope, facts) {
+    const resolved = {};
+    if (scope.channelId !== undefined) {
+        resolved.channelId = isSelfBind(scope.channelId) ? facts.channelId : scope.channelId;
+    }
+    if (scope.sessionId !== undefined) {
+        // A self-binding session becomes the purchase's own session, so the grant is
+        // scoped to where it was bought. With no session there is nothing to bind,
+        // so the dimension is dropped rather than left permanently unsatisfiable.
+        if (isSelfBind(scope.sessionId)) {
+            if (facts.sessionId)
+                resolved.sessionId = facts.sessionId;
+        }
+        else {
+            resolved.sessionId = scope.sessionId;
+        }
+    }
+    if (scope.date !== undefined) {
+        resolved.date = scope.date;
+    }
+    return resolved;
+}
+/** 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;
+}
+/**
+ * A grant is usable at a site when every dimension it names matches the site's
+ * facts. A channel-scoped grant is therefore valid anywhere in that channel,
+ * and a session-scoped grant only inside that session.
+ */
+export function grantAppliesAt(grantScope, site) {
+    if (grantScope.channelId !== undefined && grantScope.channelId !== site.channelId)
+        return false;
+    if (grantScope.sessionId !== undefined && grantScope.sessionId !== site.sessionId)
+        return false;
+    if (grantScope.date !== undefined && site.date !== undefined && utcDay(grantScope.date) !== utcDay(site.date))
+        return false;
+    return true;
+}
+/** Every dimension named by the rule and every condition must match. */
+export function ruleMatches(rule, facts) {
+    if (rule.tenantId !== facts.tenantId)
+        return false;
+    if (rule.scope.channelId !== undefined && !isSelfBind(rule.scope.channelId) && rule.scope.channelId !== facts.channelId)
+        return false;
+    // A self-binding session requires the purchase to actually be in one.
+    if (rule.scope.sessionId !== undefined && isSelfBind(rule.scope.sessionId) && !facts.sessionId)
+        return false;
+    if (rule.scope.sessionId !== undefined && !isSelfBind(rule.scope.sessionId) && rule.scope.sessionId !== facts.sessionId)
+        return false;
+    if (rule.scope.date !== undefined && utcDay(rule.scope.date) !== utcDay(facts.settledAt))
+        return false;
+    return rule.conditions.every((condition) => {
+        switch (condition.fact) {
+            case "purchaseKind":
+                return facts.kind === condition.equals;
+            case "productKey":
+                return facts.productKey === condition.equals;
+            case "amount":
+                return facts.amount >= condition.gte;
+        }
+    });
+}
+/** Grants a settled purchase should create, one per matching rule for that tenant. */
+export function grantsForSettlement(rules, facts, ids, now) {
+    return rules
+        .filter((rule) => ruleMatches(rule, facts))
+        .map((rule) => {
+        const bound = resolveScope(rule.scope, facts);
+        const expiresAt = scopeExpiresAt(bound);
+        return {
+            id: ids.next(),
+            ruleId: rule.id,
+            tenantId: rule.tenantId,
+            consumerId: facts.buyerId,
+            kind: rule.kind,
+            scope: bound,
+            quantity: rule.quantity,
+            remaining: rule.quantity,
+            purchaseId: facts.purchaseId,
+            ...(expiresAt ? { expiresAt } : {}),
+            createdAt: now,
+            updatedAt: now,
+        };
+    });
+}
+/** Rejects rules the engine cannot honour, so a bad rule fails at configuration time. */
+export function validateRule(rule) {
+    if (!rule.id.trim())
+        throw new TypeError("rule id is required");
+    if (!rule.tenantId.trim())
+        throw new TypeError("rule tenantId is required");
+    if (!rule.kind.trim())
+        throw new TypeError("rule kind is required");
+    if (!Number.isInteger(rule.quantity) || rule.quantity < 1)
+        throw new TypeError("rule quantity must be a positive integer");
+    const named = Object.values(rule.scope).filter((value) => value !== undefined);
+    if (named.length === 0)
+        throw new TypeError("rule scope must name at least one dimension");
+    if (rule.scope.date !== undefined)
+        utcDay(rule.scope.date);
+    for (const condition of rule.conditions) {
+        if (condition.fact === "amount" && (!Number.isInteger(condition.gte) || condition.gte < 0)) {
+            throw new TypeError("amount condition must be a non-negative integer");
+        }
+    }
+}
+/** Reference store for tests and single-process deployments. */
+export class InMemoryEntitlementStore {
+    rules = new Map();
+    grants = new Map();
+    granted = new Set();
+    async saveRule(rule) {
+        validateRule(rule);
+        this.rules.set(rule.id, rule);
+    }
+    async getRule(id) {
+        return this.rules.get(id);
+    }
+    async listRules(tenantId) {
+        return [...this.rules.values()].filter((rule) => rule.tenantId === tenantId);
+    }
+    async grant(grants) {
+        for (const grant of grants) {
+            const key = `${grant.ruleId}:${grant.purchaseId}`;
+            if (this.granted.has(key))
+                continue;
+            this.granted.add(key);
+            this.grants.set(grant.id, grant);
+        }
+    }
+    async consume(consumerId, kind, site, n) {
+        if (!Number.isInteger(n) || n < 1)
+            throw new TypeError("consume count must be a positive integer");
+        const candidates = [...this.grants.values()]
+            .filter((grant) => grant.consumerId === consumerId && grant.kind === kind && grant.remaining > 0 && grantAppliesAt(grant.scope, site))
+            .filter((grant) => grant.expiresAt === undefined || Date.parse(grant.expiresAt) >= Date.now())
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        const available = candidates.reduce((total, grant) => total + grant.remaining, 0);
+        if (available < n)
+            return false;
+        let owed = n;
+        for (const grant of candidates) {
+            if (owed === 0)
+                break;
+            const taken = Math.min(owed, grant.remaining);
+            grant.remaining -= taken;
+            owed -= taken;
+        }
+        return true;
+    }
+    async remaining(consumerId, kind, site) {
+        return [...this.grants.values()]
+            .filter((grant) => grant.consumerId === consumerId && grant.kind === kind && grantAppliesAt(grant.scope, site))
+            .filter((grant) => grant.expiresAt === undefined || Date.parse(grant.expiresAt) >= Date.now())
+            .reduce((total, grant) => total + grant.remaining, 0);
+    }
+    async revokeForPurchase(purchaseId) {
+        for (const [id, grant] of this.grants) {
+            if (grant.purchaseId === purchaseId)
+                this.grants.delete(id);
+        }
+    }
+}
+function utcDay(value) {
+    const parsed = new Date(value.length === 10 ? `${value}T00:00:00.000Z` : value);
+    if (Number.isNaN(parsed.getTime()))
+        throw new TypeError(`invalid date: ${value}`);
+    return parsed.toISOString().slice(0, 10);
+}
+/**
+ * Applies a settlement outbox event to the entitlement store.
+ *
+ * This is the piece that makes entitlements actually run. `BillingOutboxDispatcher`
+ * delivers each committed event to a `publish` callback; wiring that callback to
+ * this function is what grants on settlement and revokes on refund or dispute.
+ *
+ * Returns the grants created, or the number revoked, so a caller can log or
+ * assert. Safe to call twice for the same event: grants are keyed
+ * `(ruleId, purchaseId)` and revocation is idempotent.
+ */
+export async function applySettlementEvent(store, event, ids, now) {
+    const purchaseId = event.payload.purchaseId;
+    if (typeof purchaseId !== "string" || !purchaseId) {
+        throw new TypeError("outbox event is missing purchaseId");
+    }
+    if (event.type === "billing.purchase_refunded" || event.type === "billing.purchase_disputed") {
+        await store.revokeForPurchase(purchaseId);
+        return { granted: 0, revoked: 1 };
+    }
+    if (event.type !== "billing.purchase_settled") {
+        return { granted: 0, revoked: 0 };
+    }
+    const facts = readSettlementFacts(event.payload);
+    const rules = await store.listRules(facts.tenantId);
+    const grants = grantsForSettlement(rules, facts, ids, now);
+    await store.grant(grants);
+    return { granted: grants.length, revoked: 0 };
+}
+/**
+ * Narrows an outbox payload to settlement facts, rejecting a payload that cannot
+ * support rule evaluation. The payload carries `schemaVersion: "2"` in its
+ * checkout metadata; a payload without the newer fields predates entitlements
+ * and is rejected rather than silently matched against missing values.
+ */
+export function readSettlementFacts(payload) {
+    const required = (key) => {
+        const value = payload[key];
+        if (typeof value !== "string" || !value) {
+            throw new TypeError(`settlement payload is missing ${key}`);
+        }
+        return value;
+    };
+    const amount = payload.amount;
+    if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 0) {
+        throw new TypeError("settlement payload has an invalid amount");
+    }
+    return {
+        purchaseId: required("purchaseId"),
+        tenantId: required("tenantId"),
+        channelId: required("channelId"),
+        sessionId: typeof payload.sessionId === "string" && payload.sessionId ? payload.sessionId : null,
+        buyerId: required("buyerId"),
+        kind: required("kind"),
+        productKey: required("productKey"),
+        amount,
+        currency: required("currency"),
+        settledAt: required("settledAt"),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./portals-billing.js";
+export * from "./entitlements.js";
+export * from "./postgres-store.js";
+export * from "./outbox-dispatcher.js";
+export * from "./dispatcher.js";
+export * from "./stripe-client.js";
+export * from "./stripe-connect-client.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./portals-billing.js";
+export * from "./entitlements.js";
+export * from "./postgres-store.js";
+export * from "./outbox-dispatcher.js";
+export * from "./dispatcher.js";
+export * from "./stripe-client.js";
+export * from "./stripe-connect-client.js";

package/dist/outbox-dispatcher.d.ts

@@ -0,0 +1,16 @@
+import type { BillingOutboxEvent, BillingStore } from "./types.js";
+export interface BillingOutboxDispatcherOptions {
+    store: BillingStore;
+    publish(event: BillingOutboxEvent): Promise<void>;
+    batchSize?: number;
+}
+/** Delivers committed billing events without coupling webhooks to a realtime transport. */
+export declare class BillingOutboxDispatcher {
+    private readonly options;
+    private readonly batchSize;
+    constructor(options: BillingOutboxDispatcherOptions);
+    drainOnce(): Promise<{
+        delivered: number;
+        failed: number;
+    }>;
+}

package/dist/outbox-dispatcher.js

@@ -0,0 +1,29 @@
+/** Delivers committed billing events without coupling webhooks to a realtime transport. */
+export class BillingOutboxDispatcher {
+    options;
+    batchSize;
+    constructor(options) {
+        this.options = options;
+        this.batchSize = options.batchSize ?? 50;
+        if (!Number.isInteger(this.batchSize) || this.batchSize < 1 || this.batchSize > 500) {
+            throw new TypeError("batchSize must be an integer from 1 to 500");
+        }
+    }
+    async drainOnce() {
+        const events = await this.options.store.claimOutbox(this.batchSize);
+        let delivered = 0;
+        let failed = 0;
+        for (const event of events) {
+            try {
+                await this.options.publish(event);
+                await this.options.store.completeOutbox(event.id);
+                delivered += 1;
+            }
+            catch (cause) {
+                await this.options.store.failOutbox(event.id, cause instanceof Error ? cause.message : String(cause));
+                failed += 1;
+            }
+        }
+        return { delivered, failed };
+    }
+}

package/dist/portals-billing.d.ts

@@ -0,0 +1,137 @@
+import Stripe from "stripe";
+import type { BillingCatalog, BillingStore, BillingWebhookResult, CreateCheckoutInput, CreateCheckoutResult, IdGenerator, Purchase, TenantBillingProfile } from "./types.js";
+export interface MonetizationOptions {
+    /**
+     * The platform's Stripe credential. It creates charges on the platform account
+     * and transfers them to tenant accounts, so it is a charge-capable key and
+     * must be a restricted key scoped to exactly the endpoints used.
+     *
+     * The end user's `Customer` and payment method also live on this account,
+     * which is what lets one payment method be reused across every tenant.
+     */
+    stripe: Stripe;
+    store: BillingStore;
+    catalog: BillingCatalog;
+    ids: IdGenerator;
+    now?: () => Date;
+    /**
+     * Application policy for reversing a Connect transfer after a dispute. Only
+     * invoked when the charge actually produced a transfer, and the reversal uses
+     * a stable idempotency key so a retry cannot double-reverse.
+     */
+    reverseTransferForDispute?: (purchase: Purchase, dispute: Stripe.Dispute) => boolean | Promise<boolean>;
+}
+export interface EnsureTenantProfileInput {
+    tenantId: string;
+    ownerId: string;
+    email?: string;
+    country?: string;
+    defaultCurrency?: string;
+    displayName?: string;
+}
+export interface RefundPurchaseInput {
+    purchaseId: string;
+    tenantId: string;
+    amount?: number;
+    reason?: Stripe.RefundCreateParams.Reason;
+}
+/** Outcome of checking what Stripe actually recorded against the expected catalog. */
+export type SettlementVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "fee_mismatch" | "amount_mismatch";
+    expected: number;
+    actual: number;
+};
+/**
+ * Direct-charge checkout and Connect management.
+ *
+ * The tenant is merchant of record: charges are created on the tenant's own
+ * account, so the caller supplies a Stripe credential scoped to that account and
+ * the platform never holds a key that can move tenant money. The platform's own
+ * credential is limited to Connect management.
+ */
+export declare class Monetization {
+    private readonly options;
+    private readonly now;
+    constructor(options: MonetizationOptions);
+    getTenantProfile(tenantId: string): Promise<TenantBillingProfile | undefined>;
+    /**
+     * Creates the tenant's connected account via **Accounts v2**
+     * (`stripe.v2.core.accounts`), configured as a recipient for destination charges.
+     *
+     * The v1 `stripe.accounts.create({ type: "express" })` form is deprecated and
+     * is not used. `losses_collector: "application"` is required for destination
+     * charges: the platform must hold the negative balance so a dispute transfer
+     * can be reversed. The cost is that the platform carries dispute liability.
+     */
+    ensureTenantProfile(input: EnsureTenantProfileInput): Promise<TenantBillingProfile>;
+    /** Reads the v2 capability path. Never reads the deprecated v1 boolean fields. */
+    refreshTenantCapabilities(tenantId: string): Promise<TenantBillingProfile>;
+    createConnectOnboardingLink(tenantId: string, refreshUrl: string, returnUrl: string): Promise<{
+        url: string;
+    }>;
+    private tenantClient;
+    /**
+     * Creates a destination-charge Checkout Session on the **platform** account,
+     * transferring to the tenant's connected account on success.
+     *
+     * `customerId` is the end user's platform-account `Customer`. Supply it to
+     * reuse payment details already saved for another tenant; omit it and Stripe
+     * creates a Customer for this session only. This is the mechanism behind
+     * "provide payment once, use on any tenant" — a `PaymentMethod` cannot move
+     * between connected accounts, so the Customer has to live on the platform.
+     *
+     * `application_fee_amount` comes from the server-side catalog;
+     * `CreateCheckoutInput` has no fee field, so no caller can influence it.
+     *
+     * `integration_identifier` labels the session in the Dashboard for tracking
+     * and comparing checkout flows.
+     */
+    /**
+     * The platform-account `Customer` for this consumer, creating it on first use.
+     *
+     * Because the platform holds the customer rather than each tenant, one saved
+     * payment method pays for purchases across every tenant the consumer buys
+     * from. A duplicate is possible if two requests race before either commits, in
+     * which case the last write wins and the superseded Customer is orphaned in
+     * Stripe; that is a rare, harmless leak rather than a wrong charge, so it is
+     * not worth a lock.
+     */
+    ensureBillingCustomer(buyerId: string): Promise<{
+        id: string;
+    }>;
+    createCheckout(input: CreateCheckoutInput): Promise<CreateCheckoutResult>;
+    reportMeterEvent(tenantId: string, customerId: string, eventName: string, value: number, identifier: string): Promise<void>;
+    /** Customer and portal session both live on the tenant's account. */
+    createCustomerPortalSession(tenantId: string, customerId: string, returnUrl: string): Promise<Stripe.BillingPortal.Session>;
+    /**
+     * Checks what Stripe actually recorded against the server-side catalog.
+     *
+     * The platform sets the fee, so this is defense in depth rather than the
+     * primary control: it catches a misconfigured catalog, a replayed session, or
+     * a manually created charge. Call it before granting entitlements or paying
+     * out.
+     */
+    verifySettlement(purchaseId: string, actualAmount: number, actualFeeAmount: number | null): Promise<SettlementVerification>;
+    refundPurchase(input: RefundPurchaseInput): Promise<Stripe.Refund>;
+    handleWebhook(rawBody: string | Buffer, signature: string, secret: string): Promise<BillingWebhookResult>;
+    /**
+     * Reads the purchase and reverses the Connect transfer when policy allows.
+     * Runs outside the webhook transaction; the resulting ledger entry is written
+     * by `applyEvent` once the transaction commits.
+     */
+    private maybeReverseTransfer;
+    private applyEvent;
+    private ledger;
+    private findPurchaseForCharge;
+    /**
+     * Settlement facts. Every field an entitlement rule can match on is present
+     * here, so a rule is evaluable from the outbox alone without re-reading the
+     * purchase. `schemaVersion` was bumped to 2 because the payload gained
+     * `tenantId`, `sessionId`, `productKey`, and `settledAt`.
+     */
+    private outbox;
+    private requireReadyProfile;
+}