@thebes/cadmea-plugin-ecommerce 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BowenLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @thebes/cadmea-plugin-ecommerce
+
+Provider-agnostic ecommerce core for [Cadmea](https://github.com/bowenlabs/project-thebes).
+Ships the `products`/`orders`/`customers`/`payments`/`webhook_events`
+collections (plus an opt-in `subscriptions` collection), the
+`PaymentProvider` interface real provider implementations conform to, and
+`createCheckoutHandler`/`createWebhookHandler` Hono route factories.
+
+This is a **Cadmea plugin** — a `plugin(config) => config` transform on the
+`@thebes/cadmus/cms` config. `@thebes/cadmus` and `hono` are peer
+dependencies; nothing here ships at runtime except your own order data.
+
+You'll also need a `PaymentProvider` implementation —
+[`@thebes/cadmea-plugin-ecommerce-square`](https://www.npmjs.com/package/@thebes/cadmea-plugin-ecommerce-square)
+and/or
+[`@thebes/cadmea-plugin-ecommerce-stripe`](https://www.npmjs.com/package/@thebes/cadmea-plugin-ecommerce-stripe).
+
+```bash
+pnpm add @thebes/cadmea-plugin-ecommerce
+```
+
+## Add it to your config
+
+```ts
+import { defineCmsConfig } from "@thebes/cadmus/cms";
+import { ecommercePlugin } from "@thebes/cadmea-plugin-ecommerce";
+
+export const cmsConfig = defineCmsConfig({
+  collections: [pagesCollection],
+  plugins: [ecommercePlugin()],
+});
+```
+
+Pass `{ includeSubscriptions: true }` to add the `subscriptions` collection
+— off by default, since Square and Stripe model recurring billing
+differently enough (`PaymentProvider.subscriptions` is itself optional)
+that it isn't assumed needed by every store. Slugs for every collection are
+configurable (`productsSlug`, `ordersSlug`, etc.) — see the plugin's own
+type signature.
+
+## Mount checkout + webhook routes
+
+Neither is part of `mountCmsRoutes`'s generic CMS REST surface — mount them
+as plain Hono routes alongside it:
+
+```ts
+import { createCheckoutHandler, createWebhookHandler } from "@thebes/cadmea-plugin-ecommerce";
+import { createSquarePaymentProvider } from "@thebes/cadmea-plugin-ecommerce-square";
+
+const provider = createSquarePaymentProvider({ accessToken, locationId });
+
+app.post("/checkout", createCheckoutHandler({
+  provider,
+  orders: ordersApi,
+  payments: paymentsApi,
+  resolveContext: async (c) => ({ session: null, internal: true }),
+  rateLimit: { kv: c.env.KV, limit: 10, windowSeconds: 60 },
+}));
+
+app.post("/webhook", createWebhookHandler({
+  provider,
+  webhookEvents: webhookEventsApi,
+  orders: ordersApi,
+  payments: paymentsApi,
+  secret: env.SQUARE_WEBHOOK_SECRET,
+  notificationUrl: env.SQUARE_WEBHOOK_URL,
+  context: { session: null, internal: true },
+}));
+```
+
+`createCheckoutHandler` re-verifies every line item's price/availability
+against the live provider catalog before charging — a client-submitted
+price is never trusted. A DB-write failure *after* a successful charge
+degrades to a `200`-with-warning response, never a false "payment failed."
+
+`createWebhookHandler` verifies the raw-body signature before parsing,
+dedups via the `webhook_events` collection's unique `eventId` constraint,
+then dispatches by normalized event kind — each dispatch handler isolated
+so one bug can't prevent the `200` response the provider needs to stop
+retrying.
+
+## `PaymentProvider` — a plugin-defined interface, not a Cadmus adapter
+
+`PaymentProvider` mirrors the Cadmus adapter pattern's swappability (one
+interface, N implementations) but is defined by this plugin, not by Cadmus
+core — it needs commerce-domain concepts (cart line items, normalized
+webhook events) that have no business in framework-layer Cadmus. See
+[EXTENDING.md](https://github.com/bowenlabs/project-thebes/blob/main/EXTENDING.md)'s
+"Plugin-defined provider interfaces" section.
+
+Both shipped implementations talk to their provider's REST API via raw
+`fetch()` + `crypto.subtle` only — **no Square/Stripe Node SDK, ever** (this
+is a V8-isolate constraint, not a style preference).
+
+## License
+
+MIT © BowenLabs

package/dist/index.cjs

@@ -0,0 +1,558 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _thebes_cadmus_rate_limit = require("@thebes/cadmus/rate-limit");
+//#region src/errors.ts
+/**
+* Thrown by `createCheckoutHandler` on price-mismatch/inventory rejection,
+* and by `PaymentProvider` implementations on charge failure.
+* `createCheckoutHandler` catches it internally (`instanceof
+* CadmeaPaymentError`) and maps it to HTTP 402 itself — checkout/webhook
+* handlers are plain Hono routes, never mounted through
+* `@thebes/cadmus/hono`'s `mountCmsRoutes`, so there's no shared
+* error-to-status pipeline this needs to participate in.
+*
+* Deliberately a plain `Error` subclass, not a `CadmusCmsError` one — this
+* is a Cadmea-plugin-owned error, not a Cadmus-primitive one (every real
+* `CadmusError` subclass is owned by a `packages/cadmus/src/<primitive>/`
+* folder; a payment error belongs to a plugin, not a primitive), and
+* `CadmusCmsError` is only reachable via the root `@thebes/cadmus` package
+* export (not `@thebes/cadmus/cms`) — importing that root barrel here
+* would pull in every other primitive's runtime code (including
+* Workers-only modules like `cloudflare:email`) just for one base class.
+* Keeping this plugin-local and dependency-free is the honest shape.
+*/
+var CadmeaPaymentError = class extends Error {
+	cause;
+	constructor(message, cause) {
+		super(message);
+		this.cause = cause;
+		this.name = "CadmeaPaymentError";
+	}
+};
+//#endregion
+//#region src/checkout.ts
+function subtotalCents(lineItems) {
+	return lineItems.reduce((sum, item) => sum + item.clientUnitPrice.amount * item.quantity, 0);
+}
+function generateOrderNumber() {
+	return `ORD-${crypto.randomUUID().replace(/-/g, "").slice(0, 12).toUpperCase()}`;
+}
+/**
+* Returns a Hono handler implementing the checkout flow against a
+* `PaymentProvider`: rate limit → re-verify cart prices/availability
+* (never trust client-submitted prices) → idempotent customer find-or-
+* create → charge → persist `orders`/`payments` rows. A DB-write failure
+* *after* a successful charge degrades to a 200-with-warning response,
+* never a false "payment failed" — the customer's card was actually
+* charged, telling them otherwise would be worse than a delayed manual
+* reconciliation.
+*
+* Mount it as a plain Hono route alongside `mountCmsRoutes` — checkout
+* isn't part of the generic CMS REST surface that function mounts.
+*
+* ```ts
+* app.post("/api/checkout", createCheckoutHandler({ provider, orders, payments, resolveContext }));
+* ```
+*/
+function createCheckoutHandler(options) {
+	return async (c) => {
+		if (options.rateLimit) {
+			const ip = c.req.header("CF-Connecting-IP") ?? "unknown";
+			const key = `${options.rateLimit.keyPrefix ?? "checkout"}:${ip}`;
+			if (!(await (0, _thebes_cadmus_rate_limit.checkRateLimit)(options.rateLimit.kv, key, options.rateLimit.limit, options.rateLimit.windowSeconds)).allowed) return c.json({ error: "Rate limit exceeded" }, 429);
+		}
+		const body = await c.req.json();
+		if (!Array.isArray(body.lineItems) || body.lineItems.length === 0) return c.json({ error: "Checkout request must include at least one line item" }, 400);
+		if (!body.idempotencyKey) return c.json({ error: "Checkout request must include an idempotencyKey" }, 400);
+		try {
+			const refs = body.lineItems.map((item) => item.catalogRef);
+			const priceChecks = await options.provider.checkCatalogPrices(refs);
+			const checkByRef = new Map(priceChecks.map((check) => [check.catalogRef, check]));
+			for (const item of body.lineItems) {
+				const check = checkByRef.get(item.catalogRef);
+				if (!check) throw new CadmeaPaymentError(`Unknown catalog item "${item.catalogRef}"`);
+				if (check.serverUnitPrice.amount !== item.clientUnitPrice.amount) throw new CadmeaPaymentError(`Price mismatch for "${item.catalogRef}" — checkout rejected`);
+				if (check.availableQuantity !== void 0 && check.availableQuantity < item.quantity) throw new CadmeaPaymentError(`Insufficient inventory for "${item.catalogRef}"`);
+			}
+		} catch (error) {
+			if (error instanceof CadmeaPaymentError) return c.json({ error: error.message }, 402);
+			throw error;
+		}
+		if (body.customerEmail) await options.provider.findOrCreateCustomer(body.customerEmail, body.idempotencyKey);
+		const result = await options.provider.checkout({
+			lineItems: body.lineItems,
+			paymentSourceToken: body.paymentSourceToken,
+			customerEmail: body.customerEmail,
+			idempotencyKey: body.idempotencyKey,
+			metadata: body.metadata
+		});
+		const context = await options.resolveContext(c);
+		const orderData = {
+			orderNumber: generateOrderNumber(),
+			status: result.status === "succeeded" ? "paid" : "pending",
+			totalCents: result.amount.amount,
+			subtotalCents: subtotalCents(body.lineItems),
+			currency: result.amount.currency,
+			provider: options.provider.name,
+			providerOrderRef: result.providerOrderRef,
+			providerPaymentRef: result.providerPaymentRef,
+			guestEmail: body.customerEmail,
+			lineItems: body.lineItems.map((item) => ({
+				productName: item.catalogRef,
+				quantity: item.quantity,
+				unitPriceCents: item.clientUnitPrice.amount,
+				totalPriceCents: item.clientUnitPrice.amount * item.quantity,
+				catalogRef: item.catalogRef
+			})),
+			shippingAddress: body.shippingAddress
+		};
+		try {
+			const order = await options.orders.create(context, orderData);
+			await options.payments.create(context, {
+				provider: options.provider.name,
+				providerPaymentRef: result.providerPaymentRef,
+				providerOrderRef: result.providerOrderRef,
+				order: order.id,
+				status: result.status,
+				amountCents: result.amount.amount,
+				currency: result.amount.currency,
+				rawResponse: result.raw
+			});
+			return c.json({ order }, 201);
+		} catch (cause) {
+			return c.json({
+				warning: "Payment succeeded but order record-keeping failed — contact support",
+				providerPaymentRef: result.providerPaymentRef,
+				providerOrderRef: result.providerOrderRef,
+				cause: cause instanceof Error ? cause.message : String(cause)
+			}, 200);
+		}
+	};
+}
+//#endregion
+//#region src/collections.ts
+const DEFAULTS = {
+	products: "products",
+	orders: "orders",
+	customers: "customers",
+	payments: "payments",
+	webhookEvents: "webhook_events",
+	subscriptions: "subscriptions",
+	users: "users"
+};
+function buildProductsCollection(slug) {
+	return {
+		slug,
+		fields: {
+			id: {
+				type: "number",
+				autoIncrement: true
+			},
+			name: {
+				type: "text",
+				required: true
+			},
+			description: { type: "text" },
+			status: {
+				type: "select",
+				options: [
+					"draft",
+					"active",
+					"archived"
+				],
+				required: true,
+				defaultValue: "draft"
+			},
+			variants: {
+				type: "array",
+				required: true,
+				fields: {
+					sku: {
+						type: "text",
+						required: true
+					},
+					catalogRef: {
+						type: "text",
+						required: true
+					},
+					priceCents: {
+						type: "number",
+						required: true
+					},
+					currency: {
+						type: "text",
+						defaultValue: "USD"
+					},
+					inventoryCount: { type: "number" }
+				}
+			},
+			createdAt: {
+				type: "date",
+				mode: "timestamp",
+				defaultValue: "now"
+			}
+		}
+	};
+}
+function buildOrdersCollection(slug, customersSlug) {
+	return {
+		slug,
+		fields: {
+			id: {
+				type: "number",
+				autoIncrement: true
+			},
+			orderNumber: {
+				type: "text",
+				required: true,
+				unique: true
+			},
+			status: {
+				type: "select",
+				options: [
+					"pending",
+					"paid",
+					"failed",
+					"refunded",
+					"partially_refunded"
+				],
+				required: true,
+				defaultValue: "pending"
+			},
+			totalCents: {
+				type: "number",
+				required: true
+			},
+			subtotalCents: {
+				type: "number",
+				required: true
+			},
+			taxCents: { type: "number" },
+			currency: {
+				type: "text",
+				defaultValue: "USD"
+			},
+			provider: {
+				type: "select",
+				options: ["square", "stripe"],
+				required: true
+			},
+			providerOrderRef: { type: "text" },
+			providerPaymentRef: { type: "text" },
+			customer: {
+				type: "relationship",
+				relationTo: customersSlug
+			},
+			guestEmail: { type: "text" },
+			lineItems: {
+				type: "array",
+				required: true,
+				fields: {
+					productName: {
+						type: "text",
+						required: true
+					},
+					quantity: {
+						type: "number",
+						required: true
+					},
+					unitPriceCents: {
+						type: "number",
+						required: true
+					},
+					totalPriceCents: {
+						type: "number",
+						required: true
+					},
+					catalogRef: { type: "text" }
+				}
+			},
+			shippingAddress: {
+				type: "group",
+				fields: {
+					firstName: { type: "text" },
+					lastName: { type: "text" },
+					address1: { type: "text" },
+					address2: { type: "text" },
+					city: { type: "text" },
+					state: { type: "text" },
+					zip: { type: "text" },
+					country: {
+						type: "text",
+						defaultValue: "US"
+					},
+					phone: { type: "text" }
+				}
+			},
+			fulfillmentStatus: {
+				type: "select",
+				options: [
+					"pending",
+					"shipped",
+					"delivered",
+					"failed"
+				]
+			},
+			trackingNumber: { type: "text" },
+			trackingCarrier: { type: "text" },
+			trackingUrl: { type: "text" },
+			createdAt: {
+				type: "date",
+				mode: "timestamp",
+				defaultValue: "now"
+			}
+		}
+	};
+}
+function buildCustomersCollection(slug, usersSlug) {
+	return {
+		slug,
+		fields: {
+			id: {
+				type: "number",
+				autoIncrement: true
+			},
+			email: {
+				type: "text",
+				required: true,
+				unique: true
+			},
+			provider: {
+				type: "select",
+				options: ["square", "stripe"]
+			},
+			providerCustomerRef: { type: "text" },
+			linkedUser: {
+				type: "relationship",
+				relationTo: usersSlug
+			},
+			loyaltyAccountRef: { type: "text" },
+			loyaltyPoints: {
+				type: "number",
+				defaultValue: 0
+			},
+			createdAt: {
+				type: "date",
+				mode: "timestamp",
+				defaultValue: "now"
+			}
+		}
+	};
+}
+function buildPaymentsCollection(slug, ordersSlug) {
+	return {
+		slug,
+		fields: {
+			id: {
+				type: "number",
+				autoIncrement: true
+			},
+			provider: {
+				type: "select",
+				options: ["square", "stripe"],
+				required: true
+			},
+			providerPaymentRef: {
+				type: "text",
+				required: true
+			},
+			providerOrderRef: { type: "text" },
+			order: {
+				type: "relationship",
+				relationTo: ordersSlug
+			},
+			status: { type: "text" },
+			amountCents: {
+				type: "number",
+				required: true
+			},
+			currency: {
+				type: "text",
+				defaultValue: "USD"
+			},
+			rawResponse: { type: "json" },
+			createdAt: {
+				type: "date",
+				mode: "timestamp",
+				defaultValue: "now"
+			}
+		}
+	};
+}
+function buildWebhookEventsCollection(slug) {
+	return {
+		slug,
+		fields: {
+			id: {
+				type: "number",
+				autoIncrement: true
+			},
+			provider: {
+				type: "select",
+				options: ["square", "stripe"],
+				required: true
+			},
+			eventId: {
+				type: "text",
+				required: true,
+				unique: true
+			},
+			eventType: { type: "text" },
+			receivedAt: {
+				type: "date",
+				mode: "timestamp",
+				defaultValue: "now"
+			}
+		}
+	};
+}
+function buildSubscriptionsCollection(slug, customersSlug) {
+	return {
+		slug,
+		fields: {
+			id: {
+				type: "number",
+				autoIncrement: true
+			},
+			provider: {
+				type: "select",
+				options: ["square", "stripe"],
+				required: true
+			},
+			providerSubscriptionRef: {
+				type: "text",
+				required: true
+			},
+			customer: {
+				type: "relationship",
+				relationTo: customersSlug
+			},
+			status: { type: "text" },
+			chargedThroughDate: {
+				type: "date",
+				mode: "timestamp"
+			},
+			createdAt: {
+				type: "date",
+				mode: "timestamp",
+				defaultValue: "now"
+			}
+		}
+	};
+}
+/**
+* Returns a Cadmea plugin that adds the provider-agnostic ecommerce
+* collections — a no-op for any collection slug already present, the same
+* idempotent-add convention `cadmea-plugin-redirects`/`cadmea-plugin-crm`
+* use.
+*/
+function ecommercePlugin(options = {}) {
+	const slugs = {
+		products: options.productsSlug ?? DEFAULTS.products,
+		orders: options.ordersSlug ?? DEFAULTS.orders,
+		customers: options.customersSlug ?? DEFAULTS.customers,
+		payments: options.paymentsSlug ?? DEFAULTS.payments,
+		webhookEvents: options.webhookEventsSlug ?? DEFAULTS.webhookEvents,
+		subscriptions: options.subscriptionsSlug ?? DEFAULTS.subscriptions,
+		users: options.usersSlug ?? DEFAULTS.users
+	};
+	return (config) => {
+		const collections = [...config.collections];
+		const addIfMissing = (collection) => {
+			if (!collections.some((c) => c.slug === collection.slug)) collections.push(collection);
+		};
+		addIfMissing(buildProductsCollection(slugs.products));
+		addIfMissing(buildOrdersCollection(slugs.orders, slugs.customers));
+		addIfMissing(buildCustomersCollection(slugs.customers, slugs.users));
+		addIfMissing(buildPaymentsCollection(slugs.payments, slugs.orders));
+		addIfMissing(buildWebhookEventsCollection(slugs.webhookEvents));
+		if (options.includeSubscriptions) addIfMissing(buildSubscriptionsCollection(slugs.subscriptions, slugs.customers));
+		return {
+			...config,
+			collections
+		};
+	};
+}
+//#endregion
+//#region src/webhook.ts
+function isUniqueConstraintError(error) {
+	return error instanceof Error && error.message.includes("Unique constraint violated");
+}
+async function findOneByField(api, context, field, value) {
+	return (await api.find(context)).find((row) => row[field] === value);
+}
+async function dispatchEvent(event, options) {
+	switch (event.kind) {
+		case "payment.updated": {
+			const payment = await findOneByField(options.payments, options.context, "providerPaymentRef", event.providerPaymentRef);
+			if (payment) await options.payments.update(options.context, payment.id, { status: event.status });
+			const order = await findOneByField(options.orders, options.context, "providerPaymentRef", event.providerPaymentRef);
+			if (order) {
+				const status = event.status === "succeeded" ? "paid" : event.status === "refunded" ? "refunded" : "failed";
+				await options.orders.update(options.context, order.id, { status });
+			}
+			return;
+		}
+		case "order.updated": {
+			const order = await findOneByField(options.orders, options.context, "providerOrderRef", event.providerOrderRef);
+			if (order) await options.orders.update(options.context, order.id, { status: event.status });
+			return;
+		}
+		case "subscription.updated": {
+			if (!options.subscriptions) return;
+			const subscription = await findOneByField(options.subscriptions, options.context, "providerSubscriptionRef", event.providerSubscriptionRef);
+			if (subscription) await options.subscriptions.update(options.context, subscription.id, { status: event.status });
+			return;
+		}
+		case "unhandled": return;
+	}
+}
+/**
+* Returns a Hono handler implementing inbound webhook handling against a
+* `PaymentProvider`: verify signature (raw body, before any parsing) →
+* dedup via the `webhook_events` collection's unique `eventId` constraint
+* → dispatch by normalized event kind. Each step isolated so a handler bug
+* never prevents the 200 response a provider needs to stop retrying — the
+* dedup write IS the source of truth for "already processed," checked
+* before dispatch, not after.
+*
+* Mount alongside `mountCmsRoutes`, same as `createCheckoutHandler` — not
+* part of the generic CMS REST surface.
+*/
+function createWebhookHandler(options) {
+	return async (c) => {
+		const rawBody = await c.req.text();
+		if (!await options.provider.verifyWebhookSignature({
+			rawBody,
+			headers: c.req.raw.headers,
+			secret: options.secret,
+			notificationUrl: options.notificationUrl
+		})) return c.json({ error: "Invalid signature" }, 401);
+		const { eventId, event } = options.provider.parseWebhookEvent(rawBody);
+		try {
+			await options.webhookEvents.create(options.context, {
+				provider: options.provider.name,
+				eventId,
+				eventType: event.kind
+			});
+		} catch (error) {
+			if (isUniqueConstraintError(error)) return c.json({
+				ok: true,
+				duplicate: true
+			}, 200);
+			throw error;
+		}
+		try {
+			await dispatchEvent(event, options);
+		} catch (error) {
+			console.error("[cadmea-plugin-ecommerce] webhook dispatch failed", error);
+		}
+		return c.json({ ok: true }, 200);
+	};
+}
+//#endregion
+exports.CadmeaPaymentError = CadmeaPaymentError;
+exports.createCheckoutHandler = createCheckoutHandler;
+exports.createWebhookHandler = createWebhookHandler;
+exports.ecommercePlugin = ecommercePlugin;
+
+//# sourceMappingURL=index.cjs.map