includio-cms 0.26.0 → 0.27.0

package/dist/shop/http/cart-handler.js

@@ -1,10 +1,14 @@
+import { eq } from 'drizzle-orm';
 import { json } from '@sveltejs/kit';
 import { getCMS } from '../../core/cms.js';
+import { shopProductVariantsTable } from '../../db-postgres/schema/shop/index.js';
 import { addItem, readCartCookie, removeItem, setItemQty, writeCartCookie } from '../cart/cookie.js';
 import { clearCouponCookie, isValidCouponCode, normalizeCouponCode, readCouponCookie, writeCouponCookie } from '../cart/coupon-cookie.js';
 import { hydrateCart } from '../server/cart-hydrate.js';
 import { CouponError, validateCoupon } from '../server/coupons.js';
+import { getShopDb } from '../server/db.js';
 import { checkRateLimit, clientKey } from '../rate-limit.js';
+import { isVariantExpired } from '../expiry.js';
 function shopEnabled() {
     try {
         return getCMS().shopConfig !== null;
@@ -54,6 +58,21 @@ export function createCartHandler() {
             if (!Number.isFinite(qtyNum) || qtyNum <= 0) {
                 return json({ error: 'qty must be > 0' }, { status: 400 });
             }
+            const expiryConfig = getCMS().shopConfig?.variantExpiry ?? null;
+            if (expiryConfig) {
+                const db = getShopDb();
+                const [row] = await db
+                    .select({
+                    id: shopProductVariantsTable.id,
+                    attributes: shopProductVariantsTable.attributes
+                })
+                    .from(shopProductVariantsTable)
+                    .where(eq(shopProductVariantsTable.id, variantId));
+                if (row &&
+                    isVariantExpired({ attributes: row.attributes }, expiryConfig)) {
+                    return json({ error: 'VARIANT_EXPIRED', variantId }, { status: 400 });
+                }
+            }
             const items = readCartCookie(cookies);
             const next = addItem(items, variantId, qtyNum);
             writeCartCookie(cookies, next);

package/dist/shop/http/checkout-handler.js

@@ -4,6 +4,7 @@ import { readCartCookie, writeCartCookie } from '../cart/cookie.js';
 import { clearCouponCookie, readCouponCookie } from '../cart/coupon-cookie.js';
 import { writeOrderTokenCookie } from '../cart/order-token-cookie.js';
 import { createOrderFromCart, setPaymentProviderRef } from '../server/orders.js';
+import { insertPaymentRow } from '../server/payments.js';
 import { getShippingMethod } from '../server/shipping.js';
 import { checkRateLimit, clientKey } from '../rate-limit.js';
 import { requireShopConfig } from '../server/db.js';
@@ -119,10 +120,16 @@ export function createCheckoutHandler() {
                 const adapter = shop.payment.find((a) => a.id === paymentMethod);
                 let paymentResult = null;
                 if (adapter) {
+                    // Under deposit policy, charge only the resolved deposit (line
+                    // deposits + shipping) at checkout. The balance flow charges the
+                    // remainder via a signed token later. We override totalGross on
+                    // the OrderRef passed to the adapter so adapters that compute the
+                    // charge from `orderRef.totalGross` Just Work — `order.totalGross`
+                    // in the DB stays the source of truth for the full obligation.
                     const orderRef = {
                         id: result.order.id,
                         number: result.order.number,
-                        totalGross: result.order.totalGross,
+                        totalGross: result.amountToPay,
                         currency: shop.currency,
                         customerEmail: result.order.customerEmail
                     };
@@ -141,6 +148,17 @@ export function createCheckoutHandler() {
                         if (paymentResult.providerRef) {
                             await setPaymentProviderRef(result.order.id, paymentResult.providerRef);
                         }
+                        // Track this payment as its own row so the webhook can branch
+                        // by `kind` (full / deposit / balance) and `refundOrder` can
+                        // target deposit-vs-balance independently.
+                        await insertPaymentRow({
+                            orderId: result.order.id,
+                            provider: adapter.id,
+                            providerRef: paymentResult.providerRef ?? null,
+                            kind: result.paymentKind,
+                            amount: result.amountToPay,
+                            currency: shop.currency
+                        });
                     }
                     catch (err) {
                         console.error(`[shop] createPayment failed for ${result.order.number}:`, err);

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

@@ -8,3 +8,5 @@ export { createRetryPaymentHandler } from './retry-payment-handler.js';
 export { createCarrierConfigHandler } from './carrier-handler.js';
 export { createCarrierWebhookHandler } from './carrier-webhook-handler.js';
 export { createShipmentLabelHandler } from './shipment-label-handler.js';
+export { createUpcomingVariantsHandler } from './upcoming-handler.js';
+export { createBalanceHandler } from './balance-handler.js';

package/dist/shop/http/index.js

@@ -8,3 +8,5 @@ export { createRetryPaymentHandler } from './retry-payment-handler.js';
 export { createCarrierConfigHandler } from './carrier-handler.js';
 export { createCarrierWebhookHandler } from './carrier-webhook-handler.js';
 export { createShipmentLabelHandler } from './shipment-label-handler.js';
+export { createUpcomingVariantsHandler } from './upcoming-handler.js';
+export { createBalanceHandler } from './balance-handler.js';

package/dist/shop/http/upcoming-handler.d.ts

@@ -0,0 +1,16 @@
+import { type RequestHandler } from '@sveltejs/kit';
+/**
+ * Build a SvelteKit `GET` handler for upcoming variants of a single product.
+ * Mount at `/api/shop/products/[id]/variants/upcoming`.
+ *
+ * Returns `{ items: VariantRow[] }`. When `defineShop({ variantExpiry })` is
+ * configured, expired variants are filtered out; otherwise every variant for
+ * the product is returned. Order: `attributes.<source>` ascending if expiry
+ * config is set, otherwise insertion order.
+ *
+ * @experimental — HTTP shape is stable for envet pilot but may grow in 1.x
+ *   (e.g. pagination, language filter) once a second consumer lands.
+ */
+export declare function createUpcomingVariantsHandler(): {
+    GET: RequestHandler;
+};

package/dist/shop/http/upcoming-handler.js

@@ -0,0 +1,65 @@
+import { asc, eq } from 'drizzle-orm';
+import { json } from '@sveltejs/kit';
+import { getCMS } from '../../core/cms.js';
+import { shopProductVariantsTable } from '../../db-postgres/schema/shop/index.js';
+import { filterUpcoming } from '../expiry.js';
+import { getShopDb } from '../server/db.js';
+function shopEnabled() {
+    try {
+        return getCMS().shopConfig !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a SvelteKit `GET` handler for upcoming variants of a single product.
+ * Mount at `/api/shop/products/[id]/variants/upcoming`.
+ *
+ * Returns `{ items: VariantRow[] }`. When `defineShop({ variantExpiry })` is
+ * configured, expired variants are filtered out; otherwise every variant for
+ * the product is returned. Order: `attributes.<source>` ascending if expiry
+ * config is set, otherwise insertion order.
+ *
+ * @experimental — HTTP shape is stable for envet pilot but may grow in 1.x
+ *   (e.g. pagination, language filter) once a second consumer lands.
+ */
+export function createUpcomingVariantsHandler() {
+    return {
+        GET: async ({ params }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            const productId = params.id;
+            if (!productId)
+                return json({ error: 'Product id required' }, { status: 400 });
+            const db = getShopDb();
+            const rows = await db
+                .select()
+                .from(shopProductVariantsTable)
+                .where(eq(shopProductVariantsTable.productId, productId))
+                .orderBy(asc(shopProductVariantsTable.createdAt));
+            const expiryConfig = getCMS().shopConfig?.variantExpiry ?? null;
+            const variants = rows.map((r) => ({
+                ...r,
+                attributes: r.attributes
+            }));
+            const upcoming = filterUpcoming(variants, expiryConfig);
+            if (expiryConfig) {
+                upcoming.sort((a, b) => {
+                    const aVal = a.attributes?.[expiryConfig.source];
+                    const bVal = b.attributes?.[expiryConfig.source];
+                    const aTs = typeof aVal === 'string' ? Date.parse(aVal) : NaN;
+                    const bTs = typeof bVal === 'string' ? Date.parse(bVal) : NaN;
+                    if (Number.isNaN(aTs) && Number.isNaN(bTs))
+                        return 0;
+                    if (Number.isNaN(aTs))
+                        return 1;
+                    if (Number.isNaN(bTs))
+                        return -1;
+                    return aTs - bTs;
+                });
+            }
+            return json({ items: upcoming });
+        }
+    };
+}

package/dist/shop/http/webhook-handler.js

@@ -1,7 +1,8 @@
 import { json } from '@sveltejs/kit';
 import { getCMS } from '../../core/cms.js';
 import { requireShopConfig } from '../server/db.js';
-import { getOrderByNumber, updateOrderStatus } from '../server/orders.js';
+import { getOrderByNumber, markBalancePaid, updateOrderStatus } from '../server/orders.js';
+import { findPaymentByProviderRef, markPaymentFailed, markPaymentPaid } from '../server/payments.js';
 import { checkRateLimit, clientKey } from '../rate-limit.js';
 import { isTerminalStatus, mapEventToStatus } from './webhook-logic.js';
 import { markWebhookEventProcessed, reserveWebhookEvent } from './webhook-idempotency.js';
@@ -59,24 +60,60 @@ export function createPaymentWebhookHandler() {
                     await markWebhookEventProcessed(reservation.rowId, null);
                 return json({ received: true });
             }
+            // Match payment row so we know whether the event targets a `full`,
+            // `deposit`, or `balance` payment row. Falls back to `'full'` when
+            // no row exists (back-compat with orders created before 0.27).
+            const paymentRow = await findPaymentByProviderRef(provider, event.providerRef);
+            const kind = paymentRow?.kind ?? 'full';
+            const targetStatus = mapEventToStatus(event);
+            if (!targetStatus) {
+                if (reservation.rowId)
+                    await markWebhookEventProcessed(reservation.rowId, order.id);
+                return json({ received: true, noop: true });
+            }
+            // Balance events must NOT re-trigger updateOrderStatus(paid) — the
+            // order already transitioned when the deposit cleared. Use the
+            // markBalancePaid path which only updates partialPayment/balanceOwed.
+            if (kind === 'balance') {
+                try {
+                    if (targetStatus === 'paid') {
+                        await markBalancePaid(order.id);
+                        if (paymentRow)
+                            await markPaymentPaid(paymentRow.id);
+                    }
+                    else if (targetStatus === 'paymentRejected' && paymentRow) {
+                        await markPaymentFailed(paymentRow.id);
+                    }
+                }
+                catch (err) {
+                    console.error(`[shop] balance webhook failed for ${order.number}:`, err);
+                    return json({ error: 'Processing failed' }, { status: 500 });
+                }
+                if (reservation.rowId)
+                    await markWebhookEventProcessed(reservation.rowId, order.id);
+                return json({ received: true, kind: 'balance' });
+            }
             // Secondary idempotency — terminal states are no-ops (covers adapters
             // that didn't surface eventId).
             if (isTerminalStatus(order.status)) {
+                if (paymentRow && targetStatus === 'paid')
+                    await markPaymentPaid(paymentRow.id);
                 if (reservation.rowId)
                     await markWebhookEventProcessed(reservation.rowId, order.id);
                 return json({ received: true, idempotent: true });
             }
-            const targetStatus = mapEventToStatus(event);
-            if (!targetStatus) {
-                if (reservation.rowId)
-                    await markWebhookEventProcessed(reservation.rowId, order.id);
-                return json({ received: true, noop: true });
-            }
             try {
                 await updateOrderStatus(order.id, targetStatus, {
                     note: `Payment webhook (${provider})`,
-                    changedBy: 'payment-webhook'
+                    changedBy: 'payment-webhook',
+                    paymentKind: kind
                 });
+                if (paymentRow) {
+                    if (targetStatus === 'paid')
+                        await markPaymentPaid(paymentRow.id);
+                    else if (targetStatus === 'paymentRejected')
+                        await markPaymentFailed(paymentRow.id);
+                }
             }
             catch (err) {
                 console.error(`[shop] updateOrderStatus failed for ${order.number}:`, err);
@@ -85,7 +122,7 @@ export function createPaymentWebhookHandler() {
             }
             if (reservation.rowId)
                 await markWebhookEventProcessed(reservation.rowId, order.id);
-            return json({ received: true });
+            return json({ received: true, kind });
         }
     };
 }

package/dist/shop/index.d.ts

@@ -1,5 +1,7 @@
 import type { ShopConfig, ResolvedShopConfig } from './types.js';
 export declare function defineShop(config: ShopConfig): ResolvedShopConfig;
+export { InvalidVariantAttributesError } from './variant-attributes.js';
+export { isVariantExpired, filterUpcoming, VariantExpiredError } from './expiry.js';
 export { manualAdapter } from './adapters/manual/index.js';
 export { payuAdapter } from './adapters/payu/index.js';
 export type { PayuAdapterOptions } from './adapters/payu/index.js';
@@ -7,4 +9,5 @@ export { stripeAdapter } from './adapters/stripe/index.js';
 export type { StripeAdapterOptions } from './adapters/stripe/index.js';
 export { inpostAdapter } from './adapters/inpost/index.js';
 export type { InpostAdapterOptions, InpostSenderAddress, GeowidgetConfigPreset, InpostEnvironment } from './adapters/inpost/index.js';
-export type { ShopConfig, ResolvedShopConfig, Currency, OrderStatus, PaymentAdapter, PaymentCreateContext, PaymentRefundInput, PaymentRefundResult, CarrierAdapter, CarrierEvent, ShipmentCreateInput, ShipmentCreateResult, ShipmentLabel, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, CouponRef, I18nText } from './types.js';
+export type { ShopConfig, ResolvedShopConfig, Currency, 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 } from './types.js';
+export { interpolateTemplate } from './template.js';

package/dist/shop/index.js

@@ -13,10 +13,16 @@ export function defineShop(config) {
         },
         carriers: config.carriers ?? [],
         consents: config.consents ?? [],
-        orderViewUrl: config.orderViewUrl ?? '/shop/order/{orderNumber}?token={accessToken}'
+        orderViewUrl: config.orderViewUrl ?? '/shop/order/{orderNumber}?token={accessToken}',
+        variantAttributes: config.variantAttributes ?? {},
+        variantLabel: config.variantLabel ?? null,
+        variantExpiry: config.variantExpiry ?? null
     };
 }
+export { InvalidVariantAttributesError } from './variant-attributes.js';
+export { isVariantExpired, filterUpcoming, VariantExpiredError } from './expiry.js';
 export { manualAdapter } from './adapters/manual/index.js';
 export { payuAdapter } from './adapters/payu/index.js';
 export { stripeAdapter } from './adapters/stripe/index.js';
 export { inpostAdapter } from './adapters/inpost/index.js';
+export { interpolateTemplate } from './template.js';

package/dist/shop/server/balance-payment.d.ts

@@ -0,0 +1,40 @@
+import type { PaymentCreateContext, PaymentCreateResult } from '../types.js';
+/**
+ * @internal
+ * Generate a signed balance-payment token for `orderId`. Format:
+ * `base64url(payload).base64url(hmac-sha256(payload, secret))`. The token
+ * is deterministic for a given (orderId, secret) pair — server-side
+ * invalidation is by `order.balanceOwed` rather than rotation.
+ */
+export declare function generateBalanceToken(orderId: string, secret: string): string;
+/**
+ * @internal
+ * Verify a balance-payment token. Checks payload structure, `type` claim,
+ * orderId match, and constant-time HMAC compare. Does NOT consult the
+ * database — call `order.balanceOwed === true` separately as the
+ * server-side invalidation gate.
+ */
+export declare function verifyBalanceToken(token: string, orderId: string, secret: string): boolean;
+/**
+ * @internal
+ * Resolve the HMAC secret for balance tokens from the environment. Throws
+ * when missing — admin must set `INCLUDIO_BALANCE_TOKEN_SECRET` before
+ * enabling any deposit `paymentPolicy`. We refuse to silently downgrade
+ * because tokens without entropy would let arbitrary customers pay a
+ * balance for arbitrary orders.
+ */
+export declare function requireBalanceTokenSecret(): string;
+export interface CreateBalanceSessionResult {
+    status: PaymentCreateResult['status'];
+    redirectUrl?: string;
+}
+/**
+ * @experimental
+ * Initiate a payment session for the outstanding balance on a deposit order.
+ * Verifies the token + `order.balanceOwed === true` + reuses the order's
+ * original payment adapter. Inserts a `shop_payments` row tagged
+ * `kind='balance'` so the webhook can route the eventual paid event to
+ * `markBalancePaid`. Errors when token invalid, order missing, balance
+ * already cleared, or adapter not configured.
+ */
+export declare function createBalanceSession(orderNumber: string, token: string, ctx?: PaymentCreateContext): Promise<CreateBalanceSessionResult>;

package/dist/shop/server/balance-payment.js

@@ -0,0 +1,140 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { shopOrdersTable } from '../../db-postgres/schema/shop/index.js';
+import { getShopDb, requireShopConfig } from './db.js';
+import { getOrderByNumber } from './orders.js';
+import { insertPaymentRow } from './payments.js';
+function base64url(buf) {
+    return buf.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function base64urlDecode(s) {
+    if (!s)
+        return null;
+    const padded = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = padded.length % 4 === 0 ? '' : '='.repeat(4 - (padded.length % 4));
+    try {
+        return Buffer.from(padded + pad, 'base64');
+    }
+    catch {
+        return null;
+    }
+}
+function sign(payload, secret) {
+    return createHmac('sha256', secret).update(payload).digest();
+}
+/**
+ * @internal
+ * Generate a signed balance-payment token for `orderId`. Format:
+ * `base64url(payload).base64url(hmac-sha256(payload, secret))`. The token
+ * is deterministic for a given (orderId, secret) pair — server-side
+ * invalidation is by `order.balanceOwed` rather than rotation.
+ */
+export function generateBalanceToken(orderId, secret) {
+    const payload = { orderId, type: 'balance' };
+    const payloadBuf = Buffer.from(JSON.stringify(payload), 'utf8');
+    const sig = sign(payloadBuf, secret);
+    return `${base64url(payloadBuf)}.${base64url(sig)}`;
+}
+/**
+ * @internal
+ * Verify a balance-payment token. Checks payload structure, `type` claim,
+ * orderId match, and constant-time HMAC compare. Does NOT consult the
+ * database — call `order.balanceOwed === true` separately as the
+ * server-side invalidation gate.
+ */
+export function verifyBalanceToken(token, orderId, secret) {
+    if (!token || typeof token !== 'string')
+        return false;
+    const dotIndex = token.indexOf('.');
+    if (dotIndex < 1 || dotIndex >= token.length - 1)
+        return false;
+    const payloadPart = token.slice(0, dotIndex);
+    const sigPart = token.slice(dotIndex + 1);
+    const payloadBuf = base64urlDecode(payloadPart);
+    const sigBuf = base64urlDecode(sigPart);
+    if (!payloadBuf || !sigBuf)
+        return false;
+    let payload;
+    try {
+        payload = JSON.parse(payloadBuf.toString('utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (!payload || payload.type !== 'balance' || payload.orderId !== orderId)
+        return false;
+    const expected = sign(payloadBuf, secret);
+    if (expected.length !== sigBuf.length)
+        return false;
+    return timingSafeEqual(new Uint8Array(expected), new Uint8Array(sigBuf));
+}
+/**
+ * @internal
+ * Resolve the HMAC secret for balance tokens from the environment. Throws
+ * when missing — admin must set `INCLUDIO_BALANCE_TOKEN_SECRET` before
+ * enabling any deposit `paymentPolicy`. We refuse to silently downgrade
+ * because tokens without entropy would let arbitrary customers pay a
+ * balance for arbitrary orders.
+ */
+export function requireBalanceTokenSecret() {
+    const secret = process.env.INCLUDIO_BALANCE_TOKEN_SECRET;
+    if (!secret || secret.length < 16) {
+        throw new Error('INCLUDIO_BALANCE_TOKEN_SECRET env var required (≥16 chars) for balance link generation.');
+    }
+    return secret;
+}
+/**
+ * @experimental
+ * Initiate a payment session for the outstanding balance on a deposit order.
+ * Verifies the token + `order.balanceOwed === true` + reuses the order's
+ * original payment adapter. Inserts a `shop_payments` row tagged
+ * `kind='balance'` so the webhook can route the eventual paid event to
+ * `markBalancePaid`. Errors when token invalid, order missing, balance
+ * already cleared, or adapter not configured.
+ */
+export async function createBalanceSession(orderNumber, token, ctx) {
+    const shop = requireShopConfig();
+    const order = await getOrderByNumber(orderNumber);
+    if (!order)
+        throw new Error('Order not found');
+    if (!order.balanceOwed || !order.partialPayment) {
+        throw new Error('Order has no outstanding balance');
+    }
+    if (!order.paymentMethod)
+        throw new Error('Order has no payment method');
+    const secret = requireBalanceTokenSecret();
+    if (!verifyBalanceToken(token, order.id, secret)) {
+        throw new Error('Invalid balance token');
+    }
+    const adapter = shop.payment.find((a) => a.id === order.paymentMethod);
+    if (!adapter)
+        throw new Error(`Payment provider "${order.paymentMethod}" is not configured`);
+    const balanceAmount = order.partialPayment.balanceAmount;
+    const orderRef = {
+        id: order.id,
+        number: order.number,
+        totalGross: balanceAmount,
+        currency: shop.currency,
+        customerEmail: order.customerEmail
+    };
+    const result = await adapter.createPayment(orderRef, ctx);
+    await insertPaymentRow({
+        orderId: order.id,
+        provider: adapter.id,
+        providerRef: result.providerRef ?? null,
+        kind: 'balance',
+        amount: balanceAmount,
+        currency: shop.currency
+    });
+    // Mirror the latest providerRef on the order so refunds / refresh-payment
+    // (which look at order.paymentProviderRef as a fallback) point to the
+    // balance row first. Per-kind refund still uses shop_payments.kind.
+    if (result.providerRef) {
+        const db = getShopDb();
+        await db
+            .update(shopOrdersTable)
+            .set({ paymentProviderRef: result.providerRef, updatedAt: new Date() })
+            .where(eq(shopOrdersTable.id, order.id));
+    }
+    return { status: result.status, redirectUrl: result.redirectUrl };
+}

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

@@ -127,6 +127,7 @@ export async function hydrateCart(items, opts = {}) {
             variantId: ref.variantId,
             qty: effectiveQty,
             entryId: product.entryId,
+            productId: product.id,
             variantName: variant.name ?? null,
             variantSku: variant.sku,
             productTitle: title,
@@ -205,6 +206,7 @@ export async function hydrateCart(items, opts = {}) {
             variantId: ref.variantId,
             qty: 0,
             entryId: '',
+            productId: '',
             variantName: null,
             variantSku: null,
             productTitle: null,

package/dist/shop/server/init.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseAdapterWithDrizzle } from '../../db-postgres/index.js';
+import type { ResolvedShopConfig } from '../types.js';
+/**
+ * Apply variant attribute GIN indexes for the given shop config.
+ * Idempotent (`CREATE INDEX IF NOT EXISTS`) and serialized — concurrent calls
+ * share the same in-flight promise, so a HMR re-init or fire-and-forget from
+ * `initCMS()` plus an explicit caller cannot race into a postgres
+ * `pg_class_relname_nsp_index` duplicate-key error.
+ *
+ * Both args are required to keep this module free of CMS singleton coupling
+ * (it stays importable from anywhere without circular deps).
+ * @internal
+ */
+export declare function applyVariantAttributeIndexes(shop: ResolvedShopConfig, db: DatabaseAdapterWithDrizzle['_drizzle']): Promise<void>;

package/dist/shop/server/init.js

@@ -0,0 +1,35 @@
+import { sql } from 'drizzle-orm';
+import { createVariantAttributeIndexes } from '../../db-postgres/schema/shop/productVariant.js';
+let inFlight = null;
+/**
+ * Apply variant attribute GIN indexes for the given shop config.
+ * Idempotent (`CREATE INDEX IF NOT EXISTS`) and serialized — concurrent calls
+ * share the same in-flight promise, so a HMR re-init or fire-and-forget from
+ * `initCMS()` plus an explicit caller cannot race into a postgres
+ * `pg_class_relname_nsp_index` duplicate-key error.
+ *
+ * Both args are required to keep this module free of CMS singleton coupling
+ * (it stays importable from anywhere without circular deps).
+ * @internal
+ */
+export function applyVariantAttributeIndexes(shop, db) {
+    if (inFlight)
+        return inFlight;
+    // Cleanup runs via `.finally()` (microtask) — NOT inside the async body's
+    // try/finally — so the outer `inFlight = promise` assignment lands before
+    // the reset, even when the body resolves synchronously (no stmts case).
+    const promise = (async () => {
+        const stmts = createVariantAttributeIndexes(shop.variantAttributes);
+        if (stmts.length === 0)
+            return;
+        for (const stmt of stmts) {
+            await db.execute(sql.raw(stmt));
+        }
+    })();
+    inFlight = promise;
+    promise.finally(() => {
+        if (inFlight === promise)
+            inFlight = null;
+    });
+    return promise;
+}

package/dist/shop/server/orders.d.ts

@@ -1,6 +1,18 @@
 import { shopOrderItemsTable, shopOrderStatusHistoryTable, shopOrdersTable } from '../../db-postgres/schema/shop/index.js';
 import type { CartItemRef } from '../cart/types.js';
 import type { OrderStatus } from '../types.js';
+/**
+ * @public
+ * Thrown by `createOrderFromCart` when the cart contains items from multiple
+ * products and at least one of them has a deposit `paymentPolicy`. Deposit
+ * orders must span a single product (so the balance link/refund-per-kind flow
+ * stays unambiguous). Mixed-product carts are accepted only when every
+ * involved product has a `full` (or null) policy.
+ */
+export declare class MixedPaymentPolicyError extends Error {
+    readonly code = "MIXED_PAYMENT_POLICY";
+    constructor(message?: string);
+}
 export type OrderRow = typeof shopOrdersTable.$inferSelect;
 export type OrderItemRow = typeof shopOrderItemsTable.$inferSelect;
 export type OrderStatusHistoryRow = typeof shopOrderStatusHistoryTable.$inferSelect;
@@ -27,12 +39,34 @@ export interface CreateOrderResult {
     items: OrderItemRow[];
     requiresPaymentRedirect: boolean;
     redirectUrl?: string;
+    /**
+     * Minor-unit amount the customer should pay at checkout under
+     * `paymentPolicy`. Equals `order.totalGross` for full-payment orders;
+     * equals the resolved deposit + shipping for deposit orders.
+     */
+    amountToPay: number;
+    /**
+     * `'full'` for orders paid in one shot; `'deposit'` when the customer
+     * pays only a deposit at checkout and owes a balance redeemable via
+     * the balance link flow.
+     */
+    paymentKind: 'full' | 'deposit';
 }
 export declare function createOrderFromCart(input: CreateOrderInput): Promise<CreateOrderResult>;
 export declare function updateOrderStatus(orderId: string, status: OrderStatus, opts?: {
     note?: string;
     changedBy?: string;
+    paymentKind?: 'full' | 'deposit' | 'balance';
 }): Promise<OrderRow>;
+/**
+ * @internal
+ * Mark the remaining balance on a deposit order as paid. Idempotent — no-op
+ * when `balanceOwed` is already false. Updates `partialPayment.paidAmount`
+ * to the full `order.totalGross` (deposit + balance), stamps `paidAt`, and
+ * clears `balanceOwed`. Stock decrement / order status are untouched — the
+ * order already transitioned to `paid` when the deposit cleared.
+ */
+export declare function markBalancePaid(orderId: string): Promise<OrderRow | null>;
 export declare function setPaymentProviderRef(orderId: string, ref: string | null): Promise<void>;
 export interface ShipmentInfoInput {
     shipmentId: string;