@dineway-ai/plugin-payment 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dineway-ai/plugin-payment",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Provider-neutral payment infrastructure and Stripe integration for Dineway plugins",
   "type": "module",
   "publishConfig": {

package/src/admin/form.ts

@@ -2,10 +2,11 @@ import type {
 	PaymentStripeConfiguration,
 	UpdatePaymentStripeConfigurationInput,
 } from "../configuration/service.js";
-import type { StripeMode } from "../types.js";
+import type { StripeCollectionMode, StripeMode } from "../types.js";
 
 export interface PaymentSettingsForm {
 	mode: StripeMode;
+	collectionMode: StripeCollectionMode;
 	publishableKey: string;
 	secretKey: string;
 	webhookSecret: string;
@@ -16,6 +17,7 @@ export function paymentSettingsForm(
 ): PaymentSettingsForm {
 	return {
 		mode: configuration.settings.mode,
+		collectionMode: configuration.settings.collectionMode,
 		publishableKey: configuration.settings.publishableKey ?? "",
 		secretKey: "",
 		webhookSecret: "",
@@ -45,6 +47,7 @@ export function buildPaymentSettingsUpdate(
 	return {
 		expectedVersion: configuration.settings.version,
 		mode: form.mode,
+		collectionMode: form.collectionMode,
 		publishableKey: publishableKey || null,
 		...(secretKey ? { secretKey } : {}),
 		...(webhookSecret ? { webhookSecret } : {}),

package/src/admin/subscriptions.tsx

@@ -183,7 +183,10 @@ export function PaymentSubscriptionsPage() {
 						<h2 className="text-lg font-semibold">Payment webhook</h2>
 						<p className="text-sm">
 							Application: {configuration.namespace} · {configuration.mode} ·{" "}
-							{configuration.ready ? "Ready" : "Configuration required"}
+							{configuration.collectionMode === "managed"
+								? "Managed Payments"
+								: "Standard Stripe Billing"}{" "}
+							· {configuration.ready ? "Ready" : "Configuration required"}
 						</p>
 						<label className="block text-sm">
 							Endpoint
@@ -408,6 +411,10 @@ export function PaymentSubscriptionsPage() {
 														{purchase.reference}
 														<br />
 														{purchase.contract.pricing.kind}
+														<br />
+														{purchase.collectionMode === "managed"
+															? "Managed Payments"
+															: "Standard"}
 													</td>
 													<td className="p-2">
 														{formatSubscriptionPrice(

package/src/admin.tsx

@@ -103,6 +103,7 @@ export function PaymentSettingsPage() {
 		configuration.settings.publishableKey &&
 		configuration.secretKey &&
 		form.mode === configuration.settings.mode &&
+		form.collectionMode === configuration.settings.collectionMode &&
 		form.publishableKey.trim() === configuration.settings.publishableKey &&
 		!form.secretKey.trim(),
 	);
@@ -150,6 +151,31 @@ export function PaymentSettingsPage() {
 						))}
 					</div>
 				</fieldset>
+				<label className="grid gap-1 text-sm font-medium">
+					Collection mode
+					<select
+						className="rounded-lg border border-kumo-line bg-kumo-base px-3 py-2 font-normal"
+						value={form.collectionMode}
+						disabled={pending}
+						onChange={(event) =>
+							setForm({
+								...form,
+								collectionMode: event.target.value === "managed" ? "managed" : "standard",
+							})
+						}
+					>
+						<option value="standard">Standard Stripe Billing (default)</option>
+						<option value="managed">Stripe Managed Payments</option>
+					</select>
+				</label>
+				<p className="text-sm text-kumo-subtle">
+					{form.collectionMode === "managed"
+						? "Stripe acts as merchant of record for eligible digital products. Enable Managed Payments in your Stripe account and assign an eligible tax code to each product. Stripe calculates tax and chooses supported payment methods."
+						: "Your business is the merchant of record and manages its tax obligations. Subscriptions use standard Stripe Billing."}{" "}
+					This setting applies to new subscription Checkouts. Existing subscriptions and pending
+					purchases keep their original mode. Restaurant orders and venue payments continue to use
+					standard payments.
+				</p>
 				<Field
 					label="Publishable key"
 					value={form.publishableKey}

package/src/configuration/repository.ts

@@ -38,6 +38,7 @@ export class PaymentStripeConfigurationRepository {
 	): Promise<PaymentStripeSettings> {
 		const update: Updateable<PaymentDatabase["payment_stripe_settings"]> = {
 			...(input.mode === undefined ? {} : { mode: input.mode }),
+			...(input.collectionMode === undefined ? {} : { collection_mode: input.collectionMode }),
 			...(input.publishableKey === undefined ? {} : { publishable_key: input.publishableKey }),
 			...(input.configurationStatus === undefined
 				? {}
@@ -75,6 +76,7 @@ function mapSettings(row: SettingsRow): PaymentStripeSettings {
 	return {
 		id: row.id,
 		mode: row.mode,
+		collectionMode: row.collection_mode,
 		publishableKey: row.publishable_key,
 		configurationStatus: row.configuration_status,
 		stripeAccountId: row.stripe_account_id,

package/src/configuration/service.ts

@@ -1,7 +1,7 @@
 import type { Database, PluginSecretStatus, PluginSecretStoreOptions } from "dineway";
 import type { Kysely, Transaction } from "kysely";
 
-import type { StripeAccountProbe, StripeMode } from "../types.js";
+import type { StripeAccountProbe, StripeCollectionMode, StripeMode } from "../types.js";
 import { PaymentStripeConfigurationRepository } from "./repository.js";
 import {
 	PAYMENT_STRIPE_SECRET_KEY,
@@ -19,6 +19,7 @@ export interface PaymentStripeConfiguration {
 export interface UpdatePaymentStripeConfigurationInput {
 	expectedVersion: number;
 	mode?: StripeMode;
+	collectionMode?: StripeCollectionMode;
 	publishableKey?: string | null;
 	secretKey?: string | null;
 	webhookSecret?: string | null;
@@ -89,6 +90,7 @@ export async function updatePaymentStripeConfiguration(
 		const credentialsComplete = Boolean(publishableKey && nextSecret);
 		await repository.updateSettings(before.version, {
 			mode,
+			collectionMode: input.collectionMode,
 			publishableKey,
 			...(credentialsChanged || !credentialsComplete
 				? {
@@ -212,6 +214,12 @@ function normalizeOptionalSecret(value: string | null): string | null {
 }
 
 function validateUpdate(input: UpdatePaymentStripeConfigurationInput): void {
+	if (
+		input.collectionMode !== undefined &&
+		!["standard", "managed"].includes(input.collectionMode)
+	) {
+		throw new PaymentConfigurationError("VALIDATION_ERROR", "Choose Standard or Managed Payments");
+	}
 	if (!Number.isSafeInteger(input.expectedVersion) || input.expectedVersion < 1) {
 		throw new PaymentConfigurationError("VALIDATION_ERROR", "Expected version is invalid");
 	}

package/src/configuration/types.ts

@@ -1,4 +1,4 @@
-import type { StripeMode, StripeTaxStatus } from "../types.js";
+import type { StripeCollectionMode, StripeMode, StripeTaxStatus } from "../types.js";
 
 export type PaymentStripeConfigurationStatus = "unconfigured" | "unverified" | "valid" | "invalid";
 export type PaymentStripeConnectStatus = "not_configured" | "restricted" | "ready";
@@ -6,6 +6,7 @@ export type PaymentStripeConnectStatus = "not_configured" | "restricted" | "read
 export interface PaymentStripeSettings {
 	id: string;
 	mode: StripeMode;
+	collectionMode: StripeCollectionMode;
 	publishableKey: string | null;
 	configurationStatus: PaymentStripeConfigurationStatus;
 	stripeAccountId: string | null;
@@ -22,6 +23,7 @@ export interface PaymentStripeSettings {
 
 export interface UpdatePaymentStripeSettings {
 	mode?: StripeMode;
+	collectionMode?: StripeCollectionMode;
 	publishableKey?: string | null;
 	configurationStatus?: PaymentStripeConfigurationStatus;
 	stripeAccountId?: string | null;

package/src/database/index.ts

@@ -3,10 +3,12 @@ import type { PluginMigration } from "dineway";
 import * as configuration from "./migrations/001_stripe_configuration.js";
 import * as subscriptions from "./migrations/002_subscriptions.js";
 import * as purchases from "./migrations/003_purchases.js";
+import * as collectionMode from "./migrations/004_collection_mode.js";
 
 export const paymentMigrations = {
 	"001_stripe_configuration": configuration,
 	"002_subscriptions": subscriptions,
 	"003_purchases": purchases,
+	"004_collection_mode": collectionMode,
 } satisfies Record<string, PluginMigration>;
 export type { PaymentDatabase, PaymentTables } from "./types.js";

package/src/database/migrations/004_collection_mode.ts

@@ -0,0 +1,26 @@
+import { sql, type Kysely } from "kysely";
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+	for (const table of ["payment_stripe_settings", "payment_subscription_purchases"]) {
+		await db.schema
+			.alterTable(table)
+			.addColumn("collection_mode", "text", (column) =>
+				column
+					.notNull()
+					.defaultTo("standard")
+					.check(sql`collection_mode IN ('standard', 'managed')`),
+			)
+			.execute();
+	}
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	const purchases = await sql`SELECT 1 FROM payment_subscription_purchases LIMIT 1`.execute(db);
+	if (purchases.rows.length)
+		throw new Error(
+			"Restore a database snapshot to roll back payment purchases without losing their collection mode.",
+		);
+	for (const table of ["payment_subscription_purchases", "payment_stripe_settings"]) {
+		await db.schema.alterTable(table).dropColumn("collection_mode").execute();
+	}
+}

package/src/database/types.ts

@@ -1,6 +1,8 @@
 import type { Database } from "dineway";
 import type { Generated } from "kysely";
 
+import type { StripeCollectionMode } from "../types.js";
+
 export interface PaymentSubscriptionKey {
 	scope: string;
 	id: string;
@@ -86,6 +88,7 @@ export interface PaymentSubscriptionPortalTable extends PaymentSubscriptionKey {
 }
 
 export interface PaymentSubscriptionPurchaseTable extends PaymentSubscriptionKey {
+	collection_mode: Generated<StripeCollectionMode>;
 	user_id: string;
 	group_key: string;
 	contract: string;
@@ -117,6 +120,7 @@ export interface PaymentStripeSettingsTable {
 	id: string;
 	default_key: Generated<"default">;
 	mode: Generated<PaymentStripeMode>;
+	collection_mode: Generated<StripeCollectionMode>;
 	publishable_key: string | null;
 	configuration_status: Generated<PaymentStripeConfigurationStatus>;
 	stripe_account_id: string | null;

package/src/routes/index.ts

@@ -22,7 +22,7 @@ import {
 } from "./schemas.js";
 
 const AUTHORIZATION = {
-	permission: "content:edit_any" as const,
+	permission: "payments:manage" as const,
 	anyOfTokenScopes: ["admin"],
 };
 

package/src/routes/schemas.ts

@@ -6,6 +6,7 @@ export const updatePaymentStripeConfigurationSchema = z
 	.object({
 		expectedVersion: z.number().int().positive(),
 		mode: z.enum(["test", "live"]).optional(),
+		collectionMode: z.enum(["standard", "managed"]).optional(),
 		publishableKey: z.string().max(512).nullable().optional(),
 		secretKey: z.string().max(512).nullable().optional(),
 		webhookSecret: z.string().max(512).nullable().optional(),

package/src/subscriptions/funding.ts

@@ -1,5 +1,6 @@
 import type Stripe from "stripe";
 
+import type { StripeCollectionMode } from "../types.js";
 import { relationId } from "./purchases.js";
 import {
 	SubscriptionError,
@@ -92,13 +93,31 @@ export async function invoiceFunding(
 	invoice: Stripe.Invoice,
 	contract: PurchaseContract | null,
 	now: number,
+	collectionMode: StripeCollectionMode = "standard",
 ): Promise<InvoiceFundingEvidence> {
 	const item = subscription.items.data[0]!;
 	const amount = contract?.amount ?? item.price.unit_amount ?? 0;
 	const currency = contract?.currency ?? item.price.currency;
 	const credit =
 		invoice.billing_reason === "subscription_create" ? (contract?.firstPeriodCredit ?? 0) : 0;
-	const cash = amount - credit;
+	const taxes = invoice.total_taxes ?? [];
+	const invalidTax = taxes.some(
+		(tax) =>
+			!Number.isSafeInteger(tax.amount) ||
+			tax.amount < 0 ||
+			(tax.amount !== 0 &&
+				(collectionMode !== "managed" || !["exclusive", "inclusive"].includes(tax.tax_behavior))),
+	);
+	const exclusiveTax = taxes.reduce(
+		(sum, tax) => sum + (tax.tax_behavior === "exclusive" ? tax.amount : 0),
+		0,
+	);
+	// Stripe line subtotals exclude inclusive tax; invoice subtotals retain it.
+	const inclusiveTax = taxes.reduce(
+		(sum, tax) => sum + (tax.tax_behavior === "inclusive" ? tax.amount : 0),
+		0,
+	);
+	const cash = amount - credit + exclusiveTax;
 	const evidence: InvoiceFundingEvidence = {
 		verifiedAt: now,
 		amount,
@@ -132,7 +151,7 @@ export async function invoiceFunding(
 		line.quantity !== 1 ||
 		line.currency !== currency ||
 		line.amount !== amount ||
-		line.subtotal !== amount ||
+		line.subtotal !== amount - inclusiveTax ||
 		invoice.subtotal !== amount ||
 		invoice.total !== cash ||
 		invoice.amount_due !== cash ||
@@ -142,7 +161,11 @@ export async function invoiceFunding(
 		invoice.ending_balance !== 0 ||
 		invoice.pre_payment_credit_notes_amount !== 0 ||
 		invoice.post_payment_credit_notes_amount !== 0 ||
-		invoice.total_taxes?.some((tax) => tax.amount !== 0) ||
+		invalidTax ||
+		!Number.isSafeInteger(inclusiveTax) ||
+		inclusiveTax > amount - credit ||
+		!Number.isSafeInteger(cash) ||
+		cash < 0 ||
 		!Number.isSafeInteger(line.period.start) ||
 		!Number.isSafeInteger(line.period.end) ||
 		line.period.start >= line.period.end
@@ -245,7 +268,7 @@ export async function invoiceFunding(
 		const resolved =
 			typeof method === "string" ? await stripe.paymentMethods.retrieve(method) : method;
 		if (
-			resolved.type !== "card" ||
+			(collectionMode === "standard" && resolved.type !== "card") ||
 			resolved.livemode !== invoice.livemode ||
 			relationId(resolved.customer) !== customer
 		)

package/src/subscriptions/projection.ts

@@ -94,6 +94,7 @@ export function subscriptionProjection(
 		const { contract } = purchase;
 		if (
 			purchase.userId !== userId ||
+			Boolean(subscription.managed_payments?.enabled) !== (purchase.collectionMode === "managed") ||
 			subscription.metadata.purchase_reference !== purchase.reference ||
 			(purchase.subscriptionId && purchase.subscriptionId !== subscription.id) ||
 			item.price.livemode !== (scope.mode === "live") ||

package/src/subscriptions/purchases.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 
 import type Stripe from "stripe";
 
+import type { StripeCollectionMode } from "../types.js";
 import { recurringPrice } from "./projection.js";
 import type { SubscriptionRepository } from "./repository.js";
 import { purchaseSchema } from "./schemas.js";
@@ -24,6 +25,7 @@ export interface PurchaseContext {
 	scope: SubscriptionScope;
 	now: () => number;
 	origin: string;
+	collectionMode: StripeCollectionMode;
 }
 const idempotency = (context: PurchaseContext, ...values: unknown[]) =>
 	"dineway:" + digest([context.repository.scope, ...values]);
@@ -108,6 +110,8 @@ export async function createPurchase(
 	input: SubscriptionPurchaseInput,
 ) {
 	const parsed = purchaseSchema.parse(input);
+	if (!["standard", "managed"].includes(context.collectionMode))
+		throw new SubscriptionError("INVALID_COLLECTION_MODE", "Choose Standard or Managed Payments");
 	return context.repository.withLock("member:" + userId, async (store) => {
 		const previous = await store.purchase(parsed.reference);
 		if (previous) {
@@ -128,6 +132,15 @@ export async function createPurchase(
 				"Resolve the existing purchase before starting another",
 				409,
 			);
+		if (
+			context.collectionMode === "managed" &&
+			parsed.pricing.kind === "dynamic" &&
+			!parsed.pricing.taxCode
+		)
+			throw new SubscriptionError(
+				"MANAGED_PAYMENTS_TAX_CODE_REQUIRED",
+				"Managed Payments requires an eligible Stripe product tax code",
+			);
 		let contract: PurchaseContract;
 		if (parsed.pricing.kind === "catalogue") {
 			const pricing = parsed.pricing;
@@ -149,6 +162,23 @@ export async function createPurchase(
 				verified.interval !== price.interval
 			)
 				throw new SubscriptionError("PRICE_CHANGED", "Refresh the plan price before checkout", 409);
+			if (context.collectionMode === "managed") {
+				const product = await context.stripe.products.retrieve(price.productId);
+				if (
+					product.deleted ||
+					!product.active ||
+					product.livemode !== (context.scope.mode === "live")
+				)
+					throw new SubscriptionError(
+						"INVALID_PRODUCT",
+						"Choose an active product from this Stripe environment",
+					);
+				if (!product.tax_code)
+					throw new SubscriptionError(
+						"MANAGED_PAYMENTS_TAX_CODE_REQUIRED",
+						"Set an eligible tax code on the Stripe product before using Managed Payments",
+					);
+			}
 			contract = {
 				...parsed,
 				amount: price.amount,
@@ -185,6 +215,7 @@ export async function createPurchase(
 			contract,
 			digest(parsed),
 			Math.floor(context.now() / 1000) + 3600,
+			context.collectionMode,
 		);
 		return resumePurchase(context, store, (await store.purchase(parsed.reference))!);
 	});
@@ -274,9 +305,12 @@ export async function resumePurchase(
 					price_data: {
 						currency: contract.currency,
 						unit_amount: contract.amount,
+						tax_behavior:
+							contract.pricing.kind === "dynamic" ? contract.pricing.taxBehavior : undefined,
 						recurring: { interval: contract.interval, interval_count: contract.intervalCount },
 						product_data: {
 							name: contract.pricing.kind === "dynamic" ? contract.pricing.name : "Subscription",
+							tax_code: contract.pricing.kind === "dynamic" ? contract.pricing.taxCode : undefined,
 							metadata,
 						},
 					},
@@ -287,7 +321,10 @@ export async function resumePurchase(
 				mode: "subscription",
 				customer: customerId,
 				line_items: [line],
-				payment_method_types: ["card"],
+				managed_payments: { enabled: purchase.collectionMode === "managed" },
+				...(purchase.collectionMode === "standard"
+					? { payment_method_types: ["card" as const] }
+					: {}),
 				payment_method_collection: "always",
 				client_reference_id: purchase.reference,
 				metadata,
@@ -305,6 +342,7 @@ export async function resumePurchase(
 	if (
 		relationId(session.customer) !== customerId ||
 		session.mode !== "subscription" ||
+		Boolean(session.managed_payments?.enabled) !== (purchase.collectionMode === "managed") ||
 		session.livemode !== (context.scope.mode === "live") ||
 		session.metadata?.dineway_app !== context.scope.namespace ||
 		session.metadata.user_id !== purchase.userId ||

package/src/subscriptions/repository.ts

@@ -478,6 +478,7 @@ export class SubscriptionRepository {
 		if (!row) return null;
 		return {
 			reference: row.id,
+			collectionMode: row.collection_mode,
 			userId: row.user_id,
 			contract: JSON.parse(row.contract),
 			createdAt: row.created_at,
@@ -523,6 +524,7 @@ export class SubscriptionRepository {
 		contract: PurchaseContract,
 		digest: string,
 		expiresAt: number,
+		collectionMode: SubscriptionPurchase["collectionMode"],
 	) {
 		await this.db.transaction().execute(async (trx) => {
 			await this.assertLease(trx);
@@ -534,6 +536,7 @@ export class SubscriptionRepository {
 					user_id: userId,
 					group_key: contract.groupKey,
 					contract: JSON.stringify(contract),
+					collection_mode: collectionMode,
 					fingerprint: digest,
 					created_at: this.now(),
 					expires_at: expiresAt,

package/src/subscriptions/runtime.ts

@@ -41,6 +41,7 @@ export async function getPaymentSubscriptionService(
 		siteUrl: options.siteUrl,
 		secretKey,
 		webhookSecret,
+		collectionMode: config.settings.collectionMode,
 	});
 }
 
@@ -53,6 +54,7 @@ export async function getSubscriptionConfiguration(options: SubscriptionOptions)
 	return {
 		namespace: options.namespace,
 		mode: configuration.settings.mode,
+		collectionMode: configuration.settings.collectionMode,
 		accountId: configuration.settings.stripeAccountId,
 		ready:
 			configuration.settings.configurationStatus === "valid" &&

package/src/subscriptions/schemas.ts

@@ -127,6 +127,11 @@ export const purchaseSchema = z
 					currency: z.string().regex(/^[a-z]{3}$/),
 					interval: z.enum(["day", "week", "month", "year"]),
 					intervalCount: z.number().int().min(1).max(365),
+					taxCode: z
+						.string()
+						.regex(/^txcd_[0-9]+$/)
+						.optional(),
+					taxBehavior: z.enum(["exclusive", "inclusive"]).optional(),
 				})
 				.strict(),
 		]),

package/src/subscriptions/service.ts

@@ -5,7 +5,7 @@ import type { Kysely } from "kysely";
 import Stripe from "stripe";
 
 import { StripeNodeWebhookVerifier } from "../stripe/webhook-verifier.js";
-import type { StripeWebhookEvent } from "../types.js";
+import type { StripeCollectionMode, StripeWebhookEvent } from "../types.js";
 import { collectBounded, invoiceFunding, inspectCharge } from "./funding.js";
 import {
 	recurringPrice,
@@ -45,6 +45,7 @@ import {
 } from "./types.js";
 
 export interface SubscriptionServiceOptions {
+	collectionMode?: StripeCollectionMode;
 	db: Kysely<Database>;
 	scope: SubscriptionScope;
 	siteUrl: string;
@@ -237,6 +238,7 @@ export class PaymentSubscriptionService {
 			scope: this.options.scope,
 			now: this.now,
 			origin: this.origin,
+			collectionMode: this.options.collectionMode ?? "standard",
 		};
 	}
 	private async resolveSubject(subject: BillingSubject | string) {
@@ -567,6 +569,7 @@ export class PaymentSubscriptionService {
 						invoice,
 						purchase?.contract ?? null,
 						this.now(),
+						purchase?.collectionMode ?? "standard",
 					);
 					const old = previousPeriods.filter((period) => period.invoiceId === invoiceId);
 					const projected = old.length

package/src/subscriptions/types.ts

@@ -1,4 +1,4 @@
-import type { StripeMode } from "../types.js";
+import type { StripeCollectionMode, StripeMode } from "../types.js";
 
 export type SubscriptionEntitlements = Record<string, boolean | number>;
 export type SubscriptionInterval = "month" | "year";
@@ -92,6 +92,8 @@ export type PurchasePricing =
 			currency: string;
 			interval: "day" | "week" | "month" | "year";
 			intervalCount: number;
+			taxCode?: string;
+			taxBehavior?: "exclusive" | "inclusive";
 	  };
 export interface SubscriptionPurchaseInput {
 	reference: string;
@@ -110,6 +112,7 @@ export interface PurchaseContract extends SubscriptionPurchaseInput {
 	couponId: string | null;
 }
 export interface SubscriptionPurchase {
+	collectionMode: StripeCollectionMode;
 	reference: string;
 	userId: string;
 	contract: PurchaseContract;

package/src/types.ts

@@ -1,5 +1,6 @@
 export type { PaymentDatabase, PaymentTables } from "./database/types.js";
 export type StripeMode = "test" | "live";
+export type StripeCollectionMode = "standard" | "managed";
 export type StripeTaxStatus = "unknown" | "active" | "pending" | "unavailable";
 
 export type StripeProviderErrorCode =