includio-cms 0.35.0 → 0.36.0

package/API.md

@@ -1,8 +1,8 @@
-# includio-cms — Public API v0.35.0
+# includio-cms — Public API v0.36.0
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
-Entry points: **19** · Stable: **490** · Experimental: **4**
+Entry points: **19** · Stable: **492** · Experimental: **4**
 
 Tags:
 - `@public` — frozen for v1.0; semver-protected.
@@ -450,6 +450,7 @@ Tags:
 - `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 I18nTemplate = Record<string, string>`
 - `type I18nText = { [lang: string]: string; }`
 - `inpostAdapter(opts: InpostAdapterOptions): CarrierAdapter`
 - `interface InpostAdapterOptions`
@@ -480,6 +481,7 @@ Tags:
 - `interface PaymentRefundResult`
 - `payuAdapter(opts: PayuAdapterOptions): PaymentAdapter`
 - `interface PayuAdapterOptions`
+- `renderShopName(template: I18nTemplate | null | undefined, ctx: { entryData: Record<string, unknown> | null | undefi..., locale: string): string | null` — Render a multilingual shop-name template (`invoiceName` / `cartName`)
 - `interface ResolvedShopConfig`
 - `interface ShipmentCreateInput`
 - `interface ShipmentCreateResult`

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.36.0 — 2026-06-05
+
+`defineShop({ invoiceName, cartName })` — opcjonalne multilingual template overriding produktowej nazwy w koszyku, podsumowaniu zamówienia i na fakturze. Reusuje engine od `variantLabel.template` (`{slug}`, `{slug|filter}`), z nowymi możliwościami: dot-path (`{hero.title}`) i auto-unwrap pól i18n. Reserved `{variant}` = wyrenderowany variantLabel. Order item `nameSnapshot` zyskuje opcjonalne pole `invoice` (zamrażane przy checkout). Additive — brak zmian default behavior.
+
+### Added
+- `ShopConfig.invoiceName?: I18nText` i `ShopConfig.cartName?: I18nText` — template (per język) renderowany przy hydracji koszyka i tworzeniu zamówienia. Fallback chain: `cartName` (koszyk) → `invoiceName` (koszyk + faktura) → legacy `productTitle` / `product — variant`. `invoiceName` jest **full override** na fakturze — wariant NIE jest doklejany automatycznie, użyj `{variant}` w template.
+- `interpolateTemplate()` (`$lib/shop/template.ts`) zyskuje dot-path resolver (`{hero.title}`) oraz auto-unwrap pól i18n `{ pl: …, en: … }` do aktualnego języka (z fallbackiem `lang.split("-")[0]` → pierwszy klucz). Backwards-compatible: istniejące `{key}` (płaskie) działają bez zmian.
+- `renderShopName(template, ctx, locale)` (`$lib/shop/template.ts`) — public helper łączący resolverę I18nText template + budowę vars `{ ...entryData, variant }`. Używany wewnętrznie przez cart-hydrate; eksportowany dla customowych use case (np. own checkout flows).
+- `CartLine` zyskuje pole `invoiceTitle: string | null` — frozen invoice copy obok `productTitle` (cart copy). `orders.createOrderFromCart` snapshot-uje to do `nameSnapshot.invoice`. `buildInvoicePayload()` honoruje `nameSnapshot.invoice` — fallback do `product — variant` gdy brak.
+
 ## 0.35.0 — 2026-06-05
 
 Kupon `appliesTo` (netto/brutto), uczestnicy w `notes` (admin + email), Calendar+Popover w polach `date`/`datetime` (admin), `api.ts` bez `FormEntryMap` gdy projekt nie ma form. Additive only — domyślne zachowania bez zmian.

package/DOCS.md

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

package/dist/shop/cart/types.d.ts

@@ -9,6 +9,13 @@ export interface CartLine extends CartItemRef {
     variantName: Record<string, string> | null;
     variantSku: string | null;
     productTitle: string | null;
+    /**
+     * Frozen invoice-line name rendered from `ShopConfig.invoiceName` at hydrate
+     * time. Null when `invoiceName` is not configured. Carried separately from
+     * `productTitle` so order creation can snapshot the cart copy and the
+     * invoice copy independently.
+     */
+    invoiceTitle: string | null;
     productSlug: string | null;
     priceNet: number;
     priceGross: number;

package/dist/shop/index.d.ts

@@ -13,4 +13,5 @@ export { fakturowniaAdapter } from './adapters/fakturownia/index.js';
 export type { FakturowniaAdapterOptions } from './adapters/fakturownia/index.js';
 export { isValidNip } from './nip.js';
 export type { ShopConfig, ResolvedShopConfig, Currency, Order, OrderStatus, PaymentAdapter, PaymentCreateContext, PaymentRefundInput, PaymentRefundResult, CarrierAdapter, CarrierEvent, ShipmentCreateInput, ShipmentCreateResult, ShipmentLabel, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, CouponRef, I18nText, VariantAttribute, VariantAttributeText, VariantAttributeNumber, VariantAttributeDatetime, VariantAttributeSelect, VariantAttributeBoolean, VariantAttributeImage, VariantAttributeEntry, VariantAttributeSlug, VariantLabelConfig, VariantExpiryConfig, PaymentPolicy, DepositAmount, PartialPayment, InvoicingAdapter, InvoiceIssuePolicy, InvoiceBuyer, InvoiceLineItem, InvoicePayload, InvoiceCreateResult, InvoiceContext } from './types.js';
-export { interpolateTemplate } from './template.js';
+export { interpolateTemplate, renderShopName } from './template.js';
+export type { I18nTemplate } from './template.js';

package/dist/shop/index.js

@@ -17,7 +17,9 @@ export function defineShop(config) {
         orderViewUrl: config.orderViewUrl ?? '/shop/order/{orderNumber}?token={accessToken}',
         variantAttributes: config.variantAttributes ?? {},
         variantLabel: config.variantLabel ?? null,
-        variantExpiry: config.variantExpiry ?? null
+        variantExpiry: config.variantExpiry ?? null,
+        invoiceName: config.invoiceName ?? null,
+        cartName: config.cartName ?? null
     };
 }
 export { InvalidVariantAttributesError } from './variant-attributes.js';
@@ -28,4 +30,4 @@ export { stripeAdapter } from './adapters/stripe/index.js';
 export { inpostAdapter } from './adapters/inpost/index.js';
 export { fakturowniaAdapter } from './adapters/fakturownia/index.js';
 export { isValidNip } from './nip.js';
-export { interpolateTemplate } from './template.js';
+export { interpolateTemplate, renderShopName } from './template.js';

package/dist/shop/server/cart-hydrate.js

@@ -1,4 +1,4 @@
-import { eq, inArray } from 'drizzle-orm';
+import { desc, inArray } from 'drizzle-orm';
 import { shopProductsTable, shopProductVariantsTable } from '../../db-postgres/schema/shop/index.js';
 import { entriesTable } from '../../db-postgres/schema/entry.js';
 import { entryVersionsTable } from '../../db-postgres/schema/entryVersion.js';
@@ -6,6 +6,7 @@ import { getCMS } from '../../core/cms.js';
 import { getShopDb, requireShopConfig } from './db.js';
 import { grossFromNet, grossPlnFromNetPln, toCents } from '../pricing.js';
 import { buildAppliedCoupon, validateCoupon, CouponError } from './coupons.js';
+import { renderShopName } from '../template.js';
 export async function hydrateCart(items, opts = {}) {
     const shop = requireShopConfig();
     const cms = getCMS();
@@ -42,10 +43,16 @@ export async function hydrateCart(items, opts = {}) {
             .select()
             .from(entryVersionsTable)
             .where(inArray(entryVersionsTable.entryId, entryIds))
+            .orderBy(desc(entryVersionsTable.versionNumber))
         : [];
     const publishedByEntry = new Map();
+    const now = new Date();
     for (const v of versions) {
-        if (v.publishedAt != null)
+        if (v.lang !== language)
+            continue;
+        if (v.publishedAt == null || v.publishedAt > now)
+            continue;
+        if (!publishedByEntry.has(v.entryId))
             publishedByEntry.set(v.entryId, v);
     }
     const productById = new Map(products.map((p) => [p.id, p]));
@@ -62,6 +69,19 @@ export async function hydrateCart(items, opts = {}) {
         }
         return null;
     }
+    function readVariantLabel(name, lang) {
+        if (!name || typeof name !== 'object')
+            return '';
+        const map = name;
+        const direct = map[lang];
+        if (typeof direct === 'string' && direct.length > 0)
+            return direct;
+        const base = map[lang.split('-')[0]];
+        if (typeof base === 'string' && base.length > 0)
+            return base;
+        const first = Object.values(map).find((v) => typeof v === 'string' && v.length > 0);
+        return first ?? '';
+    }
     function readSlug(data) {
         if (!data || typeof data !== 'object')
             return null;
@@ -95,6 +115,11 @@ export async function hydrateCart(items, opts = {}) {
         const version = publishedByEntry.get(product.entryId);
         const title = readTitle(version?.data);
         const slug = readSlug(version?.data);
+        const entryData = (version?.data ?? null);
+        const variantLabel = readVariantLabel(variant.name, language);
+        const renderedInvoice = renderShopName(shop.invoiceName, { entryData, variant: variantLabel, language }, language);
+        const renderedCart = renderShopName(shop.cartName, { entryData, variant: variantLabel, language }, language) ?? renderedInvoice;
+        const cartTitle = renderedCart ?? title;
         // basePrice/priceDelta są numeric(20,6) → drizzle zwraca string. Konwertujemy do PLN (number).
         const priceNetPln = Number(product.basePrice) + Number(variant.priceDelta ?? 0);
         const priceGrossPln = grossPlnFromNetPln(priceNetPln, product.vatRate);
@@ -130,7 +155,8 @@ export async function hydrateCart(items, opts = {}) {
             productId: product.id,
             variantName: variant.name ?? null,
             variantSku: variant.sku,
-            productTitle: title,
+            productTitle: cartTitle,
+            invoiceTitle: renderedInvoice,
             productSlug: slug,
             priceNet,
             priceGross,
@@ -210,6 +236,7 @@ export async function hydrateCart(items, opts = {}) {
             variantName: null,
             variantSku: null,
             productTitle: null,
+            invoiceTitle: null,
             productSlug: null,
             priceNet: 0,
             priceGross: 0,

package/dist/shop/server/email.js

@@ -1,5 +1,4 @@
 import { getCMS } from '../../core/cms.js';
-import { resolveI18n } from '../pricing.js';
 import { getOrderById, getOrderItems } from './orders.js';
 import { getOrderCoupon } from './coupons.js';
 import { requireShopConfig } from './db.js';
@@ -151,13 +150,18 @@ export async function sendOrderStatusEmail(orderId, status) {
             lastName: p.lastName
         })),
         hasParticipants: participants.length > 0,
-        items: items.map((i) => ({
-            name: resolveI18n(i.nameSnapshot?.product
-                ? { pl: i.nameSnapshot.product }
-                : undefined, lang) || '—',
-            qty: i.qty,
-            lineGross: formatPrice(i.priceGrossSnapshot * i.qty, order.currency)
-        })),
+        items: items.map((i) => {
+            const snap = (i.nameSnapshot ?? {});
+            const composed = snap.invoice ||
+                (snap.product && snap.variant
+                    ? `${snap.product} — ${snap.variant}`
+                    : snap.product || snap.variant || '');
+            return {
+                name: composed || '—',
+                qty: i.qty,
+                lineGross: formatPrice(i.priceGrossSnapshot * i.qty, order.currency)
+            };
+        }),
         shop: {
             currency: order.currency,
             adminEmail: shop.adminEmail ?? null

package/dist/shop/server/invoices.js

@@ -43,10 +43,16 @@ export function decideInvoiceAction(order, existing, policy, opts = {}) {
         return 'create';
     return 'skip';
 }
-// Order-item `nameSnapshot` is `{ product, variant }` (see createOrderFromCart).
-// The invoice line shows both so the customer sees the exact session they paid
-// for (e.g. "Odporność psychiczna — Poznań • 20 września 2026").
+// Order-item `nameSnapshot` is `{ product, variant, invoice? }` (see
+// createOrderFromCart). When `invoice` is present it was rendered from
+// `ShopConfig.invoiceName` at order time and is treated as a full override —
+// the variant suffix is NOT appended (template author controls whether to
+// include `{variant}`). Otherwise the legacy `product — variant` format is
+// used (e.g. "Odporność psychiczna — Poznań • 20 września 2026").
 function lineName(name) {
+    const invoice = name.invoice ?? '';
+    if (invoice)
+        return invoice;
     const product = name.product ?? '';
     const variant = name.variant ?? '';
     if (product && variant)

package/dist/shop/server/orders.js

@@ -327,7 +327,8 @@ export async function createOrderFromCart(input) {
                 product: line.productTitle ?? '',
                 variant: line.variantName && typeof line.variantName === 'object'
                     ? (Object.values(line.variantName)[0] ?? '')
-                    : ''
+                    : '',
+                ...(line.invoiceTitle ? { invoice: line.invoiceTitle } : {})
             },
             skuSnapshot: line.variantSku ?? null,
             priceNetSnapshot: line.priceNet,

package/dist/shop/template.d.ts

@@ -11,3 +11,23 @@
  * @public
  */
 export declare function interpolateTemplate(template: string, vars: Record<string, unknown>, locale: string): string;
+/**
+ * Render a multilingual shop-name template (`invoiceName` / `cartName`)
+ * against an entry's data and a precomputed variant label. Returns `null`
+ * when the template is absent or yields an empty string after trimming —
+ * callers fall back to legacy behavior.
+ *
+ * Variables: `{<slug>}` resolves to any top-level (dot-path) field on the
+ * entry's published data. The reserved `{variant}` returns the rendered
+ * variant label. I18n fields stored as `{ pl: '…', en: '…' }` are auto
+ * unwrapped to the active language.
+ *
+ * @public
+ */
+export declare function renderShopName(template: I18nTemplate | null | undefined, ctx: {
+    entryData: Record<string, unknown> | null | undefined;
+    variant: string;
+    language: string;
+}, locale: string): string | null;
+/** @public */
+export type I18nTemplate = Record<string, string>;

package/dist/shop/template.js

@@ -17,18 +17,95 @@ export function interpolateTemplate(template, vars, locale) {
     }
     return template.replace(/\{([^}]+)\}/g, (_match, body) => {
         const { key, filter, arg } = parsePlaceholder(body);
-        if (!(key in vars)) {
+        const lookup = resolveKey(vars, key, locale);
+        if (lookup === undefined) {
             console.warn(`[interpolateTemplate] Unknown key "${key}" in template: ${template}`);
             return '';
         }
-        const raw = vars[key];
-        if (raw === null || raw === undefined)
+        if (lookup === null)
             return '';
         if (!filter)
-            return String(raw);
-        return applyFilter(raw, filter, arg, locale);
+            return String(lookup);
+        return applyFilter(lookup, filter, arg, locale);
     });
 }
+/**
+ * Resolve a placeholder key against `vars`. Supports dot-path (`hero.title`)
+ * and auto-unwraps an `I18nText`-shaped record (`{ pl: '…', en: '…' }`) to
+ * the active locale (falls back to the first key when the exact locale is
+ * missing). Returns `undefined` when the path does not exist — caller treats
+ * that as "unknown key" and warns. Returns `null` when the path exists but
+ * the value is nullish; caller emits empty string.
+ *
+ * @internal
+ */
+function resolveKey(vars, key, locale) {
+    const parts = key.split('.');
+    let current = vars;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof current !== 'object')
+            return undefined;
+        const obj = current;
+        if (!(part in obj))
+            return undefined;
+        current = obj[part];
+    }
+    return unwrapI18n(current, locale);
+}
+/** @internal */
+function unwrapI18n(value, locale) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const obj = value;
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        return value;
+    const allStrings = keys.every((k) => typeof obj[k] === 'string');
+    if (!allStrings)
+        return value;
+    if (locale in obj)
+        return obj[locale];
+    const baseLocale = locale.split('-')[0];
+    if (baseLocale in obj)
+        return obj[baseLocale];
+    return obj[keys[0]];
+}
+/**
+ * Render a multilingual shop-name template (`invoiceName` / `cartName`)
+ * against an entry's data and a precomputed variant label. Returns `null`
+ * when the template is absent or yields an empty string after trimming —
+ * callers fall back to legacy behavior.
+ *
+ * Variables: `{<slug>}` resolves to any top-level (dot-path) field on the
+ * entry's published data. The reserved `{variant}` returns the rendered
+ * variant label. I18n fields stored as `{ pl: '…', en: '…' }` are auto
+ * unwrapped to the active language.
+ *
+ * @public
+ */
+export function renderShopName(template, ctx, locale) {
+    if (!template)
+        return null;
+    const tpl = template[ctx.language] ?? template[ctx.language.split('-')[0]] ?? null;
+    if (!tpl)
+        return null;
+    const vars = {
+        ...(ctx.entryData ?? {}),
+        variant: ctx.variant
+    };
+    for (const match of tpl.matchAll(/\{([^}]+)\}/g)) {
+        const key = match[1].split('|')[0].trim();
+        const value = resolveKey(vars, key, locale);
+        if (value === undefined || value === null || value === '')
+            return null;
+    }
+    const rendered = interpolateTemplate(tpl, vars, locale).trim();
+    return rendered.length > 0 ? rendered : null;
+}
 /** @internal */
 function parsePlaceholder(body) {
     const [keyPart, filterPart] = body.split('|', 2);

package/dist/shop/types.d.ts

@@ -394,6 +394,28 @@ export interface ShopConfig {
      * @public
      */
     variantLabel?: VariantLabelConfig;
+    /**
+     * Multilingual template overriding the product name shown on invoices
+     * (Fakturownia etc.) and — unless `cartName` is set — also in cart and
+     * order views. Keys are language codes (`pl`, `en`, …). Placeholders use
+     * the same engine as `variantLabel`: `{slug}` resolves to a top-level
+     * field on the entry (dot-path supported, i18n-aware); the reserved
+     * `{variant}` resolves to the rendered `variantLabel`. Filters from
+     * {@link interpolateTemplate} (`|date`, `|currency`, `|uppercase`) apply.
+     * Omitted = legacy behavior (`product — variant`).
+     * @public
+     */
+    invoiceName?: I18nText;
+    /**
+     * Multilingual template overriding the product name shown in cart and
+     * storefront order views ONLY (invoice still uses `invoiceName` or
+     * legacy). Set this in addition to `invoiceName` when the cart needs a
+     * shorter / different copy than the invoice line. Same syntax as
+     * {@link ShopConfig.invoiceName}. Omitted = falls back to `invoiceName`,
+     * then to legacy `productTitle`.
+     * @public
+     */
+    cartName?: I18nText;
     /**
      * Opt-in storefront filter for time-bound variants (events, courses).
      * Omitted = no filtering (legacy behavior — every variant always listed).
@@ -434,7 +456,7 @@ export interface ShopConfig {
      */
     onOrderPaid?: (order: Order) => Promise<void> | void;
 }
-export interface ResolvedShopConfig extends Omit<ShopConfig, 'variantLabel' | 'variantExpiry' | 'invoicing'> {
+export interface ResolvedShopConfig extends Omit<ShopConfig, 'variantLabel' | 'variantExpiry' | 'invoicing' | 'invoiceName' | 'cartName'> {
     features: Required<ShopFeatures>;
     rateLimit: Required<ShopRateLimit>;
     carriers: CarrierAdapter[];
@@ -444,5 +466,7 @@ export interface ResolvedShopConfig extends Omit<ShopConfig, 'variantLabel' | 'v
     variantAttributes: Record<string, VariantAttribute>;
     variantLabel: VariantLabelConfig | null;
     variantExpiry: VariantExpiryConfig | null;
+    invoiceName: I18nText | null;
+    cartName: I18nText | null;
 }
 export {};

package/dist/updates/0.36.0/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.36.0/index.js

@@ -0,0 +1,13 @@
+export const update = {
+    version: '0.36.0',
+    date: '2026-06-05',
+    description: '`defineShop({ invoiceName, cartName })` — opcjonalne multilingual template overriding produktowej nazwy w koszyku, podsumowaniu zamówienia i na fakturze. Reusuje engine od `variantLabel.template` (`{slug}`, `{slug|filter}`), z nowymi możliwościami: dot-path (`{hero.title}`) i auto-unwrap pól i18n. Reserved `{variant}` = wyrenderowany variantLabel. Order item `nameSnapshot` zyskuje opcjonalne pole `invoice` (zamrażane przy checkout). Additive — brak zmian default behavior.',
+    features: [
+        '`ShopConfig.invoiceName?: I18nText` i `ShopConfig.cartName?: I18nText` — template (per język) renderowany przy hydracji koszyka i tworzeniu zamówienia. Fallback chain: `cartName` (koszyk) → `invoiceName` (koszyk + faktura) → legacy `productTitle` / `product — variant`. `invoiceName` jest **full override** na fakturze — wariant NIE jest doklejany automatycznie, użyj `{variant}` w template.',
+        '`interpolateTemplate()` (`$lib/shop/template.ts`) zyskuje dot-path resolver (`{hero.title}`) oraz auto-unwrap pól i18n `{ pl: …, en: … }` do aktualnego języka (z fallbackiem `lang.split("-")[0]` → pierwszy klucz). Backwards-compatible: istniejące `{key}` (płaskie) działają bez zmian.',
+        '`renderShopName(template, ctx, locale)` (`$lib/shop/template.ts`) — public helper łączący resolverę I18nText template + budowę vars `{ ...entryData, variant }`. Używany wewnętrznie przez cart-hydrate; eksportowany dla customowych use case (np. own checkout flows).',
+        '`CartLine` zyskuje pole `invoiceTitle: string | null` — frozen invoice copy obok `productTitle` (cart copy). `orders.createOrderFromCart` snapshot-uje to do `nameSnapshot.invoice`. `buildInvoicePayload()` honoruje `nameSnapshot.invoice` — fallback do `product — variant` gdy brak.'
+    ],
+    fixes: [],
+    breakingChanges: []
+};

package/dist/updates/index.js

@@ -66,6 +66,7 @@ import { update as update0280 } from './0.28.0/index.js';
 import { update as update0340 } from './0.34.0/index.js';
 import { update as update0341 } from './0.34.1/index.js';
 import { update as update0350 } from './0.35.0/index.js';
+import { update as update0360 } from './0.36.0/index.js';
 export const updates = [
     update0065,
     update0066,
@@ -134,7 +135,8 @@ export const updates = [
     update0280,
     update0340,
     update0341,
-    update0350
+    update0350,
+    update0360
 ];
 export const getUpdatesFrom = (fromVersion) => {
     const fromParts = fromVersion.split('.').map(Number);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "includio-cms",
-	"version": "0.35.0",
+	"version": "0.36.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",