@dineway-ai/plugin-payment 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dineway-ai/plugin-payment",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Provider-neutral payment infrastructure and Stripe integration for Dineway plugins",
   "type": "module",
   "publishConfig": {
@@ -13,7 +13,8 @@
     "./configuration": "./src/configuration/index.ts",
     "./routes": "./src/routes/index.ts",
     "./stripe": "./src/stripe/index.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./subscriptions": "./src/subscriptions/index.ts"
   },
   "files": [
     "src"
@@ -28,7 +29,7 @@
   "license": "MIT",
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "dineway": "^0.2.19"
+    "dineway": "^0.2.29"
   },
   "dependencies": {
     "@stripe/stripe-js": "9.9.0",

package/src/admin/subscriptions.tsx

@@ -0,0 +1,514 @@
+import * as React from "react";
+
+import { formatSubscriptionPrice } from "../subscriptions/format.js";
+import type { getSubscriptionConfiguration } from "../subscriptions/runtime.js";
+import type {
+	MemberBilling,
+	MemberSubscription,
+	SaveSubscriptionPlan,
+	SubscriptionPlan,
+} from "../subscriptions/types.js";
+import { postPaymentRoute } from "./api.js";
+
+type Configuration = Awaited<ReturnType<typeof getSubscriptionConfiguration>>;
+type Feature = { key: string; kind: "boolean" | "number"; value: string };
+const emptyPlan: SaveSubscriptionPlan = {
+	code: "",
+	name: "",
+	enabled: true,
+	expectedVersion: 0,
+	entitlements: {},
+	monthlyPriceId: null,
+	yearlyPriceId: null,
+};
+const inputClass = "w-full rounded-lg border border-kumo-line bg-kumo-base px-3 py-2 text-sm";
+const buttonClass = "rounded-lg border border-kumo-line px-3 py-2 text-sm disabled:opacity-50";
+
+export function PaymentSubscriptionsPage() {
+	const [configuration, setConfiguration] = React.useState<Configuration | null>(null);
+	const [plans, setPlans] = React.useState<SubscriptionPlan[]>([]);
+	const [members, setMembers] = React.useState<MemberSubscription[]>([]);
+	const [cursor, setCursor] = React.useState<string>();
+	const [form, setForm] = React.useState<SaveSubscriptionPlan>({ ...emptyPlan });
+	const [features, setFeatures] = React.useState<Feature[]>([]);
+	const [webhookSecret, setWebhookSecret] = React.useState("");
+	const [detail, setDetail] = React.useState<{
+		subscription: MemberSubscription;
+		member: MemberBilling;
+	} | null>(null);
+	const [busy, setBusy] = React.useState(false);
+	const [error, setError] = React.useState<string | null>(null);
+	const [notice, setNotice] = React.useState<string | null>(null);
+	const refresh = React.useCallback(async () => {
+		const config = await postPaymentRoute<Configuration>("subscriptions/configuration/get");
+		setConfiguration(config);
+		if (config.ready) {
+			const [catalog, subscriptions] = await Promise.all([
+				postPaymentRoute<{ items: SubscriptionPlan[] }>("subscriptions/plans/list"),
+				postPaymentRoute<{ items: MemberSubscription[]; nextCursor?: string }>(
+					"subscriptions/list",
+				),
+			]);
+			setPlans(catalog.items);
+			setMembers(subscriptions.items);
+			setCursor(subscriptions.nextCursor);
+		}
+	}, []);
+	React.useEffect(() => {
+		void refresh().catch((cause) => setError(message(cause)));
+	}, [refresh]);
+	async function run(action: () => Promise<void>) {
+		setBusy(true);
+		setError(null);
+		setNotice(null);
+		try {
+			await action();
+		} catch (cause) {
+			setError(message(cause));
+		} finally {
+			setBusy(false);
+		}
+	}
+	function edit(plan?: SubscriptionPlan) {
+		setForm(
+			plan
+				? {
+						code: plan.code,
+						name: plan.name,
+						enabled: plan.enabled,
+						expectedVersion: plan.version,
+						entitlements: plan.entitlements,
+						monthlyPriceId:
+							plan.prices.find((price) => price.enabled && price.interval === "month")?.id ?? null,
+						yearlyPriceId:
+							plan.prices.find((price) => price.enabled && price.interval === "year")?.id ?? null,
+					}
+				: { ...emptyPlan },
+		);
+		setFeatures(
+			Object.entries(plan?.entitlements ?? {}).map(([key, value]) => ({
+				key,
+				kind: typeof value === "boolean" ? "boolean" : "number",
+				value: String(value),
+			})),
+		);
+	}
+	const savePlan = async () => {
+		const entitlements: Record<string, boolean | number> = {};
+		for (const feature of features) {
+			if (Object.hasOwn(entitlements, feature.key))
+				throw new Error("Entitlement keys must be unique.");
+			if (
+				feature.kind === "number" &&
+				(!feature.value.trim() ||
+					!Number.isFinite(Number(feature.value)) ||
+					Number(feature.value) < 0)
+			) {
+				throw new Error("Enter a non-negative number for each limit.");
+			}
+			entitlements[feature.key] =
+				feature.kind === "boolean" ? feature.value === "true" : Number(feature.value);
+		}
+		const result = await postPaymentRoute<{ plan: SubscriptionPlan }>("subscriptions/plans/save", {
+			...form,
+			entitlements,
+		});
+		await refresh();
+		edit(result.plan);
+		setNotice("Plan saved. Existing subscriptions retain their price bindings.");
+	};
+	const updateFeature = (index: number, values: Partial<Feature>) =>
+		setFeatures((current) =>
+			current.map((feature, position) =>
+				position === index ? { ...feature, ...values } : feature,
+			),
+		);
+	const openDetail = async (subscriptionId: string, sync = false) => {
+		setDetail(
+			await postPaymentRoute(sync ? "subscriptions/sync" : "subscriptions/get", { subscriptionId }),
+		);
+		if (sync) {
+			await refresh();
+			setNotice("Subscription synchronized with Stripe.");
+		}
+	};
+	return (
+		<div className="space-y-8">
+			<header>
+				<h1 className="text-2xl font-semibold">Subscriptions</h1>
+				<p className="mt-2 text-sm text-kumo-subtle">
+					Bind Stripe prices, configure plan entitlements, and inspect paid membership periods.
+				</p>
+				<a href="/_dineway/admin/payments" className="mt-2 inline-block text-sm underline">
+					Stripe account settings
+				</a>
+			</header>
+			{error && (
+				<p role="alert" className="rounded-lg bg-kumo-danger/10 p-3 text-sm text-kumo-danger">
+					{error}
+				</p>
+			)}
+			{notice && (
+				<p role="status" className="rounded-lg bg-kumo-success/10 p-3 text-sm">
+					{notice}
+				</p>
+			)}
+			{!configuration ? (
+				error ? (
+					<button className={buttonClass} disabled={busy} onClick={() => void run(refresh)}>
+						Retry configuration
+					</button>
+				) : (
+					<p>Loading subscription configuration…</p>
+				)
+			) : (
+				<>
+					<section className="space-y-4 rounded-xl border border-kumo-line p-5">
+						<h2 className="text-lg font-semibold">Subscription webhook</h2>
+						<p className="text-sm">
+							Application: {configuration.namespace} · {configuration.mode} ·{" "}
+							{configuration.ready ? "Ready" : "Configuration required"}
+						</p>
+						<label className="block text-sm">
+							Endpoint
+							<input className={inputClass} readOnly value={configuration.webhookUrl} />
+						</label>
+						<p className="text-sm text-kumo-subtle">
+							Create a Stripe webhook for this endpoint using the subscription events in the Payment
+							documentation. Its signing secret is separate from other payment webhooks.
+						</p>
+						<form
+							className="flex flex-wrap items-end gap-3"
+							onSubmit={(event) => {
+								event.preventDefault();
+								void run(async () => {
+									setConfiguration(
+										await postPaymentRoute<Configuration>("subscriptions/configuration/update", {
+											webhookSecret,
+										}),
+									);
+									setWebhookSecret("");
+									await refresh();
+									setNotice("Subscription webhook secret saved.");
+								});
+							}}
+						>
+							<label className="min-w-64 flex-1 text-sm">
+								Signing secret
+								<input
+									type="password"
+									autoComplete="new-password"
+									required
+									className={inputClass}
+									value={webhookSecret}
+									placeholder={
+										configuration.webhookSecret
+											? "Leave unchanged unless rotating the secret"
+											: "whsec_…"
+									}
+									onChange={(event) => setWebhookSecret(event.target.value)}
+								/>
+							</label>
+							<button className={buttonClass} disabled={busy || !webhookSecret}>
+								Save secret
+							</button>
+						</form>
+						{!configuration.ready && (
+							<p className="text-sm text-kumo-subtle">
+								Verify the Stripe account and save this webhook secret to manage subscription plans.
+							</p>
+						)}
+					</section>
+					{configuration.ready && (
+						<>
+							<section className="space-y-4">
+								<div className="flex items-center justify-between">
+									<h2 className="text-lg font-semibold">Plans</h2>
+									<button className={buttonClass} onClick={() => edit()} disabled={busy}>
+										New plan
+									</button>
+								</div>
+								{plans.length === 0 && (
+									<p className="text-sm text-kumo-subtle">
+										No plans yet. Bind an existing Stripe price below.
+									</p>
+								)}
+								<div className="grid gap-3 md:grid-cols-2">
+									{plans.map((plan) => (
+										<button
+											key={plan.code}
+											className="rounded-lg border border-kumo-line p-4 text-left"
+											onClick={() => edit(plan)}
+											disabled={busy}
+										>
+											<strong>{plan.name}</strong>
+											<span className="ml-2 text-xs">{plan.enabled ? "Enabled" : "Archived"}</span>
+											<p className="text-sm text-kumo-subtle">{plan.code}</p>
+											{plan.prices
+												.filter((price) => price.enabled)
+												.map((price) => (
+													<p key={price.id} className="text-sm">
+														{formatSubscriptionPrice(price.amount, price.currency)} /{" "}
+														{price.interval}
+													</p>
+												))}
+										</button>
+									))}
+								</div>
+								<form
+									className="space-y-4 rounded-xl border border-kumo-line p-5"
+									onSubmit={(event) => {
+										event.preventDefault();
+										void run(savePlan);
+									}}
+								>
+									<h3 className="font-semibold">
+										{form.expectedVersion ? "Edit plan" : "Create plan"}
+									</h3>
+									<fieldset disabled={busy} className="grid gap-4 md:grid-cols-2">
+										<label className="text-sm">
+											Plan code
+											<input
+												required
+												readOnly={form.expectedVersion > 0}
+												className={inputClass}
+												value={form.code}
+												onChange={(event) => setForm({ ...form, code: event.target.value })}
+												placeholder="pro"
+											/>
+										</label>
+										<label className="text-sm">
+											Name
+											<input
+												required
+												className={inputClass}
+												value={form.name}
+												onChange={(event) => setForm({ ...form, name: event.target.value })}
+											/>
+										</label>
+										<label className="text-sm">
+											Monthly Stripe price
+											<input
+												className={inputClass}
+												value={form.monthlyPriceId ?? ""}
+												placeholder="price_…"
+												onChange={(event) =>
+													setForm({ ...form, monthlyPriceId: event.target.value || null })
+												}
+											/>
+										</label>
+										<label className="text-sm">
+											Yearly Stripe price
+											<input
+												className={inputClass}
+												value={form.yearlyPriceId ?? ""}
+												placeholder="price_…"
+												onChange={(event) =>
+													setForm({ ...form, yearlyPriceId: event.target.value || null })
+												}
+											/>
+										</label>
+										<label className="flex items-center gap-2 text-sm">
+											<input
+												type="checkbox"
+												checked={form.enabled}
+												onChange={(event) => setForm({ ...form, enabled: event.target.checked })}
+											/>{" "}
+											Available for new subscriptions
+										</label>
+									</fieldset>
+									<div className="space-y-3">
+										<h4 className="text-sm font-semibold">Entitlements</h4>
+										{features.map((feature, index) => (
+											<div key={index} className="flex flex-wrap gap-2">
+												<input
+													aria-label="Entitlement key"
+													className={inputClass + " min-w-40 flex-1"}
+													value={feature.key}
+													disabled={busy}
+													placeholder="reports.full"
+													onChange={(event) => updateFeature(index, { key: event.target.value })}
+												/>
+												<select
+													aria-label="Entitlement type"
+													className={buttonClass}
+													value={feature.kind}
+													disabled={busy}
+													onChange={(event) =>
+														updateFeature(index, {
+															kind: event.target.value === "boolean" ? "boolean" : "number",
+															value: event.target.value === "boolean" ? "true" : "0",
+														})
+													}
+												>
+													<option value="boolean">Feature</option>
+													<option value="number">Limit</option>
+												</select>
+												{feature.kind === "boolean" ? (
+													<select
+														aria-label="Feature access"
+														className={buttonClass}
+														value={feature.value}
+														disabled={busy}
+														onChange={(event) =>
+															updateFeature(index, { value: event.target.value })
+														}
+													>
+														<option value="true">Enabled</option>
+														<option value="false">Disabled</option>
+													</select>
+												) : (
+													<input
+														aria-label="Entitlement limit"
+														type="number"
+														min="0"
+														step="any"
+														className={buttonClass + " w-28"}
+														value={feature.value}
+														disabled={busy}
+														onChange={(event) =>
+															updateFeature(index, { value: event.target.value })
+														}
+													/>
+												)}
+												<button
+													type="button"
+													className={buttonClass}
+													disabled={busy}
+													onClick={() =>
+														setFeatures(features.filter((_, position) => position !== index))
+													}
+												>
+													Remove
+												</button>
+											</div>
+										))}
+										<button
+											type="button"
+											className={buttonClass}
+											disabled={busy}
+											onClick={() =>
+												setFeatures([...features, { key: "", kind: "boolean", value: "true" }])
+											}
+										>
+											Add entitlement
+										</button>
+									</div>
+									<button className={buttonClass} disabled={busy}>
+										{busy ? "Saving…" : "Verify prices and save plan"}
+									</button>
+								</form>
+							</section>
+							<section className="space-y-4">
+								<h2 className="text-lg font-semibold">Member subscriptions</h2>
+								<p className="text-sm text-kumo-subtle">
+									Failed renewals keep access until the end of the paid period. Cancellation takes
+									effect at period end.
+								</p>
+								<div className="overflow-x-auto">
+									<table className="w-full text-left text-sm">
+										<thead>
+											<tr>
+												<th className="p-2">Member</th>
+												<th className="p-2">Plan</th>
+												<th className="p-2">Payment status</th>
+												<th className="p-2">Last synchronized</th>
+												<th />
+											</tr>
+										</thead>
+										<tbody>
+											{members.map((member) => (
+												<tr key={member.id} className="border-t border-kumo-line">
+													<td className="p-2">{member.userId}</td>
+													<td className="p-2">{member.planCode}</td>
+													<td className="p-2">{member.status}</td>
+													<td className="p-2">
+														{new Date(member.verifiedAt).toLocaleString()}
+														{member.lastError && " · Retry required"}
+													</td>
+													<td className="p-2">
+														<button
+															className={buttonClass}
+															disabled={busy}
+															onClick={() => void run(() => openDetail(member.id))}
+														>
+															View
+														</button>
+													</td>
+												</tr>
+											))}
+										</tbody>
+									</table>
+								</div>
+								{members.length === 0 && (
+									<p className="text-sm text-kumo-subtle">No subscriptions have been recorded.</p>
+								)}
+								{cursor && (
+									<button
+										className={buttonClass}
+										disabled={busy}
+										onClick={() =>
+											void run(async () => {
+												const page = await postPaymentRoute<{
+													items: MemberSubscription[];
+													nextCursor?: string;
+												}>("subscriptions/list", { cursor });
+												setMembers([...members, ...page.items]);
+												setCursor(page.nextCursor);
+											})
+										}
+									>
+										Load more
+									</button>
+								)}
+								{detail && (
+									<div className="space-y-3 rounded-xl border border-kumo-line p-5">
+										<h3 className="font-semibold">{detail.subscription.id}</h3>
+										<dl className="grid gap-2 text-sm">
+											<dt>Member</dt>
+											<dd>{detail.subscription.userId}</dd>
+											<dt>Paid access until</dt>
+											<dd>
+												{detail.member.paidThrough
+													? new Date(detail.member.paidThrough * 1000).toLocaleString()
+													: "No current paid period"}
+											</dd>
+											<dt>Cancellation</dt>
+											<dd>
+												{detail.subscription.cancelAtPeriodEnd
+													? "At period end: " +
+														new Date(detail.subscription.periodEnd * 1000).toLocaleString()
+													: "Not scheduled"}
+											</dd>
+											<dt>Last synchronization</dt>
+											<dd>
+												{new Date(detail.subscription.verifiedAt).toLocaleString()}{" "}
+												{detail.subscription.lastError}
+											</dd>
+											<dt>Effective entitlements</dt>
+											<dd>
+												<pre className="overflow-auto">
+													{JSON.stringify(detail.member.entitlements, null, 2)}
+												</pre>
+											</dd>
+										</dl>
+										<button
+											className={buttonClass}
+											disabled={busy}
+											onClick={() => void run(() => openDetail(detail.subscription.id, true))}
+										>
+											Synchronize with Stripe
+										</button>
+									</div>
+								)}
+							</section>
+						</>
+					)}
+				</>
+			)}
+		</div>
+	);
+}
+function message(value: unknown): string {
+	return value instanceof Error ? value.message : "Subscription request failed";
+}

package/src/admin.tsx

@@ -6,6 +6,7 @@ import {
 	paymentSettingsForm,
 	type PaymentSettingsForm,
 } from "./admin/form.js";
+import { PaymentSubscriptionsPage } from "./admin/subscriptions.js";
 import type { PaymentStripeConfiguration } from "./configuration/service.js";
 
 type CredentialName = "secretKey" | "webhookSecret";
@@ -304,4 +305,7 @@ function message(value: unknown): string {
 	return value instanceof Error ? value.message : "Payment request failed";
 }
 
-export const pages = { "/payments": PaymentSettingsPage };
+export const pages = {
+	"/payments": PaymentSettingsPage,
+	"/payments/subscriptions": PaymentSubscriptionsPage,
+};

package/src/configuration/secrets.ts

@@ -10,10 +10,12 @@ import { PAYMENT_PLUGIN_ID } from "../constants.js";
 
 export const PAYMENT_STRIPE_SECRET_KEY = "stripe_secret_key";
 export const PAYMENT_STRIPE_WEBHOOK_SECRET = "stripe_webhook_secret";
+export const PAYMENT_STRIPE_SUBSCRIPTION_WEBHOOK_SECRET = "stripe_subscription_webhook_secret";
 
 export type PaymentStripeSecretName =
 	| typeof PAYMENT_STRIPE_SECRET_KEY
-	| typeof PAYMENT_STRIPE_WEBHOOK_SECRET;
+	| typeof PAYMENT_STRIPE_WEBHOOK_SECRET
+	| typeof PAYMENT_STRIPE_SUBSCRIPTION_WEBHOOK_SECRET;
 
 export class PaymentStripeSecretStore {
 	private readonly store: PluginSecretStore;

package/src/index.ts

@@ -5,6 +5,8 @@ import { version as packageVersion } from "../package.json";
 import { PaymentStripeConfigurationRepository } from "./configuration/repository.js";
 import { PAYMENT_PLUGIN_ID } from "./constants.js";
 import { createPaymentRoutes } from "./routes/index.js";
+import { createSubscriptionRoutes } from "./subscriptions/routes.js";
+import type { SubscriptionOptions } from "./subscriptions/types.js";
 
 const PAYMENT_ADMIN_ENTRY = "@dineway-ai/plugin-payment/admin";
 const PAYMENT_ADMIN_PAGES = [
@@ -13,6 +15,7 @@ const PAYMENT_ADMIN_PAGES = [
 
 export interface PaymentPluginOptions {
 	appName?: string;
+	subscriptions?: SubscriptionOptions;
 }
 
 export function paymentPlugin(
@@ -24,14 +27,19 @@ export function paymentPlugin(
 		format: "native",
 		entrypoint: "@dineway-ai/plugin-payment",
 		adminEntry: PAYMENT_ADMIN_ENTRY,
-		adminPages: [...PAYMENT_ADMIN_PAGES],
+		adminPages: [
+			...PAYMENT_ADMIN_PAGES,
+			...(options.subscriptions
+				? [{ path: "/payments/subscriptions", label: "Subscriptions", icon: "credit-card" }]
+				: []),
+		],
 		options,
 		capabilities: ["network:request:unrestricted"],
 		allowedHosts: ["api.stripe.com"],
 	};
 }
 
-export function createPlugin(_options: PaymentPluginOptions = {}): ResolvedPlugin {
+export function createPlugin(options: PaymentPluginOptions = {}): ResolvedPlugin {
 	const ensurePaymentFoundation = async () => {
 		await new PaymentStripeConfigurationRepository(await getDb()).ensureDefaults();
 	};
@@ -44,9 +52,20 @@ export function createPlugin(_options: PaymentPluginOptions = {}): ResolvedPlugi
 		version: packageVersion,
 		capabilities: ["network:request:unrestricted"],
 		allowedHosts: ["api.stripe.com"],
-		admin: { entry: PAYMENT_ADMIN_ENTRY, pages: [...PAYMENT_ADMIN_PAGES] },
+		admin: {
+			entry: PAYMENT_ADMIN_ENTRY,
+			pages: [
+				...PAYMENT_ADMIN_PAGES,
+				...(options.subscriptions
+					? [{ path: "/payments/subscriptions", label: "Subscriptions", icon: "credit-card" }]
+					: []),
+			],
+		},
 		hooks,
-		routes: createPaymentRoutes(),
+		routes: {
+			...createPaymentRoutes(),
+			...(options.subscriptions ? createSubscriptionRoutes(options.subscriptions) : {}),
+		},
 	});
 }
 

package/src/stripe/webhook-verifier.ts

@@ -85,6 +85,14 @@ function projectEvent(event: Stripe.Event, rawBody: Uint8Array): StripeWebhookEv
 	const objectRecord = asRecord(event.data.object as unknown);
 	const objectType = optionalSafeString(objectRecord?.object, 128);
 	const objectId = optionalSafeString(objectRecord?.id, 255);
+	const subscriptionRelation =
+		objectType === "subscription"
+			? objectId
+			: objectType === "checkout.session"
+				? objectRecord?.subscription
+				: objectType === "invoice"
+					? asRecord(asRecord(objectRecord?.parent)?.subscription_details)?.subscription
+					: null;
 	if ((objectType === null) !== (objectId === null)) throw new Error("Incomplete Stripe object");
 
 	return {
@@ -96,6 +104,9 @@ function projectEvent(event: Stripe.Event, rawBody: Uint8Array): StripeWebhookEv
 		payloadSha256: `sha256:${createHash("sha256").update(rawBody).digest("hex")}`,
 		objectType,
 		objectId,
+		...(subscriptionRelation
+			? { subscriptionId: requiredRelationId(subscriptionRelation, "sub_") }
+			: {}),
 		paymentIntent: objectType === "payment_intent" ? projectPaymentIntent(objectRecord) : null,
 		refund: objectType === "refund" ? projectRefund(objectRecord) : null,
 	};

package/src/subscriptions/format.ts

@@ -0,0 +1,12 @@
+/**
+ * Stripe charges ISK and UGX in hundredths despite their ISO zero-decimal
+ * presentation. Other supported currencies follow their ISO minor unit.
+ * https://docs.stripe.com/currencies#special-cases
+ */
+export function formatSubscriptionPrice(amount: number, currency: string, locale = "en"): string {
+	const formatter = new Intl.NumberFormat(locale, { style: "currency", currency });
+	const digits = ["isk", "ugx"].includes(currency.toLowerCase())
+		? 2
+		: (formatter.resolvedOptions().maximumFractionDigits ?? 2);
+	return formatter.format(amount / 10 ** digits);
+}

package/src/subscriptions/index.ts

@@ -0,0 +1,6 @@
+export { PaymentSubscriptionService } from "./service.js";
+export type { SubscriptionServiceOptions } from "./service.js";
+export { getPaymentSubscriptionService, getSubscriptionConfiguration } from "./runtime.js";
+export { createSubscriptionRoutes } from "./routes.js";
+export * from "./types.js";
+export { formatSubscriptionPrice } from "./format.js";