@vitrine-kit/vitrine 0.4.0 → 0.4.3

package/kit/registry/_index.json

@@ -1,11 +1,11 @@
 {
   "$schema": "../schemas/registry-index.schema.json",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.3",
   "contracts": "1.0.0",
   "features": {
     "catalog": {
       "title": "Product catalog",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "catalog",
         "simple-store",
@@ -14,7 +14,7 @@
     },
     "product-page": {
       "title": "Product page",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "catalog",
         "simple-store",
@@ -23,7 +23,7 @@
     },
     "seo": {
       "title": "SEO — metadata and JSON-LD",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "catalog",
         "simple-store",
@@ -32,7 +32,7 @@
     },
     "cart": {
       "title": "Cart",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -40,7 +40,7 @@
     },
     "checkout": {
       "title": "Checkout",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -48,7 +48,7 @@
     },
     "checkout-stripe": {
       "title": "Payment — Stripe",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -56,7 +56,7 @@
     },
     "checkout-paddle": {
       "title": "Payment — Paddle",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"
@@ -64,7 +64,7 @@
     },
     "checkout-yookassa": {
       "title": "Payment — YooKassa",
-      "kitVersion": "0.4.0",
+      "kitVersion": "0.4.3",
       "tier": [
         "simple-store",
         "full-store"

package/kit/registry/cart/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "cart",
   "title": "Cart",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.3",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

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

@@ -3,10 +3,53 @@
 // 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 { checkRateLimit, clientIpFromHeaders } from '@vitrine-kit/core';
 import type { CommerceBackend } from '@vitrine-kit/contracts';
 import { getCommerceBackend } from '@/lib/adapter';
 
 const COOKIE = 'vitrine_cart';
+const MAX_QUANTITY = 999;
+const RATE_LIMIT = { limit: 30, windowMs: 60_000 };
+
+/** Per-IP rate limit on cart mutations — returns a 429 response, or null if under the limit. */
+function rateLimited(req: Request): NextResponse | null {
+  const { allowed, retryAfterMs } = checkRateLimit(`cart:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (allowed) return null;
+  return NextResponse.json(
+    { error: 'too many requests' },
+    { status: 429, headers: { 'Retry-After': String(Math.ceil((retryAfterMs ?? 0) / 1000)) } },
+  );
+}
+
+function parseQuantity(value: unknown): number | null {
+  const n = typeof value === 'number' ? value : Number(value);
+  return Number.isInteger(n) && n >= 0 && n <= MAX_QUANTITY ? n : null;
+}
+
+function parseAddItemBody(body: unknown): { variantId: string; quantity: number } | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const { variantId, quantity = 1 } = body as { variantId?: unknown; quantity?: unknown };
+  if (typeof variantId !== 'string' || variantId.length === 0) return null;
+  const parsedQuantity = parseQuantity(quantity);
+  if (parsedQuantity === null || parsedQuantity < 1) return null;
+  return { variantId, quantity: parsedQuantity };
+}
+
+function parseUpdateItemBody(body: unknown): { lineId: string; quantity: number } | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const { lineId, quantity } = body as { lineId?: unknown; quantity?: unknown };
+  if (typeof lineId !== 'string' || lineId.length === 0) return null;
+  const parsedQuantity = parseQuantity(quantity);
+  if (parsedQuantity === null) return null;
+  return { lineId, quantity: parsedQuantity };
+}
+
+function parseRemoveItemBody(body: unknown): { lineId: string } | null {
+  if (typeof body !== 'object' || body === null) return null;
+  const { lineId } = body as { lineId?: unknown };
+  if (typeof lineId !== 'string' || lineId.length === 0) return null;
+  return { lineId };
+}
 
 async function ensureCartId(commerce: CommerceBackend): Promise<string> {
   const jar = await cookies();
@@ -18,24 +61,33 @@ async function ensureCartId(commerce: CommerceBackend): Promise<string> {
 }
 
 export async function POST(req: Request) {
-  const { variantId, quantity = 1 } = (await req.json()) as { variantId: string; quantity?: number };
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseAddItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   const commerce = await getCommerceBackend();
   const id = await ensureCartId(commerce);
-  return NextResponse.json(await commerce.addItem(id, variantId, quantity));
+  return NextResponse.json(await commerce.addItem(id, parsed.variantId, parsed.quantity));
 }
 
 export async function PATCH(req: Request) {
-  const { lineId, quantity } = (await req.json()) as { lineId: string; quantity: number };
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseUpdateItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   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));
+  return NextResponse.json(await commerce.updateItem(id, parsed.lineId, parsed.quantity));
 }
 
 export async function DELETE(req: Request) {
-  const { lineId } = (await req.json()) as { lineId: string };
+  const limited = rateLimited(req);
+  if (limited) return limited;
+  const parsed = parseRemoveItemBody(await req.json());
+  if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   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));
+  return NextResponse.json(await commerce.removeItem(id, parsed.lineId));
 }

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

@@ -1,25 +1,76 @@
 // "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).
+// (ProductView passes product). Supports option-based variants from the demo seed
+// (size/color). Mutation goes through POST /api/cart (the feature's route).
 'use client';
-import { useState } from 'react';
-import type { Product } from '@vitrine-kit/contracts';
+import { useMemo, useState } from 'react';
+import type { Product, Variant } from '@vitrine-kit/contracts';
 
 export interface AddToCartProps {
   product: Product;
 }
 
+function optionKeys(variants: Variant[]): string[] {
+  const keys = new Set<string>();
+  for (const v of variants) {
+    for (const key of Object.keys(v.options ?? {})) keys.add(key);
+  }
+  return [...keys];
+}
+
+function valuesFor(variants: Variant[], key: string): string[] {
+  const values = new Set<string>();
+  for (const v of variants) {
+    const value = v.options?.[key];
+    if (value) values.add(value);
+  }
+  return [...values];
+}
+
+function matchVariant(
+  variants: Variant[],
+  selected: Record<string, string>,
+  keys: string[],
+): Variant | undefined {
+  return variants.find((v) => keys.every((key) => (v.options?.[key] ?? '') === (selected[key] ?? '')));
+}
+
+function firstAvailable(variants: Variant[]): Variant | undefined {
+  return variants.find((v) => v.stock == null || v.stock > 0) ?? variants[0];
+}
+
+function variantLabel(variant: Variant): string {
+  const opts = variant.options;
+  if (opts && Object.keys(opts).length > 0) {
+    return Object.entries(opts)
+      .map(([k, v]) => `${k}: ${v}`)
+      .join(', ');
+  }
+  return variant.title ?? variant.sku;
+}
+
 export function AddToCart({ product }: AddToCartProps) {
+  const variants = product.variants;
+  const keys = useMemo(() => optionKeys(variants), [variants]);
   const [pending, setPending] = useState(false);
-  const variantId = product.variants[0]?.id;
+  const [selected, setSelected] = useState<Record<string, string>>(() => ({
+    ...(firstAvailable(variants)?.options ?? {}),
+  }));
+  const [variantId, setVariantId] = useState<string | undefined>(() => firstAvailable(variants)?.id);
+
+  const matched =
+    keys.length > 0 ? matchVariant(variants, selected, keys) : variants.find((v) => v.id === variantId);
+  const active = matched ?? firstAvailable(variants);
+  const activeId = active?.id;
+  const outOfStock = active != null && active.stock != null && active.stock <= 0;
 
   async function add(): Promise<void> {
-    if (!variantId) return;
+    if (!activeId || outOfStock) return;
     setPending(true);
     try {
       await fetch('/api/cart', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ variantId, quantity: 1 }),
+        body: JSON.stringify({ variantId: activeId, quantity: 1 }),
       });
       location.assign('/cart');
     } finally {
@@ -27,14 +78,55 @@ export function AddToCart({ product }: AddToCartProps) {
     }
   }
 
+  if (variants.length === 0) {
+    return <p className="text-muted-fg">This product has no purchasable variants yet.</p>;
+  }
+
   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>
+    <div className="vt-add-to-cart-wrap flex flex-col gap-gutter">
+      {keys.length > 0 ? (
+        keys.map((key) => (
+          <label key={key} className="flex flex-col gap-unit text-sm">
+            <span className="font-medium capitalize text-fg">{key}</span>
+            <select
+              className="rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+              value={selected[key] ?? ''}
+              onChange={(e) => setSelected((prev) => ({ ...prev, [key]: e.target.value }))}
+            >
+              {valuesFor(variants, key).map((value) => (
+                <option key={value} value={value}>
+                  {value}
+                </option>
+              ))}
+            </select>
+          </label>
+        ))
+      ) : variants.length > 1 ? (
+        <label className="flex flex-col gap-unit text-sm">
+          <span className="font-medium text-fg">Option</span>
+          <select
+            className="rounded-md border border-input bg-surface px-gutter py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring"
+            value={activeId ?? ''}
+            onChange={(e) => setVariantId(e.target.value)}
+          >
+            {variants.map((v) => (
+              <option key={v.id} value={v.id} disabled={v.stock != null && v.stock <= 0}>
+                {variantLabel(v)}
+                {v.stock != null && v.stock <= 0 ? ' (out of stock)' : ''}
+              </option>
+            ))}
+          </select>
+        </label>
+      ) : null}
+
+      <button
+        type="button"
+        onClick={add}
+        disabled={pending || !activeId || outOfStock}
+        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…' : outOfStock ? 'Out of stock' : 'Add to cart'}
+      </button>
+    </div>
   );
 }

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

@@ -10,7 +10,25 @@ export interface CartViewProps {
 
 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-empty flex flex-col gap-gutter">
+        <p className="text-muted-fg">Your cart is empty.</p>
+        <p className="text-sm text-muted-fg">
+          Open a product such as{' '}
+          <a href="/products/classic-tee" className="text-fg underline underline-offset-2">
+            Classic T-Shirt
+          </a>
+          , pick a size, then use <span className="text-fg">Add to cart</span> to try the checkout
+          flow.
+        </p>
+        <a
+          href="/"
+          className="w-fit rounded-md border border-border px-gutter py-unit text-fg transition hover:bg-muted focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          Continue shopping
+        </a>
+      </div>
+    );
   }
   return (
     <div className="vt-cart grid gap-section md:grid-cols-[2fr_1fr]">

package/kit/registry/catalog/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "catalog",
   "title": "Product catalog",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.3",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

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

@@ -33,7 +33,11 @@ export function ProductCard({ product }: ProductCardProps) {
         <div className="p-gutter">
           <h3 className="font-heading text-fg">{product.title}</h3>
           {price != null ? (
-            <p className="text-price">{formatPrice(price, currency)}</p>
+            <p className="text-price">
+              {product.priceRange && product.priceRange.min !== product.priceRange.max
+                ? `From ${formatPrice(price, currency)}`
+                : formatPrice(price, currency)}
+            </p>
           ) : null}
         </div>
       </a>

package/kit/registry/checkout/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout",
   "title": "Checkout",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.3",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

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

@@ -3,9 +3,19 @@
 // redirect URL. Provider-agnostic: startCheckout delegates to payments.resolve. Next glue.
 import { cookies } from 'next/headers';
 import { NextResponse } from 'next/server';
+import { checkRateLimit, clientIpFromHeaders } from '@vitrine-kit/core';
 import { getCommerceBackend } from '@/lib/adapter';
 
-export async function POST() {
+const RATE_LIMIT = { limit: 10, windowMs: 60_000 };
+
+export async function POST(req: Request) {
+  const { allowed, retryAfterMs } = checkRateLimit(`checkout:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) {
+    return NextResponse.json(
+      { error: 'too many requests' },
+      { status: 429, headers: { 'Retry-After': String(Math.ceil((retryAfterMs ?? 0) / 1000)) } },
+    );
+  }
   const cartId = (await cookies()).get('vitrine_cart')?.value;
   if (!cartId) return NextResponse.json({ error: 'cart is empty' }, { status: 400 });
   const commerce = await getCommerceBackend();

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

@@ -6,26 +6,41 @@ import { useState } from 'react';
 
 export function CheckoutButton() {
   const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
 
   async function checkout(): Promise<void> {
     setPending(true);
+    setError(null);
     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);
+      const data = (await res.json().catch(() => ({}))) as { url?: string; error?: string };
+      if (!res.ok || !data.url) {
+        setError(data.error ?? 'Checkout is unavailable — try again later.');
+        return;
+      }
+      location.assign(data.url);
+    } catch {
+      setError('Checkout is unavailable — try again later.');
     } 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>
+    <>
+      <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>
+      {error ? (
+        <p role="alert" className="vt-checkout-error text-danger">
+          {error}
+        </p>
+      ) : null}
+    </>
   );
 }

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

@@ -8,12 +8,15 @@ 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`.
+  `Paddle-Signature` via `@paddle/paddle-node-sdk`. The notification carries no email, so
+  the provider does a best-effort `customers.get(customerId)` lookup for the order's
+  `email` — a lookup failure does not fail fulfillment.
 - **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);
+- **env:** `PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET` (required — read at call time, a
+  missing key throws `[vitrine] <KEY> is not set …`; webhook route → 400);
   `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.

package/kit/registry/checkout-paddle/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-paddle",
   "title": "Payment — Paddle",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.3",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-paddle/files/app/api/webhooks/paddle/route.ts

@@ -1,11 +1,16 @@
 // Paddle webhook: paddleProvider.verifyWebhook (Paddle-Signature) →
 // normalized event → handlePaymentWebhook → the shared fulfillOrderFromEvent.
 import { NextResponse } from 'next/server';
-import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { checkRateLimit, clientIpFromHeaders, handlePaymentWebhook } from '@vitrine-kit/core';
 import { paddleProvider } from '@/lib/checkout-paddle/provider';
 import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
 
+const RATE_LIMIT = { limit: 120, windowMs: 60_000 };
+
 export async function POST(req: Request) {
+  const { allowed } = checkRateLimit(`webhook:paddle:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) return NextResponse.json({ error: 'too many requests' }, { status: 429 });
+
   const rawBody = await req.text();
   const headers = { 'paddle-signature': req.headers.get('paddle-signature') };
 
@@ -17,6 +22,8 @@ export async function POST(req: Request) {
     });
     return NextResponse.json(result);
   } catch (err) {
-    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+    // Don't echo provider-specific error text (e.g. signature failure detail) to the caller.
+    console.error('[vitrine] paddle webhook error:', err);
+    return NextResponse.json({ error: 'invalid webhook' }, { status: 400 });
   }
 }

package/kit/registry/checkout-paddle/files/lib/checkout-paddle/provider.ts

@@ -9,8 +9,15 @@
 import { Environment, Paddle, type EventEntity } from '@paddle/paddle-node-sdk';
 import type { CreateCheckoutArgs, NormalizedPaymentEvent, PaymentProvider, PaymentWebhookRequest } from '@vitrine-kit/core';
 
+/** Required env, read at call time — `next build` must not need secrets. */
+function requiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`[vitrine] ${key} is not set — add it to .env (see .env.example)`);
+  return value;
+}
+
 function client(): Paddle {
-  return new Paddle(process.env.PADDLE_API_KEY ?? '', {
+  return new Paddle(requiredEnv('PADDLE_API_KEY'), {
     environment:
       process.env.PADDLE_ENVIRONMENT === 'production' ? Environment.production : Environment.sandbox,
   });
@@ -40,16 +47,30 @@ export const paddleProvider: PaymentProvider = {
 
   async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
     const paddle = client();
-    const secret = process.env.PADDLE_WEBHOOK_SECRET ?? '';
+    const secret = requiredEnv('PADDLE_WEBHOOK_SECRET');
     const signature = req.headers['paddle-signature'] ?? '';
     // Throws on an invalid signature — handlePaymentWebhook returns a 400.
     const event = (await paddle.webhooks.unmarshal(req.rawBody, secret, signature)) as EventEntity | null;
     if (!event) return { kind: 'unknown', raw: req.rawBody };
 
     if (event.eventType === 'transaction.completed' || event.eventType === 'transaction.paid') {
-      const data = event.data as { id?: string; customData?: { cartId?: string } | null };
+      const data = event.data as {
+        id?: string;
+        customData?: { cartId?: string } | null;
+        customerId?: string | null;
+      };
       const cartId = (data.customData ?? undefined)?.cartId;
-      return { kind: 'checkout_completed', cartId, providerRef: data.id, raw: event };
+      // The notification carries no email — best-effort lookup on the Customer entity.
+      // A lookup failure must not fail fulfillment: email is optional on the event.
+      let email: string | undefined;
+      if (data.customerId) {
+        try {
+          email = (await paddle.customers.get(data.customerId)).email ?? undefined;
+        } catch {
+          // keep email undefined — the order is still created
+        }
+      }
+      return { kind: 'checkout_completed', cartId, providerRef: data.id, email, raw: event };
     }
     if (event.eventType === 'transaction.payment_failed') {
       return { kind: 'payment_failed', raw: event };

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

@@ -11,7 +11,9 @@ logic (webhook dispatcher, order from cart) lives in `@vitrine-kit/core`.
   sets `integrations.payments: "stripe"` in `site.config`.
 - **API (Next glue):** `POST /api/webhooks/stripe` → `handlePaymentWebhook` →
   `fulfillOrderFromEvent` (the `checkout` feature's shared code).
-- **env:** `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` (required).
+- **env:** `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` (required). Read at call time
+  (`next build` needs no secrets); a missing key throws `[vitrine] <KEY> is not set …` —
+  in the webhook route this surfaces as a 400, in `POST /api/checkout` as a 500.
 
 Flow: cart → `Checkout` → redirect to Stripe → webhook
 `checkout.session.completed` → order in the admin, cart `converted`.

package/kit/registry/checkout-stripe/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-stripe",
   "title": "Payment — Stripe",
-  "kitVersion": "0.4.0",
+  "kitVersion": "0.4.3",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout-stripe/files/app/api/webhooks/stripe/route.ts

@@ -2,11 +2,16 @@
 // event → handlePaymentWebhook → the shared fulfillOrderFromEvent creates an order from
 // the cart and marks it converted. No provider-specific code here — just glue.
 import { NextResponse } from 'next/server';
-import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { checkRateLimit, clientIpFromHeaders, handlePaymentWebhook } from '@vitrine-kit/core';
 import { stripeProvider } from '@/lib/checkout-stripe/provider';
 import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
 
+const RATE_LIMIT = { limit: 120, windowMs: 60_000 };
+
 export async function POST(req: Request) {
+  const { allowed } = checkRateLimit(`webhook:stripe:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) return NextResponse.json({ error: 'too many requests' }, { status: 429 });
+
   const rawBody = await req.text();
   const headers = { 'stripe-signature': req.headers.get('stripe-signature') };
 
@@ -18,6 +23,8 @@ export async function POST(req: Request) {
     });
     return NextResponse.json(result);
   } catch (err) {
-    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+    // Don't echo provider-specific error text (e.g. signature failure detail) to the caller.
+    console.error('[vitrine] stripe webhook error:', err);
+    return NextResponse.json({ error: 'invalid webhook' }, { status: 400 });
   }
 }

package/kit/registry/checkout-stripe/files/lib/checkout-stripe/provider.ts

@@ -10,6 +10,13 @@ import type {
   PaymentWebhookRequest,
 } from '@vitrine-kit/core';
 
+/** Required env, read at call time — `next build` must not need secrets. */
+function requiredEnv(key: string): string {
+  const value = process.env[key];
+  if (!value) throw new Error(`[vitrine] ${key} is not set — add it to .env (see .env.example)`);
+  return value;
+}
+
 interface StripeLineItem {
   quantity: number;
   price_data: { currency: string; unit_amount: number; product_data: { name: string } };
@@ -32,7 +39,7 @@ export const stripeProvider: PaymentProvider = {
   async createCheckout(args: CreateCheckoutArgs): Promise<{ redirectUrl: string }> {
     const { cart, baseUrl, successPath = '/order/success', cancelPath = '/cart' } = args;
     const { default: Stripe } = await import('stripe');
-    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? '');
+    const stripe = new Stripe(requiredEnv('STRIPE_SECRET_KEY'));
     const session = await stripe.checkout.sessions.create({
       mode: 'payment',
       line_items: cartToStripeLineItems(cart),
@@ -45,8 +52,8 @@ export const stripeProvider: PaymentProvider = {
 
   async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
     const { default: Stripe } = await import('stripe');
-    const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? '');
-    const secret = process.env.STRIPE_WEBHOOK_SECRET ?? '';
+    const stripe = new Stripe(requiredEnv('STRIPE_SECRET_KEY'));
+    const secret = requiredEnv('STRIPE_WEBHOOK_SECRET');
     const signature = req.headers['stripe-signature'] ?? '';
     // Throws on an invalid signature — handlePaymentWebhook surfaces it as a 400.
     const event = stripe.webhooks.constructEvent(req.rawBody, signature, secret);