@pylonsync/stripe 0.3.83

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@pylonsync/stripe",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.83",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@pylonsync/sdk": "0.3.81",
+    "@pylonsync/functions": "0.3.81"
+  },
+  "peerDependencies": {
+    "bun-types": "*"
+  },
+  "peerDependenciesMeta": {
+    "bun-types": {
+    "optional": true
+  }
+}
+}

package/src/client.ts

@@ -0,0 +1,100 @@
+/**
+ * Stripe REST client over `fetch`. Stripe's API is form-urlencoded
+ * with bracket-style nesting (`foo[bar]=1`); JSON is rejected. We
+ * skip the official `stripe` SDK because it ships a 90 MB dep tree
+ * for what amounts to one fetch + one body encoder.
+ */
+
+const STRIPE_API_BASE = "https://api.stripe.com/v1";
+const DEFAULT_API_VERSION = "2024-12-18.acacia";
+
+export class StripeError extends Error {
+	constructor(
+		public status: number,
+		public code: string,
+		public stripeType: string,
+		message: string,
+	) {
+		super(message);
+		this.name = "StripeError";
+	}
+}
+
+export interface StripeClientConfig {
+	secretKey: string;
+	apiVersion?: string;
+	baseUrl?: string;
+	/** Optional idempotency key for non-GET requests. */
+	idempotencyKey?: string;
+}
+
+/**
+ * Encode a nested object as Stripe's form-urlencoded bracket convention:
+ *   { foo: { bar: 1 } } → foo[bar]=1
+ *   { items: [{ price: "x" }] } → items[0][price]=x
+ *
+ * Stripe SDKs all do this internally; we surface it because the
+ * webhook + checkout helpers in this package use it directly.
+ */
+export function encodeFormBody(input: Record<string, unknown>): string {
+	const params = new URLSearchParams();
+	const walk = (prefix: string, value: unknown): void => {
+		if (value === undefined || value === null) return;
+		if (Array.isArray(value)) {
+			value.forEach((v, i) => walk(`${prefix}[${i}]`, v));
+			return;
+		}
+		if (typeof value === "object") {
+			for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+				walk(`${prefix}[${k}]`, v);
+			}
+			return;
+		}
+		params.append(prefix, String(value));
+	};
+	for (const [k, v] of Object.entries(input)) walk(k, v);
+	return params.toString();
+}
+
+export async function stripeRequest<T>(
+	cfg: StripeClientConfig,
+	method: "GET" | "POST" | "DELETE",
+	path: string,
+	body?: Record<string, unknown>,
+): Promise<T> {
+	const baseUrl = cfg.baseUrl ?? STRIPE_API_BASE;
+	const url = `${baseUrl}${path}`;
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${cfg.secretKey}`,
+		"Stripe-Version": cfg.apiVersion ?? DEFAULT_API_VERSION,
+	};
+	if (cfg.idempotencyKey) {
+		headers["Idempotency-Key"] = cfg.idempotencyKey;
+	}
+	let init: RequestInit = { method, headers };
+	if (method !== "GET" && body) {
+		headers["Content-Type"] = "application/x-www-form-urlencoded";
+		init = { ...init, body: encodeFormBody(body) };
+	}
+	const res = await fetch(url, init);
+	const text = await res.text();
+	const parsed: unknown = text ? safeJson(text) : null;
+	if (!res.ok) {
+		const errObj = (
+			parsed as { error?: { code?: string; type?: string; message?: string } }
+		)?.error;
+		const code = errObj?.code ?? `HTTP_${res.status}`;
+		const type = errObj?.type ?? "api_error";
+		const msg = errObj?.message ?? (text || res.statusText);
+		throw new StripeError(res.status, code, type, msg);
+	}
+	return parsed as T;
+}
+
+function safeJson(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}

package/src/handlers/cancel.ts

@@ -0,0 +1,79 @@
+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 cancels the active subscription
+ * for a reference. Two modes:
+ *
+ *   - `scheduleAtPeriodEnd: true` (default) — sets
+ *     `cancel_at_period_end` so the customer keeps access through
+ *     the paid window. The webhook handler updates the local row
+ *     to `cancelAtPeriodEnd = true`. `restoreSubscription` can undo
+ *     this any time before the period ends.
+ *
+ *   - `scheduleAtPeriodEnd: false` — immediate `DELETE`. Refunds
+ *     are NOT issued automatically; that's a Stripe dashboard
+ *     toggle. The webhook flips the row's status to `canceled`.
+ */
+export function cancelSubscriptionHandler(cfg: StripeConfig) {
+	return action({
+		args: {
+			referenceId: v.optional(v.string()),
+			scheduleAtPeriodEnd: v.optional(v.boolean()),
+		},
+		async handler(
+			ctx: HandlerCtx,
+			args: { referenceId?: string; scheduleAtPeriodEnd?: boolean },
+		) {
+			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, "cancel");
+
+			const sub = await ctx.runQuery<{
+				stripeSubscriptionId: string;
+			} | null>("_pylonStripeFindActiveSubForReference", { referenceId });
+			if (!sub) {
+				throw ctx.error("NOT_FOUND", "no active subscription for reference");
+			}
+
+			const scheduleAtPeriodEnd = args.scheduleAtPeriodEnd ?? true;
+			const secretKey = resolveSecretKey(ctx, cfg);
+			if (scheduleAtPeriodEnd) {
+				await stripeRequest(
+					{ secretKey, apiVersion: cfg.apiVersion },
+					"POST",
+					`/subscriptions/${sub.stripeSubscriptionId}`,
+					{ cancel_at_period_end: true },
+				);
+			} else {
+				await stripeRequest(
+					{ secretKey, apiVersion: cfg.apiVersion },
+					"DELETE",
+					`/subscriptions/${sub.stripeSubscriptionId}`,
+				);
+			}
+			// Local row update lands via the webhook; don't double-write
+			// here because Stripe's response carries the canonical
+			// status + period_end (and webhooks retry, so we want one
+			// path that's idempotent).
+			return { scheduled: scheduleAtPeriodEnd };
+		},
+	});
+}
+
+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/checkout.ts

@@ -0,0 +1,154 @@
+import { action, v } from "@pylonsync/functions";
+
+import { stripeRequest } from "../client";
+import { findPlanByName } from "../plans";
+import { assertSafeRedirectUrl } from "../safe-url";
+import type { HandlerCtx, StripeConfig } from "../types";
+import {
+	authorizeReference,
+	resolveCustomerForReference,
+	subscriptionEntity,
+} from "./internal";
+
+/**
+ * Factory: returns an action handler for creating a Checkout Session.
+ *
+ * Flow:
+ *   1. authorize the referenceId for `upgrade`
+ *   2. resolve the Stripe customer (create on first call, persist on
+ *      the customer-holder entity)
+ *   3. validate the success/cancel URLs against PYLON_PUBLIC_URL +
+ *      app-provided extras (closes the "yapless.com vs getyapless.com"
+ *      bug class)
+ *   4. apply free-trial config from the plan catalog
+ *   5. POST /v1/checkout/sessions with merged hook params
+ *   6. return the URL — caller redirects the user
+ */
+export function createCheckoutSessionHandler(cfg: StripeConfig) {
+	return action({
+		args: {
+			plan: v.string(),
+			referenceId: v.optional(v.string()),
+			successUrl: v.string(),
+			cancelUrl: v.string(),
+			annual: v.optional(v.boolean()),
+			seats: v.optional(v.number()),
+		},
+		async handler(
+			ctx: HandlerCtx,
+			args: {
+				plan: string;
+				referenceId?: string;
+				successUrl: string;
+				cancelUrl: string;
+				annual?: boolean;
+				seats?: number;
+			},
+		) {
+			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, "upgrade");
+
+			const plan = findPlanByName(cfg.plans, args.plan);
+			if (!plan) {
+				throw ctx.error("UNKNOWN_PLAN", `plan ${args.plan} not in catalog`);
+			}
+			const priceId = args.annual ? plan.annualPriceId : plan.priceId;
+			if (!priceId) {
+				throw ctx.error(
+					"NO_PRICE",
+					`plan ${args.plan} has no ${args.annual ? "annual" : "monthly"} priceId`,
+				);
+			}
+
+			assertSafeRedirectUrl(args.successUrl, ctx.env.PYLON_PUBLIC_URL, {
+				extraOrigins: ctx.env.PYLON_CORS_ORIGIN,
+			});
+			assertSafeRedirectUrl(args.cancelUrl, ctx.env.PYLON_PUBLIC_URL, {
+				extraOrigins: ctx.env.PYLON_CORS_ORIGIN,
+			});
+
+			const customer = await resolveCustomerForReference(ctx, cfg, referenceId);
+
+			const secretKey = resolveSecretKey(ctx, cfg);
+
+			// Block double-trials: if the customer already has any
+			// Subscription row, we set `trial_period_days` to 0
+			// regardless of plan config. Stripe also enforces this
+			// server-side via the customer's trial history, but
+			// short-circuiting here avoids the round-trip rejection
+			// AND prevents giving customers a UX "you just got a 14-day
+			// trial" message that Stripe later silently strips.
+			const priorSubs = await ctx.runQuery<Array<{ id: string }>>(
+				"_pylonStripeListSubsForReference",
+				{ referenceId },
+			);
+			const trialDays =
+				priorSubs.length === 0 && plan.freeTrial?.days
+					? plan.freeTrial.days
+					: 0;
+
+			const baseParams: Record<string, unknown> = {
+				mode: "subscription",
+				customer: customer.customerId,
+				success_url: args.successUrl,
+				cancel_url: args.cancelUrl,
+				line_items: [
+					{
+						price: priceId,
+						quantity: args.seats ?? 1,
+					},
+				],
+				allow_promotion_codes: true,
+				client_reference_id: referenceId,
+				metadata: { referenceId, plan: plan.name },
+				subscription_data: {
+					metadata: { referenceId, plan: plan.name },
+					...(trialDays > 0 ? { trial_period_days: trialDays } : {}),
+				},
+			};
+
+			const extra = cfg.hooks?.getCheckoutSessionParams
+				? await cfg.hooks.getCheckoutSessionParams(ctx, {
+						referenceId,
+						plan,
+						customerId: customer.customerId,
+						successUrl: args.successUrl,
+						cancelUrl: args.cancelUrl,
+					})
+				: {};
+			const merged = { ...baseParams, ...extra };
+
+			const session = await stripeRequest<{ id: string; url: string }>(
+				{ secretKey, apiVersion: cfg.apiVersion },
+				"POST",
+				"/checkout/sessions",
+				merged,
+			);
+			return { url: session.url, id: session.id };
+		},
+	});
+}
+
+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;
+}
+
+function resolveSecretKey(ctx: HandlerCtx, cfg: StripeConfig): string {
+	if (cfg.getSecretKey) return cfg.getSecretKey(ctx);
+	const v = ctx.env.STRIPE_SECRET_KEY;
+	if (!v) {
+		throw ctx.error("MISSING_ENV", "STRIPE_SECRET_KEY not set");
+	}
+	return v;
+}

package/src/handlers/index.ts

@@ -0,0 +1,6 @@
+export { createCheckoutSessionHandler } from "./checkout";
+export { createBillingPortalSessionHandler } from "./portal";
+export { cancelSubscriptionHandler } from "./cancel";
+export { restoreSubscriptionHandler } from "./restore";
+export { stripeWebhookHandler } from "./webhook";
+export { internalHandlers } from "./queries";

package/src/handlers/internal.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared internals used by every handler in the package.
+ *
+ * Why this file exists: the plugin needs three primitives that
+ * cross-cut every action — authorize a reference, look up / create
+ * a Stripe customer for a reference, and resolve which mutation
+ * the app declared for persisting customer-id / subscription rows.
+ * Keeping them here means the per-handler files (checkout, portal,
+ * cancel, etc.) stay focused on the Stripe-side flow.
+ */
+
+import { stripeRequest } from "../client";
+import type { HandlerCtx, StripeConfig, SubscriptionAction } from "../types";
+
+export function subscriptionEntity(cfg: StripeConfig): string {
+	return cfg.entities?.subscription ?? "StripeSubscription";
+}
+
+export function customerHolderEntity(cfg: StripeConfig): string {
+	if (cfg.entities?.customerHolder) return cfg.entities.customerHolder;
+	if (cfg.referenceType === "org") return "Org";
+	if (cfg.referenceType === "user") return "User";
+	throw new Error(
+		`@pylonsync/stripe: customerHolder entity required for referenceType=custom`,
+	);
+}
+
+/**
+ * RBAC gate. Defaults:
+ *   - `org`: owners + admins allowed (looked up via OrgMember)
+ *   - `user`: only the caller themselves
+ *   - `custom`: caller must supply `cfg.authorizeReference`
+ * Always throws on deny — callers don't need to handle false return.
+ */
+export async function authorizeReference(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+	referenceId: string,
+	action: SubscriptionAction,
+): Promise<void> {
+	if (!ctx.auth.userId) {
+		throw ctx.error("UNAUTHENTICATED", "sign in to manage subscriptions");
+	}
+	if (cfg.authorizeReference) {
+		const ok = await cfg.authorizeReference(ctx, { referenceId, action });
+		if (!ok) throw ctx.error("FORBIDDEN", `not authorized to ${action}`);
+		return;
+	}
+	if (ctx.auth.isAdmin) return;
+	if (cfg.referenceType === "user") {
+		if (ctx.auth.userId !== referenceId) {
+			throw ctx.error("FORBIDDEN", "can only manage your own subscription");
+		}
+		return;
+	}
+	if (cfg.referenceType === "org") {
+		const members = await ctx.runQuery<Array<{ role: string }>>(
+			"_pylonStripeOrgMembership",
+			{ orgId: referenceId, userId: ctx.auth.userId },
+		);
+		const role = members[0]?.role;
+		if (role !== "owner" && role !== "admin") {
+			throw ctx.error(
+				"FORBIDDEN",
+				`only org owners or admins can ${action}`,
+			);
+		}
+		return;
+	}
+	throw ctx.error(
+		"NO_AUTHORIZER",
+		"referenceType=custom requires authorizeReference hook",
+	);
+}
+
+/**
+ * Find an existing Stripe customer for the reference, or create one
+ * and persist its id on the customer-holder entity. Idempotent.
+ */
+export async function resolveCustomerForReference(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+	referenceId: string,
+): Promise<{ customerId: string; email?: string }> {
+	if (cfg.referenceType === "custom") {
+		if (!cfg.resolveCustomer) {
+			throw ctx.error(
+				"NO_RESOLVER",
+				"referenceType=custom requires resolveCustomer hook",
+			);
+		}
+		return cfg.resolveCustomer(ctx, referenceId);
+	}
+
+	const holder = customerHolderEntity(cfg);
+	const row = await ctx.runQuery<{
+		id: string;
+		stripeCustomerId?: string | null;
+		email?: string;
+		name?: string;
+	} | null>("_pylonStripeGetCustomerHolder", { entity: holder, id: referenceId });
+	if (!row) {
+		throw ctx.error("NOT_FOUND", `${holder} ${referenceId} not found`);
+	}
+	if (row.stripeCustomerId) {
+		return { customerId: row.stripeCustomerId, email: row.email };
+	}
+
+	const secretKey = resolveSecretKey(ctx, cfg);
+	const created = await stripeRequest<{ id: string }>(
+		{ secretKey, apiVersion: cfg.apiVersion },
+		"POST",
+		"/customers",
+		{
+			email: row.email,
+			name: row.name,
+			metadata: { referenceId, referenceType: cfg.referenceType },
+		},
+	);
+	await ctx.runMutation("_pylonStripeSetCustomerId", {
+		entity: holder,
+		id: referenceId,
+		stripeCustomerId: created.id,
+	});
+	if (cfg.hooks?.onCustomerCreate) {
+		await cfg.hooks.onCustomerCreate(ctx, {
+			referenceId,
+			customerId: created.id,
+			email: row.email,
+		});
+	}
+	return { customerId: created.id, email: row.email };
+}
+
+export function resolveSecretKey(ctx: HandlerCtx, cfg: StripeConfig): string {
+	if (cfg.getSecretKey) return cfg.getSecretKey(ctx);
+	const v = ctx.env.STRIPE_SECRET_KEY;
+	if (!v) {
+		throw ctx.error("MISSING_ENV", "STRIPE_SECRET_KEY not set");
+	}
+	return v;
+}
+
+export function resolveWebhookSecret(
+	ctx: HandlerCtx,
+	cfg: StripeConfig,
+): string {
+	if (cfg.getWebhookSecret) return cfg.getWebhookSecret(ctx);
+	const v = ctx.env.STRIPE_WEBHOOK_SECRET;
+	if (!v) {
+		throw ctx.error("MISSING_ENV", "STRIPE_WEBHOOK_SECRET not set");
+	}
+	return v;
+}

package/src/handlers/portal.ts

@@ -0,0 +1,69 @@
+import { action, v } from "@pylonsync/functions";
+
+import { stripeRequest } from "../client";
+import { assertSafeRedirectUrl } from "../safe-url";
+import type { HandlerCtx, StripeConfig } from "../types";
+import {
+	authorizeReference,
+	resolveCustomerForReference,
+	resolveSecretKey,
+} from "./internal";
+
+/**
+ * Factory: returns an action handler that opens a Stripe Billing
+ * Portal session for the reference. Customer manages their card,
+ * downloads invoices, cancels the subscription — all without the
+ * app having to build a billing UI.
+ *
+ * Portal config (return URL allow-list, products, branding) is set
+ * once in the Stripe dashboard; this handler just mints sessions.
+ */
+export function createBillingPortalSessionHandler(cfg: StripeConfig) {
+	return action({
+		args: {
+			referenceId: v.optional(v.string()),
+			returnUrl: v.string(),
+		},
+		async handler(
+			ctx: HandlerCtx,
+			args: { referenceId?: string; returnUrl: 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, "billingPortal");
+
+			assertSafeRedirectUrl(args.returnUrl, ctx.env.PYLON_PUBLIC_URL, {
+				extraOrigins: ctx.env.PYLON_CORS_ORIGIN,
+			});
+
+			const { customerId } = await resolveCustomerForReference(
+				ctx,
+				cfg,
+				referenceId,
+			);
+
+			const secretKey = resolveSecretKey(ctx, cfg);
+			const session = await stripeRequest<{ id: string; url: string }>(
+				{ secretKey, apiVersion: cfg.apiVersion },
+				"POST",
+				"/billing_portal/sessions",
+				{ customer: customerId, return_url: args.returnUrl },
+			);
+			return { url: session.url, id: session.id };
+		},
+	});
+}
+
+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;
+}