@pylonsync/stripe 0.3.83

package/src/handlers/queries.ts

@@ -0,0 +1,194 @@
+import { mutation, query, v } from "@pylonsync/functions";
+
+import type { StripeConfig } from "../types";
+import { subscriptionEntity } from "./internal";
+
+/**
+ * Plugin-internal queries + mutations. Names are namespaced with a
+ * `_pylonStripe` prefix to avoid colliding with app functions. The
+ * underscore + `internal: true` makes them ineligible for direct
+ * HTTP invocation — they only fire via `ctx.runQuery` /
+ * `ctx.runMutation` from the action handler factories.
+ *
+ * Each one is parameterized over the entity names from `cfg.entities`
+ * so apps can rename `StripeSubscription` → `Subscription` or
+ * `Org` → `Workspace` without forking the plugin. Entity names that
+ * the framework needs as relation targets (`v.id("Org")`) can't be
+ * dynamic, so the lookup helpers take the entity name as an arg and
+ * use the generic `ctx.db.query(entity, filter)` API.
+ */
+
+export function internalHandlers(cfg: StripeConfig): Record<string, unknown> {
+	const subEnt = subscriptionEntity(cfg);
+
+	return {
+		_pylonStripeListSubsForReference: query({
+			args: { referenceId: v.string() },
+			internal: true,
+			async handler(ctx, args: { referenceId: string }) {
+				return ctx.db.query(subEnt, { referenceId: args.referenceId });
+			},
+		}),
+
+		// First active subscription for a reference id (used by cancel
+		// + restore). "Active" here means status ∈
+		// (active, trialing, past_due) — those are the states a
+		// customer can still mutate from. Canceled / unpaid require
+		// a new checkout.
+		_pylonStripeFindActiveSubForReference: query({
+			args: { referenceId: v.string() },
+			internal: true,
+			async handler(ctx, args: { referenceId: string }) {
+				const rows = (await ctx.db.query(subEnt, {
+					referenceId: args.referenceId,
+				})) as Array<{
+					id: string;
+					stripeSubscriptionId: string;
+					status: string;
+					cancelAtPeriodEnd?: boolean;
+				}>;
+				return (
+					rows.find((r) =>
+						["active", "trialing", "past_due"].includes(r.status),
+					) ?? null
+				);
+			},
+		}),
+
+		// Read the customer-holder row. Used by resolveCustomerForReference
+		// to look up the existing stripeCustomerId + carry email/name
+		// through to customer creation.
+		_pylonStripeGetCustomerHolder: query({
+			args: { entity: v.string(), id: v.string() },
+			internal: true,
+			async handler(ctx, args: { entity: string; id: string }) {
+				return ctx.db.get(args.entity, args.id);
+			},
+		}),
+
+		// Reverse lookup: customer-id → reference row. Used by the
+		// webhook handler to map Stripe events back to our reference.
+		_pylonStripeFindByCustomerId: query({
+			args: {
+				entity: v.string(),
+				stripeCustomerId: v.string(),
+			},
+			internal: true,
+			async handler(
+				ctx,
+				args: { entity: string; stripeCustomerId: string },
+			) {
+				const rows = (await ctx.db.query(args.entity, {
+					stripeCustomerId: args.stripeCustomerId,
+				})) as Array<{ id: string }>;
+				return rows[0] ?? null;
+			},
+		}),
+
+		// Org membership check for the default `authorizeReference`.
+		// Apps with non-default OrgMember entity names pass their own
+		// authorizer instead.
+		_pylonStripeOrgMembership: query({
+			args: { orgId: v.string(), userId: v.string() },
+			internal: true,
+			async handler(ctx, args: { orgId: string; userId: string }) {
+				return ctx.db.query("OrgMember", {
+					orgId: args.orgId,
+					userId: args.userId,
+				});
+			},
+		}),
+
+		// Persist a freshly-minted Stripe customer id on the holder row.
+		_pylonStripeSetCustomerId: mutation({
+			args: {
+				entity: v.string(),
+				id: v.string(),
+				stripeCustomerId: v.string(),
+			},
+			internal: true,
+			async handler(
+				ctx,
+				args: { entity: string; id: string; stripeCustomerId: string },
+			) {
+				await ctx.db.update(args.entity, args.id, {
+					stripeCustomerId: args.stripeCustomerId,
+				});
+			},
+		}),
+
+		// Upsert the subscription row from a webhook event. Looks up
+		// by stripeSubscriptionId (unique) and updates in place when
+		// it exists; otherwise inserts. Idempotent — Stripe retries
+		// webhooks and we want the same end state on repeat delivery.
+		_pylonStripeUpsertSubscription: mutation({
+			args: {
+				referenceId: v.string(),
+				stripeCustomerId: v.string(),
+				stripeSubscriptionId: v.string(),
+				plan: v.string(),
+				status: v.string(),
+				seats: v.optional(v.number()),
+				currentPeriodEnd: v.optional(v.string()),
+				cancelAtPeriodEnd: v.optional(v.boolean()),
+				canceledAt: v.optional(v.string()),
+				trialEnd: v.optional(v.string()),
+				limits: v.optional(v.string()),
+				createdAt: v.string(),
+				updatedAt: v.string(),
+			},
+			internal: true,
+			async handler(
+				ctx,
+				args: {
+					referenceId: string;
+					stripeCustomerId: string;
+					stripeSubscriptionId: string;
+					plan: string;
+					status: string;
+					seats?: number;
+					currentPeriodEnd?: string | null;
+					cancelAtPeriodEnd?: boolean;
+					canceledAt?: string | null;
+					trialEnd?: string | null;
+					limits?: string | null;
+					createdAt: string;
+					updatedAt: string;
+				},
+			) {
+				const existing = (await ctx.db.query(subEnt, {
+					stripeSubscriptionId: args.stripeSubscriptionId,
+				})) as Array<{ id: string }>;
+				if (existing[0]) {
+					await ctx.db.update(subEnt, existing[0].id, {
+						plan: args.plan,
+						status: args.status,
+						seats: args.seats ?? 1,
+						currentPeriodEnd: args.currentPeriodEnd ?? null,
+						cancelAtPeriodEnd: args.cancelAtPeriodEnd ?? false,
+						canceledAt: args.canceledAt ?? null,
+						trialEnd: args.trialEnd ?? null,
+						limits: args.limits ?? null,
+						updatedAt: args.updatedAt,
+					});
+				} else {
+					await ctx.db.insert(subEnt, {
+						referenceId: args.referenceId,
+						stripeCustomerId: args.stripeCustomerId,
+						stripeSubscriptionId: args.stripeSubscriptionId,
+						plan: args.plan,
+						status: args.status,
+						seats: args.seats ?? 1,
+						currentPeriodEnd: args.currentPeriodEnd ?? null,
+						cancelAtPeriodEnd: args.cancelAtPeriodEnd ?? false,
+						canceledAt: args.canceledAt ?? null,
+						trialEnd: args.trialEnd ?? null,
+						limits: args.limits ?? null,
+						createdAt: args.createdAt,
+						updatedAt: args.updatedAt,
+					});
+				}
+			},
+		}),
+	};
+}

package/src/handlers/restore.ts

@@ -0,0 +1,64 @@
+import { action, v } from "@pylonsync/functions";
+
+import { stripeRequest } from "../client";
+import type { HandlerCtx, StripeConfig } from "../types";
+import { authorizeReference, resolveSecretKey } from "./internal";
+
+/**
+ * Factory: returns an action that undoes a pending cancellation
+ * (i.e. a subscription with `cancel_at_period_end: true` that
+ * hasn't yet reached its period end). Only works while
+ * `subscription.status` is still `active` and the period hasn't
+ * expired — once Stripe has actually canceled the sub, restoring
+ * requires a new checkout.
+ */
+export function restoreSubscriptionHandler(cfg: StripeConfig) {
+	return action({
+		args: {
+			referenceId: v.optional(v.string()),
+		},
+		async handler(ctx: HandlerCtx, args: { referenceId?: string }) {
+			const referenceId = args.referenceId ?? defaultReferenceId(ctx, cfg);
+			if (!referenceId) {
+				throw ctx.error(
+					"NO_REFERENCE",
+					"referenceId required (no active tenant or user)",
+				);
+			}
+			await authorizeReference(ctx, cfg, referenceId, "restore");
+
+			const sub = await ctx.runQuery<{
+				stripeSubscriptionId: string;
+				cancelAtPeriodEnd?: boolean;
+				status: string;
+			} | null>("_pylonStripeFindActiveSubForReference", { referenceId });
+			if (!sub) {
+				throw ctx.error("NOT_FOUND", "no subscription for reference");
+			}
+			if (!sub.cancelAtPeriodEnd) {
+				throw ctx.error(
+					"NOT_CANCELING",
+					"subscription is not scheduled to cancel",
+				);
+			}
+
+			const secretKey = resolveSecretKey(ctx, cfg);
+			await stripeRequest(
+				{ secretKey, apiVersion: cfg.apiVersion },
+				"POST",
+				`/subscriptions/${sub.stripeSubscriptionId}`,
+				{ cancel_at_period_end: false },
+			);
+			return { restored: true };
+		},
+	});
+}
+
+function defaultReferenceId(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+): string | null {
+	if (cfg.referenceType === "user") return ctx.auth.userId ?? null;
+	if (cfg.referenceType === "org") return ctx.auth.tenantId ?? null;
+	return null;
+}

package/src/handlers/webhook.ts

@@ -0,0 +1,156 @@
+import { action } from "@pylonsync/functions";
+
+import { periodEndFromSubscription, planFromSubscription } from "../plans";
+import { verifyStripeSignature } from "../signature";
+import type {
+	HandlerCtx,
+	StripeConfig,
+	StripeEvent,
+	StripeInvoice,
+	StripeSubscription,
+} from "../types";
+import { resolveWebhookSecret } from "./internal";
+
+/**
+ * Factory: returns the unified webhook handler. Verifies signature,
+ * routes by event type, upserts the canonical Subscription row,
+ * fires lifecycle hooks.
+ *
+ * Event coverage (matches the better-auth Stripe plugin):
+ *
+ *   customer.subscription.created   → upsert row, status=active|trialing
+ *   customer.subscription.updated   → upsert row, reflect new plan/seats/period
+ *   customer.subscription.deleted   → row → status=canceled
+ *   customer.subscription.trial_will_end → onEvent hook only
+ *   invoice.created/finalized/paid/payment_failed/voided → onInvoice hook
+ *   anything else                   → cfg.hooks.onEvent
+ *
+ * Mounted at `POST /api/webhooks/stripeWebhook` by Pylon's webhook
+ * router. Configure your Stripe dashboard endpoint with that URL
+ * and the signing secret as `STRIPE_WEBHOOK_SECRET`.
+ */
+export function stripeWebhookHandler(cfg: StripeConfig) {
+	return action({
+		args: {},
+		async handler(ctx: HandlerCtx) {
+			if (!ctx.request) {
+				throw ctx.error(
+					"BAD_INVOCATION",
+					"stripeWebhook requires HTTP request context",
+				);
+			}
+			const secret = resolveWebhookSecret(ctx, cfg);
+			const sigHeader = ctx.request.headers["stripe-signature"];
+			const ok = await verifyStripeSignature(
+				secret,
+				ctx.request.rawBody,
+				sigHeader,
+			);
+			if (ok !== true) {
+				throw ctx.error("INVALID_SIGNATURE", `stripe sig: ${ok}`);
+			}
+
+			let event: StripeEvent;
+			try {
+				event = JSON.parse(ctx.request.rawBody) as StripeEvent;
+			} catch {
+				throw ctx.error("BAD_BODY", "invalid JSON");
+			}
+
+			switch (event.type) {
+				case "customer.subscription.created":
+				case "customer.subscription.updated":
+				case "customer.subscription.deleted": {
+					const sub = event.data.object as unknown as StripeSubscription;
+					await handleSubscriptionEvent(ctx, cfg, event, sub);
+					return { ok: true, type: event.type };
+				}
+				case "invoice.created":
+				case "invoice.finalized":
+				case "invoice.paid":
+				case "invoice.payment_failed":
+				case "invoice.voided": {
+					const inv = event.data.object as unknown as StripeInvoice;
+					await handleInvoiceEvent(ctx, cfg, event, inv);
+					return { ok: true, type: event.type };
+				}
+				default:
+					if (cfg.hooks?.onEvent) await cfg.hooks.onEvent(ctx, event);
+					return { ignored: event.type };
+			}
+		},
+	});
+}
+
+async function handleSubscriptionEvent(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+	event: StripeEvent,
+	sub: StripeSubscription,
+): Promise<void> {
+	const referenceId = await referenceFromCustomerId(ctx, cfg, sub.customer);
+	if (!referenceId) {
+		// No mapping — log + drop. The app likely deleted the
+		// reference; Stripe will retry the webhook for a while and
+		// eventually mark it as failed.
+		return;
+	}
+	const { plan } = planFromSubscription(cfg.plans, sub);
+	const planName = plan?.name ?? "pending";
+	const now = new Date().toISOString();
+	await ctx.runMutation("_pylonStripeUpsertSubscription", {
+		referenceId,
+		stripeCustomerId: sub.customer,
+		stripeSubscriptionId: sub.id,
+		plan: planName,
+		status: sub.status,
+		seats: sub.items.data[0]?.quantity ?? 1,
+		currentPeriodEnd: periodEndFromSubscription(sub),
+		cancelAtPeriodEnd: !!sub.cancel_at_period_end,
+		canceledAt: sub.canceled_at
+			? new Date(sub.canceled_at * 1000).toISOString()
+			: null,
+		trialEnd: sub.trial_end ? new Date(sub.trial_end * 1000).toISOString() : null,
+		limits: plan?.limits ? JSON.stringify(plan.limits) : null,
+		createdAt: now,
+		updatedAt: now,
+	});
+	if (event.type === "customer.subscription.created" && cfg.hooks?.onSubscriptionActivate) {
+		await cfg.hooks.onSubscriptionActivate(ctx, { referenceId, plan: planName, subscription: sub });
+	} else if (event.type === "customer.subscription.updated" && cfg.hooks?.onSubscriptionUpdate) {
+		await cfg.hooks.onSubscriptionUpdate(ctx, { referenceId, plan: planName, subscription: sub });
+	} else if (event.type === "customer.subscription.deleted" && cfg.hooks?.onSubscriptionCancel) {
+		await cfg.hooks.onSubscriptionCancel(ctx, { referenceId, subscription: sub });
+	}
+}
+
+async function handleInvoiceEvent(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+	event: StripeEvent,
+	inv: StripeInvoice,
+): Promise<void> {
+	const referenceId = await referenceFromCustomerId(ctx, cfg, inv.customer);
+	if (!referenceId) return;
+	if (cfg.hooks?.onInvoice) {
+		await cfg.hooks.onInvoice(ctx, {
+			referenceId,
+			eventType: event.type,
+			invoice: inv,
+		});
+	}
+}
+
+async function referenceFromCustomerId(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+	customerId: string,
+): Promise<string | null> {
+	const holder = cfg.entities?.customerHolder ??
+		(cfg.referenceType === "user" ? "User" : "Org");
+	const row = await ctx.runQuery<{ id: string } | null>(
+		"_pylonStripeFindByCustomerId",
+		{ entity: holder, stripeCustomerId: customerId },
+	);
+	return row?.id ?? null;
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+/**
+ * `@pylonsync/stripe` — declarative Stripe billing for Pylon apps.
+ *
+ * Replaces the per-app rewrite of customer creation, checkout
+ * session minting, billing portal, webhook signature verification,
+ * plan derivation, and subscription state management.
+ *
+ * Usage (in your app.ts):
+ *
+ * ```ts
+ * import { buildManifest } from "@pylonsync/sdk";
+ * import { stripe } from "@pylonsync/stripe";
+ *
+ * const billing = stripe({
+ *   referenceType: "org",
+ *   plans: [
+ *     { name: "starter", priceId: "price_...", limits: { recordings: 50 } },
+ *     { name: "pro",     priceId: "price_...", limits: { recordings: 500 } },
+ *     { name: "scale",   priceId: "price_...", limits: { recordings: -1 } },
+ *   ],
+ *   hooks: {
+ *     onSubscriptionActivate: async (ctx, { referenceId, plan }) => {
+ *       // analytics, welcome email, etc.
+ *     },
+ *   },
+ * });
+ *
+ * console.log(JSON.stringify(buildManifest({
+ *   name: "myapp",
+ *   entities: [Org, User, ...billing.manifest.entities],
+ *   actions:  [...billing.manifest.actions],
+ *   queries:  [...billing.manifest.queries],
+ *   policies: [...billing.manifest.policies],
+ * }), null, 2));
+ * ```
+ *
+ * Then create one-line wrapper files in `functions/`:
+ *
+ * ```ts
+ * // functions/createCheckoutSession.ts
+ * export { createCheckoutSession as default } from "../billing";
+ * ```
+ *
+ * Where `../billing.ts` is:
+ *
+ * ```ts
+ * // billing.ts
+ * import { stripe } from "@pylonsync/stripe";
+ * export const billingConfig = stripe({ ... });
+ * export const {
+ *   createCheckoutSession,
+ *   createBillingPortalSession,
+ *   cancelSubscription,
+ *   restoreSubscription,
+ *   stripeWebhook,
+ *   ...internals
+ * } = billingConfig.handlers;
+ * ```
+ *
+ * Pylon's file-based function loader requires one default export
+ * per function file, which is why the per-function wrappers exist.
+ * A future SDK version may expose a `plugins: [...]` field on
+ * `buildManifest()` that auto-registers handler factories without
+ * the wrapper files; until then, the wrapper layer keeps the
+ * boilerplate to 1 line per function.
+ */
+
+import { buildStripeManifest, type StripeManifestFragment } from "./manifest";
+import {
+	cancelSubscriptionHandler,
+	createBillingPortalSessionHandler,
+	createCheckoutSessionHandler,
+	internalHandlers,
+	restoreSubscriptionHandler,
+	stripeWebhookHandler,
+} from "./handlers";
+import type { StripeConfig } from "./types";
+
+export type {
+	StripeConfig,
+	StripePlan,
+	StripeHooks,
+	StripeEvent,
+	StripeSubscription,
+	StripeInvoice,
+	HandlerCtx,
+	ReferenceType,
+	SubscriptionAction,
+} from "./types";
+export type { StripeManifestFragment } from "./manifest";
+export { StripeError } from "./client";
+export { verifyStripeSignature } from "./signature";
+export { assertSafeRedirectUrl } from "./safe-url";
+
+export interface StripePlugin {
+	/** Manifest fragment to merge into `buildManifest()`. */
+	manifest: StripeManifestFragment;
+	/**
+	 * Handler exports. One per function file: re-export as the
+	 * default export of a file under `functions/<name>.ts`. The
+	 * internal `_pylonStripe*` handlers live under `internals` and
+	 * also need re-exporting (one wrapper per name).
+	 */
+	handlers: {
+		createCheckoutSession: ReturnType<typeof createCheckoutSessionHandler>;
+		createBillingPortalSession: ReturnType<
+			typeof createBillingPortalSessionHandler
+		>;
+		cancelSubscription: ReturnType<typeof cancelSubscriptionHandler>;
+		restoreSubscription: ReturnType<typeof restoreSubscriptionHandler>;
+		stripeWebhook: ReturnType<typeof stripeWebhookHandler>;
+	} & Record<string, unknown>;
+}
+
+export function stripe(cfg: StripeConfig): StripePlugin {
+	return {
+		manifest: buildStripeManifest(cfg),
+		handlers: {
+			createCheckoutSession: createCheckoutSessionHandler(cfg),
+			createBillingPortalSession: createBillingPortalSessionHandler(cfg),
+			cancelSubscription: cancelSubscriptionHandler(cfg),
+			restoreSubscription: restoreSubscriptionHandler(cfg),
+			stripeWebhook: stripeWebhookHandler(cfg),
+			...internalHandlers(cfg),
+		},
+	};
+}

package/src/manifest.ts

@@ -0,0 +1,123 @@
+/**
+ * Manifest fragments — entities + action declarations the plugin
+ * contributes to an app's manifest. App code spreads these into
+ * its `buildManifest({ entities, actions })` call.
+ */
+
+import {
+	type ActionDefinition,
+	type EntityDefinition,
+	type PolicyDefinition,
+	type QueryDefinition,
+	action,
+	entity,
+	field,
+	policy,
+	query,
+} from "@pylonsync/sdk";
+
+import type { StripeConfig } from "./types";
+
+export interface StripeManifestFragment {
+	entities: EntityDefinition[];
+	actions: ActionDefinition[];
+	queries: QueryDefinition[];
+	policies: PolicyDefinition[];
+}
+
+/**
+ * Build the manifest fragment for the Stripe plugin. App composes
+ * this into its top-level manifest:
+ *
+ *   ```ts
+ *   const billing = stripe({ referenceType: "org", plans: [...] });
+ *
+ *   buildManifest({
+ *     entities: [Org, User, ...billing.manifest.entities],
+ *     actions:  [...billing.manifest.actions],
+ *     queries:  [...billing.manifest.queries],
+ *     policies: [...billing.manifest.policies],
+ *   });
+ *   ```
+ */
+export function buildStripeManifest(
+	cfg: StripeConfig,
+): StripeManifestFragment {
+	const subscriptionEntity = cfg.entities?.subscription ?? "StripeSubscription";
+
+	// Single source of truth for billing state. One row per
+	// referenceId — when a customer upgrades/cancels the row updates
+	// in place. Indexed by stripeSubscriptionId for webhook lookups.
+	const Subscription = entity(subscriptionEntity, {
+		referenceId: field.string(),
+		stripeCustomerId: field.string(),
+		stripeSubscriptionId: field.string().unique(),
+		plan: field.string(),
+		status: field.string(),
+		seats: field.number().optional(),
+		currentPeriodEnd: field.string().optional(),
+		cancelAtPeriodEnd: field.boolean().optional(),
+		canceledAt: field.string().optional(),
+		trialEnd: field.string().optional(),
+		annual: field.boolean().optional(),
+		limits: field.string().optional(),
+		createdAt: field.string(),
+		updatedAt: field.string(),
+	});
+
+	// Policy: subscriptions are tenant-scoped via referenceId. App
+	// auth context decides whether that referenceId is a user or
+	// org — the policy treats it opaquely. When referenceType is
+	// "org", the active tenant maps 1:1; when "user", the auth
+	// userId maps 1:1.
+	const subscriptionPolicy = policy({
+		name: `${subscriptionEntity.toLowerCase()}_read`,
+		entity: subscriptionEntity,
+		allowRead:
+			cfg.referenceType === "org"
+				? "auth.tenantId == data.referenceId"
+				: "auth.userId == data.referenceId",
+		allowInsert: "false",
+		allowUpdate: "false",
+		allowDelete: "false",
+	});
+
+	return {
+		entities: [Subscription],
+		policies: [subscriptionPolicy],
+		queries: [
+			query("listSubscriptions"),
+			query("getSubscription", {
+				input: [{ name: "referenceId", type: "string" }],
+			}),
+		],
+		actions: [
+			action("createCheckoutSession", {
+				input: [
+					{ name: "plan", type: "string" },
+					{ name: "referenceId", type: "string", optional: true },
+					{ name: "successUrl", type: "string" },
+					{ name: "cancelUrl", type: "string" },
+					{ name: "annual", type: "bool", optional: true },
+					{ name: "seats", type: "int", optional: true },
+				],
+			}),
+			action("createBillingPortalSession", {
+				input: [
+					{ name: "referenceId", type: "string", optional: true },
+					{ name: "returnUrl", type: "string" },
+				],
+			}),
+			action("cancelSubscription", {
+				input: [
+					{ name: "referenceId", type: "string", optional: true },
+					{ name: "scheduleAtPeriodEnd", type: "bool", optional: true },
+				],
+			}),
+			action("restoreSubscription", {
+				input: [{ name: "referenceId", type: "string", optional: true }],
+			}),
+			action("stripeWebhook"),
+		],
+	};
+}