@vitrine-kit/vitrine 0.4.1 → 0.5.0

package/kit/registry/checkout/files/app/(frontend)/order/success/page.tsx

@@ -0,0 +1,49 @@
+// Post-payment landing page. Stripe/Paddle/YooKassa redirect here after a successful
+// hosted checkout (successPath default: /order/success). Order fulfillment happens
+// asynchronously via the provider webhook — this page is confirmation UX only.
+import type { Metadata } from 'next';
+import { cookies } from 'next/headers';
+import { Slot } from '@vitrine-kit/core/react';
+import { siteName } from '@/lib/site';
+import { t } from '@/lib/i18n/dictionary';
+
+export const metadata: Metadata = {
+  title: 'Order confirmed',
+};
+
+interface PageProps {
+  searchParams: Promise<{ session_id?: string }>;
+}
+
+export default async function OrderSuccessPage({ searchParams }: PageProps) {
+  const params = await searchParams;
+  const sessionId = params.session_id;
+  const locale = (await cookies()).get('vitrine_locale')?.value ?? 'en';
+
+  return (
+    <div className="vt-order-success flex flex-col gap-section">
+      <Slot name="order.top" />
+      <section aria-labelledby="order-success-heading" className="flex flex-col gap-gutter">
+        <h1 id="order-success-heading" className="font-heading text-3xl text-fg">
+          {t('thankYou', locale)}
+        </h1>
+        <p className="max-w-prose text-muted-fg">
+          Your payment was received. {siteName} will email a confirmation when the order is
+          recorded{sessionId ? ' (this can take a few seconds while the payment webhook runs)' : ''}.
+        </p>
+        {sessionId ? (
+          <p className="text-sm text-muted-fg">
+            Reference: <span className="font-mono text-fg">{sessionId}</span>
+          </p>
+        ) : null}
+        <a
+          href="/"
+          className="w-fit rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          {t('continueShopping', locale)}
+        </a>
+      </section>
+      <Slot name="order.below" />
+    </div>
+  );
+}

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

@@ -3,12 +3,33 @@
 // 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 };
+
+function publicError(error: unknown): string {
+  if (!(error instanceof Error)) return 'Checkout is unavailable — try again later.';
+  return error.message.replace(/^\[vitrine\]\s*/, '');
+}
+
+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();
-  const { redirectUrl } = await commerce.startCheckout(cartId);
-  return NextResponse.json({ url: redirectUrl });
+  try {
+    const commerce = await getCommerceBackend();
+    const { redirectUrl } = await commerce.startCheckout(cartId);
+    return NextResponse.json({ url: redirectUrl });
+  } catch (error) {
+    const message = publicError(error);
+    const status = /is not set|empty/i.test(message) ? 503 : 500;
+    return NextResponse.json({ error: message }, { status });
+  }
 }

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

@@ -3,12 +3,14 @@
 // redirect URL — the component doesn't know which provider is configured (Stripe/Paddle/YooKassa).
 'use client';
 import { useState } from 'react';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
 
 export function CheckoutButton() {
   const [pending, setPending] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const checkout = useChromeLabel('checkout');
 
-  async function checkout(): Promise<void> {
+  async function startCheckout(): Promise<void> {
     setPending(true);
     setError(null);
     try {
@@ -30,11 +32,11 @@ export function CheckoutButton() {
     <>
       <button
         type="button"
-        onClick={checkout}
+        onClick={startCheckout}
         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'}
+        {pending ? 'Redirecting to payment…' : checkout}
       </button>
       {error ? (
         <p role="alert" className="vt-checkout-error text-danger">

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

@@ -12,6 +12,7 @@ import {
   type NormalizedPaymentEvent,
   type PaymentProviderName,
 } from '@vitrine-kit/core';
+import { notifyOrderConfirmation } from './notify.js';
 
 /** Creates an order from the cart on a payment event and marks the cart converted. */
 export async function fulfillOrderFromEvent(
@@ -50,6 +51,22 @@ export async function fulfillOrderFromEvent(
   };
   const order = buildOrderFromCart(cart, { id: cartId, email: event.email });
 
+  // When the accounts feature is installed, attach the matching customer by checkout email.
+  let customerId: string | undefined;
+  const email = event.email?.trim().toLowerCase();
+  if (email) {
+    const customers = await payload
+      .find({
+        collection: 'customers',
+        where: { email: { equals: email } },
+        limit: 1,
+        overrideAccess: true,
+      })
+      .catch(() => null);
+    const doc = customers?.docs[0];
+    if (doc) customerId = String(doc.id);
+  }
+
   await payload.create({
     collection: 'orders',
     data: {
@@ -62,6 +79,7 @@ export async function fulfillOrderFromEvent(
       createdAt: order.createdAt,
       paymentProvider: providerName,
       paymentRef: event.providerRef,
+      ...(customerId ? { customer: customerId } : {}),
     },
   });
   await payload.update({
@@ -69,4 +87,8 @@ export async function fulfillOrderFromEvent(
     id: cartId,
     data: { status: 'converted', paymentRef: event.providerRef },
   });
+
+  await notifyOrderConfirmation(order).catch((err) => {
+    console.warn('[vitrine] order confirmation notify failed', err);
+  });
 }

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

@@ -0,0 +1,52 @@
+// Order confirmation email. Uses Payload sendEmail when the email feature + SMTP
+// are configured; otherwise logs to the console (zero-config).
+import type { Order } from '@vitrine-kit/contracts';
+import { siteConfig } from '@/site.config';
+import { siteName } from '@/lib/site';
+
+export async function notifyOrderConfirmation(order: Order): Promise<void> {
+  const to = order.email?.trim();
+  if (!to) return;
+
+  const provider = siteConfig.integrations.email;
+  const subject = `Order confirmation — ${siteName}`;
+  const body = [
+    `Thanks for your order at ${siteName}.`,
+    ``,
+    `Order total: ${(order.total / 100).toFixed(2)} ${order.currency}`,
+    `Status: ${order.status}`,
+    `Lines: ${order.lines.map((l) => `${l.quantity}× ${l.title}`).join(', ')}`,
+  ].join('\n');
+
+  let from: string | undefined;
+  try {
+    const emailMod = await import('../email/adapter.js');
+    from = emailMod.emailFromAddress();
+  } catch {
+    // email feature not installed
+  }
+
+  if (provider || from) {
+    try {
+      const { getPayload } = await import('payload');
+      const config = (await import('@payload-config')).default;
+      const payload = await getPayload({ config });
+      await payload.sendEmail({
+        to,
+        from: from ?? undefined,
+        subject,
+        text: body,
+      });
+      return;
+    } catch (error) {
+      console.warn(
+        '[vitrine] payload.sendEmail failed — falling back to console log',
+        error instanceof Error ? error.message : error,
+      );
+    }
+  }
+
+  console.info(
+    `[vitrine] order email${provider ? ` via "${provider}"` : ''}${from ? ` from ${from}` : ''} → ${to}\n${subject}\n${body}`,
+  );
+}

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.1",
+  "kitVersion": "0.5.0",
   "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-stripe/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-stripe",
   "title": "Payment — Stripe",
-  "kitVersion": "0.4.1",
+  "kitVersion": "0.5.0",
   "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-yookassa/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout-yookassa",
   "title": "Payment — YooKassa",
-  "kitVersion": "0.4.1",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

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

@@ -2,11 +2,16 @@
 // re-checks the payment via the API (we trust only succeeded) → 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 { yookassaProvider } from '@/lib/checkout-yookassa/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:yookassa:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
+  if (!allowed) return NextResponse.json({ error: 'too many requests' }, { status: 429 });
+
   const rawBody = await req.text();
 
   try {
@@ -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. re-confirmation failure detail) to the caller.
+    console.error('[vitrine] yookassa webhook error:', err);
+    return NextResponse.json({ error: 'invalid webhook' }, { status: 400 });
   }
 }

package/kit/registry/email/docs/email.md

@@ -0,0 +1,19 @@
+# Feature: email
+
+Wires Payload's email transport for order confirmations and auth mail.
+
+## Modules
+- `lib/email/adapter.ts` — `resolveEmailAdapter()` builds `@payloadcms/email-nodemailer`
+  from `SMTP_*` / `EMAIL_FROM`, or a **console adapter** when `EMAIL_FROM` is set without
+  `SMTP_HOST` (reset links and order mail print to the terminal / `docker compose logs`)
+- `payload.config` (template) awaits the adapter when the file is present
+- Checkout `notifyOrderConfirmation` calls `payload.sendEmail` when an adapter is configured
+
+## Setup
+1. `vitrine add email` (installs `@payloadcms/email-nodemailer` + `nodemailer`)
+2. Set `EMAIL_FROM` (required for any adapter). Optionally `SMTP_HOST` / `SMTP_PORT` /
+   `SMTP_USER` / `SMTP_PASS` / `EMAIL_FROM_NAME` for real delivery
+3. `integrations.email` is set to `"smtp"` by the feature config
+
+Without `SMTP_HOST`, zero-config still works — messages (including password-reset links)
+are logged to the console via the console adapter.

package/kit/registry/email/feature.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "email",
+  "title": "Transactional email",
+  "kitVersion": "0.5.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {},
+  "npm": [
+    "@payloadcms/email-nodemailer@^3.0.0",
+    "nodemailer@^6.9.0"
+  ],
+  "files": [
+    {
+      "from": "files/lib/email/",
+      "to": "lib/email/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.email": true
+    }
+  },
+  "slots": [],
+  "env": [
+    {
+      "key": "EMAIL_FROM",
+      "required": false
+    },
+    {
+      "key": "EMAIL_FROM_NAME",
+      "required": false
+    },
+    {
+      "key": "SMTP_HOST",
+      "required": false
+    },
+    {
+      "key": "SMTP_PORT",
+      "required": false
+    },
+    {
+      "key": "SMTP_USER",
+      "required": false
+    },
+    {
+      "key": "SMTP_PASS",
+      "required": false
+    }
+  ],
+  "claudeDoc": "docs/email.md",
+  "conflicts": [],
+  "removable": true
+}

package/kit/registry/email/files/lib/email/adapter.ts

@@ -0,0 +1,89 @@
+// Avoid importing `payload` types here — registry typecheck has no Payload deps.
+export type VitrineEmailAdapter = {
+  name: string;
+  defaultFromAddress: string;
+  defaultFromName: string;
+  sendEmail: (message: unknown) => Promise<unknown>;
+};
+
+type EmailMessage = {
+  to?: string | string[];
+  subject?: string;
+  html?: string;
+  text?: string;
+};
+
+export function emailFromAddress(): string | undefined {
+  return process.env.EMAIL_FROM?.trim() || undefined;
+}
+
+export function emailFromName(): string {
+  return process.env.EMAIL_FROM_NAME?.trim() || 'Store';
+}
+
+/** Dev/zero-config adapter: logs the full message (incl. reset links) to the console. */
+function consoleEmailAdapter(from: string): VitrineEmailAdapter {
+  return {
+    name: 'vitrine-console',
+    defaultFromAddress: from,
+    defaultFromName: emailFromName(),
+    async sendEmail(message: unknown) {
+      const msg = (message ?? {}) as EmailMessage;
+      const to = Array.isArray(msg.to) ? msg.to.join(', ') : (msg.to ?? '(unknown)');
+      const body = msg.text || msg.html || '';
+      console.info(
+        [
+          '[vitrine] console email (no SMTP_HOST)',
+          `  from: ${from}`,
+          `  to: ${to}`,
+          `  subject: ${msg.subject ?? '(none)'}`,
+          '  ---',
+          body,
+          '  ---',
+        ].join('\n'),
+      );
+      return { messageId: `console-${Date.now()}` };
+    },
+  };
+}
+
+/**
+ * Resolve Payload's `email` config entry. Dynamic-imports `@payloadcms/email-nodemailer`
+ * when SMTP is configured; otherwise returns a console adapter so auth reset links
+ * and order mail still surface in docker logs / the terminal.
+ */
+export async function resolveEmailAdapter(): Promise<VitrineEmailAdapter | undefined> {
+  const from = emailFromAddress();
+  const host = process.env.SMTP_HOST?.trim();
+  if (!from) return undefined;
+
+  if (!host) {
+    console.info(`[vitrine] EMAIL_FROM=${from} (no SMTP_HOST — console email adapter)`);
+    return consoleEmailAdapter(from);
+  }
+
+  try {
+    const { nodemailerAdapter } = await import('@payloadcms/email-nodemailer');
+    const port = Number(process.env.SMTP_PORT || 587);
+    const user = process.env.SMTP_USER?.trim();
+    const pass = process.env.SMTP_PASS ?? '';
+    console.info(`[vitrine] SMTP email adapter → ${host}:${port} from ${from}`);
+    return nodemailerAdapter({
+      defaultFromAddress: from,
+      defaultFromName: emailFromName(),
+      skipVerify: process.env.NODE_ENV !== 'production',
+      transportOptions: {
+        host,
+        port,
+        secure: port === 465,
+        auth: user ? { user, pass } : undefined,
+      },
+    }) as unknown as VitrineEmailAdapter;
+  } catch (error) {
+    console.warn(
+      '[vitrine] @payloadcms/email-nodemailer not installed — falling back to console email adapter',
+      error instanceof Error ? error.message : error,
+    );
+    return consoleEmailAdapter(from);
+  }
+}

package/kit/registry/filters/docs/filters.md

@@ -0,0 +1,13 @@
+# Feature: filters
+
+Catalog toolbar for sort, option facets, and price range via the `catalog.toolbar` slot.
+
+## Modules
+- `components/filters/CatalogToolbar` — GET form updating `?sort=`, `?size=`, `?color=`,
+  `?priceMin=` / `?priceMax=` (major currency units) on the current listing URL
+- Mounted into `catalog.toolbar` on home and category pages
+
+## Contracts
+- `ProductQuery.sort` (`newest` | `price-asc` | `price-desc` | `relevance`)
+- `ProductQuery.filters` — option facets, e.g. `{ size: ['S'], color: ['Black'] }`
+- `ProductQuery.priceMin` / `priceMax` — inclusive bounds in minor units (cents)

package/kit/registry/filters/feature.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "filters",
+  "title": "Catalog sort, facets, and price filters",
+  "kitVersion": "0.5.0",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "catalog",
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "catalog"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/components/filters/",
+      "to": "components/filters/"
+    },
+    {
+      "from": "files/lib/filters/",
+      "to": "lib/filters/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.filters": true
+    }
+  },
+  "slots": [
+    {
+      "slot": "catalog.toolbar",
+      "component": "CatalogToolbar",
+      "order": 10
+    }
+  ],
+  "env": [],
+  "claudeDoc": "docs/filters.md",
+  "conflicts": [],
+  "removable": true
+}