@btst/stack 5.0.0 → 5.2.0

package/src/plugins/ecommerce/__tests__/checkout-attempt.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	canDiscardCheckoutAttempt,
+	reusableCheckoutAttempt,
+} from "../client/checkout-attempt";
+
+const attempt = {
+	fingerprint: "same cart and shipping",
+	key: "existing payment key",
+	orderId: "existing order",
+};
+
+describe("checkout attempt reuse", () => {
+	it("blocks changed details while a verified previous payment is pending", async () => {
+		const verify = vi
+			.fn()
+			.mockResolvedValue({ status: "pending", paymentStatus: "pending" });
+		await expect(
+			reusableCheckoutAttempt(attempt, "changed shipping", verify),
+		).rejects.toThrow(/previous payment/i);
+		expect(verify).toHaveBeenCalledWith(attempt.orderId);
+		expect(attempt.fingerprint).toBe("same cart and shipping");
+	});
+	it("allows changed details after the previous order is verified terminal", async () => {
+		const verify = vi
+			.fn()
+			.mockResolvedValue({ status: "cancelled", paymentStatus: "pending" });
+		expect(
+			await reusableCheckoutAttempt(attempt, "changed shipping", verify),
+		).toBeUndefined();
+		expect(verify).toHaveBeenCalledWith(attempt.orderId);
+	});
+	it("retains ambiguous attempts and blocks changed details without another payment", async () => {
+		const ambiguous = { fingerprint: attempt.fingerprint, key: attempt.key };
+		const verify = vi.fn();
+		await expect(
+			reusableCheckoutAttempt(ambiguous, "changed shipping", verify),
+		).rejects.toThrow(/previous payment/i);
+		expect(ambiguous).toEqual({
+			fingerprint: attempt.fingerprint,
+			key: attempt.key,
+		});
+		expect(verify).not.toHaveBeenCalled();
+	});
+	it("reuses ambiguous attempts without requesting another order", async () => {
+		const verify = vi.fn();
+		const ambiguous = { fingerprint: attempt.fingerprint, key: attempt.key };
+		const reused = await reusableCheckoutAttempt(
+			ambiguous,
+			attempt.fingerprint,
+			verify,
+		);
+		expect(reused).toEqual({ ...ambiguous, uncertain: true });
+		expect(
+			canDiscardCheckoutAttempt(reused, ambiguous.key, "CHECKOUT_NOT_CREATED"),
+		).toBe(false);
+		expect(verify).not.toHaveBeenCalled();
+	});
+	it("reuses a verified pending payment", async () => {
+		const verify = vi
+			.fn()
+			.mockResolvedValue({ status: "pending", paymentStatus: "pending" });
+		expect(
+			await reusableCheckoutAttempt(attempt, attempt.fingerprint, verify),
+		).toBe(attempt);
+		expect(verify).toHaveBeenCalledWith(attempt.orderId);
+	});
+	it.each([
+		{ status: "paid", paymentStatus: "paid" },
+		{ status: "cancelled", paymentStatus: "pending" },
+		{ status: "cancelled", paymentStatus: "failed" },
+		{ status: "cancelled", paymentStatus: "refunded" },
+	] as const)(
+		"allows a new attempt only after verifying $status/$paymentStatus",
+		async (order) => {
+			expect(
+				await reusableCheckoutAttempt(
+					attempt,
+					attempt.fingerprint,
+					async () => order,
+				),
+			).toBeUndefined();
+		},
+	);
+	it("retains the original attempt when verification is uncertain", async () => {
+		await expect(
+			reusableCheckoutAttempt(attempt, attempt.fingerprint, async () => {
+				throw new Error("network unavailable");
+			}),
+		).rejects.toThrow("network unavailable");
+		expect(attempt.key).toBe("existing payment key");
+	});
+});
+
+describe("checkout rejection cleanup", () => {
+	const fresh = { fingerprint: attempt.fingerprint, key: attempt.key };
+	it("allows correction after a definitive rejection before any order was created", () => {
+		expect(
+			canDiscardCheckoutAttempt(fresh, fresh.key, "CHECKOUT_NOT_CREATED"),
+		).toBe(true);
+	});
+	it("retains attempts after network errors and unknown provider outcomes", () => {
+		expect(canDiscardCheckoutAttempt(fresh, fresh.key, undefined)).toBe(false);
+	});
+	it("retains a prior ambiguous attempt even if a later request is rejected", () => {
+		expect(
+			canDiscardCheckoutAttempt(
+				{ ...fresh, uncertain: true },
+				fresh.key,
+				"CHECKOUT_NOT_CREATED",
+			),
+		).toBe(false);
+	});
+	it("retains known orders and a newer checkout attempt", () => {
+		expect(
+			canDiscardCheckoutAttempt(attempt, attempt.key, "CHECKOUT_NOT_CREATED"),
+		).toBe(false);
+		expect(
+			canDiscardCheckoutAttempt(
+				fresh,
+				"different request key",
+				"CHECKOUT_NOT_CREATED",
+			),
+		).toBe(false);
+	});
+});

package/src/plugins/ecommerce/api/adapters/lemon-squeezy.ts

@@ -0,0 +1,155 @@
+import { z } from "zod";
+import type { PaymentAdapter, PaymentWebhookResult } from "../payment-adapter";
+import { verifyHmac } from "./signatures";
+
+/** Lemon Squeezy requires a generic one-time-payment variant in the store currency. */
+export interface LemonSqueezyAdapterOptions {
+	/** Store that owns the generic checkout variant. */
+	storeId: string;
+	/** Generic single-payment variant. Disable buyer quantity changes and use tax-inclusive pricing. */
+	variantId: string;
+	/** Redirect after payment; `{orderId}` is replaced with the local order ID. */
+	redirectUrl?: string;
+	/** Match the provider's test mode. @default false */
+	testMode?: boolean;
+}
+/** Signed Lemon Squeezy checkout integration. The provider amount must equal the store's reserved total. */
+export function lemonSqueezyAdapter(
+	apiKey: string,
+	webhookSecret: string,
+	options: LemonSqueezyAdapterOptions,
+): PaymentAdapter {
+	if (!apiKey || !webhookSecret)
+		throw new Error("Lemon Squeezy API key and webhook secret are required");
+	z.string().regex(/^\d+$/).parse(options.storeId);
+	z.string().regex(/^\d+$/).parse(options.variantId);
+	if (
+		options.redirectUrl &&
+		!/^https?:\/\//.test(z.url().parse(options.redirectUrl))
+	)
+		throw new Error("Lemon Squeezy redirect must use HTTP(S)");
+	const validatePayment: NonNullable<PaymentAdapter["validatePayment"]> = ({
+		amount,
+	}) =>
+		amount > 0
+			? undefined
+			: "Lemon Squeezy requires a positive checkout amount";
+	return {
+		name: "lemon-squeezy",
+		validatePayment,
+		async createPayment({ amount, currency, orderId, metadata }) {
+			const rejection = validatePayment({ amount, currency });
+			if (rejection) throw new Error(rejection);
+			const response = await fetch(
+				"https://api.lemonsqueezy.com/v1/checkouts",
+				{
+					method: "POST",
+					headers: {
+						authorization: `Bearer ${apiKey}`,
+						accept: "application/vnd.api+json",
+						"content-type": "application/vnd.api+json",
+					},
+					body: JSON.stringify({
+						data: {
+							type: "checkouts",
+							attributes: {
+								custom_price: amount,
+								test_mode: options.testMode ?? false,
+								checkout_options: { discount: false },
+								product_options: {
+									enabled_variants: [Number(options.variantId)],
+									...(options.redirectUrl
+										? {
+												redirect_url: options.redirectUrl.replace(
+													"{orderId}",
+													encodeURIComponent(orderId),
+												),
+											}
+										: {}),
+								},
+								checkout_data: {
+									...(metadata?.email ? { email: metadata.email } : {}),
+									custom: { orderId, currency },
+								},
+							},
+							relationships: {
+								store: { data: { type: "stores", id: options.storeId } },
+								variant: { data: { type: "variants", id: options.variantId } },
+							},
+						},
+					}),
+				},
+			);
+			if (!response.ok)
+				throw new Error("Lemon Squeezy payment initialization failed");
+			const result = z
+				.object({ data: z.object({ attributes: z.object({ url: z.url() }) }) })
+				.parse(await response.json());
+			return { redirectUrl: result.data.attributes.url };
+		},
+		async handleWebhook(request): Promise<PaymentWebhookResult | null> {
+			const raw = await request.text();
+			if (
+				!(await verifyHmac(
+					webhookSecret,
+					raw,
+					request.headers.get("x-signature") ?? "",
+				))
+			)
+				throw new Error("Invalid Lemon Squeezy signature");
+			const event = z
+				.object({
+					meta: z.object({
+						event_name: z.string(),
+						custom_data: z.object({ orderId: z.string() }).optional(),
+					}),
+					data: z.object({
+						id: z.string(),
+						type: z.string(),
+						attributes: z.object({
+							store_id: z.number(),
+							test_mode: z.boolean(),
+							status: z.string(),
+							total: z.number().int().min(0),
+							currency: z.string(),
+							refunded: z.boolean().optional(),
+							first_order_item: z.object({ variant_id: z.number() }).optional(),
+						}),
+					}),
+				})
+				.parse(JSON.parse(raw));
+			if (!event.meta.custom_data || event.data.type !== "orders") return null;
+			const attributes = event.data.attributes;
+			if (
+				String(attributes.store_id) !== options.storeId ||
+				attributes.test_mode !== (options.testMode ?? false) ||
+				(attributes.first_order_item &&
+					String(attributes.first_order_item.variant_id) !== options.variantId)
+			)
+				throw new Error("Lemon Squeezy store, variant or mode mismatch");
+			if (
+				event.meta.event_name === "order_created" &&
+				attributes.status === "paid"
+			)
+				return {
+					orderId: event.meta.custom_data.orderId,
+					status: "paid",
+					paymentRef: event.data.id,
+					amount: attributes.total,
+					currency: attributes.currency,
+				};
+			if (
+				event.meta.event_name === "order_refunded" &&
+				attributes.refunded === true
+			)
+				return {
+					orderId: event.meta.custom_data.orderId,
+					status: "refunded",
+					paymentRef: event.data.id,
+					amount: attributes.total,
+					currency: attributes.currency,
+				};
+			return null;
+		},
+	};
+}

package/src/plugins/ecommerce/api/adapters/signatures.ts

@@ -0,0 +1,24 @@
+/** Verify a SHA-256 HMAC in constant time using the platform crypto implementation. */
+export async function verifyHmac(
+	secret: string,
+	payload: string,
+	signature: string,
+) {
+	if (!/^[a-f0-9]{64}$/i.test(signature)) return false;
+	const key = await crypto.subtle.importKey(
+		"raw",
+		new TextEncoder().encode(secret),
+		{ name: "HMAC", hash: "SHA-256" },
+		false,
+		["verify"],
+	);
+	const bytes = Uint8Array.from(signature.match(/.{2}/g)!, (hex) =>
+		Number.parseInt(hex, 16),
+	);
+	return crypto.subtle.verify(
+		"HMAC",
+		key,
+		bytes,
+		new TextEncoder().encode(payload),
+	);
+}

package/src/plugins/ecommerce/api/adapters/stripe.ts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import type { PaymentAdapter, PaymentWebhookResult } from "../payment-adapter";
+import { verifyHmac } from "./signatures";
+
+/** Optional hosted Checkout destinations; without these, Stripe returns a PaymentIntent client secret. */
+export interface StripeAdapterOptions {
+	/** Absolute success URL. Include your storefront confirmation route; its token remains in sessionStorage. */
+	successUrl?: string;
+	/** Absolute URL used when the buyer cancels hosted Checkout. */
+	cancelUrl?: string;
+}
+/** Stripe REST integration with signed raw-body webhooks and provider-side checkout idempotency. */
+export function stripeAdapter(
+	secretKey: string,
+	webhookSecret: string,
+	options: StripeAdapterOptions = {},
+): PaymentAdapter {
+	if (!secretKey || !webhookSecret)
+		throw new Error("Stripe secret key and webhook secret are required");
+	if (Boolean(options.successUrl) !== Boolean(options.cancelUrl))
+		throw new Error("Configure both Stripe successUrl and cancelUrl");
+	for (const url of [options.successUrl, options.cancelUrl])
+		if (url && !/^https?:\/\//.test(z.url().parse(url)))
+			throw new Error("Stripe destinations must use HTTP(S)");
+	const validatePayment: NonNullable<PaymentAdapter["validatePayment"]> = ({
+		amount,
+	}) =>
+		amount === 0 && !options.successUrl
+			? "Stripe PaymentIntent requires a positive checkout amount; use hosted Checkout for free orders"
+			: undefined;
+	return {
+		name: "stripe",
+		validatePayment,
+		async createPayment({ amount, currency, orderId, metadata }) {
+			const rejection = validatePayment({ amount, currency });
+			if (rejection) throw new Error(rejection);
+			const hosted = Boolean(options.successUrl);
+			const body = new URLSearchParams();
+			if (hosted) {
+				body.set("mode", "payment");
+				body.set(
+					"success_url",
+					options.successUrl!.replace("{orderId}", encodeURIComponent(orderId)),
+				);
+				body.set("cancel_url", options.cancelUrl!);
+				body.set("line_items[0][price_data][currency]", currency.toLowerCase());
+				body.set("line_items[0][price_data][unit_amount]", String(amount));
+				body.set(
+					"line_items[0][price_data][product_data][name]",
+					`Order ${orderId}`,
+				);
+				body.set("line_items[0][quantity]", "1");
+				body.set("payment_intent_data[metadata][orderId]", orderId);
+				if (metadata?.email) body.set("customer_email", metadata.email);
+			} else {
+				body.set("amount", String(amount));
+				body.set("currency", currency.toLowerCase());
+				body.set("automatic_payment_methods[enabled]", "true");
+			}
+			body.set("metadata[orderId]", orderId);
+			const response = await fetch(
+				`https://api.stripe.com/v1/${hosted ? "checkout/sessions" : "payment_intents"}`,
+				{
+					method: "POST",
+					headers: {
+						authorization: `Bearer ${secretKey}`,
+						"content-type": "application/x-www-form-urlencoded",
+						"idempotency-key": orderId,
+					},
+					body,
+				},
+			);
+			if (!response.ok) throw new Error("Stripe payment initialization failed");
+			const result = z
+				.object({
+					client_secret: z.string().nullable().optional(),
+					url: z.url().nullable().optional(),
+				})
+				.parse(await response.json());
+			if (hosted && result.url) return { redirectUrl: result.url };
+			if (!hosted && result.client_secret)
+				return { clientSecret: result.client_secret };
+			throw new Error("Stripe returned no checkout destination");
+		},
+		async handleWebhook(request): Promise<PaymentWebhookResult | null> {
+			const raw = await request.text();
+			const header = request.headers.get("stripe-signature") ?? "";
+			const parts = header.split(",").map((value) => value.trim().split("="));
+			const timestamp = parts.find(([key]) => key === "t")?.[1] ?? "";
+			if (
+				!/^\d+$/.test(timestamp) ||
+				Math.abs(Date.now() / 1000 - Number(timestamp)) > 300
+			)
+				throw new Error("Invalid Stripe webhook timestamp");
+			const signatures = parts
+				.filter(([key]) => key === "v1")
+				.map(([, value]) => value ?? "");
+			let verified = false;
+			for (const signature of signatures)
+				if (await verifyHmac(webhookSecret, `${timestamp}.${raw}`, signature))
+					verified = true;
+			if (!verified) throw new Error("Invalid Stripe webhook signature");
+			const event = z
+				.object({
+					type: z.string(),
+					livemode: z.boolean().optional(),
+					data: z.object({ object: z.record(z.string(), z.unknown()) }),
+				})
+				.parse(JSON.parse(raw));
+			if (
+				event.livemode !== undefined &&
+				((secretKey.startsWith("sk_live_") && !event.livemode) ||
+					(secretKey.startsWith("sk_test_") && event.livemode))
+			)
+				throw new Error("Stripe event mode mismatch");
+			const object = event.data.object;
+			const metadata = z
+				.object({ orderId: z.string().min(1) })
+				.safeParse(object.metadata);
+			if (!metadata.success) return null;
+			let status: PaymentWebhookResult["status"];
+			let amount: unknown;
+			if (event.type === "payment_intent.succeeded") {
+				status = "paid";
+				amount = object.amount_received;
+			} else if (event.type === "payment_intent.canceled") {
+				status = "failed";
+				amount = object.amount;
+			} else if (
+				event.type === "checkout.session.completed" ||
+				event.type === "checkout.session.async_payment_succeeded"
+			) {
+				if (
+					object.payment_status !== "paid" &&
+					!(
+						object.payment_status === "no_payment_required" &&
+						object.amount_total === 0
+					)
+				)
+					return null;
+				status = "paid";
+				amount = object.amount_total;
+			} else if (
+				event.type === "checkout.session.expired" ||
+				event.type === "checkout.session.async_payment_failed"
+			) {
+				status = "failed";
+				amount = object.amount_total;
+			} else if (
+				event.type === "charge.refunded" &&
+				object.refunded === true &&
+				object.amount_refunded === object.amount
+			) {
+				status = "refunded";
+				amount = object.amount;
+			} else return null;
+			return {
+				orderId: metadata.data.orderId,
+				status,
+				paymentRef: z
+					.string()
+					.min(1)
+					.parse(object.payment_intent ?? object.id),
+				amount: z.number().int().min(0).parse(amount),
+				currency: z.string().parse(object.currency),
+			};
+		},
+	};
+}

package/src/plugins/ecommerce/api/getters.ts

@@ -0,0 +1,228 @@
+import { getAssetById } from "@btst/stack/plugins/media/api";
+import type { DBAdapter as Adapter } from "@btst/db";
+import {
+	getAllContentItems,
+	getContentItemBySlug,
+} from "@btst/stack/plugins/cms/api";
+import {
+	productSchema,
+	PRODUCT_TYPE_SLUG,
+	productsQuerySchema,
+} from "../schemas";
+import type {
+	Product,
+	ProductsFilters,
+	ProductsPage,
+	OrderRecord,
+	DiscountCode,
+	InventoryRecord,
+} from "../types";
+
+/** Read-only product projection; malformed and unpublished CMS items stay private. */
+export async function listProducts(
+	adapter: Adapter,
+	filters: ProductsFilters = {},
+	mediaAvailable = false,
+): Promise<ProductsPage> {
+	const input = productsQuerySchema.parse(filters);
+	const products: Product[] = [];
+	for (let offset = 0; ; offset += 500) {
+		const page = await getAllContentItems(adapter, PRODUCT_TYPE_SLUG, {
+			limit: 500,
+			offset,
+		});
+		for (const item of page.items) {
+			const parsed = productSchema.safeParse(item.parsedData);
+			if (parsed.success && parsed.data.status === "published")
+				products.push(
+					await overlayInventory(adapter, {
+						...parsed.data,
+						id: item.id,
+						slug: item.slug,
+						createdAt: item.createdAt,
+						updatedAt: item.updatedAt,
+					}),
+				);
+		}
+		if (page.items.length < 500) break;
+	}
+	const categories = [
+		...new Set(
+			products.flatMap((product) =>
+				product.category ? [product.category] : [],
+			),
+		),
+	].sort();
+	const collections = [
+		...new Set(products.flatMap((product) => product.collections)),
+	].sort();
+	const matching = products.filter((product) => {
+		const prices = product.variants.length
+			? product.variants.map((variant) => variant.price ?? product.price)
+			: [product.price];
+		const stock = product.variants.length
+			? product.variants.reduce((sum, variant) => sum + variant.stock, 0)
+			: product.stock;
+		return (
+			(!input.category || product.category === input.category) &&
+			(!input.collection || product.collections.includes(input.collection)) &&
+			(!input.search ||
+				`${product.name} ${product.description} ${product.tags.join(" ")}`
+					.toLowerCase()
+					.includes(input.search.toLowerCase())) &&
+			(input.minPrice === undefined ||
+				prices.some(
+					(price) =>
+						price >= input.minPrice! &&
+						(input.maxPrice === undefined || price <= input.maxPrice),
+				)) &&
+			(input.maxPrice === undefined ||
+				prices.some(
+					(price) =>
+						price <= input.maxPrice! &&
+						(input.minPrice === undefined || price >= input.minPrice),
+				)) &&
+			(input.inStock === undefined || stock > 0 === input.inStock)
+		);
+	});
+	return {
+		items: await Promise.all(
+			matching
+				.slice(input.offset, input.offset + input.limit)
+				.map((product) =>
+					resolveProductImages(adapter, product, mediaAvailable),
+				),
+		),
+		total: matching.length,
+		limit: input.limit,
+		offset: input.offset,
+		categories,
+		collections,
+	};
+}
+export async function getProduct(
+	adapter: Adapter,
+	slug: string,
+	mediaAvailable = false,
+): Promise<Product | null> {
+	const item = await getContentItemBySlug(adapter, PRODUCT_TYPE_SLUG, slug);
+	if (!item) return null;
+	const parsed = productSchema.safeParse(item.parsedData);
+	return parsed.success && parsed.data.status === "published"
+		? resolveProductImages(
+				adapter,
+				await overlayInventory(adapter, {
+					...parsed.data,
+					id: item.id,
+					slug: item.slug,
+					createdAt: item.createdAt,
+					updatedAt: item.updatedAt,
+				}),
+				mediaAvailable,
+			)
+		: null;
+}
+export async function getOrder(adapter: Adapter, id: string) {
+	return adapter.findOne<OrderRecord>({
+		model: "ecommerceOrder",
+		where: [{ field: "id", value: id }],
+	});
+}
+export async function listOrders(
+	adapter: Adapter,
+	options: {
+		customerId?: string;
+		status?: string;
+		limit?: number;
+		offset?: number;
+	} = {},
+) {
+	const where = [
+		...(options.customerId
+			? [{ field: "customerId", value: options.customerId }]
+			: []),
+		...(options.status ? [{ field: "status", value: options.status }] : []),
+	];
+	const [items, total] = await Promise.all([
+		adapter.findMany<OrderRecord>({
+			model: "ecommerceOrder",
+			where,
+			limit: options.limit ?? 25,
+			offset: options.offset ?? 0,
+			sortBy: { field: "createdAt", direction: "desc" },
+		}),
+		adapter.count({ model: "ecommerceOrder", where }),
+	]);
+	return { items, total };
+}
+export async function getDiscountCode(adapter: Adapter, code: string) {
+	return adapter.findOne<DiscountCode>({
+		model: "ecommerceDiscountCode",
+		where: [{ field: "code", value: code.trim().toUpperCase() }],
+	});
+}
+
+/** Product authors explicitly publish selected media; missing assets are omitted. */
+export async function resolveProductImages(
+	adapter: Pick<Adapter, "findOne">,
+	product: Product,
+	mediaAvailable: boolean,
+): Promise<Product> {
+	if (!mediaAvailable) return product;
+	const images = await Promise.all(
+		product.images.map((image) =>
+			resolveProductImage(adapter, image, mediaAvailable),
+		),
+	);
+	return {
+		...product,
+		images: images.filter((image): image is string => Boolean(image)),
+	};
+}
+
+/** Resolve published product media consistently in catalog responses and durable order snapshots. */
+export async function resolveProductImage(
+	adapter: Pick<Adapter, "findOne">,
+	image: string | undefined,
+	mediaAvailable: boolean,
+): Promise<string | undefined> {
+	if (
+		!image ||
+		!mediaAvailable ||
+		/^https?:\/\//.test(image) ||
+		(image.startsWith("/") && !image.startsWith("//"))
+	)
+		return image;
+	return (await getAssetById(adapter, image))?.url;
+}
+
+/** Read the authoritative product/variant count without initializing or changing inventory. */
+export async function getInventory(
+	adapter: Pick<Adapter, "findOne">,
+	productId: string,
+	variantId?: string,
+) {
+	return adapter.findOne<InventoryRecord>({
+		model: "ecommerceInventory",
+		where: [
+			{ field: "key", value: JSON.stringify([productId, variantId ?? null]) },
+		],
+	});
+}
+async function overlayInventory(
+	adapter: Pick<Adapter, "findOne">,
+	product: Product,
+): Promise<Product> {
+	const [inventory, variants] = await Promise.all([
+		getInventory(adapter, product.id),
+		Promise.all(
+			product.variants.map(async (variant) => ({
+				...variant,
+				stock:
+					(await getInventory(adapter, product.id, variant.id))?.stock ??
+					variant.stock,
+			})),
+		),
+	]);
+	return { ...product, stock: inventory?.stock ?? product.stock, variants };
+}