includio-cms 0.24.0 → 0.24.1

package/API.md

@@ -1,8 +1,8 @@
-# includio-cms — Public API v0.24.0
+# includio-cms — Public API v0.24.1
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
-Entry points: **15** · Stable: **346** · Experimental: **2**
+Entry points: **15** · Stable: **369** · Experimental: **2**
 
 Tags:
 - `@public` — frozen for v1.0; semver-protected.
@@ -150,6 +150,9 @@ Tags:
 - `const ShippingMethodEditPage: LegacyComponentType`
 - `const ShippingMethodNewPage: LegacyComponentType`
 - `const ShippingMethodsListPage: LegacyComponentType`
+- `const ShopCouponEditPage: LegacyComponentType`
+- `const ShopCouponNewPage: LegacyComponentType`
+- `const ShopCouponsListPage: LegacyComponentType`
 - `const ShopOrderDetailPage: LegacyComponentType`
 - `const ShopOrdersListPage: LegacyComponentType`
 - `const ShopProductsListPage: LegacyComponentType`
@@ -167,10 +170,12 @@ Tags:
 - `const bulkSetMediaFileTags: <inferred>`
 - `const cancelShipmentForOrderCmd: <inferred>`
 - `const countMediaFiles: <inferred>`
+- `const createCouponCmd: <inferred>`
 - `const createEntry: <inferred>`
 - `const createMediaTag: <inferred>`
 - `const createShipmentForOrderCmd: <inferred>`
 - `const createShippingMethodCmd: <inferred>`
+- `const deleteCouponCmd: <inferred>`
 - `const deleteEntryCommand: <inferred>`
 - `const deleteFormSubmission: <inferred>`
 - `const deleteFormSubmissions: <inferred>`
@@ -179,11 +184,13 @@ Tags:
 - `const deleteShippingMethodCmd: <inferred>`
 - `const deleteShopDataForEntry: <inferred>`
 - `const exportFormSubmissions: <inferred>`
+- `const exportOrdersCsv: <inferred>`
 - `const findMediaReferences: <inferred>`
 - `const generateAltText: <inferred>`
 - `const getAltOverview: <inferred>`
 - `const getCollection: <inferred>`
 - `const getCollections: <inferred>`
+- `const getCouponAdmin: <inferred>`
 - `const getEmailConfigured: <inferred>`
 - `const getEntries: <inferred>`
 - `const getEntry: <inferred>`
@@ -201,6 +208,7 @@ Tags:
 - `const getMediaTags: <inferred>`
 - `const getMediaTagsWithCounts: <inferred>`
 - `const getOrderForAdmin: <inferred>`
+- `const getOrderRefundsAdmin: <inferred>`
 - `const getRawEntries: <inferred>`
 - `const getRawEntry: <inferred>`
 - `const getRecentActivity: <inferred>`
@@ -213,11 +221,13 @@ Tags:
 - `const getSingles: <inferred>`
 - `const getSubmissionsOverview: <inferred>`
 - `const isAIAvailable: <inferred>`
+- `const listCouponsAdmin: <inferred>`
 - `const listOrdersAdmin: <inferred>`
 - `const listShippingMethodsAdmin: <inferred>`
 - `const listShopableCollections: <inferred>`
 - `const listShopProductEntries: <inferred>`
 - `const populatePreviewData: <inferred>`
+- `const refundOrderCmd: <inferred>`
 - `const regenerateVideoPoster: <inferred>`
 - `const renameMediaFile: <inferred>`
 - `const reorderEntriesCommand: <inferred>`
@@ -227,6 +237,7 @@ Tags:
 - `const setMediaFileAlt: <inferred>`
 - `const setMediaFileTags: <inferred>`
 - `const unarchiveEntryCommand: <inferred>`
+- `const updateCouponCmd: <inferred>`
 - `const updateEntryCommand: <inferred>`
 - `const updateEntryVersionCommand: <inferred>`
 - `const updateFormSubmission: <inferred>`
@@ -305,6 +316,9 @@ Tags:
 - `const sessionRelations: <inferred>`
 - `interface ShippingCarrierConfig`
 - `type ShopCarrierType = 'none' | 'inpost' | string`
+- `const shopCouponRedemptionsTable: <inferred>`
+- `const shopCouponsTable: <inferred>`
+- `type ShopCouponType = 'percent' | 'fixed'`
 - `const shopOrderItemsTable: <inferred>`
 - `const shopOrdersTable: <inferred>`
 - `const shopOrderStatusHistoryTable: <inferred>`
@@ -312,8 +326,11 @@ Tags:
 - `type ShopPaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded' | 'cancelled'`
 - `const shopProductsTable: <inferred>`
 - `const shopProductVariantsTable: <inferred>`
+- `const shopRefundsTable: <inferred>`
+- `type ShopRefundStatus = 'pending' | 'succeeded' | 'failed'`
 - `const shopShippingMethodsTable: <inferred>`
 - `const shopStockReservationsTable: <inferred>`
+- `const shopWebhookEventsTable: <inferred>`
 - `const user: <inferred>`
 - `const userRelations: <inferred>`
 - `const verification: <inferred>`
@@ -324,9 +341,10 @@ Tags:
 - `interface CarrierAdapter`
 - `interface CarrierEvent`
 - `interface ConsentConfig`
+- `interface CouponRef`
 - `type Currency = 'PLN'`
 - `defineShop(config: ShopConfig): ResolvedShopConfig`
-- `type GeowidgetConfigPreset = | 'parcelcollect' | 'parcelsend' | 'parcelcollect247' | string`
+- `type GeowidgetConfigPreset = 'parcelcollect' | 'parcelsend' | 'parcelcollect247' | string`
 - `type I18nText = { [lang: string]: string; }`
 - `inpostAdapter(opts: InpostAdapterOptions): CarrierAdapter`
 - `interface InpostAdapterOptions`
@@ -339,6 +357,8 @@ Tags:
 - `interface PaymentCreateContext`
 - `interface PaymentCreateResult`
 - `interface PaymentEvent`
+- `interface PaymentRefundInput`
+- `interface PaymentRefundResult`
 - `payuAdapter(opts: PayuAdapterOptions): PaymentAdapter`
 - `interface PayuAdapterOptions`
 - `interface ResolvedShopConfig`
@@ -347,6 +367,8 @@ Tags:
 - `interface ShipmentLabel`
 - `interface ShopConfig`
 - `interface ShopFeatures`
+- `stripeAdapter(opts: StripeAdapterOptions): PaymentAdapter` — Stripe payment adapter (Checkout Session flow).
+- `interface StripeAdapterOptions`
 
 ### `includio-cms/shop/client`
 
@@ -357,7 +379,7 @@ Tags:
 - `interface CheckoutResult`
 - `createOrderState(opts: CreateOrderStateOptions): OrderState`
 - `interface CreateOrderStateOptions`
-- `createShopClient(options: ShopClientOptions = {}): ShopClient`
+- `createShopClient(options: ShopClientOptions = {}): ShopClient` — Create a typed, isomorphic shop SDK client.
 - `const DEFAULT_LABELS_PL: OrderStatusLabels`
 - `const InpostPicker: LegacyComponentType`
 - `interface OrderDetailResponse`
@@ -368,13 +390,14 @@ Tags:
 - `interface RefreshPaymentResult`
 - `interface RetryPaymentResult`
 - `interface ShippingMethodPublic`
-- `interface ShopClient`
-- `interface ShopClientOptions`
+- `interface ShopClient` — Headless shop SDK surface returned by `createShopClient()`.
+- `interface ShopClientOptions` — Options for `createShopClient()`.
 
 ### `includio-cms/shop/http`
 
 - `createCarrierConfigHandler(): { GET: RequestHandler }` — Public endpoint that returns front-end facing carrier widget descriptor for
 - `createCarrierWebhookHandler(): { POST: RequestHandler }` — Public webhook receiver for carrier events (e.g. ShipX `shipment_status_changed`).
+- `createCartCouponHandler(): { POST: RequestHandler; DELETE: RequestHandler }` — Cart coupon endpoints — POST applies a code, DELETE removes it.
 - `createCartHandler(): { GET: RequestHandler; POST: RequestHandler; PATCH: RequestHandler; DELETE: R...`
 - `createCheckoutHandler(): { POST: RequestHandler }`
 - `createOrderHandler(): { GET: RequestHandler }`

package/CHANGELOG.md

@@ -3,6 +3,101 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.25.0 — 2026-05-06
+
+Faza 11.5 — Shop polish. Stripe payment adapter (Checkout Session flow z native webhook signature verify), refund infrastructure (full + partial, cross-adapter Stripe + PayU), webhook idempotency table (`shop_webhook_events` z UNIQUE(provider, event_id)), coupons (% / fixed PLN, expiresAt, maxUses, minOrderAmount, OCC race-safe redemption), low-stock email alert (per-product `lowStockThreshold`), order export CSV w admin, default email templates rozszerzone o `refunded` status, SDK `applyCoupon`/`removeCoupon` + JSDoc body + `@public` tagi, pełna dokumentacja shopa (DOCS.md + adapter guides + cURL examples + Stripe/Coupons/Refund pages). Shop = `@public` w v1.0.
+
+### Added
+- `stripeAdapter()` — Stripe Checkout Session flow. `createPayment()` → `stripe.checkout.sessions.create` (zwraca redirect URL); `handleWebhook()` → natywny `stripe.webhooks.constructEvent` (sig + timestamp skew); `getStatus()` → `checkout.sessions.retrieve` poll fallback dla lost webhooks; `refund()` → resolve session → payment_intent → `stripe.refunds.create({ amount? })`. Stripe SDK = optional peer (lazy import + caching). Status mapping: `complete + paid → paid`, `expired → paymentRejected`. Eksport: `stripeAdapter`, `StripeAdapterOptions`.
+- **Refund infrastructure** (cross-adapter, full + partial). `PaymentAdapter.refund?(input)` opcjonalna metoda interfejsu (`PaymentRefundInput` / `PaymentRefundResult`). Server: `refundOrder({ orderId, amount?, reason?, createdBy })` w `src/lib/shop/server/refund.ts` — walidacja eligibility (status `paid|preparing|sent|done`, `paymentProviderRef`, adapter wsparcie, `amount <= remaining`), insert pending row, call adapter, update do `succeeded`/`failed`, full refund → `updateOrderStatus(refunded)`. PayU `client.refundOrder()` + `payuAdapter().refund()`. Stripe refund built-in. DB: nowa tabela `shop_refunds` (orderId FK, paymentId FK?, provider, providerRef, amount cents, currency, reason, status, createdBy, createdAt). `getRefundedAmount()` + `listRefunds()` helpers.
+- **Webhook idempotency table** (`shop_webhook_events`). UNIQUE(provider, event_id) — duplikaty short-circuit z 200 + `replay: true` przed mutacją state. PayU `notify_id` (lub fallback `${orderId}:${status}`), Stripe natywny `event.id`. `reserveWebhookEvent()` + `markWebhookEventProcessed()` w `src/lib/shop/http/webhook-idempotency.ts`. Stara terminal-status check zachowana jako fallback dla adapterów bez `eventId`.
+- **Coupons** — code-based discounts. DB: `shop_coupons` (code UNIQUE uppercase, type `percent|fixed`, value numeric 20,6, minOrderAmount cents, maxUses, usedCount, expiresAt, isActive) + `shop_coupon_redemptions` (couponId FK, orderId FK UNIQUE, discountAmount, redeemedAt). Server: `validateCoupon()` (feature flag + lookup + isActive + expiresAt + maxUses + minOrderAmount), `reserveCouponSlot()` z OCC `WHERE max_uses IS NULL OR used_count < max_uses`, `recordCouponRedemption()` `onConflictDoNothing(orderId)`, `releaseCouponSlot()`. Pricing: discount przed VAT, uniform per-line factor (`calculateCouponDiscountNet()` + line-level factor w `cart-hydrate`). REST: `POST/DELETE /api/shop/cart/coupon` (`createCartCouponHandler()`), separate cookie `aria_shop_coupon` (7d TTL, `[A-Z0-9_-]{1,64}`). SDK: `cart.applyCoupon(code)` / `cart.removeCoupon()`. Admin UI: lista kodów + new/edit form, walidacja kodu (uppercase, alfanumeryczny). Feature flag: `defineShop({ features: { coupons: true } })`.
+- **Low-stock email alert.** Per-produkt `lowStockThreshold: int?` w `shop_products`. Hook po `updateOrderStatus(paid)` decrement: jeśli `stock <= threshold` AND `stock + qty > threshold` (boundary cross), `sendLowStockEmail()` (PL) → `shop.adminEmail`. Brak `adminEmail` lub brak email adaptera = no-op.
+- **Order export CSV** (admin). `exportOrdersCsv(filters)` query w `shop.remote.ts` — RFC 4180 escape (commas, quotes, newlines), BOM dla Excel UTF-8. Button "Eksport CSV" na orders list page (honors current `status` + `email` filters). Kolumny: number, status, customerEmail, customerName, totalGross, currency, shippingGross, paymentMethod, createdAt.
+- **Default email templates** — `OrderStatus` += `refunded` (terminal w webhook-logic, propagacja: `STATUS_SUBJECTS`/`STATUS_INTRO` PL/EN, customer-facing labels, admin Zod schema, admin detail page styles). Plus low-stock template dla admina.
+- **SDK polish** — `createShopClient()` + `ShopClient` + `ShopClientOptions` z pełnym JSDoc body (description + @param + @returns + @example). Per-method docs dla `cart.{get,add,update,remove,clear,applyCoupon,removeCoupon}`, `shipping.list`, `checkout.submit`, `orders.{get,refreshPayment,retryPayment}`. Wszystkie eksporty `@public`.
+- **Dokumentacja** — pełna sekcja Shop w `DOCS.md` (overview rozszerzony o Coupons/Refunds/Stripe/Low-stock/CSV export, sekcja "cURL examples" + "Error codes"), 5 nowych stron: `/docs/shop/{stripe,coupons,refund,payment-adapter,carrier-adapter}`. `payment-adapter` guide pokazuje pełen interfejs + lazy peer pattern + signature verify + idempotency via eventId + lost-webhook recovery + refund. Update `nav.ts`.
+- **Admin UI**. Order detail: sidebar "Zwroty" (lista refund rows + aggregate refunded/remaining + `RefundDialog` modal z full/partial mode + reason). Orders list: "Eksport CSV" button. Coupons CRUD: `/admin/shop/coupons` lista + `/new` + `/[id]` edit (validacja code uppercase + alfanumeryczny). Nav-shop link. Refunded status w STATUS_STYLES.
+
+### Breaking
+- `OrderStatus` typ rozszerzony o `"refunded"` (terminal status). Custom UI/email logic używające `Record<OrderStatus, …>` musi dodać entry. Zaktualizowane in-tree: email templates, `svelte/labels.ts` `DEFAULT_LABELS_PL`, admin detail page, admin Zod schema, webhook-logic terminal set.
+- `PaymentAdapter` interface += optional `refund?(input)` method i optional `eventId?` / `eventType?` fields w `PaymentEvent`. Custom adaptery działają bez zmian (`refund` opcjonalne; brak `eventId` skutkuje fallback do terminal-status idempotency).
+- `CartSnapshot` rozszerzony o `subtotalNet`/`subtotalGross`/`subtotalVat` + opcjonalny `coupon: AppliedCoupon`. `totalNet`/`totalGross` teraz reprezentują wartość PO odjęciu discountu. Storefronty czytające tylko `total*` działają bez zmian dla cartów bez coupons; kod renderujący detal pre-discount musi czytać `subtotal*`.
+- `ShopFeatures` += opcjonalny `coupons?: boolean` (default `false`). `ShopConfig` += opcjonalny `adminEmail?: string` (default brak — low-stock alert no-op). Backward compatible defaults.
+
+### Migration
+
+```sql
+-- 0.25.0 — Shop polish DB additions
+-- Run via drizzle-kit push or apply manually before deploying 0.25.0.
+
+-- Refunds — one row per refund attempt (succeeded / pending / failed)
+CREATE TABLE IF NOT EXISTS shop_refunds (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id uuid NOT NULL REFERENCES shop_orders(id) ON DELETE CASCADE,
+  payment_id uuid REFERENCES shop_payments(id) ON DELETE SET NULL,
+  provider text NOT NULL,
+  provider_ref text,
+  amount integer NOT NULL,
+  currency text NOT NULL,
+  reason text,
+  status text NOT NULL DEFAULT 'pending',
+  created_by text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Webhook idempotency log — UNIQUE(provider, event_id) prevents replay
+CREATE TABLE IF NOT EXISTS shop_webhook_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  provider text NOT NULL,
+  event_id text NOT NULL,
+  event_type text,
+  order_id uuid REFERENCES shop_orders(id) ON DELETE SET NULL,
+  order_number text,
+  payload_hash text,
+  raw jsonb,
+  received_at timestamptz NOT NULL DEFAULT now(),
+  processed_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS shop_webhook_events_provider_event_unique
+  ON shop_webhook_events (provider, event_id);
+
+-- Coupons
+CREATE TABLE IF NOT EXISTS shop_coupons (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  code text NOT NULL,
+  type text NOT NULL,
+  value numeric(20,6) NOT NULL,
+  min_order_amount integer,
+  max_uses integer,
+  used_count integer NOT NULL DEFAULT 0,
+  expires_at timestamptz,
+  is_active boolean NOT NULL DEFAULT true,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS shop_coupons_code_unique ON shop_coupons (code);
+
+-- Coupon redemptions — UNIQUE(order_id) prevents double-redeem on retry
+CREATE TABLE IF NOT EXISTS shop_coupon_redemptions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  coupon_id uuid NOT NULL REFERENCES shop_coupons(id) ON DELETE CASCADE,
+  order_id uuid NOT NULL REFERENCES shop_orders(id) ON DELETE CASCADE,
+  discount_amount integer NOT NULL,
+  redeemed_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS shop_coupon_redemptions_order_unique
+  ON shop_coupon_redemptions (order_id);
+
+-- Low-stock alert column
+ALTER TABLE shop_products ADD COLUMN IF NOT EXISTS low_stock_threshold integer;
+```
+
+### Notes
+
+Migracja czysto additive — istniejące zamówienia pozostają nietknięte, refunded jest nową gałęzią graph statusów. Stripe SDK trzeba zainstalować osobno (`pnpm add stripe`) jeśli używa się `stripeAdapter()` — `optionalDependencies` + `peerDependenciesMeta`. Coupons opt-in via `features: { coupons: true }`. Low-stock email wymaga `shop.adminEmail` w `defineShop` + skonfigurowanego email adaptera. Webhook idempotency table jest backwards-compatible: adaptery które nie surface eventId nadal działają poprzez terminal-status fallback. Test coverage 1053/1053 unit tests zielone (37 nowych: Stripe sig verify 4, getStatus 1, refund 3, payload 6, status-map 10, pricing-coupon 5, coupon-cookie 8). DoD: gap analysis vs Woo/Presta zatwierdzona, MUST-v1 (Stripe + Refund + Idempotency + Coupons) wdrożone, NICE-v1 (Low-stock + CSV export) wdrożone, dokumentacja shopa pełna.
+
 ## 0.24.0 — 2026-04-30
 
 Faza 11 — Performance Pass. Eliminacja N+1 w render path: `getImageStylesBatch` (jeden SELECT zamiast N×getImageStyle dla styles + srcset wariantów) + `_getRawEntries` z batchowanym `getEntryVersions` (jeden call zamiast per-entry). Sharp srcset pipeline odrefactorowany — Promise.all wokół per-style queries usunięty (jeden batch + sequential Sharp generation z try/catch dla missing entries). Background maintenance lock potwierdzony testami (concurrent invocation skipped). Bench infra: nowy projekt vitest `bench` + skrypt `pnpm bench` + 2 representative benchmarks (image styles + raw entries).

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.24.0)
+# Includio CMS Documentation (v0.24.1)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 
@@ -4987,18 +4987,22 @@ For error handling patterns (`CmsError`, `instanceof`-based branching), see [Ent
 
 Headless e-commerce module. Optional — activate by adding `shop: defineShop({...})` to your CMS config.
 
-> Shop is in beta. API may change between 0.15.x patches.
+> Shop is `@public` from 0.25.0 — covered by the v1 stability promise. Breaking changes only at major bumps.
 
 ## What you get
 
 - **Products as entries** — add `{ type: 'shop', slug: 'shop' }` to any collection; its entries become purchasable.
 - **Cart** — signed cookie, headless SDK (`createShopClient()`), `POST/PATCH/DELETE /api/shop/cart`.
-- **Checkout + orders** — `POST /api/shop/checkout` creates an order with consent validation, stock reservation (30-min TTL), and status emails.
-- **Payment adapters** — `manualAdapter()` (bank transfer / COD) and `payuAdapter()` ship built-in; plug your own by implementing `PaymentAdapter`.
+- **Coupons** — code-based discounts (% / fixed PLN), expiry, max-uses, min-order. Apply via `cart.applyCoupon('CODE')`. See [Coupons](/docs/shop/coupons).
+- **Checkout + orders** — `POST /api/shop/checkout` creates an order with consent validation, stock reservation (30-min TTL), coupon redemption (race-safe), and status emails.
+- **Payment adapters** — `manualAdapter()` (bank transfer / COD), `payuAdapter()`, and `stripeAdapter()` ship built-in. See [Stripe](/docs/shop/stripe) and [Writing your own payment adapter](/docs/shop/payment-adapter).
+- **Refunds** — full and partial, cross-adapter (Stripe + PayU). Admin button on order detail. See [Refunds](/docs/shop/refund).
 - **Carrier adapters** — `inpostAdapter()` ships built-in (Geowidget v5 picker + ShipX shipments + webhook). Plug other carriers by implementing `CarrierAdapter`.
-- **Webhook infrastructure** — `createPaymentWebhookHandler()` dispatches provider callbacks, verifies signatures, is idempotent.
+- **Webhook infrastructure** — `createPaymentWebhookHandler()` dispatches provider callbacks, verifies signatures, persists `(provider, event_id)` for proper idempotency.
 - **Secure order view** — per-order `accessToken` + cookie fallback + `GET /api/shop/orders/[number]` token-gated API.
 - **Shipping ↔ payment compatibility** — restrict payment methods per shipping (e.g. no COD for paczkomat).
+- **Low-stock alert** — set `lowStockThreshold` per product; admin gets an email when stock crosses the boundary.
+- **Order export** — admin "Export CSV" button on the orders list (honors current filters).
 
 ## Config
 
@@ -5045,6 +5049,7 @@ Scaffold provisions these endpoints (when shop is enabled):
 | Path | Handler | Purpose |
 |------|---------|---------|
 | `POST /api/shop/cart` | `createCartHandler()` | Cart CRUD |
+| `POST/DELETE /api/shop/cart/coupon` | `createCartCouponHandler()` | Apply / remove coupon |
 | `GET /api/shop/shipping-methods` | `createShippingMethodsHandler()` | List active shipping |
 | `POST /api/shop/checkout` | `createCheckoutHandler()` | Create order + initiate payment |
 | `GET /api/shop/orders/[number]` | `createOrderHandler()` | Token-gated order view |
@@ -5055,8 +5060,78 @@ Scaffold provisions these endpoints (when shop is enabled):
 | `POST /api/shop/carriers/[id]/webhook` | `createCarrierWebhookHandler()` | Carrier event receiver |
 | `GET /api/shop/admin/orders/[id]/label` | `createShipmentLabelHandler()` | Admin shipping-label PDF proxy |
 
+## cURL examples
+
+Get cart (cookie-based):
+
+```sh
+curl -i 'https://example.com/api/shop/cart' --cookie cookies.txt --cookie-jar cookies.txt
+```
+
+Add a variant:
+
+```sh
+curl -X POST 'https://example.com/api/shop/cart' \
+  -H 'Content-Type: application/json' \
+  -d '{"variantId":"v_abc","qty":2}' \
+  --cookie cookies.txt --cookie-jar cookies.txt
+```
+
+Apply a coupon:
+
+```sh
+curl -X POST 'https://example.com/api/shop/cart/coupon' \
+  -H 'Content-Type: application/json' \
+  -d '{"code":"ARIA10"}' \
+  --cookie cookies.txt --cookie-jar cookies.txt
+```
+
+Submit checkout:
+
+```sh
+curl -X POST 'https://example.com/api/shop/checkout' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "customerEmail": "buyer@example.com",
+    "shippingMethodId": "ship_xyz",
+    "paymentMethod": "stripe",
+    "consents": [{"id": "terms", "accepted": true}]
+  }' \
+  --cookie cookies.txt
+# → { "orderNumber": "ARI-X1Y2Z3", "redirectUrl": "https://checkout.stripe.com/...", "requiresPaymentRedirect": true }
+```
+
+Fetch order (with access token):
+
+```sh
+curl 'https://example.com/api/shop/orders/ARI-X1Y2Z3?token=<accessToken>'
+```
+
+## Error codes
+
+Cart endpoints return `400` with `{ "error": "<code>" }` for known failures:
+
+| Code | Meaning |
+|------|---------|
+| `code required` | `POST /cart/coupon` body lacks `code` |
+| `invalid_code` | Coupon code format invalid (uppercase / 1–64 chars / `[A-Z0-9_-]`) |
+| `not_found` | Coupon code does not exist |
+| `inactive` | Coupon set to inactive |
+| `expired` | `expiresAt` in the past |
+| `exhausted` | `usedCount >= maxUses` |
+| `min_order_not_met` | Cart subtotal below `minOrderAmount` |
+| `feature_disabled` | `features.coupons` is `false` in `defineShop` |
+| `empty_cart` | No items to apply discount to |
+
+Webhook endpoints return `200` for replay/already-processed events (`{"replay": true}`), `400` for signature/payload failures, `429` rate-limit, `500` for provider/server errors (provider should retry).
+
 ## See also
 
+- [Stripe](/docs/shop/stripe) — Checkout Session adapter + webhook + refund
+- [Coupons](/docs/shop/coupons) — code-based discounts, % / fixed, expiry, max-uses
+- [Refunds](/docs/shop/refund) — full + partial, cross-adapter
+- [Writing your own payment adapter](/docs/shop/payment-adapter)
+- [Writing your own carrier adapter](/docs/shop/carrier-adapter)
 - [Order view](/docs/shop/order-view) — generic `<OrderStatus>` component + headless helper
 - [Retry payment](/docs/shop/retry-payment) — lifecycle + endpoint
 - [InPost carrier](/docs/shop/inpost) — Geowidget v5 + ShipX shipment + webhook

package/ROADMAP.md

@@ -18,6 +18,7 @@
 - [x] `[breaking]` `[P0]` Faza 9 — DX & config validation (0.22.0): `defineConfig` Zod strict z field path + hint, `CmsError` + `ConfigValidationError` z code/context, resolver throw sites zmigrowane, CLI `--help` per subcommand + `--version`, `.env.example` rozszerzony o `INCLUDIO_*`, README rebuild (TOC + system req + 5-min quickstart), JSDoc body (opis + @param + @returns + @example) na każdym `@public` <!-- files: src/lib/core/errors.ts, src/lib/types/cms.schema.ts, src/lib/sveltekit/config.ts, src/lib/cli/index.ts, README.md, .env.example, src/lib/updates/0.22.0/ -->
 - [x] `[chore]` `[P1]` Faza 10 — Documentation Pass (0.23.0): DOCS.md uzupełnione (number/boolean/date edge cases, REST cURL + error codes, Entries error handling + transactions, Admin UI a11y, Adapter Contracts), nowe sekcje (Stability Promise, Security Model), Migration Guide v0.x → v1.0 master cheatsheet (0.16-0.22), ROADMAP cleanup (pre-v1.0 → ROADMAP-ARCHIVE.md) <!-- files: src/routes/docs/{stability-promise,security}/+page.svx, src/routes/docs/migration/+page.svx, src/routes/docs/_config/nav.ts, scripts/compile-docs.ts, ROADMAP-ARCHIVE.md, src/lib/updates/0.23.0/ -->
 - [x] `[chore]` `[P1]` Faza 11 — Performance Pass (0.24.0): N+1 elimination (`getImageStyle` batch IN query, `getRawEntries` batch entry versions), Sharp srcset `Promise.allSettled` (one timeout doesn't kill batch), background maintenance in-process lock verified + tested, bench infra (`pnpm bench` + representative benchmarks), lazy adapter imports verified <!-- files: src/lib/core/server/media/styles/operations/, src/lib/core/server/fields/resolveImageFields.ts, src/lib/core/server/entries/operations/get.ts, src/lib/db-postgres/index.ts, src/lib/core/server/media/operations/backgroundMaintenance.spec.ts, src/lib/updates/0.24.0/ -->
+- [x] `[feature]` `[P0]` Faza 11.5 — Shop polish (0.25.0): Stripe adapter (Checkout Session, sig verify, idempotency), refund infra (full + partial cross-adapter), webhook idempotency table (`shop_webhook_events`), coupons (% / fixed, expiresAt, maxUses, minOrder), low-stock email alert, order export CSV, default email templates (PL/EN), SDK JSDoc + `@public`, pełna dokumentacja shopa <!-- files: src/lib/shop/adapters/stripe/, src/lib/shop/server/{refund,coupons}.ts, src/lib/db-postgres/schema/shop/{refunds,webhookEvents,coupons,couponRedemptions}.ts, src/lib/admin/client/shop/, src/lib/updates/0.25.0/ -->
 - [ ] `[fix]` `[P1]` Select field — `defaultValue` propagacja do zod schema (full repro: `ideas/post-v1/select-field-defaultvalue-bug.md`); fix planowany w Fazie 12 (RC)
 
 ## v1.x — Post-v1.0 deferred

package/dist/admin/client/index.d.ts

@@ -18,5 +18,8 @@ export { default as ShippingMethodNewPage } from './shop/shipping-method-new-pag
 export { default as ShippingMethodEditPage } from './shop/shipping-method-edit-page.svelte';
 export { default as ShopOrdersListPage } from './shop/shop-orders-list-page.svelte';
 export { default as ShopOrderDetailPage } from './shop/shop-order-detail-page.svelte';
+export { default as ShopCouponsListPage } from './shop/coupons-list-page.svelte';
+export { default as ShopCouponNewPage } from './shop/coupon-new-page.svelte';
+export { default as ShopCouponEditPage } from './shop/coupon-edit-page.svelte';
 export * from '../helpers/index.js';
 export * from '../ui/index.js';

package/dist/admin/client/index.js

@@ -18,6 +18,9 @@ export { default as ShippingMethodNewPage } from './shop/shipping-method-new-pag
 export { default as ShippingMethodEditPage } from './shop/shipping-method-edit-page.svelte';
 export { default as ShopOrdersListPage } from './shop/shop-orders-list-page.svelte';
 export { default as ShopOrderDetailPage } from './shop/shop-order-detail-page.svelte';
+export { default as ShopCouponsListPage } from './shop/coupons-list-page.svelte';
+export { default as ShopCouponNewPage } from './shop/coupon-new-page.svelte';
+export { default as ShopCouponEditPage } from './shop/coupon-edit-page.svelte';
 // Folded from `./admin/helpers` (dropped as separate export in 0.20.0)
 export * from '../helpers/index.js';
 // Folded from `./admin/ui` (dropped as separate export in 0.20.0)

package/dist/admin/client/shop/coupon-edit-page.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { page } from '$app/state';
+	import { getRemotes } from '../../../sveltekit/index.js';
+	import CouponForm from './coupon-form.svelte';
+
+	const remotes = getRemotes();
+	const id = $derived(page.params.id ?? '');
+	const query = $derived(remotes.getCouponAdmin(id));
+</script>
+
+<div class="mx-auto max-w-2xl space-y-6 p-6">
+	<header>
+		<h1 class="text-2xl font-extrabold tracking-tight">Edytuj kod rabatowy</h1>
+		<p class="text-muted-foreground text-sm">
+			<a href="/admin/shop/coupons" class="hover:underline">← Wróć do listy</a>
+		</p>
+	</header>
+
+	{#if !query.ready}
+		<p class="text-muted-foreground">Ładowanie…</p>
+	{:else if !query.current}
+		<p>Kod nie został znaleziony.</p>
+	{:else}
+		{@const c = query.current}
+		<CouponForm
+			initial={{
+				code: c.code,
+				type: c.type,
+				value: Number(c.value),
+				minOrderAmount: c.minOrderAmount,
+				maxUses: c.maxUses,
+				expiresAt: c.expiresAt instanceof Date ? c.expiresAt.toISOString() : c.expiresAt,
+				isActive: c.isActive
+			}}
+			submitLabel="Zapisz zmiany"
+			onSubmit={async (input) => {
+				await remotes.updateCouponCmd({ id, input });
+				await goto('/admin/shop/coupons');
+			}}
+			onCancel={() => goto('/admin/shop/coupons')}
+		/>
+	{/if}
+</div>

package/dist/admin/client/shop/coupon-edit-page.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const CouponEditPage: import("svelte").Component<Record<string, never>, {}, "">;
+type CouponEditPage = ReturnType<typeof CouponEditPage>;
+export default CouponEditPage;

package/dist/admin/client/shop/coupon-form.svelte

@@ -0,0 +1,170 @@
+<script lang="ts">
+	import { Input } from '../../../components/ui/input/index.js';
+	import { Button } from '../../../components/ui/button/index.js';
+	import Label from '../../../components/ui/label/label.svelte';
+
+	type CouponInput = {
+		code: string;
+		type: 'percent' | 'fixed';
+		value: number;
+		minOrderAmount: number | null;
+		maxUses: number | null;
+		expiresAt: string | null;
+		isActive: boolean;
+	};
+
+	type Props = {
+		initial?: Partial<CouponInput>;
+		submitLabel?: string;
+		onSubmit: (input: CouponInput) => Promise<void>;
+		onCancel?: () => void;
+	};
+
+	let { initial, submitLabel = 'Zapisz', onSubmit, onCancel }: Props = $props();
+
+	let code = $state(initial?.code ?? '');
+	let type = $state<'percent' | 'fixed'>(initial?.type ?? 'percent');
+	let value = $state(initial?.value != null ? String(initial.value) : '');
+	let minOrderAmountPln = $state(
+		initial?.minOrderAmount != null ? (initial.minOrderAmount / 100).toFixed(2) : ''
+	);
+	let maxUses = $state(initial?.maxUses != null ? String(initial.maxUses) : '');
+	let expiresAt = $state(initial?.expiresAt ? initial.expiresAt.slice(0, 10) : '');
+	let isActive = $state(initial?.isActive ?? true);
+
+	let submitting = $state(false);
+	let error = $state<string | null>(null);
+
+	async function handleSubmit(e: Event) {
+		e.preventDefault();
+		error = null;
+		const numValue = Number(value.replace(',', '.'));
+		if (!Number.isFinite(numValue) || numValue <= 0) {
+			error = 'Podaj wartość większą od zera.';
+			return;
+		}
+		if (type === 'percent' && numValue > 100) {
+			error = 'Procent nie może przekraczać 100.';
+			return;
+		}
+		const minOrderCents = minOrderAmountPln
+			? Math.round(Number(minOrderAmountPln.replace(',', '.')) * 100)
+			: null;
+		if (minOrderCents != null && (!Number.isFinite(minOrderCents) || minOrderCents < 0)) {
+			error = 'Minimalna wartość zamówienia musi być nieujemna.';
+			return;
+		}
+		const maxUsesNum = maxUses ? Number(maxUses) : null;
+		if (maxUsesNum != null && (!Number.isInteger(maxUsesNum) || maxUsesNum <= 0)) {
+			error = 'Maksymalna liczba użyć musi być dodatnią liczbą całkowitą.';
+			return;
+		}
+
+		submitting = true;
+		try {
+			await onSubmit({
+				code: code.trim().toUpperCase(),
+				type,
+				value: numValue,
+				minOrderAmount: minOrderCents,
+				maxUses: maxUsesNum,
+				expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null,
+				isActive
+			});
+		} catch (err) {
+			error = err instanceof Error ? err.message : 'Nie udało się zapisać.';
+			submitting = false;
+		}
+	}
+</script>
+
+<form onsubmit={handleSubmit} class="space-y-5">
+	<div class="space-y-2">
+		<Label for="coupon-code">Kod</Label>
+		<Input
+			id="coupon-code"
+			bind:value={code}
+			placeholder="np. ARIA10"
+			required
+			pattern="[A-Za-z0-9_-]+"
+			maxlength={64}
+			aria-describedby="coupon-code-hint"
+		/>
+		<p id="coupon-code-hint" class="text-muted-foreground text-xs">
+			Wielkość liter zostanie ujednolicona do dużych liter. Tylko litery, cyfry, „_”, „-”.
+		</p>
+	</div>
+
+	<fieldset class="space-y-2">
+		<legend class="mb-1 text-sm font-semibold">Typ rabatu</legend>
+		<label class="flex items-center gap-2 text-sm">
+			<input type="radio" name="coupon-type" value="percent" bind:group={type} />
+			<span>Procent (% od kwoty netto)</span>
+		</label>
+		<label class="flex items-center gap-2 text-sm">
+			<input type="radio" name="coupon-type" value="fixed" bind:group={type} />
+			<span>Kwota stała (PLN)</span>
+		</label>
+	</fieldset>
+
+	<div class="space-y-2">
+		<Label for="coupon-value">{type === 'percent' ? 'Procent (0–100)' : 'Kwota (PLN)'}</Label>
+		<Input
+			id="coupon-value"
+			type="text"
+			inputmode="decimal"
+			bind:value
+			placeholder={type === 'percent' ? 'np. 10' : 'np. 50,00'}
+			required
+		/>
+	</div>
+
+	<div class="grid grid-cols-2 gap-4">
+		<div class="space-y-2">
+			<Label for="coupon-min-order">Min. wartość zamówienia (PLN)</Label>
+			<Input
+				id="coupon-min-order"
+				type="text"
+				inputmode="decimal"
+				bind:value={minOrderAmountPln}
+				placeholder="opcjonalnie"
+			/>
+		</div>
+		<div class="space-y-2">
+			<Label for="coupon-max-uses">Maks. liczba użyć</Label>
+			<Input
+				id="coupon-max-uses"
+				type="number"
+				min="1"
+				step="1"
+				bind:value={maxUses}
+				placeholder="bez limitu"
+			/>
+		</div>
+	</div>
+
+	<div class="space-y-2">
+		<Label for="coupon-expires-at">Data wygaśnięcia</Label>
+		<Input id="coupon-expires-at" type="date" bind:value={expiresAt} />
+	</div>
+
+	<label class="flex items-center gap-2 text-sm">
+		<input type="checkbox" bind:checked={isActive} />
+		<span>Aktywny (dostępny przy checkoucie)</span>
+	</label>
+
+	{#if error}
+		<p class="text-destructive text-sm" role="alert">{error}</p>
+	{/if}
+
+	<div class="flex gap-2">
+		<Button type="submit" disabled={submitting}>
+			{submitting ? 'Zapisywanie…' : submitLabel}
+		</Button>
+		{#if onCancel}
+			<Button type="button" variant="outline" onclick={onCancel} disabled={submitting}>
+				Anuluj
+			</Button>
+		{/if}
+	</div>
+</form>

package/dist/admin/client/shop/coupon-form.svelte.d.ts

@@ -0,0 +1,18 @@
+type CouponInput = {
+    code: string;
+    type: 'percent' | 'fixed';
+    value: number;
+    minOrderAmount: number | null;
+    maxUses: number | null;
+    expiresAt: string | null;
+    isActive: boolean;
+};
+type Props = {
+    initial?: Partial<CouponInput>;
+    submitLabel?: string;
+    onSubmit: (input: CouponInput) => Promise<void>;
+    onCancel?: () => void;
+};
+declare const CouponForm: import("svelte").Component<Props, {}, "">;
+type CouponForm = ReturnType<typeof CouponForm>;
+export default CouponForm;