@vitrine-kit/vitrine 0.3.1 → 0.4.1

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

@@ -0,0 +1,46 @@
+// 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);
+  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().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>
+      {error ? (
+        <p role="alert" className="vt-checkout-error text-danger">
+          {error}
+        </p>
+      ) : null}
+    </>
+  );
+}

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,25 @@
+# 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`. 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 — 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.
+
+Paddle expects amounts as a string in the currency's minor units — this matches `Money`,
+so we pass `String(unitPrice)` as-is.

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

@@ -0,0 +1,62 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout-paddle",
+  "title": "Payment — Paddle",
+  "kitVersion": "0.4.1",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [
+    "@paddle/paddle-node-sdk@^2.0.0"
+  ],
+  "files": [
+    {
+      "from": "files/lib/checkout-paddle/",
+      "to": "lib/checkout-paddle/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout-paddle": true
+    }
+  },
+  "payment": {
+    "provider": "paddle"
+  },
+  "env": [
+    {
+      "key": "PADDLE_API_KEY",
+      "required": true
+    },
+    {
+      "key": "PADDLE_WEBHOOK_SECRET",
+      "required": true
+    },
+    {
+      "key": "PADDLE_ENVIRONMENT",
+      "required": false
+    },
+    {
+      "key": "PADDLE_CHECKOUT_URL",
+      "required": false
+    }
+  ],
+  "claudeDoc": "docs/checkout-paddle.md",
+  "conflicts": [
+    "checkout-stripe",
+    "checkout-yookassa"
+  ],
+  "removable": true
+}

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

@@ -0,0 +1,22 @@
+// Paddle webhook: paddleProvider.verifyWebhook (Paddle-Signature) →
+// normalized event → handlePaymentWebhook → the shared fulfillOrderFromEvent.
+import { NextResponse } from 'next/server';
+import { handlePaymentWebhook } from '@vitrine-kit/core';
+import { paddleProvider } from '@/lib/checkout-paddle/provider';
+import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const headers = { 'paddle-signature': req.headers.get('paddle-signature') };
+
+  try {
+    const result = await handlePaymentWebhook({
+      provider: paddleProvider,
+      req: { rawBody, headers },
+      handlers: { onCheckoutCompleted: (event) => fulfillOrderFromEvent(event, 'paddle') },
+    });
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+  }
+}

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

@@ -0,0 +1,80 @@
+// PaymentProvider over Paddle Billing. The SDK lives here (in the feature), not in the core.
+// createCheckout creates a transaction with non-catalog line items (prices set on the fly
+// from the cart) and custom_data.cartId → returns the hosted checkout URL. verifyWebhook
+// verifies the Paddle-Signature (HMAC) and normalizes the event.
+//
+// Paddle expects amounts as a string in the currency's minor units (like our Money), so
+// we pass String(unitPrice) as-is. For hosted checkout, the Paddle dashboard needs a
+// default payment link OR set PADDLE_CHECKOUT_URL (override).
+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(requiredEnv('PADDLE_API_KEY'), {
+    environment:
+      process.env.PADDLE_ENVIRONMENT === 'production' ? Environment.production : Environment.sandbox,
+  });
+}
+
+export const paddleProvider: PaymentProvider = {
+  name: 'paddle',
+
+  async createCheckout(args: CreateCheckoutArgs): Promise<{ redirectUrl: string }> {
+    const { cart, baseUrl, cancelPath = '/cart' } = args;
+    const paddle = client();
+    const txn = await paddle.transactions.create({
+      items: cart.lines.map((l) => ({
+        quantity: l.quantity,
+        price: {
+          description: l.title,
+          name: l.title,
+          unitPrice: { amount: String(l.unitPrice), currencyCode: cart.currency },
+          product: { name: l.title, taxCategory: 'standard' },
+        },
+      })),
+      customData: { cartId: cart.id },
+      ...(process.env.PADDLE_CHECKOUT_URL ? { checkout: { url: process.env.PADDLE_CHECKOUT_URL } } : {}),
+    });
+    return { redirectUrl: txn.checkout?.url ?? `${baseUrl}${cancelPath}` };
+  },
+
+  async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
+    const paddle = client();
+    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;
+        customerId?: string | null;
+      };
+      const cartId = (data.customData ?? undefined)?.cartId;
+      // 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 };
+    }
+    return { kind: 'unknown', raw: event };
+  },
+};

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

@@ -0,0 +1,7 @@
+// Registers the Paddle payment provider. The CLI calls this from lib/payments.ts.
+import { payments } from '@vitrine-kit/core';
+import { paddleProvider } from './provider.js';
+
+export function registerCheckoutPaddleProvider(): void {
+  payments.register(paddleProvider);
+}

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

@@ -0,0 +1,19 @@
+# Feature: checkout-stripe (Stripe payment provider)
+
+A Stripe Hosted Checkout provider for the `checkout` scaffold (which it depends on). Installed
+instead of `checkout-paddle` / `checkout-yookassa` (mutually exclusive). The critical
+logic (webhook dispatcher, order from cart) lives in `@vitrine-kit/core`.
+
+- **Provider:** `lib/checkout-stripe/provider.ts` → `stripeProvider`
+  (`PaymentProvider`): `createCheckout` creates a Stripe session; `verifyWebhook`
+  verifies the signature via the Stripe SDK and normalizes the event.
+- **Registration:** `registerCheckoutStripeProvider()` (called from `lib/payments.ts`),
+  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). 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

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout-stripe",
+  "title": "Payment — Stripe",
+  "kitVersion": "0.4.1",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [
+    "stripe@^17.0.0"
+  ],
+  "files": [
+    {
+      "from": "files/lib/checkout-stripe/",
+      "to": "lib/checkout-stripe/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout-stripe": true
+    }
+  },
+  "payment": {
+    "provider": "stripe"
+  },
+  "env": [
+    {
+      "key": "STRIPE_SECRET_KEY",
+      "required": true
+    },
+    {
+      "key": "STRIPE_WEBHOOK_SECRET",
+      "required": true
+    }
+  ],
+  "claudeDoc": "docs/checkout-stripe.md",
+  "conflicts": [
+    "checkout-paddle",
+    "checkout-yookassa"
+  ],
+  "removable": true
+}

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

@@ -0,0 +1,23 @@
+// Stripe webhook: stripeProvider.verifyWebhook (Stripe SDK signature) → normalized
+// 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 { stripeProvider } from '@/lib/checkout-stripe/provider';
+import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const headers = { 'stripe-signature': req.headers.get('stripe-signature') };
+
+  try {
+    const result = await handlePaymentWebhook({
+      provider: stripeProvider,
+      req: { rawBody, headers },
+      handlers: { onCheckoutCompleted: (event) => fulfillOrderFromEvent(event, 'stripe') },
+    });
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+  }
+}

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

@@ -0,0 +1,80 @@
+// PaymentProvider over Stripe Hosted Checkout. The Stripe SDK lives here (in the feature),
+// not in the core: createCheckout creates a session, verifyWebhook verifies the signature and
+// normalizes the event into a NormalizedPaymentEvent. Mapping the cart into Stripe line items
+// (price_data — dynamic prices, unit_amount in minor units) also lives here.
+import type { Cart } from '@vitrine-kit/contracts';
+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;
+}
+
+interface StripeLineItem {
+  quantity: number;
+  price_data: { currency: string; unit_amount: number; product_data: { name: string } };
+}
+
+function cartToStripeLineItems(cart: Cart): StripeLineItem[] {
+  return cart.lines.map((l) => ({
+    quantity: l.quantity,
+    price_data: {
+      currency: cart.currency.toLowerCase(),
+      unit_amount: l.unitPrice,
+      product_data: { name: l.title },
+    },
+  }));
+}
+
+export const stripeProvider: PaymentProvider = {
+  name: 'stripe',
+
+  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(requiredEnv('STRIPE_SECRET_KEY'));
+    const session = await stripe.checkout.sessions.create({
+      mode: 'payment',
+      line_items: cartToStripeLineItems(cart),
+      success_url: `${baseUrl}${successPath}?session_id={CHECKOUT_SESSION_ID}`,
+      cancel_url: `${baseUrl}${cancelPath}`,
+      metadata: { cartId: cart.id },
+    });
+    return { redirectUrl: session.url ?? `${baseUrl}${cancelPath}` };
+  },
+
+  async verifyWebhook(req: PaymentWebhookRequest): Promise<NormalizedPaymentEvent> {
+    const { default: Stripe } = await import('stripe');
+    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);
+
+    if (event.type === 'checkout.session.completed') {
+      const session = event.data.object as {
+        id?: string;
+        metadata?: { cartId?: string };
+        customer_details?: { email?: string };
+      };
+      return {
+        kind: 'checkout_completed',
+        cartId: session.metadata?.cartId,
+        providerRef: session.id,
+        email: session.customer_details?.email,
+        raw: event,
+      };
+    }
+    if (event.type === 'payment_intent.payment_failed') {
+      return { kind: 'payment_failed', raw: event };
+    }
+    return { kind: 'unknown', raw: event };
+  },
+};

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

@@ -0,0 +1,7 @@
+// Registers the Stripe payment provider. The CLI calls this from lib/payments.ts.
+import { payments } from '@vitrine-kit/core';
+import { stripeProvider } from './provider.js';
+
+export function registerCheckoutStripeProvider(): void {
+  payments.register(stripeProvider);
+}

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

@@ -0,0 +1,23 @@
+# Feature: checkout-yookassa (YooKassa payment provider)
+
+A YooKassa (yookassa.ru) provider — Russian acquiring: cards, SBP, wallets. For the
+`checkout` scaffold (which it depends on). Installed instead of `checkout-stripe` / `checkout-paddle`
+(mutually exclusive). No SDK needed — REST `/v3/payments` + Basic auth.
+
+- **Provider:** `lib/checkout-yookassa/provider.ts` → `yookassaProvider`
+  (`PaymentProvider`): `createCheckout` creates a payment (`confirmation.redirect`) →
+  `confirmation_url`; `verifyWebhook` confirms the payment with a follow-up request to the API.
+- **Registration:** `registerCheckoutYookassaProvider()` (from `lib/payments.ts`),
+  sets `integrations.payments: "yookassa"`.
+- **API (Next glue):** `POST /api/webhooks/yookassa` → `handlePaymentWebhook` →
+  `fulfillOrderFromEvent`.
+- **env:** `YOOKASSA_SHOP_ID`, `YOOKASSA_SECRET_KEY` (required — read at call time, a
+  missing key throws `[vitrine] <KEY> is not set …`; webhook route → 400).
+
+**Security:** YooKassa notifications are **not signed** — the provider re-verifies the
+payment via `GET /v3/payments/{id}` and trusts only `status: "succeeded"`. A 404 on that
+check (forged/foreign payment id) is acked as `kind: "unknown"`; other API failures throw,
+so the non-200 response makes YooKassa redeliver the notification.
+
+**Money:** YooKassa expects a decimal string (`"1990.00"`); `Money` is in minor
+units, so we divide by 100 (RUB and most currencies have 2 decimal places).

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

@@ -0,0 +1,52 @@
+{
+  "$schema": "../../schemas/feature.schema.json",
+  "name": "checkout-yookassa",
+  "title": "Payment — YooKassa",
+  "kitVersion": "0.4.1",
+  "requiresContracts": ">=1.0.0 <2.0.0",
+  "tier": [
+    "simple-store",
+    "full-store"
+  ],
+  "registryDependencies": [
+    "checkout"
+  ],
+  "corePackages": {
+    "@vitrine-kit/core": ">=0.1.0"
+  },
+  "npm": [],
+  "files": [
+    {
+      "from": "files/lib/checkout-yookassa/",
+      "to": "lib/checkout-yookassa/"
+    },
+    {
+      "from": "files/app/",
+      "to": "app/"
+    }
+  ],
+  "config": {
+    "set": {
+      "features.checkout-yookassa": true
+    }
+  },
+  "payment": {
+    "provider": "yookassa"
+  },
+  "env": [
+    {
+      "key": "YOOKASSA_SHOP_ID",
+      "required": true
+    },
+    {
+      "key": "YOOKASSA_SECRET_KEY",
+      "required": true
+    }
+  ],
+  "claudeDoc": "docs/checkout-yookassa.md",
+  "conflicts": [
+    "checkout-stripe",
+    "checkout-paddle"
+  ],
+  "removable": true
+}

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

@@ -0,0 +1,22 @@
+// YooKassa webhook: the notification is unsigned — yookassaProvider.verifyWebhook
+// 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 { yookassaProvider } from '@/lib/checkout-yookassa/provider';
+import { fulfillOrderFromEvent } from '@/lib/checkout/fulfill';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+
+  try {
+    const result = await handlePaymentWebhook({
+      provider: yookassaProvider,
+      req: { rawBody, headers: {} },
+      handlers: { onCheckoutCompleted: (event) => fulfillOrderFromEvent(event, 'yookassa') },
+    });
+    return NextResponse.json(result);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 400 });
+  }
+}