includio-cms 0.25.0 → 0.27.0

package/dist/shop/server/refund.js

@@ -1,7 +1,8 @@
-import { and, eq, sum } from 'drizzle-orm';
-import { shopOrdersTable, shopRefundsTable } from '../../db-postgres/schema/shop/index.js';
+import { and, eq, sql, sum } from 'drizzle-orm';
+import { shopOrderItemsTable, shopProductVariantsTable, shopRefundsTable } from '../../db-postgres/schema/shop/index.js';
 import { getShopDb, requireShopConfig } from './db.js';
 import { getOrderById, updateOrderStatus } from './orders.js';
+import { listOrderPayments } from './payments.js';
 export class RefundError extends Error {
     code;
     cause;
@@ -46,6 +47,42 @@ function findAdapter(provider) {
  * `pending` refund row is marked `failed` on provider error so admin can see
  * what was attempted.
  */
+async function resolveTargetPayment(orderId, requestedKind) {
+    const payments = await listOrderPayments(orderId);
+    const paid = payments.filter((p) => p.status === 'paid');
+    if (requestedKind) {
+        const match = paid.find((p) => p.kind === requestedKind);
+        if (!match) {
+            throw new RefundError('no_payment_kind', `No paid ${requestedKind} payment row on order to refund`);
+        }
+        return { payment: match, kind: requestedKind };
+    }
+    // No explicit kind: prefer a `full` row; with exactly one paid row of any
+    // kind, derive from it (keeps single-payment-row orders refunding their
+    // only paid payment). Legacy orders with no shop_payments rows fall back
+    // to the `'full'` path that uses order.paymentProviderRef.
+    const full = paid.find((p) => p.kind === 'full');
+    if (full)
+        return { payment: full, kind: 'full' };
+    if (paid.length === 1)
+        return { payment: paid[0], kind: paid[0].kind };
+    return { payment: null, kind: 'full' };
+}
+async function releaseOrderStock(orderId) {
+    const db = getShopDb();
+    const items = await db
+        .select()
+        .from(shopOrderItemsTable)
+        .where(eq(shopOrderItemsTable.orderId, orderId));
+    for (const item of items) {
+        if (!item.variantId)
+            continue;
+        await db
+            .update(shopProductVariantsTable)
+            .set({ stock: sql `${shopProductVariantsTable.stock} + ${item.qty}` })
+            .where(and(eq(shopProductVariantsTable.id, item.variantId), sql `${shopProductVariantsTable.stock} IS NOT NULL`));
+    }
+}
 export async function refundOrder(input) {
     const db = getShopDb();
     const order = await getOrderById(input.orderId);
@@ -60,9 +97,6 @@ export async function refundOrder(input) {
     if (!order.paymentMethod) {
         throw new RefundError('unknown_provider', `Order ${order.number} has no payment method`);
     }
-    if (!order.paymentProviderRef) {
-        throw new RefundError('no_provider_ref', `Order ${order.number} has no payment provider reference`);
-    }
     const adapter = findAdapter(order.paymentMethod);
     if (!adapter) {
         throw new RefundError('unknown_provider', `Payment provider "${order.paymentMethod}" is not configured`);
@@ -70,10 +104,23 @@ export async function refundOrder(input) {
     if (typeof adapter.refund !== 'function') {
         throw new RefundError('refund_unsupported', `Payment provider "${adapter.id}" does not support refunds`);
     }
-    const alreadyRefunded = await getRefundedAmount(order.id);
-    const remaining = order.totalGross - alreadyRefunded;
+    // Pick the payment row to target — explicit kind, single paid row, or
+    // legacy fallback to order.paymentProviderRef when no rows exist.
+    const target = await resolveTargetPayment(order.id, input.kind);
+    const providerRef = target.payment?.providerRef ?? order.paymentProviderRef;
+    if (!providerRef) {
+        throw new RefundError('no_provider_ref', `Order ${order.number} has no payment provider reference`);
+    }
+    // Per-kind cap: refund up to the matched row's amount (not order total)
+    // minus any prior refunds against that same payment row. Legacy path
+    // (no payment row) caps at order.totalGross.
+    const refundCeiling = target.payment ? target.payment.amount : order.totalGross;
+    const priorOnTarget = target.payment
+        ? await getRefundedAmountForPayment(target.payment.id)
+        : await getRefundedAmount(order.id);
+    const remaining = refundCeiling - priorOnTarget;
     if (remaining <= 0) {
-        throw new RefundError('amount_exceeds_remaining', `Order ${order.number} already fully refunded`);
+        throw new RefundError('amount_exceeds_remaining', `Payment already fully refunded (${target.kind})`);
     }
     const amount = input.amount ?? remaining;
     if (!Number.isInteger(amount) || amount <= 0) {
@@ -86,6 +133,7 @@ export async function refundOrder(input) {
         .insert(shopRefundsTable)
         .values({
         orderId: order.id,
+        paymentId: target.payment?.id ?? null,
         provider: adapter.id,
         amount,
         currency: order.currency,
@@ -94,15 +142,15 @@ export async function refundOrder(input) {
         createdBy: input.createdBy ?? null
     })
         .returning();
-    let providerRef = null;
+    let resultProviderRef = null;
     try {
         const providerResult = await adapter.refund({
-            providerRef: order.paymentProviderRef,
+            providerRef,
             amount,
             currency: order.currency,
             reason: input.reason
         });
-        providerRef = providerResult.providerRef;
+        resultProviderRef = providerResult.providerRef;
     }
     catch (err) {
         await db
@@ -118,23 +166,58 @@ export async function refundOrder(input) {
         .update(shopRefundsTable)
         .set({
         status: 'succeeded',
-        providerRef,
+        providerRef: resultProviderRef,
         updatedAt: new Date()
     })
         .where(eq(shopRefundsTable.id, pending.id))
         .returning();
     const newRemaining = remaining - amount;
     let orderStatusChanged = false;
-    if (newRemaining === 0) {
+    // Transition order to `refunded` only when the cumulative refund across
+    // ALL paid payment rows equals the total collected. For deposit-only
+    // orders pre-balance the "collected" = deposit row.amount; with balance
+    // paid it's deposit+balance.
+    const allCollected = await getCollectedAmount(order.id, order.totalGross);
+    const totalRefundedAfter = (await getRefundedAmount(order.id)) + 0; // succeeded row already counted
+    if (totalRefundedAfter >= allCollected) {
         await updateOrderStatus(order.id, 'refunded', {
             note: `Refund ${amount}${input.reason ? ` — ${input.reason}` : ''}`,
             changedBy: input.createdBy ?? 'admin'
         });
         orderStatusChanged = true;
     }
+    if (input.releaseStock) {
+        await releaseOrderStock(order.id);
+    }
     return {
         refund: succeeded,
         remainingRefundable: newRemaining,
         orderStatusChanged
     };
 }
+/** @internal Sum of succeeded refunds attached to a specific payment row. */
+async function getRefundedAmountForPayment(paymentId) {
+    const db = getShopDb();
+    const [row] = await db
+        .select({ total: sum(shopRefundsTable.amount) })
+        .from(shopRefundsTable)
+        .where(and(eq(shopRefundsTable.paymentId, paymentId), eq(shopRefundsTable.status, 'succeeded')));
+    const raw = row?.total;
+    if (raw == null)
+        return 0;
+    const n = typeof raw === 'string' ? Number(raw) : raw;
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * @internal
+ * Total collected amount on an order — sum of `paid` payment row amounts
+ * when shop_payments rows exist; falls back to `order.totalGross` for
+ * legacy orders (no rows). Used to decide when to transition to `refunded`.
+ */
+async function getCollectedAmount(orderId, fallback) {
+    const payments = await listOrderPayments(orderId);
+    const paid = payments.filter((p) => p.status === 'paid');
+    if (paid.length === 0)
+        return fallback;
+    return paid.reduce((sum, p) => sum + p.amount, 0);
+}

package/dist/shop/server/shop-data.d.ts

@@ -1,4 +1,5 @@
 import { shopProductsTable, shopProductVariantsTable } from '../../db-postgres/schema/shop/index.js';
+import type { PaymentPolicy } from '../types.js';
 type RawShopDataRow = typeof shopProductsTable.$inferSelect;
 type RawVariantRow = typeof shopProductVariantsTable.$inferSelect;
 export type ShopDataRow = Omit<RawShopDataRow, 'basePrice'> & {
@@ -15,6 +16,8 @@ export interface ShopDataInput {
     vatRate: number;
     isActive?: boolean;
     sortOrder?: number | null;
+    /** Per-product payment policy. Null = full payment (legacy). */
+    paymentPolicy?: PaymentPolicy | null;
 }
 export interface VariantInput {
     id?: string;
@@ -22,7 +25,7 @@ export interface VariantInput {
     name?: Record<string, string> | null;
     priceDelta?: number;
     stock?: number | null;
-    attributes?: Record<string, string> | null;
+    attributes?: Record<string, unknown> | null;
 }
 declare function validateShopData(input: ShopDataInput): void;
 export declare function getShopDataByEntry(entryId: string): Promise<ShopDataWithVariants | null>;
@@ -51,6 +54,8 @@ export interface ShopEntryListItem {
     updatedAt: Date;
     publishedData: Record<string, unknown> | null;
     draftData: Record<string, unknown> | null;
+    publishedByLang: Record<string, Record<string, unknown>>;
+    draftByLang: Record<string, Record<string, unknown>>;
     published: boolean;
 }
 export declare function listShopEntries(opts?: ListShopEntriesOptions): Promise<ShopEntryListItem[]>;

package/dist/shop/server/shop-data.js

@@ -2,7 +2,10 @@ import { asc, eq, 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';
+import { getCMS } from '../../core/cms.js';
 import { getShopDb } from './db.js';
+import { validateVariantAttributes } from '../variant-attributes.js';
+import { validatePaymentPolicy } from './payment-policy.js';
 const MAX_PLN = 1e9;
 function validateShopData(input) {
     if (!Number.isFinite(input.basePrice) || input.basePrice < 0 || input.basePrice > MAX_PLN) {
@@ -11,6 +14,8 @@ function validateShopData(input) {
     if (!Number.isInteger(input.vatRate) || input.vatRate < 0 || input.vatRate > 100) {
         throw new Error('vatRate must be an integer between 0 and 100.');
     }
+    if (input.paymentPolicy != null)
+        validatePaymentPolicy(input.paymentPolicy);
 }
 function mapShopRow(r) {
     return { ...r, basePrice: Number(r.basePrice) };
@@ -40,13 +45,18 @@ export async function upsertShopData(entryId, input, variants) {
     let productId;
     const basePriceSql = String(input.basePrice);
     if (existing) {
+        // `paymentPolicy === undefined` (caller didn't include the key) preserves
+        // the existing policy — admin clients that don't surface the field
+        // must not silently wipe it. Explicit `null` clears.
+        const nextPolicy = input.paymentPolicy === undefined ? existing.paymentPolicy : input.paymentPolicy;
         const [updated] = await db
             .update(shopProductsTable)
             .set({
             basePrice: basePriceSql,
             vatRate: input.vatRate,
             isActive: input.isActive ?? existing.isActive,
-            sortOrder: input.sortOrder ?? existing.sortOrder,
+            sortOrder: input.sortOrder ?? existing.sortOrder ?? null,
+            paymentPolicy: nextPolicy,
             updatedAt: new Date()
         })
             .where(eq(shopProductsTable.entryId, entryId))
@@ -61,12 +71,24 @@ export async function upsertShopData(entryId, input, variants) {
             basePrice: basePriceSql,
             vatRate: input.vatRate,
             isActive: input.isActive ?? true,
-            sortOrder: input.sortOrder
+            sortOrder: input.sortOrder ?? null,
+            paymentPolicy: input.paymentPolicy ?? null
         })
             .returning();
         productId = created.id;
     }
     if (variants !== undefined) {
+        // Validate against the schema declared in defineShop({ variantAttributes }).
+        // Missing/extra keys, type mismatches → InvalidVariantAttributesError
+        // (code INVALID_VARIANT_ATTRIBUTES). Skipped if no shop config or empty
+        // schema (legacy untyped behavior preserved).
+        const shopConfig = getCMS().shopConfig;
+        const attrSchema = shopConfig?.variantAttributes ?? {};
+        if (Object.keys(attrSchema).length > 0) {
+            for (const v of variants) {
+                validateVariantAttributes(v.attributes, attrSchema);
+            }
+        }
         const submittedIds = new Set(variants.filter((v) => v.id).map((v) => v.id));
         const currentVariants = existing?.variants ?? [];
         for (const v of currentVariants) {
@@ -172,8 +194,21 @@ export async function listShopEntries(opts = {}) {
         const variants = allVariants.filter((v) => v.productId === r.shopId);
         const stocks = variants.map((v) => v.stock).filter((s) => s != null);
         const versions = allVersions.filter((v) => v.entryId === r.entryId);
-        const published = versions.find((v) => v.publishedAt != null);
-        const draft = versions.find((v) => v.publishedAt == null);
+        const publishedByLang = {};
+        const draftByLang = {};
+        for (const v of versions) {
+            const data = v.data;
+            if (v.publishedAt != null) {
+                if (!publishedByLang[v.lang])
+                    publishedByLang[v.lang] = data;
+            }
+            else {
+                if (!draftByLang[v.lang])
+                    draftByLang[v.lang] = data;
+            }
+        }
+        const firstPublished = versions.find((v) => v.publishedAt != null);
+        const firstDraft = versions.find((v) => v.publishedAt == null);
         return {
             entryId: r.entryId,
             collectionSlug: r.collectionSlug,
@@ -185,9 +220,11 @@ export async function listShopEntries(opts = {}) {
             totalStock: stocks.length > 0 ? stocks.reduce((a, b) => a + b, 0) : null,
             createdAt: r.createdAt,
             updatedAt: r.updatedAt,
-            publishedData: published?.data ?? null,
-            draftData: draft?.data ?? null,
-            published: published != null
+            publishedData: firstPublished?.data ?? null,
+            draftData: firstDraft?.data ?? null,
+            publishedByLang,
+            draftByLang,
+            published: firstPublished != null
         };
     });
 }

package/dist/shop/template.d.ts

@@ -0,0 +1,13 @@
+/**
+ * String interpolation engine used by `defineShop({ variantLabel.template })`
+ * to render variant names from typed `variantAttributes`.
+ *
+ * Syntax: `{key}` or `{key|filter}` or `{key|filter:arg}`.
+ * Supported filters: `date` (long|medium|short), `currency` (PLN by default),
+ * `uppercase`. Unknown filter → value passes through unchanged. Unknown key
+ * → empty string + `console.warn` in dev. Malformed template (unclosed brace)
+ * → raw template + warn.
+ *
+ * @public
+ */
+export declare function interpolateTemplate(template: string, vars: Record<string, unknown>, locale: string): string;

package/dist/shop/template.js

@@ -0,0 +1,98 @@
+/**
+ * String interpolation engine used by `defineShop({ variantLabel.template })`
+ * to render variant names from typed `variantAttributes`.
+ *
+ * Syntax: `{key}` or `{key|filter}` or `{key|filter:arg}`.
+ * Supported filters: `date` (long|medium|short), `currency` (PLN by default),
+ * `uppercase`. Unknown filter → value passes through unchanged. Unknown key
+ * → empty string + `console.warn` in dev. Malformed template (unclosed brace)
+ * → raw template + warn.
+ *
+ * @public
+ */
+export function interpolateTemplate(template, vars, locale) {
+    if (!hasBalancedBraces(template)) {
+        console.warn(`[interpolateTemplate] Malformed template (unclosed brace): ${template}`);
+        return template;
+    }
+    return template.replace(/\{([^}]+)\}/g, (_match, body) => {
+        const { key, filter, arg } = parsePlaceholder(body);
+        if (!(key in vars)) {
+            console.warn(`[interpolateTemplate] Unknown key "${key}" in template: ${template}`);
+            return '';
+        }
+        const raw = vars[key];
+        if (raw === null || raw === undefined)
+            return '';
+        if (!filter)
+            return String(raw);
+        return applyFilter(raw, filter, arg, locale);
+    });
+}
+/** @internal */
+function parsePlaceholder(body) {
+    const [keyPart, filterPart] = body.split('|', 2);
+    const key = keyPart.trim();
+    if (!filterPart)
+        return { key, filter: null, arg: null };
+    const [filterName, ...argParts] = filterPart.split(':');
+    return {
+        key,
+        filter: filterName.trim(),
+        arg: argParts.length > 0 ? argParts.join(':').trim() : null
+    };
+}
+/** @internal */
+function applyFilter(value, filter, arg, locale) {
+    switch (filter) {
+        case 'date':
+            return formatDate(value, arg ?? 'medium', locale);
+        case 'currency':
+            return formatCurrency(value, arg ?? 'PLN', locale);
+        case 'uppercase':
+            return String(value).toUpperCase();
+        default:
+            return String(value);
+    }
+}
+/** @internal */
+function formatDate(value, style, locale) {
+    const date = new Date(String(value));
+    if (Number.isNaN(date.getTime()))
+        return String(value);
+    const dateStyle = ['long', 'medium', 'short'].includes(style)
+        ? style
+        : 'medium';
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle }).format(date);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** @internal */
+function formatCurrency(value, currency, locale) {
+    const num = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(num))
+        return String(value);
+    try {
+        return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(num);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** @internal */
+function hasBalancedBraces(template) {
+    let depth = 0;
+    for (const ch of template) {
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth < 0)
+                return false;
+        }
+    }
+    return depth === 0;
+}

package/dist/shop/types.d.ts

@@ -147,6 +147,124 @@ export interface CouponRef {
     value: number;
     discountAmount: number;
 }
+/**
+ * Schema descriptor for one product-variant attribute (city, startsAt, …).
+ * Drives Zod validation, ts-gen typings, GIN indexes, and admin renderers.
+ * @public
+ */
+export type VariantAttribute = VariantAttributeText | VariantAttributeNumber | VariantAttributeDatetime | VariantAttributeSelect | VariantAttributeBoolean | VariantAttributeImage | VariantAttributeEntry | VariantAttributeSlug;
+interface VariantAttributeBase {
+    label: I18nText;
+    required?: boolean;
+    /**
+     * Generate a `GIN ((attributes->'<key>'))` index on the variants table.
+     * Enable for keys filtered on storefront (`city`, `startsAt`, …).
+     */
+    indexable?: boolean;
+}
+/** @public */
+export interface VariantAttributeText extends VariantAttributeBase {
+    type: 'text';
+}
+/** @public */
+export interface VariantAttributeNumber extends VariantAttributeBase {
+    type: 'number';
+}
+/** @public — value stored as ISO-8601 string. */
+export interface VariantAttributeDatetime extends VariantAttributeBase {
+    type: 'datetime';
+}
+/** @public */
+export interface VariantAttributeSelect extends VariantAttributeBase {
+    type: 'select';
+    options: {
+        value: string;
+        label: I18nText;
+    }[];
+}
+/** @public */
+export interface VariantAttributeBoolean extends VariantAttributeBase {
+    type: 'boolean';
+}
+/** @public — value = media file id (UUID). */
+export interface VariantAttributeImage extends VariantAttributeBase {
+    type: 'image';
+}
+/** @public — value = entry id (UUID) from given collection. */
+export interface VariantAttributeEntry extends VariantAttributeBase {
+    type: 'entry';
+    entryCollection: string;
+}
+/** @public — value matches slug regex `^[a-z0-9-]+$`. */
+export interface VariantAttributeSlug extends VariantAttributeBase {
+    type: 'slug';
+}
+/**
+ * Template used to auto-generate `variant.name` from `variantAttributes`.
+ * Syntax: `{key|filter:arg}`. Filters: `date` (long|medium|short),
+ * `currency` (currency code), `uppercase`. Admin pre-fills the name input
+ * with the interpolated string; once the editor types into the name field,
+ * pre-fill stops for that variant (per-session dirty flag).
+ * @public
+ */
+export interface VariantLabelConfig {
+    template: string;
+}
+/**
+ * Per-product payment policy. `full` (default) charges the full order total
+ * immediately; `deposit` charges only a deposit at checkout and leaves a
+ * remaining balance owed by the customer, redeemable via a signed balance
+ * link sent by the admin. Set on `ShopFieldData.paymentPolicy` per product
+ * entry — not globally on `defineShop`.
+ * @public
+ */
+export type PaymentPolicy = {
+    type: 'full';
+} | {
+    type: 'deposit';
+    depositAmount: DepositAmount;
+};
+/**
+ * Deposit amount specifier. `percent` charges `floor(base * value / 100)` of
+ * the line total; `amount` charges a fixed minor-unit value (clamped to the
+ * line total). Validation: `value > 0` always; `percent` ≤ 100; `amount` in
+ * the same minor-unit as `order.totalGross` (grosze for PLN).
+ * @public
+ */
+export type DepositAmount = {
+    type: 'percent';
+    value: number;
+} | {
+    type: 'amount';
+    value: number;
+};
+/**
+ * Persisted partial-payment summary on `order.partialPayment` when the order
+ * was placed under a deposit policy. Amounts are in minor currency units
+ * (grosze for PLN). `paidAt` is the ISO timestamp when the deposit cleared
+ * (or `null` while still pending). On balance payment, `paidAmount` is
+ * bumped to the full order total and `paidAt` is refreshed.
+ * @public
+ */
+export interface PartialPayment {
+    kind: 'deposit';
+    paidAmount: number;
+    balanceAmount: number;
+    paidAt: string | null;
+}
+/**
+ * Opt-in storefront filter that hides variants whose datetime attribute
+ * (`source`, e.g. `startsAt`) has already passed. `offsetDays` shifts the
+ * cut-off: `0` = expire exactly when the source datetime hits now, `1` = one
+ * day after (grace period), `-1` = one day before. Admin still shows expired
+ * variants with a "Zakończony" badge; storefront `listUpcoming` filters them
+ * out and cart/checkout reject them with `VARIANT_EXPIRED`.
+ * @public
+ */
+export interface VariantExpiryConfig {
+    source: string;
+    offsetDays: number;
+}
 export interface ShopConfig {
     currency: Currency;
     vatRates: number[];
@@ -168,11 +286,34 @@ export interface ShopConfig {
      * automatic admin notifications. Omitted = those alerts are no-ops.
      */
     adminEmail?: string;
+    /**
+     * Typed variant attribute schema. Each key declares one attribute (city,
+     * startsAt, …) — drives Zod validation, ts-gen typings, GIN indexes, and
+     * admin variant form renderer. Omitted = legacy untyped string map.
+     * @public
+     */
+    variantAttributes?: Record<string, VariantAttribute>;
+    /**
+     * Template used by admin to auto-prefill `variant.name` from typed
+     * `variantAttributes`. Omitted = no pre-fill (editor enters name manually).
+     * @public
+     */
+    variantLabel?: VariantLabelConfig;
+    /**
+     * Opt-in storefront filter for time-bound variants (events, courses).
+     * Omitted = no filtering (legacy behavior — every variant always listed).
+     * @public
+     */
+    variantExpiry?: VariantExpiryConfig;
 }
-export interface ResolvedShopConfig extends ShopConfig {
+export interface ResolvedShopConfig extends Omit<ShopConfig, 'variantLabel' | 'variantExpiry'> {
     features: Required<ShopFeatures>;
     rateLimit: Required<ShopRateLimit>;
     carriers: CarrierAdapter[];
     consents: ConsentConfig[];
     orderViewUrl: string;
+    variantAttributes: Record<string, VariantAttribute>;
+    variantLabel: VariantLabelConfig | null;
+    variantExpiry: VariantExpiryConfig | null;
 }
+export {};

package/dist/shop/variant-attributes.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { VariantAttribute } from './types.js';
+/**
+ * Build a Zod object schema from a `defineShop({ variantAttributes })` map.
+ * Required attributes are mandatory keys; optional ones use `.optional()`.
+ * Empty map → `z.object({})`.
+ * @internal
+ */
+export declare function buildVariantAttributesSchema(attrs: Record<string, VariantAttribute>): z.ZodObject<Record<string, z.ZodType>>;
+/**
+ * @public
+ * Thrown by `upsertShopData` (and `validateVariantAttributes`) when a
+ * `variant.attributes` payload fails the schema derived from
+ * `defineShop({ variantAttributes })`. Carries the raw Zod issues.
+ */
+export declare class InvalidVariantAttributesError extends Error {
+    readonly code = "INVALID_VARIANT_ATTRIBUTES";
+    readonly issues: z.ZodIssue[];
+    constructor(issues: z.ZodIssue[]);
+}
+/**
+ * Validate a variant attributes payload against a shop config.
+ * Throws `InvalidVariantAttributesError` (code `INVALID_VARIANT_ATTRIBUTES`) on
+ * failure. Returns the parsed (and coerced where applicable) value on success.
+ * `null` / `undefined` payloads are treated as `{}`.
+ * @internal
+ */
+export declare function validateVariantAttributes(value: unknown, attrs: Record<string, VariantAttribute>): Record<string, unknown>;

package/dist/shop/variant-attributes.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+const SLUG_REGEX = /^[a-z0-9-]+$/;
+function buildLeafSchema(attr) {
+    switch (attr.type) {
+        case 'text':
+            return attr.required ? z.string().min(1) : z.string();
+        case 'number':
+            return z.number().finite();
+        case 'datetime':
+            // Accept full ISO 8601: UTC (`...Z`) AND offset forms (`+02:00`).
+            // Admin DatetimeField produces `Z` via toISOString(); imports/seeds
+            // may use local offsets. Both are valid ISO 8601.
+            return z.string().datetime({ offset: true });
+        case 'select':
+            return z.enum(attr.options.map((o) => o.value));
+        case 'boolean':
+            return z.boolean();
+        case 'image':
+        case 'entry':
+            return z.string().uuid();
+        case 'slug':
+            return z.string().regex(SLUG_REGEX);
+    }
+}
+/**
+ * Build a Zod object schema from a `defineShop({ variantAttributes })` map.
+ * Required attributes are mandatory keys; optional ones use `.optional()`.
+ * Empty map → `z.object({})`.
+ * @internal
+ */
+export function buildVariantAttributesSchema(attrs) {
+    const shape = {};
+    for (const [key, attr] of Object.entries(attrs)) {
+        const leaf = buildLeafSchema(attr);
+        shape[key] = attr.required ? leaf : leaf.optional();
+    }
+    return z.object(shape);
+}
+/**
+ * @public
+ * Thrown by `upsertShopData` (and `validateVariantAttributes`) when a
+ * `variant.attributes` payload fails the schema derived from
+ * `defineShop({ variantAttributes })`. Carries the raw Zod issues.
+ */
+export class InvalidVariantAttributesError extends Error {
+    code = 'INVALID_VARIANT_ATTRIBUTES';
+    issues;
+    constructor(issues) {
+        super(`Invalid variant attributes: ${issues.map((i) => i.message).join('; ')}`);
+        this.name = 'InvalidVariantAttributesError';
+        this.issues = issues;
+    }
+}
+/**
+ * Validate a variant attributes payload against a shop config.
+ * Throws `InvalidVariantAttributesError` (code `INVALID_VARIANT_ATTRIBUTES`) on
+ * failure. Returns the parsed (and coerced where applicable) value on success.
+ * `null` / `undefined` payloads are treated as `{}`.
+ * @internal
+ */
+export function validateVariantAttributes(value, attrs) {
+    const schema = buildVariantAttributesSchema(attrs);
+    const input = value ?? {};
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        throw new InvalidVariantAttributesError(result.error.issues);
+    }
+    return result.data;
+}