includio-cms 0.14.6 → 0.15.1

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.15.1 — 2026-04-15
+
+Shop: PayU payment adapter + secure order access (token-gated view API, email link).
+
+### Added
+- Orders now carry an `accessToken` — public order-view API is gated by this token (no enumeration by order number).
+- New `createOrderHandler()` in `includio-cms/shop/http` — `GET /api/shop/orders/[number]?token=...` returns order + items + status history; accepts cookie fallback `aria_shop_order` written on checkout (30-min httpOnly).
+- `ShopConfig.orderViewUrl` template — placeholders `{orderNumber}`, `{orderId}`, `{accessToken}`, `{language}`. Default: `/shop/order/{orderNumber}?token={accessToken}`. When set to an absolute URL, status emails include a "View order" button.
+- New `createPaymentWebhookHandler()` — mount at `/api/shop/webhooks/[provider]/+server.ts`. Dispatches to the matching `PaymentAdapter.handleWebhook`, maps payment event to order status, and is idempotent (terminal orders ack 200 no-op — safe against provider retries). 400 on bad signature, 200 on unknown order.
+- Checkout now calls `PaymentAdapter.createPayment()` after the order is created. The response exposes `paymentStatus`, `requiresPaymentRedirect`, `redirectUrl`, and `accessToken` so the frontend can redirect to the gateway and deep-link back to the order view.
+- Orders store `paymentProviderRef` — the external id returned by the payment adapter (e.g. PayU orderId). Used to correlate webhooks and future refunds/status polls.
+- New `payuAdapter()` — OAuth token caching, create order (REST v2.1), MD5 `OpenPayU-Signature` verification on webhooks, full PayU status mapping (including REJECTED and WAITING_FOR_CONFIRMATION). Import from `includio-cms/shop`.
+- `PaymentAdapter.createPayment()` receives an optional `{ customerIp, language }` context, threaded from the SvelteKit request in the built-in checkout handler.
+- Shipping ↔ payment compatibility: `shop_shipping_methods.allowed_payment_methods` (jsonb string[] | null). Null/empty = any payment method allowed; otherwise checkout rejects the order when the chosen payment is not in the list (e.g. disable COD for paczkomat). The shipping-methods API exposes the list so the frontend can filter payment options per shipping choice.
+- Admin: shipping method form now exposes an "allowed payment methods" section with a restrict toggle + multi-select of configured payment adapters. `getShopConfig` remote returns the payment adapter list (id + i18n label).
+- New optional `PaymentAdapter.getStatus(providerRef)` for provider-side polling, plus `createRefreshPaymentHandler()` mounted at `/api/shop/orders/[number]/refresh-payment`. Token-gated (same as order view). Used as a safety net when a webhook is lost — PayU adapter implements it out of the box.
+- Retry payment — `createRetryPaymentHandler()` at `POST /api/shop/orders/[number]/retry-payment`. Reuses the same order, creates a fresh payment session via the adapter, stores the new `paymentProviderRef`. Status `paymentRejected` is rolled back to `awaitingPayment`. Terminal states return 409.
+- Shop SDK: new `orders` namespace on `createShopClient()` — `get(number, token)`, `refreshPayment(number, token)`, `retryPayment(number, token)`. All response types exported from `includio-cms/shop/client`.
+- Headless Svelte 5 helper `createOrderState({ number, token, initialData? })` — reactive state class with `data/loading/error/phase`, `load()`, `refreshPayment()`, `retry()`, `startPolling()/stopPolling()`. Supports SSR via `initialData`.
+- Generic `<OrderStatus />` Svelte component — drop-in order view with awaiting/success/rejected states, auto-polling, retry button, status timeline. Full theming via CSS custom properties and `::part()`. Import from `includio-cms/shop/svelte`.
+- Docs: new section covering the shop module, order view patterns (generic vs headless), and retry lifecycle.
+
+### Migration
+
+```sql
+ALTER TABLE shop_orders ADD COLUMN access_token uuid NOT NULL DEFAULT gen_random_uuid();
+ALTER TABLE shop_orders ADD COLUMN payment_provider_ref text;
+ALTER TABLE shop_shipping_methods ADD COLUMN allowed_payment_methods jsonb;
+```
+
+### Notes
+
+Requires `gen_random_uuid()` (pgcrypto or Postgres 13+). Existing orders get a fresh random token on migration — pre-existing customer links keep working because order view links were not shipped before this version.
+
+## 0.15.0 — 2026-04-14
+
+Shop module MVP — headless e-commerce: products, cart, orders, payments, emails
+
+### Added
+- New optional `shop` module — activate via `defineShop()` in `cms.config.ts`
+- Product = CMS entry + built-in `shop` field (like `seo`) — add `{ type: "shop", slug: "shop" }` to any collection to make its entries purchasable. Shop data lives in `shop_products` (keyed by entry_id FK cascade), never in entry JSON
+- Runtime `schema.ts` generator — auto-emits `src/lib/cms/runtime/schema.ts` combining core + auth + shop tables; point your `drizzle.config.ts` schema field at it, then `pnpm drizzle-kit push`
+- Entry edit panel shows Shop section with net/gross toggle + live VAT preview; optional variants (auto default variant when disabled) and per-variant stock
+- Shop admin: list of all shoppable entries across collections, list+drag-n-drop reorder for shipping methods, full orders list + detail with status history, change status, resend status email
+- Headless cart (signed cookie) with server-hydrated totals — `POST/PATCH/DELETE /api/shop/cart` + typed `createShopClient()` SDK
+- Checkout endpoint `POST /api/shop/checkout` — creates order from cart with consent validation, stock reservation (30-min TTL, released on cancel/reject, consumed on paid), and status emails
+- Payment adapter interface + `manualAdapter()` for bank transfer / COD (order stays in `awaitingPayment` until admin marks paid)
+- Shipping methods — admin CRUD with free-above threshold, carrier-agnostic (InPost/Stripe etc. slotted as adapters in later 0.15.x patches)
+- Feature flags `variants`, `stock`, `accounts` — off by default; enable per project
+- Rate-limit middleware on checkout + webhook endpoints
+- Status-change emails rendered inline (PL/EN), sent via existing `EmailAdapter` — no new dependency
+- Order numbers: random Crockford base32 (`XXXXX-XXXXX`) — unguessable
+- CLI scaffold includes all shop routes (admin pages + public API stubs) — run `scaffoldAdmin()` to provision them in your consumer app
+- `nodemailerAdapter` — `transportOptions` now typed as full `SMTPTransport.Options`, unlocking OAuth2 (Gmail etc.), pooled connections and all native Nodemailer options
+
+### Notes
+
+Headless e-commerce MVP. Stripe (0.15.1), PayU (0.15.2) and InPost geowidget (0.15.3) ship as optional adapters in follow-up patches. Consumer UI (cart drawer, checkout forms, success screens) is built in the app — shop only exposes the API and admin.
+
 ## 0.14.6 — 2026-04-13
 
 Admin page titles — meaningful <title> in every admin route

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.14.6)
+# Includio CMS Documentation (v0.15.1)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 
@@ -3240,6 +3240,10 @@ interface SendMailOptions {
 
 ## Built-in: Nodemailer
 
+`transportOptions` accepts the full Nodemailer `SMTPTransport.Options` type, so anything Nodemailer supports works — classic SMTP, OAuth2, pooled connections, TLS options, etc.
+
+### SMTP with user/password
+
 ```typescript
 import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
 
@@ -3257,6 +3261,46 @@ email: nodemailerAdapter({
 })
 ```
 
+### OAuth2 (generic)
+
+```typescript
+email: nodemailerAdapter({
+  defaultFromAddress: 'noreply@example.com',
+  defaultFromName: 'My Site',
+  transportOptions: {
+    host: 'smtp.example.com',
+    port: 465,
+    secure: true,
+    auth: {
+      type: 'OAuth2',
+      user: 'noreply@example.com',
+      clientId: process.env.OAUTH_CLIENT_ID,
+      clientSecret: process.env.OAUTH_CLIENT_SECRET,
+      refreshToken: process.env.OAUTH_REFRESH_TOKEN
+    }
+  }
+})
+```
+
+### OAuth2 (Gmail)
+
+```typescript
+email: nodemailerAdapter({
+  defaultFromAddress: 'noreply@gmail.com',
+  defaultFromName: 'My Site',
+  transportOptions: {
+    service: 'gmail',
+    auth: {
+      type: 'OAuth2',
+      user: 'noreply@gmail.com',
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+      refreshToken: process.env.GOOGLE_REFRESH_TOKEN
+    }
+  }
+})
+```
+
 > **Transactional Email:** For production, use a transactional email service (SendGrid, Postmark, Resend, etc). Implement the `EmailAdapter` interface with their SDK.
 
 ## Custom Adapter Example
@@ -4253,6 +4297,236 @@ Options for `create`/`createAndPublish`: `{ skipValidation?, sortOrder?, lang? }
 > **Delete Restrictions:** Only archived entries can be permanently deleted. Call `archive` first, then `delete`.
 
 
+---
+
+# Shop
+
+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.
+
+## 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`.
+- **Webhook infrastructure** — `createPaymentWebhookHandler()` dispatches provider callbacks, verifies signatures, is idempotent.
+- **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).
+
+## Config
+
+```ts
+import { defineShop, manualAdapter, payuAdapter } from 'includio-cms/shop';
+
+export const cmsConfig = defineCMS({
+  shop: defineShop({
+    currency: 'PLN',
+    vatRates: [23, 8, 0],
+    orderViewUrl: `${process.env.PUBLIC_URL}/shop/order/{orderNumber}?token={accessToken}`,
+    payment: [
+      manualAdapter({ id: 'transfer', label: { pl: 'Przelew', en: 'Bank transfer' } }),
+      payuAdapter({
+        posId: process.env.PAYU_POS_ID!,
+        clientId: process.env.PAYU_CLIENT_ID!,
+        clientSecret: process.env.PAYU_CLIENT_SECRET!,
+        secondKey: process.env.PAYU_SECOND_KEY!,
+        environment: 'sandbox',
+        notifyUrl: `${process.env.PUBLIC_URL}/api/shop/webhooks/payu`
+      })
+    ],
+    features: { variants: true, stock: true },
+    consents: [{ id: 'terms', required: true, labelI18n: { pl: 'Akceptuję regulamin', en: 'I accept terms' } }]
+  })
+})
+```
+
+## Routes
+
+Scaffold provisions these endpoints in your app:
+
+| Path | Handler | Purpose |
+|------|---------|---------|
+| `POST /api/shop/cart` | `createCartHandler()` | Cart CRUD |
+| `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 |
+| `POST /api/shop/orders/[number]/refresh-payment` | `createRefreshPaymentHandler()` | Pull status from provider |
+| `POST /api/shop/orders/[number]/retry-payment` | `createRetryPaymentHandler()` | New payment attempt |
+| `POST /api/shop/webhooks/[provider]` | `createPaymentWebhookHandler()` | Provider callbacks |
+
+## See also
+
+- [Order view](/docs/shop/order-view) — generic `<OrderStatus>` component + headless helper
+- [Retry payment](/docs/shop/retry-payment) — lifecycle + endpoint
+
+
+---
+
+# Order view
+
+After checkout the customer needs a page that shows their order status, payment outcome, and retry options. Shop offers two paths — a batteries-included component for quick projects, and a headless helper for custom designs.
+
+## 1. Generic component (`<OrderStatus />`)
+
+Drop-in view with three visual states (awaiting payment / success / rejected), auto-polling, retry button, status timeline. Theme through CSS custom properties.
+
+```svelte
+<!-- src/routes/shop/order/[number]/+page.svelte -->
+<OrderStatus {number} {token} />
+```
+
+### Theming
+
+All styling sits on CSS variables — override in your page or app.css:
+
+```css
+.aria-order-status {
+  --shop-bg: #171717;
+  --shop-fg: #f2e9e1;
+  --shop-muted: rgba(242, 233, 225, 0.6);
+  --shop-accent: #f2e9e1;
+  --shop-success: #8fb58c;
+  --shop-error: #c44b4b;
+  --shop-border: rgba(242, 233, 225, 0.15);
+  --shop-radius: 2px;
+  --shop-font-display: 'Syncopate', sans-serif;
+  --shop-font-body: 'Figtree', sans-serif;
+}
+```
+
+Fine-grained overrides via `part="..."` selectors:
+
+```css
+.aria-order-status::part(title) { text-transform: uppercase; }
+.aria-order-status::part(btn-retry) { letter-spacing: 0.08em; }
+```
+
+### Props
+
+| Prop | Type | Notes |
+|------|------|-------|
+| `number` | `string` | Order number (from URL) |
+| `token` | `string?` | Access token from `?token=`; falls back to cookie |
+| `initialData` | `OrderDetailResponse?` | SSR snapshot from `+page.server.ts` |
+| `labels` | `Partial<OrderStatusLabels>` | Override copy (Polish by default) |
+| `autoPoll` | `boolean` | Default `true` — polls every 5s when status is `awaitingPayment` |
+| `onPaid` | `(data) => void` | Fires the first time status becomes `paid` |
+
+### SSR
+
+Fetch on the server for instant render and email-from-SPA support:
+
+```ts
+// +page.server.ts
+import { createShopClient } from 'includio-cms/shop/client';
+import { readOrderTokenCookie } from 'includio-cms/shop/client'; // exposed from shop module
+
+export const load = async ({ params, url, cookies, fetch }) => {
+  const client = createShopClient({ fetch });
+  const token = url.searchParams.get('token') ?? undefined;
+  try {
+    const initialData = await client.orders.get(params.number, token);
+    return { initialData, token };
+  } catch {
+    return { initialData: null, token };
+  }
+};
+```
+
+## 2. Custom UI (headless)
+
+For fully custom designs, use `createOrderState` — a reactive Svelte 5 state object. Build whatever markup you want.
+
+```svelte
+{#if order.loading && !order.data}
+  <p>Ładowanie…</p>
+{:else if order.data}
+  {@const o = order.data.order}
+  <h1>Zamówienie {o.number}</h1>
+  <p>Status: {o.status}</p>
+
+  {#if o.status === 'awaitingPayment' || o.status === 'paymentRejected'}
+    <button onclick={handleRetry} disabled={order.phase === 'retrying'}>
+      Zapłać ponownie
+    </button>
+  {/if}
+{/if}
+```
+
+### State API
+
+- `order.data` — `OrderDetailResponse | null`
+- `order.loading` — initial fetch flag
+- `order.error` — last error (`Error | null`)
+- `order.phase` — `'idle' | 'polling' | 'retrying' | 'refreshing'`
+- `order.status` — shorthand for `data.order.status`
+- `order.load()` — fetch fresh data
+- `order.refreshPayment()` — ask provider for latest (useful if webhook is lost)
+- `order.retry()` — create new payment attempt, returns `redirectUrl | null`
+- `order.startPolling() / stopPolling()` — auto-refresh every 5s (max 2min), stops on terminal status
+- `order.dispose()` — clear timers (call in `onDestroy`)
+
+## Security
+
+- Every order has an `accessToken` (uuid). The view API (`/api/shop/orders/[number]`) requires it in `?token=` or in the `aria_shop_order` cookie (same-browser fallback, 30-min httpOnly).
+- Status emails include the full URL with token — the customer can return from any device.
+- Order numbers are Crockford base32 but token-gating prevents enumeration regardless.
+
+
+---
+
+# Retry payment
+
+When a payment attempt is rejected or left hanging, the customer must be able to try again without going through checkout a second time.
+
+## Lifecycle
+
+1. Customer completes checkout → order created with status `awaitingPayment`, adapter creates a payment session, `paymentProviderRef` stored.
+2. Something goes wrong — customer cancels on gateway, card declined, session expires → webhook flips status to `paymentRejected` (or stays `awaitingPayment` if the gateway never called back).
+3. Customer hits "Zapłać ponownie" on the order view.
+4. `POST /api/shop/orders/[number]/retry-payment?token=...` →
+   - token-gated, status must be `awaitingPayment` or `paymentRejected` (409 otherwise)
+   - adapter's `createPayment()` is called again with the same `OrderRef`
+   - new `paymentProviderRef` replaces the old one
+   - if coming from `paymentRejected`, status rolls back to `awaitingPayment` (logged in status history as `changedBy: 'retry-payment'`)
+   - response contains `redirectUrl` for the new gateway session
+
+## SDK
+
+```ts
+import { createShopClient } from 'includio-cms/shop/client';
+
+const client = createShopClient();
+const result = await client.orders.retryPayment(orderNumber, token);
+
+if (result.requiresPaymentRedirect && result.redirectUrl) {
+  window.location.href = result.redirectUrl;
+}
+```
+
+## With `createOrderState`
+
+The headless helper handles the redirect for you — it returns the URL, you navigate:
+
+```ts
+const url = await order.retry();
+if (url) window.location.href = url;
+```
+
+## Constraints
+
+- The same order is reused — numbers, tokens, items, totals stay the same.
+- Terminal statuses (`paid`, `done`, `cancelled`) block retry with **409**.
+- Orders without a payment method or whose adapter was removed from config return **400**.
+- Adapter errors bubble up as **502**.
+
+## Admin override
+
+If the customer is completely stuck, the admin can manually move the order to `paid` / `cancelled` from the orders detail page — same as before, status-change emails trigger automatically.
+
+
 ---
 
 # Migration Guide

package/ROADMAP.md

@@ -287,14 +287,35 @@
 - [x] `[feature]` `[P2]` Manual poster regeneration in media library file details <!-- files: src/lib/core/server/media/operations/regenerateVideoPoster.ts, src/lib/admin/components/media/file/file-details.svelte -->
 - [x] `[feature]` `[P2]` Config flag `sidebarHelp` to hide admin sidebar Help link (default true) <!-- files: src/lib/types/cms.ts, src/lib/core/cms.ts, src/routes/admin/(afterLogin)/+layout.server.ts, src/lib/admin/components/layout/nav-footer.svelte -->
 
-## 0.15.0 — SEO module
+## 0.15.0 — Shop MVP (headless e-commerce)
+
+- [x] `[feature]` `[P0]` Scaffold: `defineShop`, types, CMSConfig slot, package export `./shop` <!-- files: src/lib/shop/index.ts, src/lib/shop/types.ts -->
+- [x] `[feature]` `[P0]` Drizzle tables: products (entry-backed), variants, orders, order items, status history, payments, shipping methods, stock reservations <!-- files: src/lib/db-postgres/schema/shop/ -->
+- [x] `[feature]` `[P0]` Runtime `schema.ts` generator for drizzle-kit (core + auth + optional shop) <!-- files: src/lib/core/server/generator/generator.ts, src/lib/db-postgres/schema-core.ts, src/lib/db-postgres/schema-shop.ts -->
+- [x] `[feature]` `[P0]` Rate-limit middleware (checkout/webhook) <!-- files: src/lib/shop/rate-limit.ts -->
+- [x] `[feature]` `[P0]` Built-in `shop` field type — makes entries purchasable, auto-hydrated via populateEntryData <!-- files: src/lib/admin/components/fields/shop-field.svelte, src/lib/shop/server/populate.ts -->
+- [x] `[feature]` `[P0]` Net/gross price toggle + live VAT preview in shop field and shipping form
+- [x] `[feature]` `[P0]` Auto default variant on upsert — cart/order always reference variantId
+- [x] `[feature]` `[P0]` Shop admin: products list (JOIN entries × shop_products), shipping methods CRUD with drag-n-drop reorder + free-above threshold
+- [x] `[feature]` `[P0]` Cart (signed cookie) service + `/api/shop/cart` REST + headless SDK `createShopClient()` <!-- files: src/lib/shop/cart/, src/lib/shop/client/ -->
+- [x] `[feature]` `[P0]` Orders + checkout + `manualAdapter` + status emails (inline HTML, PL/EN) <!-- files: src/lib/shop/server/orders.ts, src/lib/shop/http/checkout-handler.ts -->
+- [x] `[feature]` `[P0]` Stock reservation with 30-min TTL — released on cancel/reject, consumed on paid
+- [x] `[feature]` `[P0]` Admin orders view — list (status + email filter), detail (items, history, customer/address/consents, change status, resend email)
+- [x] `[feature]` `[P0]` Random Crockford base32 order numbers (`XXXXX-XXXXX`), unguessable
+- [x] `[feature]` `[P0]` CLI scaffold provisions all shop routes (admin + public API) in consumer app
+- [x] `[feature]` `[P1]` PayU payment adapter + webhook — shipped in 0.15.1 (access-token-gated order view, idempotent webhooks, MD5 signature, shipping↔payment compat, poll fallback)
+- [ ] `[feature]` `[P1]` Stripe payment adapter + webhook — deferred to 0.15.2
+- [ ] `[feature]` `[P2]` InPost carrier adapter (headless geowidget config) — deferred to 0.15.3
+- [x] `[feature]` `[P2]` `nodemailerAdapter` — typowanie `transportOptions` jako `SMTPTransport.Options` (OAuth2, pool, itd.)
+
+## 0.16.0 — SEO module
 
 - [ ] `[feature]` `[P1]` SERP preview + character limits for title/description <!-- files: src/lib/admin/components/fields/seo-field.svelte -->
 - [ ] `[feature]` `[P1]` Global SEO settings
 - [ ] `[feature]` `[P1]` Dedicated frontend SEO components <!-- files: src/lib/sveltekit/components/seo.svelte -->
 - [ ] `[feature]` `[P2]` Sitemap generation
 
-## 0.16.0 — WCAG/ATAG compliance
+## 0.17.0 — WCAG/ATAG compliance
 
 - [ ] `[chore]` `[P0]` Full WCAG/ATAG audit
 - [ ] `[feature]` `[P0]` Accessibility rework based on audit findings