includio-cms 0.25.0 → 0.27.0

package/dist/core/server/fields/slugResolver.js

@@ -1,50 +1,21 @@
 import { getCMS } from '../../cms.js';
-const DEFAULT_SLUG_PATH = 'seo.slug';
-/**
- * Get the dot-path to the slug field for a given collection/single slug.
- * Falls back to 'seo.slug' if no slugField is configured.
- */
+import { getSlugFromEntryData, resolveSlugPath, applyPathTemplate } from '../../fields/slugPath.js';
+export { getSlugFromEntryData } from '../../fields/slugPath.js';
+/** Get dot-path to slug field for a collection. Falls back to 'seo.slug'. */
 export function getEntrySlugPath(configSlug) {
     try {
-        const config = getCMS().getBySlug(configSlug);
-        return config.slugField || DEFAULT_SLUG_PATH;
+        return resolveSlugPath(getCMS().getBySlug(configSlug).slugField);
     }
     catch {
-        return DEFAULT_SLUG_PATH;
+        return resolveSlugPath(undefined);
     }
 }
-/**
- * Traverse a dot-path in entry data and return the slug value.
- * Handles both plain strings and localized objects { lang: string }.
- */
-export function getSlugFromEntryData(data, slugPath, language) {
-    const parts = slugPath.split('.');
-    let current = data;
-    for (const part of parts) {
-        if (current == null || typeof current !== 'object')
-            return undefined;
-        current = current[part];
-    }
-    if (typeof current === 'string')
-        return current;
-    if (language && current != null && typeof current === 'object') {
-        return current[language];
-    }
-    return undefined;
-}
-/**
- * Build full entry path using collection's pathTemplate.
- * If no template configured, returns the raw slug.
- */
+/** Build full entry path using collection's pathTemplate. */
 export function getEntryPath(configSlug, slug) {
     try {
-        const config = getCMS().getBySlug(configSlug);
-        if (config.pathTemplate) {
-            return config.pathTemplate.replace('{slug}', slug);
-        }
+        return applyPathTemplate(getCMS().getBySlug(configSlug).pathTemplate, slug);
     }
     catch {
-        // Config not found — fall through
+        return applyPathTemplate(undefined, slug);
     }
-    return slug;
 }

package/dist/core/server/generator/fields.d.ts

@@ -1,6 +1,8 @@
 import type { Field } from '../../../types/fields.js';
 import type { CustomFieldDefinition } from '../../../types/plugins.js';
+import type { VariantAttribute } from '../../../shop/types.js';
 export declare function setGeneratorCustomFields(customFields: Map<string, CustomFieldDefinition>): void;
+export declare function setGeneratorShopVariantAttributes(attrs: Record<string, VariantAttribute>): void;
 export declare function generateTsTypeFromFields(fields: Field[]): string;
 export declare function generateFlatTsTypeFromFields(fields: Field[]): string;
 export interface InlineBlockTypeDef {

package/dist/core/server/generator/fields.js

@@ -1,11 +1,44 @@
-import { toPascalCase } from './utils.js';
+import { toPascalCase, quoteKey } from './utils.js';
+import { buildSeoTsType } from '../../fields/seoFieldDescriptor.js';
 let _customFields = new Map();
+let _shopVariantAttributes = {};
 function isGuaranteed(f) {
     return !!(f.required || f.type === 'seo' || f.defaultValue !== undefined);
 }
 export function setGeneratorCustomFields(customFields) {
     _customFields = customFields;
 }
+export function setGeneratorShopVariantAttributes(attrs) {
+    _shopVariantAttributes = attrs;
+}
+function variantAttributeTsType(attr) {
+    switch (attr.type) {
+        case 'text':
+        case 'datetime':
+        case 'image':
+        case 'entry':
+        case 'slug':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'select':
+            return attr.options.map((o) => `'${o.value}'`).join(' | ');
+    }
+}
+function buildShopAttributesType() {
+    const entries = Object.entries(_shopVariantAttributes);
+    if (entries.length === 0)
+        return 'Record<string, string> | null';
+    const fields = entries
+        .map(([key, attr]) => {
+        const opt = attr.required ? '' : '?';
+        return `${quoteKey(key)}${opt}: ${variantAttributeTsType(attr)}`;
+    })
+        .join('; ');
+    return `{ ${fields} }`;
+}
 function getFieldTypeAsString(field) {
     switch (field.type) {
         case 'text':
@@ -43,7 +76,7 @@ function getFieldTypeAsString(field) {
         case 'object':
             return `{
 				slug: '${field.slug}';
-				data: {${field.fields.map((f) => `  ${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFieldTypeAsString(f)}`).join(';\n')}};
+				data: {${field.fields.map((f) => `  ${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFieldTypeAsString(f)}`).join(';\n')}};
 			}`;
         case 'blocks':
             return `
@@ -52,7 +85,7 @@ function getFieldTypeAsString(field) {
                 .map((f) => `
 				{
 					slug: '${f.slug}';
-					data: {${f.fields.map((f) => `  ${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFieldTypeAsString(f)}`).join(';\n')}};
+					data: {${f.fields.map((f) => `  ${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFieldTypeAsString(f)}`).join(';\n')}};
 				}
 			`)
                 .join(' | ')}
@@ -67,17 +100,10 @@ function getFieldTypeAsString(field) {
                     return 'UrlFieldData[]';
             }
         case 'slug':
+        case 'icon':
             return 'string';
         case 'seo':
-            return `{
-				slug: string;
-				canonicalUrl?: string;
-				title: string;
-				description?: string;
-				ogImage?: string;
-				keywords?: string;
-				customCode?: string;
-			}`;
+            return buildSeoTsType();
         case 'shop':
             return `{
 				basePrice: number;
@@ -89,7 +115,7 @@ function getFieldTypeAsString(field) {
 					name: Record<string, string> | null;
 					priceDelta: number;
 					stock: number | null;
-					attributes: Record<string, string> | null;
+					attributes: ${buildShopAttributesType()};
 				}>;
 			} | null`;
         case 'url': {
@@ -110,12 +136,12 @@ function getFieldTypeAsString(field) {
 }
 export function generateTsTypeFromFields(fields) {
     return `{
-    ${fields.map((f) => `  ${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFieldTypeAsString(f)}`).join(';\n')};
+    ${fields.map((f) => `  ${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFieldTypeAsString(f)}`).join(';\n')};
   }`;
 }
 export function generateFlatTsTypeFromFields(fields) {
     return `{
-    ${fields.map((f) => `  ${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
+    ${fields.map((f) => `  ${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
   }`;
 }
 function getFlatFieldTypeAsString(field) {
@@ -133,7 +159,7 @@ function getFlatFieldTypeAsString(field) {
         case 'object':
             return `{
 				_slug: '${field.slug}';
-				${field.fields.map((f) => `${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
+				${field.fields.map((f) => `${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
 			}`;
         case 'blocks':
             return `
@@ -142,7 +168,7 @@ function getFlatFieldTypeAsString(field) {
                 .map((f) => `
 				{
 					_slug: '${f.slug}';
-					${f.fields.map((f) => `${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
+					${f.fields.map((f) => `${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
 				}
 			`)
                 .join(' | ')}
@@ -153,6 +179,6 @@ function getFlatFieldTypeAsString(field) {
 }
 export function generateInlineBlockTypeString(block) {
     return `{
-    ${block.fields.map((f) => `  ${f.slug}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
+    ${block.fields.map((f) => `  ${quoteKey(f.slug)}${isGuaranteed(f) ? '' : '?'}: ${getFlatFieldTypeAsString(f)}`).join(';\n')};
   }`;
 }

package/dist/core/server/generator/formFields.js

@@ -1,3 +1,4 @@
+import { quoteKey } from './utils.js';
 function getFormFieldTypeAsString(field) {
     switch (field.type) {
         case 'text':
@@ -15,6 +16,6 @@ function getFormFieldTypeAsString(field) {
 }
 export function generateTsTypeFromFormFields(fields) {
     return `{
-    ${fields.map((f) => `  ${f.slug}: ${getFormFieldTypeAsString(f)}`).join(';\n')};
+    ${fields.map((f) => `  ${quoteKey(f.slug)}: ${getFormFieldTypeAsString(f)}`).join(';\n')};
   }`;
 }

package/dist/core/server/generator/generator.js

@@ -1,9 +1,9 @@
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { generateTsTypeFromFields, generateFlatTsTypeFromFields, generateInlineBlockTypeString, setGeneratorCustomFields } from './fields.js';
+import { generateTsTypeFromFields, generateFlatTsTypeFromFields, generateInlineBlockTypeString, setGeneratorCustomFields, setGeneratorShopVariantAttributes } from './fields.js';
 import { generateTsTypeFromFormFields } from './formFields.js';
 import { generateZodSchemaStringFromFormFieldsAsString } from './formFieldSchemaToString.js';
-import { toPascalCase } from './utils.js';
+import { toPascalCase, quoteKey } from './utils.js';
 import { getFieldsFromConfig } from '../../fields/layoutUtils.js';
 function createCmsRuntimeDir() {
     const cmsDir = join(process.cwd(), 'src/lib/cms/runtime');
@@ -54,7 +54,7 @@ function generateTypesStringForRecords(type, records) {
 		export type ${recordTypeString}EntryMap = {
 			${records
         .map((single) => {
-        const key = single.slug.includes('-') ? `'${single.slug}'` : single.slug;
+        const key = quoteKey(single.slug);
         return `${key}: ${toPascalCase(single.slug)}`;
     })
         .join(';\n')}
@@ -82,7 +82,7 @@ function generateTypesStringForForms(records) {
 		export type ${recordTypeString}EntryMap = {
 			${records
         .map((single) => {
-        const key = single.slug.includes('-') ? `'${single.slug}'` : single.slug;
+        const key = quoteKey(single.slug);
         return `${key}: ${toPascalCase(single.slug)}`;
     })
         .join(';\n')}
@@ -163,7 +163,7 @@ function generateTypes(config) {
                     const mapName = toPascalCase(record.slug) + toPascalCase(field.slug) + 'BlockDataMap';
                     code += `\nexport type ${mapName} = {\n`;
                     for (const block of cf.inlineBlocks) {
-                        const key = block.slug.includes('-') ? `'${block.slug}'` : block.slug;
+                        const key = quoteKey(block.slug);
                         code += `  ${key}: ${toPascalCase(block.slug)}BlockData;\n`;
                     }
                     code += `};\n`;
@@ -312,6 +312,7 @@ export function generateRuntime(config) {
         }
     }
     setGeneratorCustomFields(customFields);
+    setGeneratorShopVariantAttributes(config.shop?.variantAttributes ?? {});
     createCmsRuntimeDir();
     generateTypes(config);
     generateAPI(config);

package/dist/core/server/generator/utils.d.ts

@@ -1 +1,2 @@
 export declare function toPascalCase(slug: string): string;
+export declare function quoteKey(slug: string): string;

package/dist/core/server/generator/utils.js

@@ -4,3 +4,7 @@ export function toPascalCase(slug) {
         .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
         .join('');
 }
+const JS_IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+export function quoteKey(slug) {
+    return JS_IDENT_RE.test(slug) ? slug : `'${slug}'`;
+}

package/dist/db-postgres/schema/shop/order.d.ts

@@ -1,4 +1,4 @@
-import type { OrderStatus } from '../../../shop/types.js';
+import type { OrderStatus, PartialPayment } from '../../../shop/types.js';
 export declare const shopOrdersTable: import("drizzle-orm/pg-core/table", { with: { "resolution-mode": "require" } }).PgTableWithColumns<{
     name: "shop_orders";
     schema: undefined;
@@ -459,6 +459,42 @@ export declare const shopOrdersTable: import("drizzle-orm/pg-core/table", { with
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        partialPayment: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "partial_payment";
+            tableName: "shop_orders";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: PartialPayment | null;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: PartialPayment | null;
+        }>;
+        balanceOwed: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "balance_owed";
+            tableName: "shop_orders";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
             name: "created_at";
             tableName: "shop_orders";

package/dist/db-postgres/schema/shop/order.js

@@ -1,4 +1,4 @@
-import { integer, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { boolean, integer, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
 import { shopShippingMethodsTable } from './shippingMethod.js';
 export const shopOrdersTable = pgTable('shop_orders', {
     id: uuid('id').primaryKey().defaultRandom(),
@@ -29,6 +29,8 @@ export const shopOrdersTable = pgTable('shop_orders', {
     notes: text('notes'),
     language: text('language'),
     accessToken: uuid('access_token').defaultRandom().notNull(),
+    partialPayment: jsonb('partial_payment').$type(),
+    balanceOwed: boolean('balance_owed').default(false).notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull()
 });

package/dist/db-postgres/schema/shop/payment.d.ts

@@ -1,4 +1,7 @@
 export type ShopPaymentStatus = 'pending' | 'paid' | 'failed' | 'refunded' | 'cancelled';
+/** `kind` distinguishes full / deposit / balance payment rows under paymentPolicy A-lite. */
+export declare const shopPaymentKindEnum: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgEnum<["full", "deposit", "balance"]>;
+export type ShopPaymentKind = 'full' | 'deposit' | 'balance';
 export declare const shopPaymentsTable: import("drizzle-orm/pg-core/table", { with: { "resolution-mode": "require" } }).PgTableWithColumns<{
     name: "shop_payments";
     schema: undefined;
@@ -90,6 +93,23 @@ export declare const shopPaymentsTable: import("drizzle-orm/pg-core/table", { wi
         }, {}, {
             $type: ShopPaymentStatus;
         }>;
+        kind: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "kind";
+            tableName: "shop_payments";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "full" | "deposit" | "balance";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["full", "deposit", "balance"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         amount: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
             name: "amount";
             tableName: "shop_payments";

package/dist/db-postgres/schema/shop/payment.js

@@ -1,5 +1,7 @@
-import { integer, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { integer, jsonb, pgEnum, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
 import { shopOrdersTable } from './order.js';
+/** `kind` distinguishes full / deposit / balance payment rows under paymentPolicy A-lite. */
+export const shopPaymentKindEnum = pgEnum('shop_payment_kind', ['full', 'deposit', 'balance']);
 export const shopPaymentsTable = pgTable('shop_payments', {
     id: uuid('id').primaryKey().defaultRandom(),
     orderId: uuid('order_id')
@@ -8,6 +10,7 @@ export const shopPaymentsTable = pgTable('shop_payments', {
     provider: text('provider').notNull(),
     providerRef: text('provider_ref'),
     status: text('status').$type().notNull().default('pending'),
+    kind: shopPaymentKindEnum('kind').notNull().default('full'),
     amount: integer('amount').notNull(),
     currency: text('currency').notNull(),
     raw: jsonb('raw'),

package/dist/db-postgres/schema/shop/product.d.ts

@@ -1,3 +1,4 @@
+import type { PaymentPolicy } from '../../../shop/types.js';
 export declare const shopProductsTable: import("drizzle-orm/pg-core/table", { with: { "resolution-mode": "require" } }).PgTableWithColumns<{
     name: "shop_products";
     schema: undefined;
@@ -121,6 +122,25 @@ export declare const shopProductsTable: import("drizzle-orm/pg-core/table", { wi
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        paymentPolicy: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "payment_policy";
+            tableName: "shop_products";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: PaymentPolicy | null;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: PaymentPolicy | null;
+        }>;
         createdAt: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
             name: "created_at";
             tableName: "shop_products";

package/dist/db-postgres/schema/shop/product.js

@@ -1,4 +1,4 @@
-import { boolean, integer, numeric, pgTable, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { boolean, integer, jsonb, numeric, pgTable, timestamp, uuid } from 'drizzle-orm/pg-core';
 import { entriesTable } from '../entry.js';
 export const shopProductsTable = pgTable('shop_products', {
     id: uuid('id').primaryKey().defaultRandom(),
@@ -13,6 +13,8 @@ export const shopProductsTable = pgTable('shop_products', {
     sortOrder: integer('sort_order'),
     // Null = alert disabled. When stock decrement crosses threshold, fire-and-forget admin email.
     lowStockThreshold: integer('low_stock_threshold'),
+    // Per-product payment policy. Null = full payment (legacy).
+    paymentPolicy: jsonb('payment_policy').$type(),
     createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull()
 });

package/dist/db-postgres/schema/shop/productVariant.d.ts

@@ -1,3 +1,4 @@
+import type { VariantAttribute } from '../../../shop/types.js';
 export declare const shopProductVariantsTable: import("drizzle-orm/pg-core/table", { with: { "resolution-mode": "require" } }).PgTableWithColumns<{
     name: "shop_product_variants";
     schema: undefined;
@@ -111,7 +112,7 @@ export declare const shopProductVariantsTable: import("drizzle-orm/pg-core/table
             tableName: "shop_product_variants";
             dataType: "json";
             columnType: "PgJsonb";
-            data: Record<string, string>;
+            data: Record<string, unknown>;
             driverParam: unknown;
             notNull: false;
             hasDefault: false;
@@ -123,7 +124,7 @@ export declare const shopProductVariantsTable: import("drizzle-orm/pg-core/table
             identity: undefined;
             generated: undefined;
         }, {}, {
-            $type: Record<string, string>;
+            $type: Record<string, unknown>;
         }>;
         sortOrder: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
             name: "sort_order";
@@ -162,3 +163,12 @@ export declare const shopProductVariantsTable: import("drizzle-orm/pg-core/table
     };
     dialect: "pg";
 }>;
+/**
+ * Build `CREATE INDEX IF NOT EXISTS … USING gin ((attributes->'<key>'))` DDL
+ * statements — one per attribute marked `indexable: true`. Drizzle's static
+ * schema can't capture user-defined variantAttributes, so apply these at shop
+ * bootstrap (or via the migration in `src/lib/updates/0.27.0`).
+ * Index name pattern: `shop_variant_attr_<key>_gin_idx`.
+ * @internal
+ */
+export declare function createVariantAttributeIndexes(attrs: Record<string, VariantAttribute>): string[];

package/dist/db-postgres/schema/shop/productVariant.js

@@ -14,3 +14,25 @@ export const shopProductVariantsTable = pgTable('shop_product_variants', {
     sortOrder: integer('sort_order'),
     createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull()
 });
+const SAFE_KEY = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/**
+ * Build `CREATE INDEX IF NOT EXISTS … USING gin ((attributes->'<key>'))` DDL
+ * statements — one per attribute marked `indexable: true`. Drizzle's static
+ * schema can't capture user-defined variantAttributes, so apply these at shop
+ * bootstrap (or via the migration in `src/lib/updates/0.27.0`).
+ * Index name pattern: `shop_variant_attr_<key>_gin_idx`.
+ * @internal
+ */
+export function createVariantAttributeIndexes(attrs) {
+    const stmts = [];
+    for (const [key, attr] of Object.entries(attrs)) {
+        if (!attr.indexable)
+            continue;
+        if (!SAFE_KEY.test(key)) {
+            throw new Error(`variantAttribute key "${key}" is not a safe SQL identifier (allowed: [A-Za-z][A-Za-z0-9_]*).`);
+        }
+        stmts.push(`CREATE INDEX IF NOT EXISTS shop_variant_attr_${key}_gin_idx ` +
+            `ON shop_product_variants USING gin ((attributes->'${key}'))`);
+    }
+    return stmts;
+}

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

@@ -5,6 +5,7 @@ export interface CartItemRef {
 }
 export interface CartLine extends CartItemRef {
     entryId: string;
+    productId: string;
     variantName: Record<string, string> | null;
     variantSku: string | null;
     productTitle: string | null;

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

@@ -114,6 +114,34 @@ export interface RetryPaymentResult {
     requiresPaymentRedirect: boolean;
     redirectUrl: string | null;
 }
+/**
+ * Result of `orders.payBalance` — initiates a payment session for the
+ * outstanding balance on a deposit order.
+ * @public
+ */
+export interface PayBalanceResult {
+    status: 'redirect' | 'manual' | 'error';
+    requiresPaymentRedirect: boolean;
+    redirectUrl: string | null;
+}
+/**
+ * Public-facing variant row returned by `client.products.listUpcoming`.
+ * Mirrors the `shop_product_variants` schema with `priceDelta` decoded as
+ * the raw numeric(20,6) string and `attributes` as the typed map declared
+ * in `defineShop({ variantAttributes })`.
+ * @public
+ */
+export interface VariantPublic {
+    id: string;
+    productId: string;
+    sku: string | null;
+    name: Record<string, string> | null;
+    priceDelta: string;
+    stock: number | null;
+    attributes: Record<string, unknown> | null;
+    sortOrder: number | null;
+    createdAt: string;
+}
 /**
  * Headless shop SDK surface returned by `createShopClient()`.
  *
@@ -124,6 +152,21 @@ export interface RetryPaymentResult {
  * @public
  */
 export interface ShopClient {
+    /** Product / variant discovery. */
+    products: {
+        /**
+         * List upcoming (non-expired) variants for a product. When
+         * `defineShop({ variantExpiry })` is not configured this returns
+         * every variant; otherwise variants whose datetime attribute has
+         * already passed (per `offsetDays`) are filtered out and the
+         * remainder are sorted ascending by that attribute.
+         *
+         * @param productId - The shop product id (UUID).
+         */
+        listUpcoming(productId: string): Promise<{
+            items: VariantPublic[];
+        }>;
+    };
     /** Cart operations — read state and mutate items / coupon. */
     cart: {
         /**
@@ -201,6 +244,17 @@ export interface ShopClient {
          * re-fill the checkout form.
          */
         retryPayment(orderNumber: string, token?: string): Promise<RetryPaymentResult>;
+        /**
+         * Pay the outstanding balance on a deposit-policy order. `token` is
+         * the signed balance token from the admin-generated balance link;
+         * the server returns a redirect URL when the payment provider needs
+         * to take over, or `paymentStatus: 'manual'` for manual methods.
+         *
+         * @param orderNumber - The order number from the balance link.
+         * @param token - Signed balance token (query parameter on the link).
+         * @experimental
+         */
+        payBalance(orderNumber: string, token: string): Promise<PayBalanceResult>;
     };
 }
 /**

package/dist/shop/client/index.js

@@ -59,6 +59,9 @@ export function createShopClient(options = {}) {
         return (await res.json());
     }
     return {
+        products: {
+            listUpcoming: (productId) => call('GET', `/api/shop/products/${encodeURIComponent(productId)}/variants/upcoming`)
+        },
         cart: {
             get: () => call('GET', '/api/shop/cart'),
             add: (variantId, qty = 1) => call('POST', '/api/shop/cart', { variantId, qty }),
@@ -77,7 +80,8 @@ export function createShopClient(options = {}) {
         orders: {
             get: (orderNumber, token) => call('GET', `/api/shop/orders/${encodeURIComponent(orderNumber)}${tokenQuery(token)}`),
             refreshPayment: (orderNumber, token) => call('POST', `/api/shop/orders/${encodeURIComponent(orderNumber)}/refresh-payment${tokenQuery(token)}`),
-            retryPayment: (orderNumber, token) => call('POST', `/api/shop/orders/${encodeURIComponent(orderNumber)}/retry-payment${tokenQuery(token)}`)
+            retryPayment: (orderNumber, token) => call('POST', `/api/shop/orders/${encodeURIComponent(orderNumber)}/retry-payment${tokenQuery(token)}`),
+            payBalance: (orderNumber, token) => call('POST', `/api/shop/orders/${encodeURIComponent(orderNumber)}/balance?token=${encodeURIComponent(token)}`, {})
         }
     };
 }

package/dist/shop/expiry.d.ts

@@ -0,0 +1,35 @@
+import type { VariantExpiryConfig } from './types.js';
+/**
+ * Thrown by `createOrderFromCart` / cart-add HTTP guard when a referenced
+ * variant has already expired under the configured `variantExpiry`. The
+ * `code` is `VARIANT_EXPIRED` and `variantId` identifies the offending row.
+ * @public
+ */
+export declare class VariantExpiredError extends Error {
+    readonly code = "VARIANT_EXPIRED";
+    readonly variantId: string;
+    constructor(variantId: string);
+}
+interface VariantLike {
+    attributes: Record<string, unknown> | null;
+}
+/**
+ * Check whether a variant has expired under the given config. Fail-open by
+ * design: `null` config, missing source attribute, non-string value, or
+ * malformed datetime all return `false` — only a parseable past datetime
+ * counts as expired. Malformed datetimes emit `console.warn` so authoring
+ * issues surface in dev without blocking checkout.
+ *
+ * @param variant - Object with an `attributes` map (e.g. `shop_product_variants.attributes`).
+ * @param config - Result of `defineShop({ variantExpiry })`, or `null` when not configured.
+ * @param now - Override the current time (test seam). Defaults to `Date.now()`.
+ * @public
+ */
+export declare function isVariantExpired(variant: VariantLike, config: VariantExpiryConfig | null, now?: Date): boolean;
+/**
+ * Return the subset of `variants` that have not yet expired. Order is
+ * preserved. `null` config = passthrough.
+ * @public
+ */
+export declare function filterUpcoming<T extends VariantLike>(variants: T[], config: VariantExpiryConfig | null, now?: Date): T[];
+export {};