@voltro/plugin-billing 0.85.0 → 0.86.0

package/README.md

@@ -20,6 +20,13 @@ Installation, guides, the full API reference, and examples all live in the
 **[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
 deliberately short so there is nothing here to drift out of date.
 
+
+`billing.subscription` and `billing.entitlementStatus` stream changes from the subscription table; `billing.invoices` follows invoice and customer-link changes. Cancelling, resuming, webhooks and reconciliation therefore update existing query subscriptions without client polling or reloading. Tenant and scope checks apply to each recomputation.
+
+Checkout and portal URL routes recheck current authentication and their declared
+manager guard after provider IO, before releasing the private URL. A refusal does
+not undo or replay an already created external session.
+
 ## License
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the

package/THIRD-PARTY-NOTICES.md

@@ -1,11 +1,11 @@
 # Third-Party Notices — @voltro/plugin-billing
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-billing itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (42 packages).
+Generated from the resolved runtime dependency closure (41 packages).
 
 ---
 
@@ -3636,34 +3636,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## lib0@0.2.117
 
 License: MIT
@@ -4013,14 +3985,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/catalog.js

@@ -0,0 +1,471 @@
+import { Stripe as e } from "./stripeClient.js";
+import { STRIPE_WEBHOOK_EVENTS as t } from "./stripeProvider.js";
+//#region src/catalog.ts
+var n = e.API_VERSION, r = [
+	"Checkout → \"Limit customers to one subscription\" (with the customer portal login link enabled) — Stripe's own refusal of a second subscription",
+	"Smart Retries + failed-payment emails (Billing → Revenue recovery)",
+	"invoice branding and email settings",
+	"a restricted key (rk_) for the app, separate from the provisioning key"
+], i = (e) => typeof e.tax_code == "string" ? e.tax_code : e.tax_code?.id ?? null, a = (e) => ({
+	name: e.name,
+	description: e.description,
+	unit_label: e.unitLabel,
+	tax_code: e.taxCode,
+	metadata: {
+		...e.metadata,
+		voltro_key: e.key
+	}
+}), o = (e, t) => {
+	let n = [];
+	t.active || n.push("active"), t.name !== e.name && n.push("name"), (t.description ?? "") !== e.description && n.push("description"), (t.unit_label ?? "") !== e.unitLabel && n.push("unit_label"), i(t) !== e.taxCode && n.push("tax_code");
+	for (let [r, i] of Object.entries({
+		...e.metadata,
+		voltro_key: e.key
+	})) t.metadata[r] !== i && n.push(`metadata.${r}`);
+	return n;
+}, s = (e, t) => {
+	let n = `product ${e.key}`, r = t.filter((t) => t.metadata.voltro_key === e.key);
+	if (r.length > 1) return {
+		finding: {
+			kind: "manual",
+			object: n,
+			detail: `${r.length} products carry this key — archive the extra ones`
+		},
+		id: null
+	};
+	let i = r[0];
+	if (i !== void 0) {
+		let t = o(e, i);
+		return t.length === 0 ? {
+			finding: {
+				kind: "ok",
+				object: n
+			},
+			id: i.id
+		} : {
+			finding: {
+				kind: "update",
+				object: n,
+				detail: t.join(", "),
+				apply: {
+					method: "POST",
+					path: `/v1/products/${i.id}`,
+					params: {
+						...a(e),
+						active: !0
+					}
+				}
+			},
+			id: i.id
+		};
+	}
+	let s = t.filter((t) => t.active && t.metadata.voltro_key === void 0 && Object.keys(e.metadata).length > 0 && Object.entries(e.metadata).every(([e, n]) => t.metadata[e] === n));
+	if (s.length === 1) {
+		let t = s[0];
+		return {
+			finding: {
+				kind: "adopt",
+				object: n,
+				detail: "existing product gets the catalog key",
+				apply: {
+					method: "POST",
+					path: `/v1/products/${t.id}`,
+					params: a(e)
+				}
+			},
+			id: t.id
+		};
+	}
+	return s.length > 1 ? {
+		finding: {
+			kind: "manual",
+			object: n,
+			detail: `${s.length} products could be this one — archive all but one`
+		},
+		id: null
+	} : {
+		finding: {
+			kind: "create",
+			object: n,
+			detail: e.name,
+			apply: {
+				method: "POST",
+				path: "/v1/products",
+				params: a(e)
+			}
+		},
+		id: null
+	};
+}, c = (e, t, n, r) => {
+	let i = [];
+	return r.product !== t && i.push("product"), r.currency !== e.currency && i.push("currency"), r.unit_amount !== e.unitAmount && i.push("unit_amount"), r.recurring?.interval !== e.interval && i.push("interval"), r.recurring?.usage_type !== e.usageType && i.push("usage_type"), e.usageType === "metered" && r.recurring?.meter !== n && i.push("meter"), r.tax_behavior !== e.taxBehavior && i.push("tax_behavior"), i;
+}, l = (e, t, n, r) => ({
+	product: t,
+	currency: e.currency,
+	unit_amount: e.unitAmount,
+	recurring: {
+		interval: e.interval,
+		usage_type: e.usageType,
+		...e.usageType === "metered" && n !== null ? { meter: n } : {}
+	},
+	tax_behavior: e.taxBehavior,
+	lookup_key: e.lookupKey,
+	...r ? { transfer_lookup_key: !0 } : {},
+	metadata: { voltro_key: e.lookupKey }
+}), u = (e, t, n, r, i, a) => {
+	let o = `price ${e.lookupKey}`;
+	if (t === null) return {
+		finding: {
+			kind: "manual",
+			object: o,
+			detail: "its product is unresolved"
+		},
+		id: null
+	};
+	if (e.usageType === "metered" && n === null) return {
+		finding: {
+			kind: "manual",
+			object: o,
+			detail: "its meter is unresolved"
+		},
+		id: null
+	};
+	if (r !== null) {
+		let i = c(e, t, n, r);
+		if (i.length > 0) {
+			let s = {
+				method: "POST",
+				path: "/v1/prices",
+				params: l(e, t, n, !0)
+			};
+			return a ? {
+				finding: {
+					kind: "drift",
+					object: o,
+					detail: `replaced (${i.join(", ")}); existing subscriptions keep the old price`,
+					apply: s
+				},
+				id: null
+			} : {
+				finding: {
+					kind: "drift",
+					object: o,
+					detail: `${i.join(", ")} differ — a price change; rerun with --allow-price-change to replace it`
+				},
+				id: r.id
+			};
+		}
+		return r.active ? {
+			finding: {
+				kind: "ok",
+				object: o
+			},
+			id: r.id
+		} : {
+			finding: {
+				kind: "update",
+				object: o,
+				detail: "inactive",
+				apply: {
+					method: "POST",
+					path: `/v1/prices/${r.id}`,
+					params: { active: !0 }
+				}
+			},
+			id: r.id
+		};
+	}
+	let s = i.filter((r) => r.active && r.lookup_key === null && c(e, t, n, r).length === 0)[0];
+	return s === void 0 ? {
+		finding: {
+			kind: "create",
+			object: o,
+			detail: `${e.unitAmount} ${e.currency} / ${e.interval}`,
+			apply: {
+				method: "POST",
+				path: "/v1/prices",
+				params: l(e, t, n, !1)
+			}
+		},
+		id: null
+	} : {
+		finding: {
+			kind: "adopt",
+			object: o,
+			detail: "existing price gets the lookup key",
+			apply: {
+				method: "POST",
+				path: `/v1/prices/${s.id}`,
+				params: {
+					lookup_key: e.lookupKey,
+					metadata: { voltro_key: e.lookupKey }
+				}
+			}
+		},
+		id: s.id
+	};
+}, d = (e, t) => {
+	let n = `meter ${e.eventName}`, r = t.find((t) => t.event_name === e.eventName);
+	if (r === void 0) return {
+		finding: {
+			kind: "create",
+			object: n,
+			detail: e.displayName,
+			apply: {
+				method: "POST",
+				path: "/v1/billing/meters",
+				params: {
+					display_name: e.displayName,
+					event_name: e.eventName,
+					default_aggregation: { formula: e.formula },
+					customer_mapping: {
+						type: "by_id",
+						event_payload_key: e.customerPayloadKey
+					},
+					value_settings: { event_payload_key: e.valuePayloadKey }
+				}
+			}
+		},
+		id: null
+	};
+	let i = [];
+	return r.default_aggregation.formula !== e.formula && i.push("aggregation"), (r.customer_mapping.type !== "by_id" || r.customer_mapping.event_payload_key !== e.customerPayloadKey) && i.push("customer mapping"), r.value_settings.event_payload_key !== e.valuePayloadKey && i.push("value key"), i.length > 0 ? {
+		finding: {
+			kind: "drift",
+			object: n,
+			detail: `${i.join(", ")} differ and cannot be edited — a new meter needs a new event name`
+		},
+		id: r.id
+	} : r.status === "active" ? r.display_name === e.displayName ? {
+		finding: {
+			kind: "ok",
+			object: n
+		},
+		id: r.id
+	} : {
+		finding: {
+			kind: "update",
+			object: n,
+			detail: "display name",
+			apply: {
+				method: "POST",
+				path: `/v1/billing/meters/${r.id}`,
+				params: { display_name: e.displayName }
+			}
+		},
+		id: r.id
+	} : {
+		finding: {
+			kind: "update",
+			object: n,
+			detail: "inactive",
+			apply: {
+				method: "POST",
+				path: `/v1/billing/meters/${r.id}/reactivate`,
+				params: {}
+			}
+		},
+		id: r.id
+	};
+}, f = (e, t) => {
+	let n = "tax settings", r = t.head_office?.address ?? {}, i = [];
+	for (let [t, n] of Object.entries(e.headOffice)) r[t] !== n && i.push(`head_office.${t}`);
+	return t.defaults.tax_code !== e.defaultTaxCode && i.push("defaults.tax_code"), t.defaults.tax_behavior !== e.defaultTaxBehavior && i.push("defaults.tax_behavior"), i.length === 0 ? t.status === "active" ? {
+		kind: "ok",
+		object: n
+	} : {
+		kind: "manual",
+		object: n,
+		detail: `status ${t.status}`
+	} : {
+		kind: "update",
+		object: n,
+		detail: i.join(", "),
+		apply: {
+			method: "POST",
+			path: "/v1/tax/settings",
+			params: {
+				head_office: { address: e.headOffice },
+				defaults: {
+					tax_code: e.defaultTaxCode,
+					tax_behavior: e.defaultTaxBehavior
+				}
+			}
+		}
+	};
+}, p = (e, t, n) => ({
+	business_profile: {
+		headline: e.headline,
+		privacy_policy_url: e.privacyPolicyUrl,
+		terms_of_service_url: e.termsOfServiceUrl
+	},
+	default_return_url: t.portalReturnUrl,
+	features: {
+		customer_update: {
+			enabled: !0,
+			allowed_updates: [
+				"email",
+				"address",
+				"tax_id",
+				"name"
+			]
+		},
+		invoice_history: { enabled: !0 },
+		payment_method_update: { enabled: !0 },
+		subscription_cancel: {
+			enabled: !0,
+			mode: "at_period_end"
+		},
+		subscription_update: {
+			enabled: !0,
+			default_allowed_updates: ["price", "quantity"],
+			proration_behavior: "create_prorations",
+			products: n.map((e) => ({
+				product: e.productId,
+				prices: [e.priceId]
+			}))
+		}
+	},
+	metadata: { voltro_key: e.key }
+}), m = (e) => JSON.stringify([...e ?? []].sort()), h = (e, t) => {
+	let n = [], r = t.features, i = e.features;
+	t.default_return_url !== e.default_return_url && n.push("default_return_url");
+	let a = e.business_profile;
+	for (let e of Object.keys(a)) t.business_profile[e] !== a[e] && n.push(`business_profile.${e}`);
+	for (let e of [
+		"customer_update",
+		"invoice_history",
+		"payment_method_update",
+		"subscription_cancel"
+	]) r[e]?.enabled !== !0 && n.push(`${e}.enabled`);
+	m(r.customer_update?.allowed_updates) !== m(i.customer_update.allowed_updates) && n.push("customer_update.allowed_updates"), r.subscription_cancel?.mode !== "at_period_end" && n.push("subscription_cancel.mode");
+	let o = r.subscription_update ?? {}, s = i.subscription_update;
+	o.enabled !== !0 && n.push("subscription_update.enabled"), o.proration_behavior !== s.proration_behavior && n.push("subscription_update.proration_behavior");
+	let c = (e) => JSON.stringify((e ?? []).map((e) => `${e.product}:${[...e.prices].sort().join("|")}`).sort());
+	return c(o.products) !== c(s.products) && n.push("subscription_update.products"), m(o.default_allowed_updates) !== m(s.default_allowed_updates) && n.push("subscription_update.default_allowed_updates"), n;
+}, g = (e, t, n, r) => {
+	let i = "customer portal";
+	if (n === null) return [{
+		kind: "manual",
+		object: i,
+		detail: "its plan prices are unresolved"
+	}];
+	let a = p(e, t, n), o = r.find((t) => t.metadata.voltro_key === e.key) ?? r.find((t) => t.active && t.name === e.name);
+	if (o === void 0) return [{
+		kind: "create",
+		object: i,
+		detail: "self-service configuration",
+		apply: {
+			method: "POST",
+			path: "/v1/billing_portal/configurations",
+			params: {
+				...a,
+				name: e.name
+			}
+		}
+	}, ...r.some((e) => e.is_default) ? [{
+		kind: "manual",
+		object: i,
+		detail: "another configuration is the default — make this one the default in the Dashboard"
+	}] : []];
+	let s = [], c = h(a, o), l = o.metadata.voltro_key !== e.key;
+	return c.length > 0 || l || !o.active ? s.push({
+		kind: l ? "adopt" : "update",
+		object: i,
+		detail: [...c, ...o.active ? [] : ["active"]].join(", ") || "catalog key",
+		apply: {
+			method: "POST",
+			path: `/v1/billing_portal/configurations/${o.id}`,
+			params: {
+				...a,
+				active: !0
+			}
+		}
+	}) : s.push({
+		kind: "ok",
+		object: i
+	}), o.is_default || s.push({
+		kind: "manual",
+		object: i,
+		detail: "not the account default — portal sessions would use another configuration"
+	}), s;
+}, _ = (e, r) => {
+	if (e.webhookUrl === null) return {
+		kind: "ok",
+		object: "webhook endpoint (none: stripe listen forwards locally)"
+	};
+	let i = `webhook endpoint ${e.webhookUrl}`, a = r.filter((t) => t.url === e.webhookUrl);
+	if (a.length > 1) return {
+		kind: "manual",
+		object: i,
+		detail: `${a.length} endpoints for this url — delete all but one`
+	};
+	let o = a[0], s = [...t].sort();
+	return o === void 0 ? {
+		kind: "create",
+		object: i,
+		detail: `${s.length} events`,
+		apply: {
+			method: "POST",
+			path: "/v1/webhook_endpoints",
+			params: {
+				url: e.webhookUrl,
+				enabled_events: s,
+				api_version: n,
+				description: "Voltro billing"
+			}
+		}
+	} : o.api_version !== null && o.api_version !== n ? {
+		kind: "drift",
+		object: i,
+		detail: `api version ${o.api_version} — payloads would not match the SDK; recreate it (and rotate STRIPE_WEBHOOK_SECRET)`
+	} : JSON.stringify([...o.enabled_events].sort()) !== JSON.stringify(s) || o.status !== "enabled" ? {
+		kind: "update",
+		object: i,
+		detail: o.status === "enabled" ? "events" : "disabled",
+		apply: {
+			method: "POST",
+			path: `/v1/webhook_endpoints/${o.id}`,
+			params: {
+				enabled_events: s,
+				disabled: !1
+			}
+		}
+	} : {
+		kind: "ok",
+		object: i
+	};
+}, v = (e) => {
+	let t = [];
+	for (let n of e.catalog.tax.registrationCountries) e.activeRegistrations.includes(n) || t.push({
+		kind: "manual",
+		object: `tax registration ${n}`,
+		detail: "none active — automatic tax collects nothing until it is registered (Dashboard → Tax → Registrations)"
+	});
+	if (!e.env.requireSellingReadiness) return t;
+	e.chargesEnabled === !1 && t.push({
+		kind: "manual",
+		object: "account",
+		detail: "charges not enabled — finish activation (business details, bank account) in the Dashboard"
+	}), e.chargesEnabled === null && t.push({
+		kind: "manual",
+		object: "account",
+		detail: "activation not readable with this key — check it in the Dashboard"
+	}), e.accountTaxIds === 0 && t.push({
+		kind: "manual",
+		object: "account tax id",
+		detail: "no VAT id on the account — invoices lack the issuer id"
+	}), e.accountTaxIds === null && t.push({
+		kind: "manual",
+		object: "account tax id",
+		detail: "not readable with this key — check Dashboard → Settings → Tax ids"
+	});
+	for (let n of e.catalog.dashboardReminders ?? r) t.push({
+		kind: "manual",
+		object: "dashboard",
+		detail: `${n} — not checkable through the API`
+	});
+	return t;
+};
+//#endregion
+export { n as STRIPE_API_VERSION, r as STRIPE_DASHBOARD_REMINDERS, d as diffMeter, g as diffPortal, u as diffPrice, s as diffProduct, f as diffTaxSettings, _ as diffWebhook, p as portalParams, v as sellingReadiness };