@voltro/plugin-billing 0.85.0 → 0.87.0

package/dist/dunning.js

@@ -0,0 +1,209 @@
+import { BillingError as e, DEFAULT_PLAN as t } from "./types.js";
+import { Effect as n } from "effect";
+import { and as r, eq as i, id as a, table as o, text as s, timestamp as c } from "@voltro/database";
+//#region src/dunning.ts
+var l = "_voltro_billing_dunning_notices", u = o(l, {
+	id: a({ prefix: "bdun" }),
+	tenantId: s().maxLength(191),
+	episode: s().maxLength(32),
+	stepId: s().maxLength(64),
+	sentAt: c()
+}).unique("byBillingDunningNotice", [
+	"tenantId",
+	"episode",
+	"stepId"
+]), d = "locked", f = [
+	{
+		id: "payment-failed",
+		afterHours: 0
+	},
+	{
+		id: "reminder",
+		afterHours: 72
+	},
+	{
+		id: "final-warning",
+		afterHours: 144
+	}
+], p = 168, m = "hard", h = (e, t, n) => {
+	if (e === void 0 || e.trim() === "") return t;
+	let r = Number(e);
+	if (!Number.isFinite(r) || r < 0) throw Error(`billingPlugin: ${n} must be a non-negative number, got '${e}'`);
+	return r;
+}, g = (e, t) => {
+	let n = t.VOLTRO_BILLING_DUNNING;
+	if (n !== void 0 && n !== "" && n !== "on" && n !== "off") throw Error(`billingPlugin: VOLTRO_BILLING_DUNNING must be 'on' or 'off', got '${n}'`);
+	let r = n === "off" ? !1 : n === "on" ? !0 : e?.enabled ?? !0, i = t.VOLTRO_BILLING_LOCKOUT;
+	if (i !== void 0 && i !== "" && i !== "hard" && i !== "soft") throw Error(`billingPlugin: VOLTRO_BILLING_LOCKOUT must be 'hard' or 'soft', got '${i}'`);
+	let a = i === "hard" || i === "soft" ? i : e?.lockout ?? "hard", o = h(t.VOLTRO_BILLING_GRACE_HOURS, e?.graceHours ?? 168, "VOLTRO_BILLING_GRACE_HOURS"), s = e?.steps ?? f, c = t.VOLTRO_BILLING_DUNNING_STEP_HOURS, l = s;
+	if (c !== void 0 && c.trim() !== "") {
+		let e = c.split(",").map((e) => e.trim());
+		if (e.length !== s.length) throw Error(`billingPlugin: VOLTRO_BILLING_DUNNING_STEP_HOURS lists ${e.length} value(s) but the sequence declares ${s.length} step(s) (${s.map((e) => e.id).join(", ")})`);
+		l = s.map((t, n) => ({
+			id: t.id,
+			afterHours: h(e[n], t.afterHours, "VOLTRO_BILLING_DUNNING_STEP_HOURS")
+		}));
+	}
+	let u = /* @__PURE__ */ new Set();
+	for (let e of l) {
+		if (e.id === "locked") throw Error(`billingPlugin: '${d}' is the reserved lockout step id`);
+		if (u.has(e.id)) throw Error(`billingPlugin: duplicate dunning step id '${e.id}'`);
+		u.add(e.id);
+	}
+	return {
+		enabled: r,
+		graceHours: o,
+		lockout: a,
+		steps: [...l].sort((e, t) => e.afterHours - t.afterHours),
+		...e?.notify === void 0 ? {} : { notify: e.notify },
+		...e?.resolveRecipient === void 0 ? {} : { resolveRecipient: e.resolveRecipient },
+		...e?.portalReturnUrl === void 0 ? {} : { portalReturnUrl: e.portalReturnUrl }
+	};
+}, _ = 36e5, v = (e) => String(e.getTime()), y = (e, t) => new Date(e.getTime() + t * _), b = (e, t, n) => {
+	let r = (n.getTime() - t.getTime()) / _;
+	return e.filter((e) => r >= e.afterHours);
+}, x = (e, n, r, i) => {
+	let a = {
+		tenantId: e?.tenantId ?? i ?? "",
+		lockout: n.lockout
+	};
+	if (e === null) return {
+		...a,
+		plan: t,
+		billedPlan: t,
+		status: "none",
+		entitled: !0,
+		inGrace: !1,
+		graceEndsAt: null,
+		lockedSince: null
+	};
+	if (e.status === "active" || e.status === "trialing") return {
+		...a,
+		plan: e.plan,
+		billedPlan: e.plan,
+		status: e.status,
+		entitled: !0,
+		inGrace: !1,
+		graceEndsAt: null,
+		lockedSince: null
+	};
+	if (e.status === "pastDue") {
+		if (!n.enabled) return {
+			...a,
+			plan: t,
+			billedPlan: e.plan,
+			status: e.status,
+			entitled: !0,
+			inGrace: !1,
+			graceEndsAt: null,
+			lockedSince: null
+		};
+		if (e.pastDueSince === null) return {
+			...a,
+			plan: e.plan,
+			billedPlan: e.plan,
+			status: e.status,
+			entitled: !0,
+			inGrace: !0,
+			graceEndsAt: null,
+			lockedSince: null
+		};
+		let i = y(e.pastDueSince, n.graceHours), o = r.getTime() >= i.getTime();
+		return {
+			...a,
+			plan: o && n.lockout === "hard" ? t : e.plan,
+			billedPlan: e.plan,
+			status: e.status,
+			entitled: !o,
+			inGrace: !o,
+			graceEndsAt: i,
+			lockedSince: o ? i : null
+		};
+	}
+	return {
+		...a,
+		plan: t,
+		billedPlan: e.plan,
+		status: e.status,
+		entitled: !0,
+		inGrace: !1,
+		graceEndsAt: null,
+		lockedSince: null
+	};
+}, S = (e) => e.toISOString().slice(0, 10), C = (e) => {
+	let t = e.portalUrl, n = t === null ? "<p>Please update your payment method in the billing settings.</p>" : `<p><a href="${t}">Update your payment method</a></p>`, r = t === null ? "Please update your payment method in the billing settings." : `Update your payment method: ${t}`;
+	if (e.locked) return {
+		subject: "Your subscription has been suspended",
+		html: `<p>We were unable to collect payment, and your subscription is now suspended.</p>${n}`,
+		text: `We were unable to collect payment, and your subscription is now suspended.\n\n${r}`
+	};
+	let i = S(e.graceEndsAt), a = e.stepId === "payment-failed" ? "Your last payment could not be collected." : "Your payment is still outstanding.";
+	return {
+		subject: "Action needed: your payment could not be collected",
+		html: `<p>${a} Your subscription stays active until ${i}.</p>${n}`,
+		text: `${a} Your subscription stays active until ${i}.\n\n${r}`
+	};
+}, w = (e) => (t) => t.to === null ? n.void : e.send({
+	to: t.to,
+	subject: t.subject,
+	html: t.html,
+	text: t.text
+}).pipe(n.asVoid), T = (e, t, n) => `${e}\u0000${t}\u0000${n}`, E = () => {
+	let e = /* @__PURE__ */ new Map();
+	return {
+		claim: (t, r, i, a) => n.sync(() => {
+			let n = T(t, r, i);
+			return !e.has(n) && (e.set(n, {
+				tenantId: t,
+				episode: r,
+				stepId: i,
+				sentAt: a
+			}), !0);
+		}),
+		sentSteps: (t, r) => n.sync(() => [...e.values()].filter((e) => e.tenantId === t && e.episode === r))
+	};
+}, D = () => `bdun_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`, O = (t) => ({
+	claim: (r, i, a, o) => n.tryPromise({
+		try: async () => {
+			let e = D(), n = await t.insertIgnore(l, {
+				id: e,
+				tenantId: r,
+				episode: i,
+				stepId: a,
+				sentAt: o
+			}, { conflictColumns: [
+				"tenantId",
+				"episode",
+				"stepId"
+			] });
+			return String(n.id) === e;
+		},
+		catch: (t) => new e({
+			source: "dunningNoticeStore",
+			message: String(t?.message ?? t),
+			transient: !0
+		})
+	}),
+	sentSteps: (a, o) => n.tryPromise({
+		try: async () => (await t.query({
+			table: l,
+			predicate: r(i("tenantId", a), i("episode", o)),
+			order: [],
+			take: void 0,
+			skip: void 0,
+			projection: void 0
+		})).map((e) => ({
+			tenantId: String(e.tenantId),
+			episode: String(e.episode),
+			stepId: String(e.stepId),
+			sentAt: e.sentAt == null ? null : new Date(e.sentAt)
+		})),
+		catch: (t) => new e({
+			source: "dunningNoticeStore",
+			message: String(t?.message ?? t),
+			transient: !0
+		})
+	})
+});
+//#endregion
+export { l as BILLING_DUNNING_NOTICES_TABLE, f as DEFAULT_DUNNING_STEPS, p as DEFAULT_GRACE_HOURS, m as DEFAULT_LOCKOUT, d as DUNNING_LOCK_STEP_ID, u as billingDunningNoticesTable, O as dataStoreDunningNoticeStore, C as defaultDunningEmail, b as dueSteps, w as dunningMailNotifier, v as episodeKeyOf, x as evaluateBillingEntitlement, y as graceEndOf, E as memoryDunningNoticeStore, g as resolveDunningConfig };

package/dist/economy.d.ts

@@ -0,0 +1,30 @@
+import { IapProviderDefinition } from '@voltro/plugin-economy/server';
+
+export declare interface StripeIapWebOptions {
+    /** Stripe secret or restricted key; `sk_test_`/`rk_test_` for sandbox, `_live_` for production. */
+    readonly secretKey: string;
+    readonly environment: 'sandbox' | 'production';
+    /** The economy's application ID for this provider (an identifier you choose, e.g. the app name). */
+    readonly applicationId: string;
+    /** Origins players return to after paying (`https://game.example`). */
+    readonly returnOrigins: readonly string[];
+    /** Minutes a started checkout stays open (Stripe allows 30–1440; default 30). */
+    readonly checkoutTtlMinutes?: number;
+    /** Signing secret of a Stripe webhook endpoint (`whsec_…`) pointed at the economy's notification
+     * route (`/_voltro/economy/iap/web`). Set: refunds and lost disputes revoke the purchase
+     * (`charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`), and paid checkouts and
+     * subscription renewals arrive without the player (`checkout.session.completed`, `invoice.paid`). */
+    readonly webhookSecret?: string;
+    /** Transport for tests; defaults to global `fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Clock for webhook timestamps (tests). */
+    readonly now?: () => number;
+}
+
+/** A Stripe Checkout provider for the economy's `web` channel. */
+export declare const stripeIapWebProvider: (options: StripeIapWebOptions) => IapProviderDefinition;
+
+/** The request ID a renewal invoice is redeemed under (economy identifiers have no `_`). */
+export declare const stripeRenewalRequestId: (invoice: string) => string;
+
+export { }

package/dist/economy.js

@@ -0,0 +1,266 @@
+import { StripeRestError as e, stripeRest as t } from "./stripeRest.js";
+import { Effect as n } from "effect";
+import { createHmac as r, timingSafeEqual as i } from "node:crypto";
+import { EconomyError as a, economyError as o } from "@voltro/plugin-economy/errors";
+import { iapCurrentStatePort as s, iapVerificationPort as c, issueVerifiedIapNotification as l } from "@voltro/plugin-economy/server";
+//#region src/economy.ts
+var u = /* @__PURE__ */ new Set([
+	"BIF",
+	"CLP",
+	"DJF",
+	"GNF",
+	"JPY",
+	"KMF",
+	"KRW",
+	"MGA",
+	"PYG",
+	"RWF",
+	"UGX",
+	"VND",
+	"VUV",
+	"XAF",
+	"XOF",
+	"XPF"
+]), d = /* @__PURE__ */ new Set([
+	"BHD",
+	"JOD",
+	"KWD",
+	"OMR",
+	"TND"
+]), f = (e) => u.has(e) ? 0 : d.has(e) ? 3 : 2, p = /^cs_(test|live)_[A-Za-z0-9]{1,200}$/, m = /^in_[A-Za-z0-9]{1,200}$/, h = /^pi_[A-Za-z0-9]{1,200}$/, g = /^sub_[A-Za-z0-9]{1,200}$/, _ = /^cus_[A-Za-z0-9]{1,200}$/, v = (e) => "renew." + e.replace("_", "."), y = (t) => t instanceof a ? t : o(t instanceof e && t.status >= 400 && t.status < 500 && t.status !== 429 ? "forbidden" : "unavailable"), b = (e) => {
+	let u = /^(sk|rk)_live_/.test(e.secretKey), d = /^(sk|rk)_test_/.test(e.secretKey);
+	if (!u && !d || u !== (e.environment === "production")) throw o("invalid_input");
+	let b = e.checkoutTtlMinutes ?? 30;
+	if (!Number.isInteger(b) || b < 30 || b > 1440) throw o("invalid_input");
+	let x = t(e.secretKey, e.fetch ?? fetch), S = (e) => n.tryPromise({
+		try: e,
+		catch: y
+	}), C = () => S(() => x.get("/v1/checkout/sessions", { limit: 1 })).pipe(n.asVoid), w = (t, n, r) => t.voltro_account === n && t.voltro_application === e.applicationId && t.voltro_offer === r.offer.id && t.voltro_offer_version === r.offer.version, T = (e) => n.tryPromise({
+		try: e,
+		catch: (e) => e instanceof a ? e : o("unavailable")
+	}), E = (t) => ({
+		initialize: C,
+		start: (t) => T(async () => {
+			let n = new URL(t.returnUrl);
+			n.searchParams.set("checkout", "success");
+			let r = new URL(t.returnUrl);
+			r.searchParams.set("checkout", "cancel");
+			let i = {
+				voltro_account: t.accountToken,
+				voltro_offer: t.product.offer.id,
+				voltro_offer_version: t.product.offer.version,
+				voltro_application: e.applicationId
+			}, a = t.product.kind === "subscription", s = await x.post("/v1/checkout/sessions", {
+				mode: a ? "subscription" : "payment",
+				line_items: [{
+					price: t.product.storeProductId,
+					quantity: 1
+				}],
+				success_url: n.toString() + "&checkout_id={CHECKOUT_SESSION_ID}",
+				cancel_url: r.toString(),
+				client_reference_id: t.accountToken,
+				expires_at: Math.floor(t.at / 1e3) + b * 60,
+				metadata: {
+					...i,
+					voltro_request: t.requestId
+				},
+				...a ? { subscription_data: { metadata: i } } : {}
+			});
+			if (!s.url || !p.test(s.id)) throw o("invalid_record");
+			return {
+				checkoutId: s.id,
+				redirectUrl: s.url,
+				expiresAt: s.expires_at * 1e3
+			};
+		})
+	}), D = async (t, n, r, i) => {
+		let a = await x.get(`/v1/invoices/${t}`, { expand: ["payments"] }), s = a.parent?.subscription_details, c = s?.subscription ?? null, l = a.lines.data.filter((e) => e.parent?.subscription_item_details && !e.parent.subscription_item_details.proration && e.pricing?.price_details?.price === i.storeProductId), d = (a.payments?.data ?? []).find((e) => e.status === "paid" && e.payment.type === "payment_intent")?.payment.payment_intent;
+		if (a.id !== t || a.status !== "paid" || a.livemode !== u || c === null || !g.test(c) || n !== null && c !== n || !w(s?.metadata ?? {}, r, i) || l.length !== 1 || l[0].quantity !== 1 || !(a.amount_paid > 0) || !d || !h.test(d)) throw o("forbidden");
+		let p = l[0], m = a.currency.toUpperCase();
+		return {
+			invoice: a,
+			facts: {
+				channel: "web",
+				environment: e.environment,
+				applicationId: e.applicationId,
+				transactionId: d,
+				originalTransactionId: c,
+				storeProductId: i.storeProductId,
+				kind: "subscription",
+				quantity: 1,
+				purchasedAt: p.period.start * 1e3,
+				expiresAt: p.period.end * 1e3,
+				paid: {
+					currency: m,
+					units: String(a.amount_paid),
+					scale: f(m)
+				},
+				acknowledgement: "none",
+				consumption: "none"
+			}
+		};
+	}, O = (t) => c(t, {
+		initialize: C,
+		verify: (t) => n.suspend(() => {
+			let r = t.intent.receipt, i = t.product.kind === "subscription";
+			return i && m.test(r) ? t.intent.requestId === v(r) ? S(async () => {
+				let { invoice: e, facts: n } = await D(r, null, t.accountToken, t.product);
+				if (e.billing_reason === "subscription_create") throw o("forbidden");
+				return n;
+			}) : n.fail(o("forbidden")) : p.test(r) ? S(async () => {
+				let n = await x.get(`/v1/checkout/sessions/${r}`, { expand: ["line_items"] }), a = n.metadata ?? {}, s = n.line_items?.data ?? [], c = s[0];
+				if (n.id !== r || n.mode !== (i ? "subscription" : "payment") || n.status !== "complete" || n.payment_status !== "paid" || n.livemode !== u || !w(a, t.accountToken, t.product) || a.voltro_request !== t.intent.requestId || s.length !== 1 || c?.price?.id !== t.product.storeProductId || !c.quantity || n.currency === null || n.amount_total === null) throw o("forbidden");
+				if (i) {
+					if (!n.invoice || !m.test(n.invoice) || !n.subscription) throw o("forbidden");
+					return (await D(n.invoice, n.subscription, t.accountToken, t.product)).facts;
+				}
+				let l = n.currency.toUpperCase();
+				return {
+					channel: "web",
+					environment: e.environment,
+					applicationId: e.applicationId,
+					transactionId: n.payment_intent ?? n.id,
+					originalTransactionId: null,
+					storeProductId: c.price.id,
+					kind: t.product.kind,
+					quantity: c.quantity,
+					purchasedAt: n.created * 1e3,
+					expiresAt: null,
+					paid: {
+						currency: l,
+						units: String(n.amount_total),
+						scale: f(l)
+					},
+					acknowledgement: "none",
+					consumption: "none"
+				};
+			}) : n.fail(o("forbidden"));
+		})
+	}), k = e.webhookSecret, A = e.now ?? Date.now;
+	if (k !== void 0 && !/^whsec_[A-Za-z0-9+/=_-]{8,}$/.test(k)) throw o("invalid_input");
+	let j = (e) => {
+		let t = e.headers?.["stripe-signature"], n = /* @__PURE__ */ new Map();
+		for (let e of (t ?? "").split(",")) {
+			let [t, r] = e.split("=");
+			t && r && n.set(t, [...n.get(t) ?? [], r]);
+		}
+		let a = Number(n.get("t")?.[0]), s = r("sha256", k).update(`${n.get("t")?.[0]}.${e.body}`).digest();
+		if (!(n.get("v1") ?? []).some((e) => /^[0-9a-f]{64}$/.test(e) && i(Buffer.from(e, "hex"), s)) || !Number.isSafeInteger(a) || Math.abs(A() / 1e3 - a) > 300) throw o("forbidden");
+		let c = JSON.parse(e.body);
+		if (typeof c.id != "string" || !/^evt_[A-Za-z0-9]{1,200}$/.test(c.id) || typeof c.type != "string" || typeof c.created != "number" || c.livemode !== u) throw o("invalid_record");
+		return {
+			id: c.id,
+			type: c.type,
+			created: c.created,
+			object: c.data?.object ?? {}
+		};
+	}, M = (e) => e instanceof a ? e : o("invalid_record"), N = (t) => ({
+		initialize: () => n.void,
+		verify: (r) => n.try({
+			try: () => {
+				let n = j(r), i = n.object, a = typeof i.payment_intent == "string" && h.test(i.payment_intent) ? i.payment_intent : null, o = a !== null && (n.type === "charge.refunded" || n.type === "charge.dispute.created" || n.type === "charge.dispute.closed");
+				return l({
+					channel: "web",
+					applicationId: t.applicationId,
+					environment: e.environment,
+					noticeId: n.id,
+					sourceType: "web." + n.type.replace(/[^a-z._]/g, "").slice(0, 100),
+					kind: o ? n.type === "charge.dispute.created" ? "review" : "voided" : "test",
+					occurredAt: Math.min(n.created * 1e3, A()),
+					transactionId: o ? a : null,
+					originalTransactionId: null,
+					storeProductId: null
+				}, { event: {
+					id: n.id,
+					type: n.type
+				} });
+			},
+			catch: M
+		})
+	}), P = (e) => typeof e == "string" ? e : "";
+	return {
+		channel: "web",
+		environment: e.environment,
+		applicationId: e.applicationId,
+		checkoutReturnOrigins: e.returnOrigins,
+		create: O,
+		createCheckout: E,
+		createManagement: (t) => ({
+			initialize: C,
+			open: (t) => S(async () => {
+				for (let n of t.originals) {
+					if (!g.test(n)) continue;
+					let r = await x.get(`/v1/subscriptions/${n}`), i = r.metadata ?? {};
+					if (r.id === n && r.livemode === u && _.test(r.customer) && i.voltro_account === t.accountToken && i.voltro_application === e.applicationId) return { url: (await x.post("/v1/billing_portal/sessions", {
+						customer: r.customer,
+						return_url: t.returnUrl
+					})).url };
+				}
+				throw o("not_found");
+			})
+		}),
+		...k === void 0 ? {} : {
+			createNotifications: N,
+			createCurrentState: (t) => s({
+				realMoney: !0,
+				channel: "web",
+				applicationId: t.applicationId,
+				environment: e.environment,
+				accounts: t.accounts,
+				now: t.now
+			}, {
+				initialize: C,
+				read: (e) => S(async () => {
+					let n = e.facts.transactionId;
+					if (!h.test(n)) throw o("forbidden");
+					let r = await x.get(`/v1/payment_intents/${n}`, { expand: ["latest_charge"] });
+					if (r.id !== n || r.livemode !== u || !r.latest_charge || !(r.amount_received > 0)) throw o("forbidden");
+					let i = r.latest_charge.dispute !== null && (await x.get(`/v1/disputes/${r.latest_charge.dispute}`)).status === "lost", a = r.amount_received, s = i ? a : Math.min(r.latest_charge.amount_refunded, a), c = (e, t) => t === 0 ? e : c(t, e % t), l = c(s, a) || 1, d = s / l, f = a / l;
+					f > 1e5 && (d = s === a ? 1 : Math.floor(s * 1e5 / a), f = s === a ? 1 : 1e5);
+					let p = t.now();
+					return {
+						orderId: e.orderId,
+						channel: "web",
+						state: d === 0 ? "active" : d === f ? "revoked" : "partially-refunded",
+						refundNumerator: d,
+						refundDenominator: f,
+						observedAt: p,
+						revokedAt: d === 0 ? null : p
+					};
+				})
+			}),
+			createDeliveries: (t) => ({
+				initialize: () => n.void,
+				read: (t) => n.try({
+					try: () => {
+						let n = j(t), r = n.object;
+						if (n.type === "checkout.session.completed" || n.type === "checkout.session.async_payment_succeeded") {
+							let t = r.metadata ?? {};
+							return r.payment_status !== "paid" || !p.test(P(r.id)) || t.voltro_application !== e.applicationId ? null : {
+								accountToken: P(t.voltro_account),
+								requestId: P(t.voltro_request),
+								offerId: P(t.voltro_offer),
+								offerVersion: P(t.voltro_offer_version),
+								receipt: P(r.id)
+							};
+						}
+						if (n.type === "invoice.paid") {
+							let t = r.parent?.subscription_details?.metadata ?? {};
+							return r.billing_reason === "subscription_create" || !m.test(P(r.id)) || t.voltro_application !== e.applicationId ? null : {
+								accountToken: P(t.voltro_account),
+								requestId: v(P(r.id)),
+								offerId: P(t.voltro_offer),
+								offerVersion: P(t.voltro_offer_version),
+								receipt: P(r.id)
+							};
+						}
+						return null;
+					},
+					catch: M
+				})
+			})
+		}
+	};
+};
+//#endregion
+export { b as stripeIapWebProvider, v as stripeRenewalRequestId };

package/dist/entitlement.js

@@ -0,0 +1,41 @@
+import { BillingService as e, EntitlementExceeded as t, SubscriptionLocked as n } from "./types.js";
+import { Effect as r } from "effect";
+//#region src/entitlement.ts
+var i = (e, t, n, r) => ({
+	allowed: !Number.isFinite(t) || r <= 0 || n + r <= t,
+	entitlement: e,
+	limit: t,
+	used: n,
+	cost: r
+}), a = (e) => e.tenantId, o = (n, i, o) => r.gen(function* () {
+	let s = a(n.request.subject);
+	if (s === null) return o <= 0 ? void 0 : yield* r.fail(new t({
+		entitlement: i,
+		limit: 0,
+		used: 0,
+		cost: o
+	}));
+	yield* (yield* e).consumeEntitlement(s, i, o);
+}), s = (t) => r.gen(function* () {
+	let i = a(t.request.subject);
+	if (i === null) return;
+	let o = yield* (yield* e).entitlementStatus(i);
+	if (!o.entitled) return yield* r.fail(new n({
+		tenantId: i,
+		status: o.status,
+		lockedSince: (o.lockedSince ?? /* @__PURE__ */ new Date()).toISOString(),
+		lockout: o.lockout
+	}));
+}), c = (e, n) => (i, a) => {
+	let o = e[a.tag];
+	if (o === void 0) return i;
+	let s = o.cost ?? 1, c = a.subject.tenantId;
+	return c === null ? s <= 0 ? i : r.fail(new t({
+		entitlement: o.entitlement,
+		limit: 0,
+		used: 0,
+		cost: s
+	})) : r.flatMap(n.consumeEntitlement(c, o.entitlement, s), () => i);
+};
+//#endregion
+export { c as buildEnforceInterceptor, i as evaluateEntitlement, s as requireEntitled, o as requireEntitlement };

package/dist/eventDelivery.js

@@ -0,0 +1,72 @@
+import { BillingError as e } from "./types.js";
+import { captureProviderAccount as t, sameProviderAccount as n } from "./providerIdentity.js";
+import { Effect as r, Schema as i } from "effect";
+import { beginIdempotent as a, failIdempotent as o, finishIdempotent as s, holdIdempotentClaim as c, memoryIdempotencyStore as l, prepareIdempotentInput as u, systemSubject as d } from "@voltro/protocol";
+//#region src/eventDelivery.ts
+var f = 864e5, p = (t) => new e({
+	source: "billing.delivery",
+	message: t,
+	transient: !0
+}), m = (m) => {
+	let h = l(), g, _ = d("billing.provider-delivery", []);
+	return (l) => r.tryPromise({
+		try: async () => {
+			let e = structuredClone(l);
+			if (e.rejected) throw p("The provider event could not be normalized and requires reconciliation.");
+			if (typeof e.id != "string" || !e.id || e.id.trim() !== e.id || e.createdAt !== null && (!(e.createdAt instanceof Date) || !Number.isFinite(e.createdAt.getTime()))) throw p("The verified provider delivery requires exact identity and time evidence.");
+			let d = m.receipts?.store() ?? h;
+			if (g === void 0) {
+				let e = m.provider.fetchAccountIdentity?.bind(m.provider);
+				if (e === void 0) throw p("Account-qualified provider delivery is unsupported.");
+				let i = t(await r.runPromise(e()));
+				if (g !== void 0 && !n(g, i)) throw p("The provider delivery account changed.");
+				g ??= i;
+			}
+			let v = g, y = JSON.stringify([
+				"voltro.billing-delivery.v2",
+				m.provider.name,
+				m.receipts?.scope ?? "standalone",
+				v.providerAccountId,
+				v.livemode
+			]), b = await u(i.Unknown, e, _), x = await a(d, y, e.id, b.fingerprint, f, Date.now());
+			if (x.kind === "replay") {
+				if (x.response.status !== 204 || x.response.body !== null) throw p("The retained delivery receipt is invalid.");
+				return "replayed";
+			}
+			if (x.kind !== "fresh") throw p("The provider delivery is busy or its retained input needs reconciliation.");
+			let S = c(d, x.claim);
+			try {
+				if (!await d.renew(x.claim, Date.now())) throw p("The provider delivery claim changed before processing.");
+				let t = e.event, n = e.providerCustomerId ?? (t !== null && "providerCustomerId" in t ? t.providerCustomerId : null);
+				if (t !== null && "providerCustomerId" in t && e.providerCustomerId !== null && t.providerCustomerId !== e.providerCustomerId) throw p("The provider delivery has inconsistent customer identities.");
+				let i = t?._tag === "invoicePaid" || t?._tag === "invoicePaymentFailed", a = n !== null && t?._tag !== "customerUnlinked" && !i, o = [];
+				if (t !== null && (!a || t._tag !== "subscriptionUpserted" && t._tag !== "subscriptionCanceled" && t._tag !== "customerLinked") && o.push(await r.runPromise(m.service.applyEvent(t))), a) {
+					let e = await r.runPromise(m.service.syncCustomer(n, t !== null && "tenantId" in t && typeof t.tenantId == "string" ? t.tenantId : void 0));
+					o.push(...e.events);
+				}
+				for (let t of o) {
+					if (!await d.renew(x.claim, Date.now())) throw p("The provider delivery claim changed before callback dispatch.");
+					let n = m.onEvent?.[t._tag];
+					n !== void 0 && await r.runPromise(n(t, Object.freeze({
+						provider: m.provider.name,
+						providerEventId: e.id,
+						receiptScope: y,
+						...v
+					})));
+				}
+				if (!await s(d, x.claim, {
+					status: 204,
+					body: null
+				}, Date.now())) throw p("Delivery processing finished without confirmed receipt ownership.");
+				return "processed";
+			} catch (e) {
+				throw await o(d, x.claim), e;
+			} finally {
+				S();
+			}
+		},
+		catch: (t) => t instanceof e ? t : p("Provider delivery processing failed and remains retryable.")
+	});
+};
+//#endregion
+export { m as makeBillingEventDelivery };

package/dist/flushClaim.js

@@ -0,0 +1,20 @@
+import { id as e, table as t, text as n, timestamp as r } from "@voltro/database";
+//#region src/flushClaim.ts
+var i = "_voltro_billing_flush_claims", a = t(i, {
+	id: e({ scheme: "numeric" }),
+	windowKey: n(),
+	claimedBy: n(),
+	claimedAt: r().default("now")
+}).unique("billingFlushClaimWindow", ["windowKey"]), o = (e, t) => `billing-flush:${Math.floor(e / Math.max(1, t))}`, s = async (e, t, n, r) => {
+	try {
+		return (await e.insertIgnore(i, {
+			windowKey: t,
+			claimedBy: n,
+			claimedAt: new Date(r)
+		}, { conflictColumns: ["windowKey"] })).claimedBy === n;
+	} catch {
+		return !0;
+	}
+};
+//#endregion
+export { i as BILLING_FLUSH_CLAIMS_TABLE, a as billingFlushClaimsTable, s as claimFlushWindow, o as flushWindowKey };