@vitrine-kit/vitrine 0.3.1 → 0.4.0

package/kit/registry/cart/files/app/api/cart/route.ts

@@ -0,0 +1,41 @@
+// Cart API: POST add, PATCH change quantity, DELETE remove a line.
+// Cart id in an httpOnly cookie. Mutations are delegated to CommerceBackend (lib/adapter),
+// the arithmetic lives in @vitrine-kit/core. Next glue, not typechecked in the monorepo.
+import { cookies } from 'next/headers';
+import { NextResponse } from 'next/server';
+import type { CommerceBackend } from '@vitrine-kit/contracts';
+import { getCommerceBackend } from '@/lib/adapter';
+
+const COOKIE = 'vitrine_cart';
+
+async function ensureCartId(commerce: CommerceBackend): Promise<string> {
+  const jar = await cookies();
+  const existing = jar.get(COOKIE)?.value;
+  if (existing) return existing;
+  const cart = await commerce.createCart();
+  jar.set(COOKIE, cart.id, { httpOnly: true, sameSite: 'lax', path: '/' });
+  return cart.id;
+}
+
+export async function POST(req: Request) {
+  const { variantId, quantity = 1 } = (await req.json()) as { variantId: string; quantity?: number };
+  const commerce = await getCommerceBackend();
+  const id = await ensureCartId(commerce);
+  return NextResponse.json(await commerce.addItem(id, variantId, quantity));
+}
+
+export async function PATCH(req: Request) {
+  const { lineId, quantity } = (await req.json()) as { lineId: string; quantity: number };
+  const id = (await cookies()).get(COOKIE)?.value;
+  if (!id) return NextResponse.json({ error: 'cart not found' }, { status: 400 });
+  const commerce = await getCommerceBackend();
+  return NextResponse.json(await commerce.updateItem(id, lineId, quantity));
+}
+
+export async function DELETE(req: Request) {
+  const { lineId } = (await req.json()) as { lineId: string };
+  const id = (await cookies()).get(COOKIE)?.value;
+  if (!id) return NextResponse.json({ error: 'cart not found' }, { status: 400 });
+  const commerce = await getCommerceBackend();
+  return NextResponse.json(await commerce.removeItem(id, lineId));
+}

package/kit/registry/cart/files/components/cart/AddToCart.tsx

@@ -0,0 +1,40 @@
+// "Add to cart" button — client component. Mounted into the product.purchase slot
+// (ProductView passes product). Mutation goes through POST /api/cart (the feature's route).
+'use client';
+import { useState } from 'react';
+import type { Product } from '@vitrine-kit/contracts';
+
+export interface AddToCartProps {
+  product: Product;
+}
+
+export function AddToCart({ product }: AddToCartProps) {
+  const [pending, setPending] = useState(false);
+  const variantId = product.variants[0]?.id;
+
+  async function add(): Promise<void> {
+    if (!variantId) return;
+    setPending(true);
+    try {
+      await fetch('/api/cart', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ variantId, quantity: 1 }),
+      });
+      location.assign('/cart');
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={add}
+      disabled={pending || !variantId}
+      className="vt-add-to-cart rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+    >
+      {pending ? 'Adding…' : 'Add to cart'}
+    </button>
+  );
+}

package/kit/registry/cart/files/components/cart/CartIndicator.tsx

@@ -0,0 +1,11 @@
+// Header cart link (global.header-actions slot). Presentational.
+export function CartIndicator() {
+  return (
+    <a
+      href="/cart"
+      className="vt-cart-indicator text-fg transition hover:text-primary focus-visible:outline-none focus-visible:ring-2 ring-ring"
+    >
+      Cart
+    </a>
+  );
+}

package/kit/registry/cart/files/components/cart/CartLineItem.tsx

@@ -0,0 +1,27 @@
+// Cart line item — presentational.
+import type { CartLine } from '@vitrine-kit/contracts';
+import { formatMoney } from '../../lib/cart/data.js';
+
+export interface CartLineItemProps {
+  line: CartLine;
+  currency: string;
+}
+
+export function CartLineItem({ line, currency }: CartLineItemProps) {
+  return (
+    <li className="vt-cart-line flex items-center gap-gutter border-b border-border py-unit">
+      {line.image ? (
+        <img src={line.image} alt="" className="h-16 w-16 rounded-md object-cover" />
+      ) : (
+        <div className="h-16 w-16 rounded-md bg-muted" aria-hidden="true" />
+      )}
+      <div className="flex-1">
+        <p className="text-fg">{line.title}</p>
+        <p className="text-muted-fg">
+          {line.quantity} × {formatMoney(line.unitPrice, currency)}
+        </p>
+      </div>
+      <p className="text-price">{formatMoney(line.lineTotal, currency)}</p>
+    </li>
+  );
+}

package/kit/registry/cart/files/components/cart/CartSummary.tsx

@@ -0,0 +1,31 @@
+// Cart totals. Hosts the cart.summary slot (where checkout-stripe mounts the checkout
+// button) and passes it cartId.
+import type { Cart } from '@vitrine-kit/contracts';
+import { Slot } from '@vitrine-kit/core/react';
+import { formatMoney } from '../../lib/cart/data.js';
+
+export interface CartSummaryProps {
+  cart: Cart;
+}
+
+export function CartSummary({ cart }: CartSummaryProps) {
+  return (
+    <aside className="vt-cart-summary flex flex-col gap-unit rounded-md border border-border p-gutter">
+      <div className="flex justify-between text-muted-fg">
+        <span>Subtotal</span>
+        <span>{formatMoney(cart.subtotal, cart.currency)}</span>
+      </div>
+      {cart.discountTotal ? (
+        <div className="flex justify-between text-muted-fg">
+          <span>Discount</span>
+          <span>−{formatMoney(cart.discountTotal, cart.currency)}</span>
+        </div>
+      ) : null}
+      <div className="flex justify-between text-fg">
+        <span>Total</span>
+        <span className="text-price">{formatMoney(cart.total, cart.currency)}</span>
+      </div>
+      <Slot name="cart.summary" cartId={cart.id} />
+    </aside>
+  );
+}

package/kit/registry/cart/files/components/cart/CartView.tsx

@@ -0,0 +1,31 @@
+// Cart contents — presentational. Hosts the cart.items-bottom / cart.below slots.
+import type { Cart } from '@vitrine-kit/contracts';
+import { Slot } from '@vitrine-kit/core/react';
+import { CartLineItem } from './CartLineItem.js';
+import { CartSummary } from './CartSummary.js';
+
+export interface CartViewProps {
+  cart: Cart;
+}
+
+export function CartView({ cart }: CartViewProps) {
+  if (cart.lines.length === 0) {
+    return <p className="text-muted-fg">Your cart is empty.</p>;
+  }
+  return (
+    <div className="vt-cart grid gap-section md:grid-cols-[2fr_1fr]">
+      <div>
+        <ul role="list">
+          {cart.lines.map((line) => (
+            <CartLineItem key={line.id} line={line} currency={cart.currency} />
+          ))}
+        </ul>
+        <Slot name="cart.items-bottom" />
+      </div>
+      <div className="flex flex-col gap-gutter">
+        <CartSummary cart={cart} />
+        <Slot name="cart.below" />
+      </div>
+    </div>
+  );
+}

package/kit/registry/cart/files/lib/cart/data.ts

@@ -0,0 +1,12 @@
+// Cart access via the CommerceBackend contract + price formatting.
+// The cart arithmetic lives in @vitrine-kit/core (critical logic); a ready Cart arrives here.
+import type { Cart, CommerceBackend } from '@vitrine-kit/contracts';
+
+export async function loadCart(commerce: CommerceBackend, cartId: string): Promise<Cart | null> {
+  return commerce.getCart(cartId);
+}
+
+/** Money — minor units (e.g. cents); divide by 100 for 2-decimal currencies. */
+export function formatMoney(amount: number, currency: string, locale = 'en-US'): string {
+  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount / 100);
+}

package/kit/registry/cart/files/lib/cart/register.ts

@@ -0,0 +1,10 @@
+// Registers the cart feature's slots. The client calls this from lib/slots.ts.
+// AddToCart — on the product page (product.purchase), CartIndicator — in the header.
+import { registerSlot } from '@vitrine-kit/core';
+import { AddToCart } from '../../components/cart/AddToCart.js';
+import { CartIndicator } from '../../components/cart/CartIndicator.js';
+
+export function registerCartSlots(): void {
+  registerSlot({ slot: 'product.purchase', component: AddToCart, order: 10 });
+  registerSlot({ slot: 'global.header-actions', component: CartIndicator, order: 20 });
+}

package/kit/registry/catalog/docs/catalog.md

@@ -0,0 +1,18 @@
+# Feature: catalog
+
+Browsing the assortment: product grid, product card, category navigation.
+
+## Components
+- `components/catalog/ProductGrid` — grid (semantic list) of `ProductCard`s.
+- `components/catalog/ProductCard` — card (image, title, price).
+- `components/catalog/CategoryNav` — navigation; mounted into the `global.header-nav` slot.
+
+## Data
+- `lib/catalog/data` — `loadProducts`/`loadProduct`/`loadCategories` over the `CatalogSource` contract + `formatPrice` (price in minor units).
+- `lib/catalog/register` — registers the `global.header-nav` slot.
+
+## Styling
+All classes are token-based (`bg-surface`, `text-fg`, `text-price`, `rounded-md`, `gap-gutter`). The design step changes only token values, not structure/a11y.
+
+## Contracts
+Depends only on `@vitrine-kit/contracts` (types, `CatalogSource`) and `@vitrine-kit/core` (`registerSlot`). Portable between Payload and Vendure.

package/kit/registry/catalog/feature.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "catalog",
+  "title": "Product catalog",
+  "kitVersion": "0.4.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "catalog",
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/catalog/",
+      "to": "components/catalog/"
+    },
+    {
+      "from": "files/lib/catalog/",
+      "to": "lib/catalog/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.catalog": true
+    }
+  },
+  "slots": [
+    {
+      "slot": "global.header-nav",
+      "component": "CategoryNav",
+      "order": 10
+    }
+  ],
+  "env": [],
+  "claudeDoc": "docs/catalog.md",
+  "conflicts": [],
+  "removable": false
+}

package/kit/registry/catalog/files/components/catalog/CategoryNav.tsx

@@ -0,0 +1,26 @@
+// Category navigation — presentational. Data comes as a prop from the slot host
+// (<Slot name="global.header-nav" categories={…} />).
+import type { Category } from '@vitrine-kit/contracts';
+
+export interface CategoryNavProps {
+  categories: Category[];
+}
+
+export function CategoryNav({ categories }: CategoryNavProps) {
+  return (
+    <nav aria-label="Categories" className="vt-category-nav">
+      <ul role="list" className="flex flex-wrap gap-gutter">
+        {categories.map((category) => (
+          <li key={category.id}>
+            <a
+              href={`/categories/${category.slug}`}
+              className="text-fg transition hover:text-primary focus-visible:outline-none focus-visible:ring-2 ring-ring"
+            >
+              {category.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

package/kit/registry/catalog/files/components/catalog/ProductCard.tsx

@@ -0,0 +1,42 @@
+// Product card — presentational, visually neutral (classes → tokens).
+// The design step doesn't touch structure/a11y, only tokens.
+import type { Product } from '@vitrine-kit/contracts';
+import { formatPrice } from '../../lib/catalog/data.js';
+
+export interface ProductCardProps {
+  product: Product;
+}
+
+export function ProductCard({ product }: ProductCardProps) {
+  const price = product.priceRange?.min ?? product.variants[0]?.price;
+  const currency = product.priceRange?.currency ?? product.variants[0]?.currency ?? 'USD';
+  const image = product.images[0];
+
+  return (
+    <article className="vt-product-card rounded-md border border-border bg-surface text-surface-fg">
+      <a
+        href={`/products/${product.slug}`}
+        className="block focus-visible:outline-none focus-visible:ring-2 ring-ring"
+      >
+        {image ? (
+          <img
+            src={image.url}
+            alt={image.alt ?? product.title}
+            width={image.width}
+            height={image.height}
+            loading="lazy"
+            className="aspect-square w-full rounded-t-md object-cover"
+          />
+        ) : (
+          <div className="aspect-square w-full rounded-t-md bg-muted" aria-hidden="true" />
+        )}
+        <div className="p-gutter">
+          <h3 className="font-heading text-fg">{product.title}</h3>
+          {price != null ? (
+            <p className="text-price">{formatPrice(price, currency)}</p>
+          ) : null}
+        </div>
+      </a>
+    </article>
+  );
+}

package/kit/registry/catalog/files/components/catalog/ProductGrid.tsx

@@ -0,0 +1,25 @@
+// Product grid — presentational, semantic list.
+import type { Product } from '@vitrine-kit/contracts';
+import { ProductCard } from './ProductCard.js';
+
+export interface ProductGridProps {
+  products: Product[];
+}
+
+export function ProductGrid({ products }: ProductGridProps) {
+  if (products.length === 0) {
+    return <p className="text-muted-fg">No products found.</p>;
+  }
+  return (
+    <ul
+      role="list"
+      className="vt-product-grid grid grid-cols-2 gap-gutter md:grid-cols-3 lg:grid-cols-4"
+    >
+      {products.map((product) => (
+        <li key={product.id}>
+          <ProductCard product={product} />
+        </li>
+      ))}
+    </ul>
+  );
+}

package/kit/registry/catalog/files/lib/catalog/data.ts

@@ -0,0 +1,24 @@
+// Catalog access via the CatalogSource contract. The source (Payload*/Vendure*)
+// is resolved in the page data (template); a ready CatalogSource arrives here —
+// so the feature depends only on the contract and is portable across backends.
+import type { CatalogSource, Category, Product, ProductQuery } from '@vitrine-kit/contracts';
+
+export async function loadProducts(
+  source: CatalogSource,
+  query: ProductQuery = {},
+): Promise<Product[]> {
+  return source.listProducts(query);
+}
+
+export async function loadProduct(source: CatalogSource, slug: string): Promise<Product | null> {
+  return source.getProduct(slug);
+}
+
+export async function loadCategories(source: CatalogSource): Promise<Category[]> {
+  return source.listCategories();
+}
+
+/** Money — minor units (e.g. cents); divide by 100 for 2-decimal currencies. */
+export function formatPrice(amount: number, currency: string, locale = 'en-US'): string {
+  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount / 100);
+}

package/kit/registry/catalog/files/lib/catalog/register.ts

@@ -0,0 +1,8 @@
+// Registers the catalog feature's slots. The client calls this from lib/slots.ts.
+// CategoryNav receives categories from the slot host via <Slot> props.
+import { registerSlot } from '@vitrine-kit/core';
+import { CategoryNav } from '../../components/catalog/CategoryNav.js';
+
+export function registerCatalogSlots(): void {
+  registerSlot({ slot: 'global.header-nav', component: CategoryNav, order: 10 });
+}

package/kit/registry/checkout/docs/checkout.md

@@ -0,0 +1,17 @@
+# Feature: checkout
+
+A provider-agnostic checkout scaffold for `simple-store` / `full-store`. Depends on the
+`cart` feature. It does NOT process payments on its own — add one of the provider features:
+`checkout-stripe`, `checkout-paddle`, or `checkout-yookassa` (exactly one).
+
+- **Component:** `CheckoutButton` (client component) — `cart.summary` slot. Calls
+  `POST /api/checkout` and redirects to the provider URL. It knows nothing about the provider.
+- **API (Next glue):** `POST /api/checkout` — `CommerceBackend.startCheckout`
+  delegates to the active provider (`payments.resolve` by `integrations.payments`).
+- **Shared webhook code:** `lib/checkout/fulfill.ts` → `fulfillOrderFromEvent` —
+  idempotent order creation from a normalized event (used by all provider webhook
+  routes). The critical logic (dedup by `paymentRef`, order snapshot) lives in
+  `@vitrine-kit/core` (`shouldCreateOrder`, `buildOrderFromCart`).
+
+Flow: cart → `Checkout` → `POST /api/checkout` → redirect to the provider →
+provider webhook → `fulfillOrderFromEvent` → order in the admin, cart `converted`.

package/kit/registry/checkout/feature.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout",
+  "title": "Checkout",
+  "kitVersion": "0.4.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "cart"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/checkout/",
+      "to": "components/checkout/"
+    },
+    {
+      "from": "files/lib/checkout/",
+      "to": "lib/checkout/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout": true
+    }
+  },
+  "slots": [
+    {
+      "slot": "cart.summary",
+      "component": "CheckoutButton",
+      "order": 10
+    }
+  ],
+  "claudeDoc": "docs/checkout.md",
+  "conflicts": [],
+  "removable": true
+}

package/kit/registry/checkout/files/app/api/checkout/route.ts

@@ -0,0 +1,14 @@
+// POST /api/checkout — creates a checkout session with the active payment provider for
+// the current cart (cookie) via CommerceBackend.startCheckout and returns the
+// redirect URL. Provider-agnostic: startCheckout delegates to payments.resolve. Next glue.
+import { cookies } from 'next/headers';
+import { NextResponse } from 'next/server';
+import { getCommerceBackend } from '@/lib/adapter';
+
+export async function POST() {
+  const cartId = (await cookies()).get('vitrine_cart')?.value;
+  if (!cartId) return NextResponse.json({ error: 'cart is empty' }, { status: 400 });
+  const commerce = await getCommerceBackend();
+  const { redirectUrl } = await commerce.startCheckout(cartId);
+  return NextResponse.json({ url: redirectUrl });
+}

package/kit/registry/checkout/files/components/checkout/CheckoutButton.tsx

@@ -0,0 +1,31 @@
+// Checkout button — client component. Mounted into the cart.summary slot.
+// POST /api/checkout creates a payment session with the active provider and returns the
+// redirect URL — the component doesn't know which provider is configured (Stripe/Paddle/YooKassa).
+'use client';
+import { useState } from 'react';
+
+export function CheckoutButton() {
+  const [pending, setPending] = useState(false);
+
+  async function checkout(): Promise<void> {
+    setPending(true);
+    try {
+      const res = await fetch('/api/checkout', { method: 'POST' });
+      const data = (await res.json()) as { url?: string; error?: string };
+      if (data.url) location.assign(data.url);
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={checkout}
+      disabled={pending}
+      className="vt-checkout-button rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+    >
+      {pending ? 'Redirecting to payment…' : 'Checkout'}
+    </button>
+  );
+}

package/kit/registry/checkout/files/lib/checkout/fulfill.ts

@@ -0,0 +1,72 @@
+// Idempotent order creation from a normalized payment event — shared code
+// for all webhook routes (checkout-stripe/paddle/yookassa). The provider has already
+// verified and normalized the event; here it's only Payload persistence.
+// The critical logic (dedup, order snapshot) lives in @vitrine-kit/core (shouldCreateOrder,
+// buildOrderFromCart). Next/Payload glue, not typechecked in the monorepo.
+import { getPayload } from 'payload';
+import config from '@payload-config';
+import type { Cart } from '@vitrine-kit/contracts';
+import {
+  buildOrderFromCart,
+  shouldCreateOrder,
+  type NormalizedPaymentEvent,
+  type PaymentProviderName,
+} from '@vitrine-kit/core';
+
+/** Creates an order from the cart on a payment event and marks the cart converted. */
+export async function fulfillOrderFromEvent(
+  event: NormalizedPaymentEvent,
+  providerName: PaymentProviderName,
+): Promise<void> {
+  if (event.kind !== 'checkout_completed') return;
+  const cartId = event.cartId;
+  if (!cartId) return;
+
+  const payload = await getPayload({ config });
+  const cartDoc = await payload.findByID({ collection: 'carts', id: cartId }).catch(() => null);
+  if (!cartDoc) return;
+
+  // Idempotency: the provider retries the webhook — don't create the order twice
+  // (the cart is already converted, or an order with this payment reference already exists).
+  const prior = event.providerRef
+    ? await payload
+        .find({ collection: 'orders', where: { paymentRef: { equals: event.providerRef } }, limit: 1 })
+        .catch(() => ({ docs: [] as Array<{ paymentRef?: string }> }))
+    : { docs: [] as Array<{ paymentRef?: string }> };
+  const consumable = shouldCreateOrder({
+    cartStatus: (cartDoc as { status?: string }).status,
+    providerRef: event.providerRef,
+    existingOrderRefs: (prior.docs as Array<{ paymentRef?: string }>).map((d) => d.paymentRef),
+  });
+  if (!consumable) return;
+
+  const cart: Cart = {
+    id: String(cartDoc.id),
+    lines: (cartDoc.lines as Cart['lines']) ?? [],
+    currency: (cartDoc.currency as string) ?? 'USD',
+    subtotal: (cartDoc.subtotal as number) ?? 0,
+    discountTotal: cartDoc.discountTotal as number | undefined,
+    total: (cartDoc.total as number) ?? 0,
+  };
+  const order = buildOrderFromCart(cart, { id: cartId, email: event.email });
+
+  await payload.create({
+    collection: 'orders',
+    data: {
+      status: order.status,
+      email: order.email,
+      currency: order.currency,
+      subtotal: order.subtotal,
+      total: order.total,
+      lines: order.lines,
+      createdAt: order.createdAt,
+      paymentProvider: providerName,
+      paymentRef: event.providerRef,
+    },
+  });
+  await payload.update({
+    collection: 'carts',
+    id: cartId,
+    data: { status: 'converted', paymentRef: event.providerRef },
+  });
+}

package/kit/registry/checkout/files/lib/checkout/register.ts

@@ -0,0 +1,8 @@
+// Registers the checkout feature's slots. The checkout button goes in the cart totals.
+// The payment provider is registered separately — in the checkout-<provider> feature.
+import { registerSlot } from '@vitrine-kit/core';
+import { CheckoutButton } from '../../components/checkout/CheckoutButton.js';
+
+export function registerCheckoutSlots(): void {
+  registerSlot({ slot: 'cart.summary', component: CheckoutButton, order: 10 });
+}

package/kit/registry/checkout-paddle/docs/checkout-paddle.md

@@ -0,0 +1,22 @@
+# Feature: checkout-paddle (Paddle payment provider)
+
+A Paddle Billing provider for the `checkout` scaffold (which it depends on). Installed instead of
+`checkout-stripe` / `checkout-yookassa` (mutually exclusive). Paddle is a Merchant of
+Record: it handles taxes/VAT. The critical logic (webhook dispatcher, order from cart) lives
+in `@vitrine-kit/core`.
+
+- **Provider:** `lib/checkout-paddle/provider.ts` → `paddleProvider`
+  (`PaymentProvider`): `createCheckout` creates a Paddle transaction with non-catalog
+  line items (prices from the cart, `customData.cartId`); `verifyWebhook` verifies the
+  `Paddle-Signature` via `@paddle/paddle-node-sdk`.
+- **Registration:** `registerCheckoutPaddleProvider()` (from `lib/payments.ts`), sets
+  `integrations.payments: "paddle"`.
+- **API (Next glue):** `POST /api/webhooks/paddle` → `handlePaymentWebhook` →
+  `fulfillOrderFromEvent` (on `transaction.completed`/`transaction.paid`).
+- **env:** `PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET` (required);
+  `PADDLE_ENVIRONMENT` (`sandbox`|`production`, default `sandbox`),
+  `PADDLE_CHECKOUT_URL` (override the hosted checkout, otherwise a default payment link
+  in the Paddle dashboard is required) — optional.
+
+Paddle expects amounts as a string in the currency's minor units — this matches `Money`,
+so we pass `String(unitPrice)` as-is.