includio-cms 0.26.0 → 0.28.0

package/API.md

@@ -1,8 +1,8 @@
-# includio-cms — Public API v0.26.0
+# includio-cms — Public API v0.28.0
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
-Entry points: **18** · Stable: **413** · Experimental: **2**
+Entry points: **18** · Stable: **464** · Experimental: **4**
 
 Tags:
 - `@public` — frozen for v1.0; semver-protected.
@@ -75,10 +75,14 @@ Tags:
 - `interface FormSubmission`
 - `interface FormTextareaField`
 - `interface FormTextField`
+- `interface IconDefinition`
+- `interface IconField`
 - `type IconName = keyof typeof iconMap`
+- `interface IconSetPlugin`
 - `interface ImageFieldData`
 - `interface ImageFieldStyle`
 - `interface ImageStyle`
+- `isIconSetPlugin(p: Plugin): p is IconSetPlugin` — Type guard for {@link IconSetPlugin}.
 - `type Language = 'en' | 'pl'`
 - `type Layout = LayoutPreset | LayoutNode[]`
 - `type LayoutNode = | SectionNode | ColumnsNode | CardNode | AccordionNode | StackNode | TabsNode | TabNode`
@@ -93,6 +97,7 @@ Tags:
 - `interface NumberField`
 - `interface ObjectField`
 - `type ObjectFieldData = { _id?: string; _slug?: string; } & Record<string, unknown>`
+- `type Plugin = PluginConfig | IconSetPlugin`
 - `interface RadioField`
 - `interface RelationField`
 - `type RelationFieldData = string | string[]`
@@ -132,6 +137,7 @@ Tags:
 - `const AdminLayout: LegacyComponentType`
 - `const Badge: LegacyComponentType`
 - `buildCustomFieldsMap(...plugins: PluginConfig[]): Map<string, CustomFieldDefinition>` — Build a Map<fieldType, CustomFieldDefinition> from plugin configs.
+- `buildIconSetMap(...plugins: IconSetPlugin[]): Map<string, IconSetPlugin>` — Build a Map<slug, IconSetPlugin> from icon-set plugin instances.
 - `const Button: LegacyComponentType`
 - `Card`
 - `const CollectionPage: LegacyComponentType`
@@ -143,6 +149,7 @@ Tags:
 - `const FormSubmissionPage: LegacyComponentType`
 - `getContentLanguage`
 - `getCustomFields(): Map<string, CustomFieldDefinition>`
+- `getIconSets(): Map<string, IconSetPlugin>`
 - `getLocalizedLabel(label: Localized | undefined, lang: InterfaceLanguage): string`
 - `getRemotes(): typeof remotes`
 - `const Input: LegacyComponentType`
@@ -152,6 +159,7 @@ Tags:
 - `const MediaPage: LegacyComponentType`
 - `const MediaSelector: LegacyComponentType`
 - `const ResetPasswordPage: LegacyComponentType`
+- `resolveIconSet(slug?: string): IconSetPlugin | null` — Resolve a single icon set: explicit `slug` (from {@link IconField.set}) takes
 - `const Separator: LegacyComponentType`
 - `const ShippingMethodEditPage: LegacyComponentType`
 - `const ShippingMethodNewPage: LegacyComponentType`
@@ -193,6 +201,7 @@ Tags:
 - `const exportOrdersCsv: <inferred>`
 - `const findMediaReferences: <inferred>`
 - `const generateAltText: <inferred>`
+- `const generateBalanceLinkForOrder: <inferred>`
 - `const getAltOverview: <inferred>`
 - `const getCollection: <inferred>`
 - `const getCollections: <inferred>`
@@ -214,6 +223,7 @@ Tags:
 - `const getMediaTags: <inferred>`
 - `const getMediaTagsWithCounts: <inferred>`
 - `const getOrderForAdmin: <inferred>`
+- `const getOrderInvoiceAdmin: <inferred>`
 - `const getOrderRefundsAdmin: <inferred>`
 - `const getRawEntries: <inferred>`
 - `const getRawEntry: <inferred>`
@@ -227,6 +237,7 @@ Tags:
 - `const getSingles: <inferred>`
 - `const getSubmissionsOverview: <inferred>`
 - `const isAIAvailable: <inferred>`
+- `const issueInvoiceCmd: <inferred>`
 - `const listCouponsAdmin: <inferred>`
 - `const listOrdersAdmin: <inferred>`
 - `const listShippingMethodsAdmin: <inferred>`
@@ -289,6 +300,7 @@ Tags:
 - `cmsLayoutLoad(event: RequestEvent): <inferred>` — Returns `cmsContext` from `event.locals` for use in a SvelteKit layout
 - `countEntries(opts: CountEntriesOptions): Promise<number>` — Count entries matching the same filters as `resolveEntries`, without
 - `type CountEntriesOptions = Omit< ResolveEntriesOptions, 'limit' | 'offset' | 'populate' | 'orderBy' | 'dataOrderBy' >`
+- `createAdminApiHandler(options?: AdminApiOptions): <inferred>`
 - `const createConsentLog: <inferred>`
 - `const createFormSubmission: <inferred>`
 - `createRestApiHandler(): <inferred>` — REST API handler factory. Returns `{ GET, POST, PUT, DELETE }`
@@ -327,9 +339,13 @@ Tags:
 - `const shopCouponRedemptionsTable: <inferred>`
 - `const shopCouponsTable: <inferred>`
 - `type ShopCouponType = 'percent' | 'fixed'`
+- `const shopInvoicesTable: <inferred>`
+- `type ShopInvoiceStatus = 'pending' | 'issued' | 'sent' | 'failed'`
 - `const shopOrderItemsTable: <inferred>`
 - `const shopOrdersTable: <inferred>`
 - `const shopOrderStatusHistoryTable: <inferred>`
+- `type ShopPaymentKind = 'full' | 'deposit' | 'balance'`
+- `const shopPaymentKindEnum: <inferred>`
 - `const shopPaymentsTable: <inferred>`
 - `type ShopPaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded' | 'cancelled'`
 - `const shopProductsTable: <inferred>`
@@ -365,9 +381,13 @@ Tags:
 - `const shopCouponRedemptionsTable: <inferred>`
 - `const shopCouponsTable: <inferred>`
 - `type ShopCouponType = 'percent' | 'fixed'`
+- `const shopInvoicesTable: <inferred>`
+- `type ShopInvoiceStatus = 'pending' | 'issued' | 'sent' | 'failed'`
 - `const shopOrderItemsTable: <inferred>`
 - `const shopOrdersTable: <inferred>`
 - `const shopOrderStatusHistoryTable: <inferred>`
+- `type ShopPaymentKind = 'full' | 'deposit' | 'balance'`
+- `const shopPaymentKindEnum: <inferred>`
 - `const shopPaymentsTable: <inferred>`
 - `type ShopPaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded' | 'cancelled'`
 - `const shopProductsTable: <inferred>`
@@ -397,19 +417,36 @@ Tags:
 - `interface CouponRef`
 - `type Currency = 'PLN'`
 - `defineShop(config: ShopConfig): ResolvedShopConfig`
+- `type DepositAmount = { type: 'percent'; value: number } | { type: 'amount'; value: number }` — Deposit amount specifier. `percent` charges `floor(base * value / 100)` of
+- `fakturowniaAdapter(opts: FakturowniaAdapterOptions): InvoicingAdapter` — Invoicing adapter backed by Fakturownia (fakturownia.pl). Issues a paid VAT
+- `interface FakturowniaAdapterOptions`
+- `filterUpcoming(variants: T[], config: VariantExpiryConfig | null, now?: Date): T[]` — Return the subset of `variants` that have not yet expired. Order is
 - `type GeowidgetConfigPreset = 'parcelcollect' | 'parcelsend' | 'parcelcollect247' | string`
 - `type I18nText = { [lang: string]: string; }`
 - `inpostAdapter(opts: InpostAdapterOptions): CarrierAdapter`
 - `interface InpostAdapterOptions`
 - `type InpostEnvironment = 'production' | 'sandbox'` — InPost Points API — public, no auth required. Used to validate that a parcel
 - `interface InpostSenderAddress`
+- `interpolateTemplate(template: string, vars: Record<string, unknown>, locale: string): string` — String interpolation engine used by `defineShop({ variantLabel.template })`
+- `class InvalidVariantAttributesError`
+- `interface InvoiceBuyer`
+- `interface InvoiceContext`
+- `interface InvoiceCreateResult`
+- `type InvoiceIssuePolicy = 'b2bAndOnRequest' | 'always'` — When an invoice should be issued automatically after an order is fully paid.
+- `interface InvoiceLineItem`
+- `interface InvoicePayload`
+- `interface InvoicingAdapter` — Adapter that issues invoices with an external provider (e.g. Fakturownia).
+- `isValidNip(nip: string): boolean` — Validate a Polish NIP (tax id) — 10 digits with a weighted checksum.
+- `isVariantExpired(variant: VariantLike, config: VariantExpiryConfig | null, now: Date = new Date(Date.now())): boolean` — Check whether a variant has expired under the given config. Fail-open by
 - `manualAdapter(opts: ManualPaymentAdapterOptions = {}): PaymentAdapter` — Manual payment adapter — order goes to awaitingPayment, admin marks as paid later
 - `interface OrderRef`
 - `type OrderStatus = | 'new' | 'awaitingPayment' | 'paid' | 'preparing' | 'sent' | 'done' | 'cancelled' | 'paymentReje...`
+- `interface PartialPayment` — Persisted partial-payment summary on `order.partialPayment` when the order
 - `interface PaymentAdapter`
 - `interface PaymentCreateContext`
 - `interface PaymentCreateResult`
 - `interface PaymentEvent`
+- `type PaymentPolicy = { type: 'full' } | { type: 'deposit'; depositAmount: DepositAmount }` — Per-product payment policy. `full` (default) charges the full order total
 - `interface PaymentRefundInput`
 - `interface PaymentRefundResult`
 - `payuAdapter(opts: PayuAdapterOptions): PaymentAdapter`
@@ -422,6 +459,18 @@ Tags:
 - `interface ShopFeatures`
 - `stripeAdapter(opts: StripeAdapterOptions): PaymentAdapter` — Stripe payment adapter (Checkout Session flow).
 - `interface StripeAdapterOptions`
+- `type VariantAttribute = | VariantAttributeText | VariantAttributeNumber | VariantAttributeDatetime | VariantAttributeSele...` — Schema descriptor for one product-variant attribute (city, startsAt, …).
+- `interface VariantAttributeBoolean`
+- `interface VariantAttributeDatetime`
+- `interface VariantAttributeEntry`
+- `interface VariantAttributeImage`
+- `interface VariantAttributeNumber`
+- `interface VariantAttributeSelect`
+- `interface VariantAttributeSlug`
+- `interface VariantAttributeText`
+- `class VariantExpiredError` — Thrown by `createOrderFromCart` / cart-add HTTP guard when a referenced
+- `interface VariantExpiryConfig` — Opt-in storefront filter that hides variants whose datetime attribute
+- `interface VariantLabelConfig` — Template used to auto-generate `variant.name` from `variantAttributes`.
 
 ### `includio-cms/shop/client`
 
@@ -440,11 +489,13 @@ Tags:
 - `type OrderState = OrderStateImpl`
 - `const OrderStatus: LegacyComponentType`
 - `interface OrderStatusLabels`
+- `interface PayBalanceResult` — Result of `orders.payBalance` — initiates a payment session for the
 - `interface RefreshPaymentResult`
 - `interface RetryPaymentResult`
 - `interface ShippingMethodPublic`
 - `interface ShopClient` — Headless shop SDK surface returned by `createShopClient()`.
 - `interface ShopClientOptions` — Options for `createShopClient()`.
+- `interface VariantPublic` — Public-facing variant row returned by `client.products.listUpcoming`.
 
 ### `includio-cms/shop/http`
 
@@ -484,3 +535,8 @@ Tags:
 
 - `interface CustomFieldDefinition` — Defines a custom field type contributed by a plugin.
 - `interface PluginConfig` — CMS plugin configuration — register custom field types and CRUD lifecycle hooks.
+
+### `includio-cms/shop/http`
+
+- `createBalanceHandler(): { GET: RequestHandler; POST: RequestHandler }`
+- `createUpcomingVariantsHandler(): { GET: RequestHandler }` — Build a SvelteKit `GET` handler for upcoming variants of a single product.

package/CHANGELOG.md

@@ -3,6 +3,111 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.28.0 — 2026-06-01
+
+Fakturowanie — integracja sklepu z Fakturownią: automatyczne wystawianie i wysyłka faktury po opłaceniu zamówienia. Nowy generyczny `InvoicingAdapter` (spójny z payment/carrier) + `fakturowniaAdapter()` jako pierwsza implementacja. Faktura wystawiana fire-and-forget gdy zamówienie jest w pełni opłacone (`!balanceOwed` — zaliczki czekają na dopłatę balansu), wysyłana przez Fakturownię (`send_by_email`). Trigger konfigurowalny per-adapter (`issueWhen`: `b2bAndOnRequest` domyślnie / `always`). Checkout zbiera dane B2B (NIP z twardą walidacją sumy kontrolnej, nazwa firmy, adres do faktury, opt-in „chcę fakturę"). Idempotencja przez `shop_invoices` (unikat per zamówienie); ręczny retry w adminie. Additive only — żadnych breaking zmian.
+
+### Added
+- `defineShop({ invoicing })` (`includio-cms/shop`) — nowy opcjonalny slot adaptera fakturowania, analogiczny do `payment` / `carriers`. `InvoicingAdapter { id, issueWhen?, createInvoice(payload, ctx), send?(externalId, ctx) }` + typy payloadu (`InvoicePayload`, `InvoiceBuyer`, `InvoiceLineItem`, `InvoiceCreateResult`, `InvoiceContext`, `InvoiceIssuePolicy`) wyeksportowane jako `@public` z `includio-cms/shop`.
+- `fakturowniaAdapter({ domain, apiToken, kind?, issueWhen?, sendEmail? })` (`includio-cms/shop`, `@public`) — adapter dla Fakturowni (fakturownia.pl). `createInvoice` mapuje zamówienie na fakturę VAT oznaczoną jako opłacona (`paid_date` = data potwierdzenia płatności), `send` woła `send_by_email` (domyślnie włączone). Numeracja i dane sprzedawcy zarządzane po stronie konta Fakturowni. Sekret `apiToken` przekazywany przez konsumenta z `$env/dynamic/private` (jak `STRIPE_SECRET_KEY`).
+- Auto-faktura po opłaceniu — `maybeIssueInvoiceForOrder(orderId)` (`$lib/shop/server/invoices.ts`) wołane fire-and-forget z `updateOrderStatus` (przy `paid`) oraz z `markBalancePaid` (po dopłacie balansu). Fail-open: błąd providera nie blokuje webhooka płatności. Guard wystawia fakturę tylko gdy zamówienie w pełni opłacone (`status ∈ {paid, preparing, sent, done}` && `!balanceOwed`) — deposit czeka na dopłatę.
+- Konfigurowalny trigger `issueWhen`: `b2bAndOnRequest` (domyślny — faktura gdy podano NIP lub zaznaczono „chcę fakturę") albo `always` (każde opłacone zamówienie, np. dla klienta wymagającego faktur również dla osób fizycznych).
+- `shop_invoices` (nowa tabela) — jedna faktura per zamówienie (`order_id` UNIQUE → idempotencja). Pola `status` (`pending`/`issued`/`sent`/`failed`), `external_id`, `number`, `pdf_url`, `attempts`, `next_retry_at`, `last_error`, `raw`. Kolumny `attempts`/`next_retry_at` zarezerwowane pod przyszły automatyczny retry (obecnie tylko ręczny).
+- Checkout B2B — `shop_orders` dostaje kolumny `customer_nip`, `customer_company_name`, `billing_address` (jsonb), `invoice_requested` (boolean). `createOrderFromCart` / `checkout-handler` przyjmują i zapisują te pola; `CheckoutInput` (`includio-cms/shop/client`) rozszerzony. Storefront form (pola NIP/firma/checkbox/adres) = warstwa konsumenta.
+- `isValidNip(nip)` (`includio-cms/shop`, `@public`) — twarda walidacja polskiego NIP (10 cyfr + suma kontrolna, wagi `[6,5,7,2,3,4,5,6,7]`). Checkout odrzuca nieprawidłowy NIP (400) zanim trafi do bazy — Fakturownia odrzuciłaby błędny NIP, a faktura idzie dalej do KSeF, więc walidujemy u źródła.
+- `getOrderInvoiceAdmin` (query) + `issueInvoiceCmd` (command) — admin remote functions (`includio-cms/admin/remote`). `shop-order-detail-page.svelte` zyskuje sekcję „Faktura": numer, link do PDF, status, przycisk „Wystaw fakturę" / „Wystaw ponownie" (ręczny retry, `force`). Auth-protected (`requireAuth`).
+
+### Migration
+
+```sql
+CREATE TABLE IF NOT EXISTS shop_invoices (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id uuid NOT NULL UNIQUE REFERENCES shop_orders(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  external_id text,
+  number text,
+  pdf_url text,
+  kind text NOT NULL DEFAULT 'vat',
+  status text NOT NULL DEFAULT 'pending',
+  attempts integer NOT NULL DEFAULT 0,
+  next_retry_at timestamptz,
+  last_error text,
+  raw jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS customer_nip text;
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS customer_company_name text;
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS billing_address jsonb;
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS invoice_requested boolean NOT NULL DEFAULT false;
+```
+
+## 0.27.0 — 2026-05-29
+
+Shop platformowy — Fazy 1 + 2 + 3 + 4 + 5: schema-driven `variantAttributes` (typed `defineShop` schema, Zod walidacja, GIN index helper, ts-gen typed `variant.attributes`) + admin renderer per attribute type + `variantLabel.template` interpolacja z admin auto-prefill nazwy wariantu + `variantExpiry` opt-in (storefront filter, cart/checkout guard, admin "Zakończony" badge) + `paymentPolicy` A-lite (deposit + balance + signed token + refund per kind + admin balance link + per-kind refund dialog). Faza 6 envet pilot (consumer-side end-to-end QA: szkolenia variants + deposit flow + balance link — nie wymaga zmian w core). Post-Faza-5 hot-fixy uwzględnione w tym wydaniu (single release, nie patch): datetime walidator z offsetem, auto-detect deposit kind przy admin manual mark-paid, admin paymentPolicy UI + preserve-on-undefined w upsert. Additive only — żadnych breaking zmian. Plan: `/Users/patryk/.claude/plans/implementacja-ariacms-0-27-partitioned-kahn.md`.
+
+### Added
+- `defineShop({ variantAttributes })` (`includio-cms/shop`) — typed schema dla atrybutów wariantu: `text | number | datetime | select | boolean | image | entry | slug` z polami `{ type, label, required?, indexable?, options?, entryCollection? }`. Zostaje jedno źródło prawdy: napędza Zod walidację, ts-gen typings, GIN index utility oraz renderer admin form.
+- `VariantAttribute` + per-type interfejsy (`VariantAttributeText/Number/Datetime/Select/Boolean/Image/Entry/Slug`) wyeksportowane jako `@public` z `includio-cms/shop`.
+- `InvalidVariantAttributesError` (code `INVALID_VARIANT_ATTRIBUTES`) — rzucany przez `upsertShopData` gdy `variant.attributes` nie pasują do schemy. Eksport publiczny z `includio-cms/shop`.
+- `runtime/types.ts` — pole `shop` w entry typings generuje teraz typed `variant.attributes` (`{ city: string; startsAt: string; online?: boolean; level: 'basic' | 'advanced' }`) zamiast `Record<string, string>` gdy `defineShop` ma `variantAttributes`. Brak `variantAttributes` = poprzednie `Record<string, string> | null` (backwards-compatible).
+- `createVariantAttributeIndexes(attrs)` w `$lib/db-postgres/schema/shop/productVariant.ts` — zwraca `CREATE INDEX IF NOT EXISTS shop_variant_attr_<key>_gin_idx ON shop_product_variants USING gin ((attributes->'<key>'))` DDL per atrybut z `indexable: true`. Wymusza safe SQL identifier dla klucza (`[A-Za-z][A-Za-z0-9_]*`).
+- `applyVariantAttributeIndexes(shop, db)` w `$lib/shop/server/init.ts` — idempotentny serialized applier indeksów GIN. `initCMS()` odpala go automatycznie fire-and-forget gdy shop jest skonfigurowany (zero ręcznych hooków u konsumenta). `cms.shopInitPromise` wystawiony jako `@internal` punkt synchronizacji dla testów.
+- `VariantAttributeRenderer.svelte` (NEW, `$lib/admin/components/variant-form/`) — switch po `attr.type`, deleguje do field components z `$lib/admin/components/fields/` (text/number/datetime/select/boolean) lub renderuje prosty Input dla slug/image/entry (pełny picker UI dla image/entry defer post-1.0).
+- `shop-field.svelte` (admin variant editor) — variant row pokazuje siatkę atrybutów (responsywna 1/2-col) ponad legacy polami (nazwa/SKU/delta/stock) gdy `shopConfig.variantAttributes` ma wpisy. Brak attrs = legacy behavior bez zmian. Hydratacja + save propaguje `variant.attributes` jako `Record<string, unknown>`.
+- `getShopConfig` remote (admin) — response zawiera teraz `variantAttributes` z `ResolvedShopConfig`, dzięki czemu `shop-field` może lokalnie renderować typed atrybuty bez dodatkowego round-tripa.
+- `upsertShopDataForEntry` (admin remote command) — input schema dla `variant.attributes` zluzowany do `z.record(z.string(), z.unknown())`; typed shape egzekwowany serwerowo przez `validateVariantAttributes` (jedno źródło prawdy).
+- `defineShop({ variantLabel: { template } })` (`includio-cms/shop`) — opcjonalny szablon nazwy wariantu w składni `{key|filter:arg}`. Filtry: `date` (long/medium/short), `currency` (kod waluty, domyślnie PLN), `uppercase`. Nieznany klucz → pusty string + dev warn; nieznany filtr → passthrough; malformed template → surowy template + warn.
+- `interpolateTemplate(template, vars, locale)` (`includio-cms/shop`, `@public`) — silnik interpolacji wykorzystywany wewnętrznie przez admin do pre-fill `variant.name`, dostępny też publicznie dla konsumentów (np. storefront-side derived labels).
+- `VariantLabelConfig` eksportowany jako `@public` typ z `includio-cms/shop`.
+- `getShopConfig` remote response zawiera teraz `variantLabel: shop.variantLabel ?? null`.
+- `shop-field.svelte` (admin variant editor) — gdy `variantLabel.template` zdefiniowany, pole `Nazwa` auto-wypełnia się z interpolacji `variantAttributes` (locale `pl` w 0.27; multi-locale defer post-1.0). Per-variant dirty flag: po hydratacji z niepustym `name` lock = aktywny (nie nadpisujemy editor decision); ręczna edycja w polu `Nazwa` (`oninput`) trwale wyłącza pre-fill dla wariantu w bieżącej sesji.
+- `defineShop({ variantExpiry: { source, offsetDays } })` (`includio-cms/shop`, `@public`) — opt-in filtr wariantów time-bound (events, courses, szkolenia). `source` = klucz atrybutu typu `datetime`; `offsetDays` przesuwa cut-off (`0` = expire dokładnie gdy datetime hits now, `1` = jeden dzień grace, `-1` = jeden dzień przed). Globalny config — brak per-product override.
+- `isVariantExpired(variant, config, now?)` + `filterUpcoming(variants, config, now?)` (`includio-cms/shop`, `@public`) — fail-open helpers: `null` config / brak source attribute / non-string / malformed datetime → variant traktowany jako upcoming (z `console.warn` dla malformed w dev). `filterUpcoming` zachowuje order; sort source-asc realizowany na poziomie HTTP / admin osobno.
+- `VariantExpiredError` (code `VARIANT_EXPIRED`, `variantId`) — eksport `@public`. Rzucany przez `createOrderFromCart` w `server/orders.ts` przed stock reservation (idempotent guard).
+- `POST /api/shop/cart` (add) — preflight `VARIANT_EXPIRED` guard: kiedy `variantExpiry` jest skonfigurowany i variant ma expired source attribute, response 400 JSON `{ error: "VARIANT_EXPIRED", variantId }` bez aktualizacji cart cookie.
+- `createUpcomingVariantsHandler` (`includio-cms/shop/http`, `@experimental`) — nowy GET endpoint `/api/shop/products/[id]/variants/upcoming`. Zwraca `{ items: VariantPublic[] }` przefiltrowanych przez `filterUpcoming` + posortowanych ascendingly po `attributes.<source>` (Date.parse) gdy `variantExpiry` ustawiony, w insertion order gdy brak.
+- `client.products.listUpcoming(productId)` + `VariantPublic` (`includio-cms/shop/client`, `@public`) — nowy namespace SDK. Zwraca upcoming variants per produkt; zero-config passthrough kiedy `variantExpiry` nieustawiony.
+- `getShopConfig` remote (admin) — response zawiera teraz `variantExpiry: shop.variantExpiry ?? null`.
+- `shop-field.svelte` (admin variant editor) — gdy `variantExpiry` skonfigurowany: per-variant badge "Zakończony" (greyed-out, `bg-muted text-muted-foreground` z border), checkbox filter "Pokaż zakończone (N)" w toolbarze wariantów (default off, ukryty gdy zero expired), opacity-60 na expired row, sort wariantów po source ASC (closer terms first). Brak config = zero zmian w UI.
+- `PaymentPolicy` + `DepositAmount` + `PartialPayment` (`includio-cms/shop`, `@public`) — per-product policy `{ type: "full" } | { type: "deposit", depositAmount: { type: "percent" | "amount", value } }` ustawiana w `ShopFieldData.paymentPolicy`. Cart deposit-aware: order zachowuje pełen `totalGross`, `partialPayment.balanceAmount` = co zostaje do dopłaty, `balanceOwed = true` po zapłaconym depozycie. Walidacja: percent w (0, 100], amount = positive integer (minor units). `validatePaymentPolicy` wymusza to przy upsert produktu.
+- `resolvePaymentAmount(policy, lineGross)` + `computeDepositAmount(spec, base)` (`$lib/shop/server/payment-policy.ts`, server-internal — nie eksportowane z publicznego entry pointu) — silnik resolver per linia. `percent` flooruje `base * value / 100`; `amount` klampuje do `base`. Null / `full` policy → pełen `lineGross`, `kind = "full"`, balance 0. 15 spec testów + 10 integration.
+- `MixedPaymentPolicyError` (code `MIXED_PAYMENT_POLICY`) — `createOrderFromCart` odrzuca cart z więcej niż jednym produktem gdy którykolwiek z nich ma deposit policy. Decyzja: deposit orders span ONE product (refund-per-kind + balance link unambiguous). Cart all-`full` mixed-product nadal działa.
+- `shop_orders.partial_payment jsonb + balance_owed boolean` — nowe kolumny. `shop_payments.kind enum ("full" | "deposit" | "balance")` z default `"full"` — back-compat dla istniejących płatności. `shop_products.payment_policy jsonb` przechowuje per-product policy.
+- `shop_payments` zaczyna być aktywnie wypełniane: `checkout-handler` po `adapter.createPayment` insert payment row z odpowiednim `kind` (full lub deposit) + `providerRef`. Webhook handler matchuje (provider, providerRef) → branchuje per kind: `full`/`deposit` przepuszcza `updateOrderStatus(paid, paymentKind)`, `balance` bypasses status flow i woła `markBalancePaid` (stock przy depozycie już permanentnie potwierdzony).
+- `createOrderFromCart` CreateOrderResult: nowe pola `amountToPay` (deposit-aware kwota do pobrania na checkout) + `paymentKind` (`"full" | "deposit"`). `checkout-handler` przekazuje `amountToPay` do adaptera przez OrderRef.totalGross override — adaptery PayU/Stripe/manual działają bez zmian.
+- `generateBalanceToken` + `verifyBalanceToken` (`includio-cms/shop/server`, `@internal`) — HMAC-SHA256 nad JSON payload `{orderId, type: "balance"}`, encoding `base64url(payload).base64url(sig)`. Deterministic per (orderId, secret) — brak rotation, brak exp, server-side invalidation przez `order.balanceOwed === true`. Secret = `INCLUDIO_BALANCE_TOKEN_SECRET` env (≥16 chars, hard-fail przy brak gdy deposit policy aktywne). 8 spec testów (roundtrip, tampered, wrong orderId/secret, malformed, deterministic).
+- `createBalanceSession(orderNumber, token, ctx?)` (`includio-cms/shop/server`, `@experimental`) — customer flow: verify token + `balanceOwed`, reuse `order.paymentMethod` adapter, call `adapter.createPayment` z `amount = partialPayment.balanceAmount`, insert payment row `kind: "balance"`, mirror providerRef na order. `markBalancePaid` (idempotent) clears balanceOwed + bumps `paidAmount` do `totalGross`.
+- `createBalanceHandler` (`includio-cms/shop/http`, `@experimental`) — GET `/api/shop/orders/[number]/balance?token=...` zwraca minimalny widok ({orderNumber, currency, totalGross, amountToPay, paidAmount, paymentMethod, language}); POST inicjuje payment session ({status, redirectUrl, requiresPaymentRedirect}). 403 przy złym tokenie lub wyczyszczonym `balanceOwed`.
+- `client.orders.payBalance(orderNumber, token)` + `PayBalanceResult` (`includio-cms/shop/client`, `@public` / `@experimental`) — REST wrapper dla customer flow dopłaty.
+- `refundOrder({ kind?, releaseStock?, ... })` (`includio-cms/shop/server`) — per-kind routing. `kind: "deposit" | "balance" | "full"` matchuje konkretny payment row; kwota cap = `row.amount - prior refunds`. Domyślnie `kind` = `"full"` z heurystyką: pojedynczy paid row → użyj go, multi-row → wybierz `full`, brak rows → legacy fallback do `order.paymentProviderRef`. Refund row link do `paymentId` dla per-row audit. `getCollectedAmount` decyduje o transition do `refunded` (sum paid rows lub `totalGross` dla legacy). `releaseStock: true` (opt-in) reinkrementuje variant.stock per order item. 6 integration spec.
+- `refundOrderCmd` (admin remote) dostaje `kind` + `releaseStock` w schemacie input. `refund-dialog.svelte` — radio "Która płatność?" (deposit/balance) widoczne gdy `hasPartial`, balance radio disabled gdy `balanceOwed=true` (nic do refund), checkbox "Zwolnij stan magazynowy".
+- `generateBalanceLinkForOrder` (admin remote) — auth-protected, requires `INCLUDIO_BALANCE_TOKEN_SECRET`, builds URL z configured `orderViewUrl` + `?balance=1&balanceToken=...`. Zwraca `{ success, url, balanceAmount }`.
+- `shop-order-detail-page.svelte` — nowa sekcja "Płatność dzielona" widoczna gdy `order.partialPayment != null`: Plum badge "Czeka na dopłatę" przy `balanceOwed=true` / success badge "Opłacone w całości" po dopłacie, paid/owed/total breakdown z `formatCentsPrice`, button "Wyślij link do dopłaty" generuje token + kopiuje URL do clipboard, wyświetla URL w `<code>` blocku jako fallback dla "skopiuj ręcznie".
+
+### Fixed
+- `variant-attributes.ts` — `datetime` walidator używa teraz `z.string().datetime({ offset: true })`: akceptuje pełen ISO 8601 (`Z` UTC z admin `DatetimeField.toISOString()` ORAZ offset `+02:00` z importów/seedów/zewnętrznych systemów). Wcześniej tryb default odrzucał offset, blokując offsetowe wartości atrybutów.
+- `updateOrderStatus` (`server/orders.ts`) — admin manual mark-paid auto-detektuje `deposit` kind: gdy `order.partialPayment.kind === "deposit"` + `!balanceOwed` + `paidAt == null`, `effectiveKind = "deposit"`. Wcześniej `updateOrderStatusCmd` (w przeciwieństwie do webhooka) nie przekazywał `paymentKind`, więc admin oznaczając deposit order jako paid pomijał deposit logic (`paidAmount` nie był bumpowany, `balanceOwed` nie był ustawiany). Pozwala testować pełny deposit flow przez manual adapter bez sandbox PayU; webhook bez zmian (zawsze pass explicit kind).
+- admin `paymentPolicy` — trzy bugi powodujące kasowanie deposit policy przy każdym save naprawione razem: (1) `upsertShopData` (`server/shop-data.ts`) — `undefined` zachowuje istniejącą policy, tylko `null` kasuje (było `?? null` nadpisujące przy każdym upsert innego pola); (2) `shopDataInputSchema` (admin remote) — dodany discriminated union `paymentPolicy` (full/deposit + percent/amount), wcześniej command odrzucał pole; (3) `shop-field.svelte` — sekcja "Zasady płatności" (radio full/deposit + warunkowe inputy percent/amount + live preview kwoty depozytu), wcześniej brak UI do ustawienia deposit.
+
+## 0.26.1 — 2026-05-28
+
+Nowy typ pola `icon` + IconSetPlugin (zestaw ikon dostarczany przez aplikację, dialog z gridem + search). Scaffolder fix + DataTable polish: scaffold admin używa publicznych entry points; pierwsza kolumna tabeli bez sticky-first; checkbox visual wraca do 16 px z transparent hit-area 24×24 (WCAG 2.5.5).
+
+### Added
+- Nowy typ pola `icon` (`IconField` @public, `src/lib/types/fields.ts`) — kompaktowy kafelek 96×96 w formularzu (ikona + nazwa, X do wyczyszczenia) otwiera dialog z gridem responsive 3–6 kolumn, wyszukiwarką (filtruje po `key`, lokalizowanym `label`, opcjonalnych `keywords`) i przyciskami Anuluj / OK. Klik na kafelku w dialogu zaznacza, OK zatwierdza; dwuklik = szybki zapis. Stan "missing" (wartość w DB nieobecna w bibliotece) pokazuje placeholder + przyjazne ostrzeżenie zamiast resetować wartość — zgodne z ToV "informuj, nie strasz". i18n PL/EN, `role="listbox"`/`role="option"`/`aria-selected`, LiveRegion z liczbą wyników.
+- `IconSetPlugin` / `IconDefinition` (`@public`, `src/lib/types/plugins.ts`) — nowy rodzaj pluginu rejestrujący nazwany zestaw ikon: `{ slug, type: 'icon-set', icons: Record<key, { component, label: Localized, keywords?: string[] }> }`. Komponenty Svelte (eager import, tree-shakable — np. `Brain` z `@lucide/svelte`) ŻYJĄ w pluginie, bo `cms.config.ts` jest server-only i Zod-validated. `Plugin = PluginConfig | IconSetPlugin` + `isIconSetPlugin` type guard.
+- `buildIconSetMap(...plugins)` (`includio-cms/admin`) + nowy prop `iconSets?: Map<string, IconSetPlugin>` na `AdminLayout` — konsumencki `+layout.svelte` admina przekazuje plugin instancje na klienta (funkcji komponentów nie da się serializować przez SvelteKit data). `getIconSets()` / `resolveIconSet(slug?)` w `includio-cms/admin` — runtime lookup używany przez `icon-field.svelte` przez Svelte context.
+- `CMS.iconSets: Map<slug, IconSetPlugin>` agregowane przy starcie z `cms.config.plugins` przez `isIconSetPlugin` guard; duplikat slug → throw. Generator TS mapuje `icon` → `string` w wygenerowanym `types.ts`; Zod runtime → `z.string()` (analogicznie do `slug` field).
+
+### Fixed
+- `scaffold admin` generuje `src/routes/admin/api/[...path]/+server.ts` z `import { createAdminApiHandler } from 'includio-cms/sveltekit/server'`. Wcześniej generowany import `includio-cms/admin/api/handler` rzucał Vite `Missing "./admin/api/handler" specifier in "includio-cms" package` przy starcie dev/build — `admin/api/handler` nie ma w `exports` (v1.0 frozen 18 ścieżek).
+- `scaffold admin` generuje `src/routes/admin/api/rest/[...restPath]/+server.ts` z `import { createRestApiHandler } from 'includio-cms/sveltekit/server'` (analogicznie — był broken w 0.20.0+ ale scaffolder nie zaktualizowany).
+- `includio-cms/sveltekit/server` re-eksportuje teraz `createAdminApiHandler` (obok istniejącego `createRestApiHandler`).
+- `DataTable`: revert sticky-first column (z 0.26.0 / S10c) — pierwsza kolumna scrolluje razem z resztą, bez wyróżnienia kolorystycznego. Usunięty prop `stickyFirstColumn` i powiązany CSS.
+- `Checkbox` primitive: visual wraca do 16×16 px (z 24×24 w 0.26.0 / S10b), klikalny obszar utrzymany na ≥24×24 przez transparent `::after` pseudo-element (`after:-inset-1`) — WCAG 2.5.5 target-size AA dalej spełniony, lepszy wygląd zgodny z proporcjami pól tekstowych.
+
 ## 0.26.0 — 2026-05-26
 
 UI Normalization → release readiness: slug regex camelCase + S8 detail/edit + S9 fields a11y polish + S10 a11y final audit + S10b/S10c mobile responsiveness full pass (sticky first column DataTable, Dialog fullscreenMobile prop, media library Sheet drawers, entry hybrid preview drawer toggle, dashboard mobile layout flip). 43/43 mobile Playwright pass (3 viewports × 12 widoków, 0 critical axe).

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.26.0)
+# Includio CMS Documentation (v0.28.0)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 

package/ROADMAP.md

@@ -21,6 +21,14 @@
 - [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)
 - [x] `[chore]` `[P2]` Demo orchestrator — `pnpm demo` startuje czystą instancję na tmpfs DB :5436, seeduje 12 blog postów / 6 projektów / 5 contact submissions / 8 gradient PNG-ów, włącza `demo-site` frontend pod `/demo-site`, każdy start = czysty stan <!-- files: scripts/demo.ts, scripts/seed-demo.ts, src/routes/demo-site/, docker-compose.yml, .env.demo -->
+- [x] `[feature]` `[P1]` Shop platformowy 0.27.0 — schema-driven variants + booking deposit (envet pilot). Plan: 7 faz. <!-- files: docs/superpowers/specs/2026-05-28-shop-platformowy-design.md, /Users/patryk/.claude/plans/implementacja-ariacms-0-27-partitioned-kahn.md -->
+  - [x] Faza 1 — Schema-driven `variantAttributes` (typed `defineShop` schema, Zod builder, GIN index util, ts-gen typed `variant.attributes`, `INVALID_VARIANT_ATTRIBUTES` guard w `upsertShopData`). <!-- files: src/lib/shop/types.ts, src/lib/shop/variant-attributes.ts, src/lib/shop/server/{shop-data,init}.ts, src/lib/db-postgres/schema/shop/productVariant.ts, src/lib/core/server/generator/fields.ts -->
+  - [x] Faza 2 — Admin dynamic variant attribute form renderer (`VariantAttributeRenderer.svelte`, integracja w `shop-field.svelte`, `getShopConfig` remote response zwraca `variantAttributes`, auto-apply GIN indexes na `initCMS()`). <!-- files: src/lib/admin/components/variant-form/VariantAttributeRenderer.svelte, src/lib/admin/components/fields/shop-field.svelte, src/lib/admin/remote/shop.remote.ts, src/lib/core/cms.ts, src/lib/shop/server/init.ts, src/stories/fields/shop-with-attributes.stories.svelte -->
+  - [x] Faza 3 — `variantLabel.template` interpolation + admin pre-fill (`interpolateTemplate` engine z filtrami `date`/`currency`/`uppercase`, `ShopConfig.variantLabel`, `defineShop` przepuszcza, `getShopConfig` remote zwraca, `shop-field.svelte` auto-prefills `variant.name` per locale `pl` z per-variant dirty flag — locked po hydratacji jeśli name istnieje + po `oninput` w name). <!-- files: src/lib/shop/template.ts, src/lib/shop/types.ts, src/lib/shop/index.ts, src/lib/admin/remote/shop.remote.ts, src/lib/admin/components/fields/shop-field.svelte, src/stories/fields/shop-with-attributes-story-demo.svelte, src/stories/fields/shop-with-attributes.stories.svelte -->
+  - [x] Faza 4 — `variantExpiry` opt-in (storefront filter + cart-add guard + checkout guard + admin "Zakończony" badge + filter toggle + source-asc sort + upcoming HTTP endpoint + `client.products.listUpcoming` SDK). <!-- files: src/lib/shop/expiry.ts, src/lib/shop/types.ts, src/lib/shop/index.ts, src/lib/shop/server/orders.ts, src/lib/shop/http/{cart-handler,upcoming-handler,index}.ts, src/lib/shop/client/index.ts, src/lib/admin/remote/shop.remote.ts, src/lib/admin/components/fields/shop-field.svelte -->
+  - [x] Faza 5 — `paymentPolicy` A-lite (deposit + balance + signed token + refund per kind, admin balance link + refund-per-kind dialog, shop_payments rows tagged by kind). <!-- files: src/lib/shop/types.ts, src/lib/shop/server/{payment-policy,balance-payment,payments,orders,refund,shop-data}.ts, src/lib/shop/http/{balance-handler,checkout-handler,webhook-handler,index}.ts, src/lib/shop/client/index.ts, src/lib/db-postgres/schema/shop/{order,payment,product}.ts, src/lib/admin/{remote/shop.remote.ts,client/shop/{shop-order-detail-page,refund-dialog}.svelte} -->
+  - [x] Faza 6 — envet integration (pilot consumer) — szkolenia variants + deposit flow + balance link end-to-end QA. <!-- files: envet repo src/lib/cms/cms.config.ts, src/routes/api/shop/, src/routes/(website)/{szkolenia,koszyk}/, src/lib/components/{CartIcon,AddToCartModal,CoursePage}.svelte, cli/seed.ts -->
+  - [x] Faza 7 — Release artifacts (changelog, ROADMAP cleanup, API.md, build) — 3 post-Faza-5 hotfixy w 0.27.0 (single release). <!-- files: src/lib/updates/0.27.0/index.ts, ROADMAP.md, CHANGELOG.md, API.md, MIGRATION-... -->
 - [x] `[feature]` `[P1]` Slug first-class + SEO v1.0 freeze (0.26.0) — `resolveSeo` public (`includio-cms/core`), `seoFieldDescriptor` SSOT (Zod+TS drift-guard), admin URL un-hardcode (`slugPath.ts` pure resolver, no `seo`-field requirement), `SlugField`/`SeoField`/`SeoFieldData` `@public` v1.0-frozen <!-- files: src/lib/core/fields/slugPath.ts, src/lib/core/fields/seoFieldDescriptor.ts, src/lib/core/fields/resolveSeo.ts, src/lib/types/fields.ts, src/lib/admin/client/collection/collection-entries.svelte, src/lib/updates/0.26.0/ -->
 
 ## v1.x — Post-v1.0 deferred