includio-cms 0.26.0 → 0.28.0

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/invoices.d.ts

@@ -0,0 +1,64 @@
+import { shopInvoicesTable, type ShopInvoiceStatus } from '../../db-postgres/schema/shop/index.js';
+import type { Currency, InvoiceIssuePolicy, InvoicePayload, OrderStatus } from '../types.js';
+type InvoiceRow = typeof shopInvoicesTable.$inferSelect;
+/** Order fields the trigger / idempotency decision depends on. */
+export interface InvoiceOrderState {
+    status: OrderStatus;
+    balanceOwed: boolean;
+    customerNip: string | null;
+    invoiceRequested: boolean;
+}
+/** Order fields needed to build the invoice payload. */
+export interface InvoiceOrderData {
+    number: string;
+    currency: Currency;
+    customerEmail: string;
+    customerName: string | null;
+    customerNip: string | null;
+    customerCompanyName: string | null;
+    shippingAddress: Record<string, string> | null;
+    billingAddress: Record<string, string> | null;
+    language: string | null;
+}
+export interface InvoiceItemData {
+    nameSnapshot: Record<string, string>;
+    qty: number;
+    priceGrossSnapshot: number;
+    vatRate: number;
+}
+export type InvoiceAction = 'skip' | 'create' | 'resend';
+export declare class InvoiceError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Does the order qualify for an automatic invoice under `policy`? Pure. */
+export declare function shouldIssueInvoice(order: InvoiceOrderState, policy: InvoiceIssuePolicy): boolean;
+/** Fully paid = a paid-or-later status with no outstanding balance. Pure. */
+export declare function isOrderFullyPaid(order: InvoiceOrderState): boolean;
+/**
+ * Decide what to do with an order's invoice given any existing record. Pure —
+ * encodes the trigger + idempotency rules so they can be tested without a DB.
+ */
+export declare function decideInvoiceAction(order: InvoiceOrderState, existing: {
+    status: ShopInvoiceStatus;
+} | null, policy: InvoiceIssuePolicy, opts?: {
+    force?: boolean;
+}): InvoiceAction;
+/** Map order + items onto the provider-agnostic {@link InvoicePayload}. Pure. */
+export declare function buildInvoicePayload(order: InvoiceOrderData, items: InvoiceItemData[], paidAt: string): InvoicePayload;
+export declare function getInvoiceByOrderId(orderId: string): Promise<InvoiceRow | null>;
+/**
+ * Issue an invoice for an order if it qualifies. Fire-and-forget, fail-open —
+ * never throws, so a failing invoicing provider can't block the payment webhook.
+ * Called from `updateOrderStatus` (on `paid`) and `markBalancePaid`.
+ */
+export declare function maybeIssueInvoiceForOrder(orderId: string): Promise<void>;
+/**
+ * Issue (or retry/resend) an invoice on demand from the admin. Throws on error
+ * so the caller can surface it. `force` bypasses the trigger policy and allows
+ * re-sending an already-issued invoice.
+ */
+export declare function issueInvoiceForOrder(orderId: string, opts?: {
+    force?: boolean;
+}): Promise<InvoiceRow | null>;
+export {};

package/dist/shop/server/invoices.js

@@ -0,0 +1,237 @@
+import { eq } from 'drizzle-orm';
+import { shopInvoicesTable, shopOrderItemsTable, shopOrdersTable } from '../../db-postgres/schema/shop/index.js';
+import { getShopDb, requireShopConfig } from './db.js';
+const FULLY_PAID_STATES = new Set(['paid', 'preparing', 'sent', 'done']);
+export class InvoiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'InvoiceError';
+    }
+}
+/** Does the order qualify for an automatic invoice under `policy`? Pure. */
+export function shouldIssueInvoice(order, policy) {
+    if (policy === 'always')
+        return true;
+    return Boolean(order.customerNip) || order.invoiceRequested;
+}
+/** Fully paid = a paid-or-later status with no outstanding balance. Pure. */
+export function isOrderFullyPaid(order) {
+    return FULLY_PAID_STATES.has(order.status) && !order.balanceOwed;
+}
+/**
+ * Decide what to do with an order's invoice given any existing record. Pure —
+ * encodes the trigger + idempotency rules so they can be tested without a DB.
+ */
+export function decideInvoiceAction(order, existing, policy, opts = {}) {
+    if (!isOrderFullyPaid(order))
+        return 'skip';
+    const force = opts.force ?? false;
+    if (existing) {
+        switch (existing.status) {
+            case 'issued':
+            case 'sent':
+                return force ? 'resend' : 'skip';
+            case 'failed':
+                return 'create';
+            case 'pending':
+                return force ? 'create' : 'skip';
+        }
+    }
+    if (force || shouldIssueInvoice(order, policy))
+        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").
+function lineName(name) {
+    const product = name.product ?? '';
+    const variant = name.variant ?? '';
+    if (product && variant)
+        return `${product} — ${variant}`;
+    return product || variant || Object.values(name)[0] || '';
+}
+/** Map order + items onto the provider-agnostic {@link InvoicePayload}. Pure. */
+export function buildInvoicePayload(order, items, paidAt) {
+    return {
+        orderNumber: order.number,
+        currency: order.currency,
+        paidAt,
+        buyer: {
+            name: order.customerName || order.customerEmail,
+            email: order.customerEmail,
+            nip: order.customerNip,
+            companyName: order.customerCompanyName,
+            address: order.billingAddress ?? order.shippingAddress ?? null
+        },
+        items: items.map((item) => ({
+            name: lineName(item.nameSnapshot),
+            quantity: item.qty,
+            unitPriceGross: item.priceGrossSnapshot,
+            vatRate: item.vatRate
+        }))
+    };
+}
+export async function getInvoiceByOrderId(orderId) {
+    const db = getShopDb();
+    const [row] = await db
+        .select()
+        .from(shopInvoicesTable)
+        .where(eq(shopInvoicesTable.orderId, orderId));
+    return row ?? null;
+}
+function toOrderData(order) {
+    return {
+        number: order.number,
+        currency: order.currency,
+        customerEmail: order.customerEmail,
+        customerName: order.customerName,
+        customerNip: order.customerNip,
+        customerCompanyName: order.customerCompanyName,
+        shippingAddress: order.shippingAddress ?? null,
+        billingAddress: order.billingAddress ?? null,
+        language: order.language
+    };
+}
+function toItemData(items) {
+    return items.map((i) => ({
+        nameSnapshot: i.nameSnapshot,
+        qty: i.qty,
+        priceGrossSnapshot: i.priceGrossSnapshot,
+        vatRate: i.vatRate
+    }));
+}
+async function runCreate(order, existing, adapter) {
+    const db = getShopDb();
+    const now = new Date();
+    let invoiceId;
+    if (existing) {
+        const [row] = await db
+            .update(shopInvoicesTable)
+            .set({
+            status: 'pending',
+            provider: adapter.id,
+            attempts: existing.attempts + 1,
+            lastError: null,
+            updatedAt: now
+        })
+            .where(eq(shopInvoicesTable.id, existing.id))
+            .returning();
+        invoiceId = row.id;
+    }
+    else {
+        const [row] = await db
+            .insert(shopInvoicesTable)
+            .values({
+            orderId: order.id,
+            provider: adapter.id,
+            status: 'pending',
+            attempts: 1
+        })
+            .returning();
+        invoiceId = row.id;
+    }
+    const items = await db
+        .select()
+        .from(shopOrderItemsTable)
+        .where(eq(shopOrderItemsTable.orderId, order.id));
+    const paidAt = order.partialPayment?.paidAt ?? now.toISOString();
+    const payload = buildInvoicePayload(toOrderData(order), toItemData(items), paidAt);
+    try {
+        const result = await adapter.createInvoice(payload, { language: order.language });
+        let status = 'issued';
+        if (adapter.send) {
+            await adapter.send(result.externalId, { language: order.language });
+            status = 'sent';
+        }
+        const [updated] = await db
+            .update(shopInvoicesTable)
+            .set({
+            status,
+            externalId: result.externalId,
+            number: result.number ?? null,
+            pdfUrl: result.pdfUrl ?? null,
+            raw: result.raw ?? null,
+            lastError: null,
+            updatedAt: new Date()
+        })
+            .where(eq(shopInvoicesTable.id, invoiceId))
+            .returning();
+        return updated;
+    }
+    catch (err) {
+        await db
+            .update(shopInvoicesTable)
+            .set({
+            status: 'failed',
+            lastError: err instanceof Error ? err.message : String(err),
+            updatedAt: new Date()
+        })
+            .where(eq(shopInvoicesTable.id, invoiceId));
+        throw err;
+    }
+}
+async function runResend(order, existing, adapter) {
+    if (!existing.externalId)
+        throw new InvoiceError('not_issued', 'No issued invoice to resend');
+    if (!adapter.send)
+        throw new InvoiceError('send_unsupported', 'Adapter cannot e-mail invoices');
+    const db = getShopDb();
+    await adapter.send(existing.externalId, { language: order.language });
+    const [updated] = await db
+        .update(shopInvoicesTable)
+        .set({ status: 'sent', updatedAt: new Date() })
+        .where(eq(shopInvoicesTable.id, existing.id))
+        .returning();
+    return updated;
+}
+/**
+ * Issue an invoice for an order if it qualifies. Fire-and-forget, fail-open —
+ * never throws, so a failing invoicing provider can't block the payment webhook.
+ * Called from `updateOrderStatus` (on `paid`) and `markBalancePaid`.
+ */
+export async function maybeIssueInvoiceForOrder(orderId) {
+    try {
+        const adapter = requireShopConfig().invoicing;
+        if (!adapter)
+            return;
+        const db = getShopDb();
+        const [order] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
+        if (!order)
+            return;
+        const existing = await getInvoiceByOrderId(orderId);
+        const policy = adapter.issueWhen ?? 'b2bAndOnRequest';
+        const action = decideInvoiceAction(order, existing, policy);
+        if (action === 'create')
+            await runCreate(order, existing, adapter);
+        else if (action === 'resend' && existing)
+            await runResend(order, existing, adapter);
+    }
+    catch (err) {
+        console.error(`[shop] invoice issuance failed for order ${orderId}:`, err);
+    }
+}
+/**
+ * Issue (or retry/resend) an invoice on demand from the admin. Throws on error
+ * so the caller can surface it. `force` bypasses the trigger policy and allows
+ * re-sending an already-issued invoice.
+ */
+export async function issueInvoiceForOrder(orderId, opts = {}) {
+    const adapter = requireShopConfig().invoicing;
+    if (!adapter)
+        throw new InvoiceError('no_adapter', 'No invoicing adapter configured');
+    const db = getShopDb();
+    const [order] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
+    if (!order)
+        throw new InvoiceError('order_not_found', 'Order not found');
+    const existing = await getInvoiceByOrderId(orderId);
+    const policy = adapter.issueWhen ?? 'b2bAndOnRequest';
+    const action = decideInvoiceAction(order, existing, policy, { force: opts.force ?? false });
+    if (action === 'create')
+        return runCreate(order, existing, adapter);
+    if (action === 'resend' && existing)
+        return runResend(order, existing, adapter);
+    return existing;
+}

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;
@@ -13,7 +25,11 @@ export interface CreateOrderInput {
     customerEmail: string;
     customerName?: string;
     customerPhone?: string;
+    customerNip?: string;
+    customerCompanyName?: string;
     shippingAddress?: Record<string, string>;
+    billingAddress?: Record<string, string>;
+    invoiceRequested?: boolean;
     shippingMethodId: string;
     carrierRef?: string;
     paymentMethod: string;
@@ -27,12 +43,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;

package/dist/shop/server/orders.js

@@ -7,7 +7,25 @@ import { resolveShippingPrice } from './shipping.js';
 import { generateOrderNumber } from './order-number.js';
 import { sendLowStockEmail, sendOrderStatusEmail } from './email.js';
 import { isPaymentMethodAllowed } from './payment-compat.js';
+import { isVariantExpired, VariantExpiredError } from '../expiry.js';
+import { resolvePaymentAmount } from './payment-policy.js';
+import { maybeIssueInvoiceForOrder } from './invoices.js';
 import { CouponError, recordCouponRedemption, releaseCouponSlot, reserveCouponSlot, validateCoupon } from './coupons.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 class MixedPaymentPolicyError extends Error {
+    code = 'MIXED_PAYMENT_POLICY';
+    constructor(message = 'Cart mixes a deposit-policy product with other products.') {
+        super(message);
+        this.name = 'MixedPaymentPolicyError';
+    }
+}
 const STOCK_RESERVATION_TTL_MINUTES = 30;
 async function purgeExpiredReservations() {
     const db = getShopDb();
@@ -97,6 +115,43 @@ export async function createOrderFromCart(input) {
             discountAmount: snapshot.subtotalGross - snapshot.totalGross
         };
     }
+    // Payment policy lookup + mixed-cart guard. Load each line's product
+    // paymentPolicy from shop_products. If any product has a deposit policy
+    // and the cart spans more than one product, refuse with
+    // MIXED_PAYMENT_POLICY (keeps balance link / refund-per-kind unambiguous).
+    const uniqueProductIds = Array.from(new Set(snapshot.items.map((l) => l.productId).filter(Boolean)));
+    const productPolicyRows = uniqueProductIds.length > 0
+        ? await db
+            .select({
+            id: shopProductsTable.id,
+            paymentPolicy: shopProductsTable.paymentPolicy
+        })
+            .from(shopProductsTable)
+            .where(inArray(shopProductsTable.id, uniqueProductIds))
+        : [];
+    const policyByProductId = new Map(productPolicyRows.map((r) => [r.id, r.paymentPolicy]));
+    const hasDepositPolicy = productPolicyRows.some((r) => r.paymentPolicy?.type === 'deposit');
+    if (hasDepositPolicy && uniqueProductIds.length > 1) {
+        throw new MixedPaymentPolicyError();
+    }
+    // Variant expiry guard (opt-in via defineShop.variantExpiry). Run before
+    // stock reservation so expired variants surface a domain error instead of
+    // taking a reservation slot they will never use.
+    if (shop.variantExpiry) {
+        const variantIds = snapshot.items.map((l) => l.variantId);
+        const variantRows = await db
+            .select({
+            id: shopProductVariantsTable.id,
+            attributes: shopProductVariantsTable.attributes
+        })
+            .from(shopProductVariantsTable)
+            .where(inArray(shopProductVariantsTable.id, variantIds));
+        for (const v of variantRows) {
+            if (isVariantExpired({ attributes: v.attributes }, shop.variantExpiry)) {
+                throw new VariantExpiredError(v.id);
+            }
+        }
+    }
     // Stock availability under active reservations (when stock feature on)
     if (shop.features.stock) {
         await purgeExpiredReservations();
@@ -120,6 +175,30 @@ export async function createOrderFromCart(input) {
     const totalNet = snapshot.totalNet + shippingResolved.net;
     const totalGross = snapshot.totalGross + shippingResolved.gross;
     const totalVat = snapshot.totalVat + shippingResolved.vat;
+    // Resolve per-line payment amounts under each product's paymentPolicy.
+    // `depositSum` is what we charge at checkout under deposit policy; the
+    // remainder + shipping rolls into `partialPayment.balanceAmount`.
+    let depositSum = 0;
+    let goodsBalance = 0;
+    let anyDepositLine = false;
+    for (const line of snapshot.items) {
+        const policy = policyByProductId.get(line.productId) ?? null;
+        const resolved = resolvePaymentAmount(policy, line.lineGross);
+        depositSum += resolved.amountToPay;
+        goodsBalance += resolved.balanceAmount;
+        if (resolved.kind === 'deposit')
+            anyDepositLine = true;
+    }
+    const paymentKind = anyDepositLine ? 'deposit' : 'full';
+    const amountToPay = anyDepositLine ? depositSum + shippingResolved.gross : totalGross;
+    const partialPayment = anyDepositLine
+        ? {
+            kind: 'deposit',
+            paidAmount: 0,
+            balanceAmount: goodsBalance,
+            paidAt: null
+        }
+        : null;
     // Consents snapshot
     const consentSnapshot = shop.consents.map((c) => {
         const accepted = input.consents?.find((x) => x.id === c.id)?.accepted ?? false;
@@ -159,7 +238,11 @@ export async function createOrderFromCart(input) {
             customerEmail: input.customerEmail,
             customerName: input.customerName ?? null,
             customerPhone: input.customerPhone ?? null,
+            customerNip: input.customerNip ?? null,
+            customerCompanyName: input.customerCompanyName ?? null,
             shippingAddress: input.shippingAddress ?? null,
+            billingAddress: input.billingAddress ?? null,
+            invoiceRequested: input.invoiceRequested ?? false,
             totalNet,
             totalGross,
             vatAmount: totalVat,
@@ -171,7 +254,9 @@ export async function createOrderFromCart(input) {
             paymentMethod: input.paymentMethod,
             consents: consentSnapshot,
             notes: input.notes ?? null,
-            language: input.language ?? cms.languages[0] ?? null
+            language: input.language ?? cms.languages[0] ?? null,
+            partialPayment,
+            balanceOwed: false
         })
             .returning();
         order = inserted;
@@ -237,7 +322,9 @@ export async function createOrderFromCart(input) {
     return {
         order,
         items,
-        requiresPaymentRedirect: false
+        requiresPaymentRedirect: false,
+        amountToPay,
+        paymentKind
     };
 }
 export async function updateOrderStatus(orderId, status, opts = {}) {
@@ -248,6 +335,32 @@ export async function updateOrderStatus(orderId, status, opts = {}) {
     if (order.status === status)
         return order;
     const shop = requireShopConfig();
+    // Deposit-kind transition to `paid`: bump partialPayment.paidAmount to the
+    // deposit amount, stamp paidAt, and flag balanceOwed = true. Stock is
+    // permanently confirmed by the existing `paid` branch below — no TTL
+    // release. Balance-kind transitions skip the order-level status change
+    // (handled separately by markBalancePaid) so we never reach this branch.
+    //
+    // Auto-detect deposit context when caller (e.g. admin manual mark-paid)
+    // didn't pass paymentKind: a non-balance-owed deposit order with paidAt
+    // still null = the initial deposit payment is the one being confirmed.
+    const partial = order.partialPayment;
+    const effectiveKind = opts.paymentKind ??
+        (partial?.kind === 'deposit' && !order.balanceOwed && partial.paidAt == null
+            ? 'deposit'
+            : undefined);
+    if (status === 'paid' && effectiveKind === 'deposit' && order.partialPayment) {
+        const pp = order.partialPayment;
+        const paidAt = new Date().toISOString();
+        const paidAmount = order.totalGross - pp.balanceAmount;
+        await db
+            .update(shopOrdersTable)
+            .set({
+            partialPayment: { ...pp, paidAmount, paidAt },
+            balanceOwed: true
+        })
+            .where(eq(shopOrdersTable.id, orderId));
+    }
     await db
         .update(shopOrdersTable)
         .set({ status, updatedAt: new Date() })
@@ -322,8 +435,45 @@ export async function updateOrderStatus(orderId, status, opts = {}) {
     }
     const [updated] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
     void sendOrderStatusEmail(orderId, status);
+    // Auto-issue an invoice once the order is paid. Fail-open / fire-and-forget —
+    // the guard inside skips deposit orders that still owe a balance.
+    if (status === 'paid')
+        void maybeIssueInvoiceForOrder(orderId);
     return updated;
 }
+/**
+ * @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 async function markBalancePaid(orderId) {
+    const db = getShopDb();
+    const [order] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
+    if (!order)
+        return null;
+    if (!order.balanceOwed || !order.partialPayment)
+        return order;
+    const pp = order.partialPayment;
+    await db
+        .update(shopOrdersTable)
+        .set({
+        partialPayment: {
+            ...pp,
+            paidAmount: order.totalGross,
+            paidAt: new Date().toISOString()
+        },
+        balanceOwed: false,
+        updatedAt: new Date()
+    })
+        .where(eq(shopOrdersTable.id, orderId));
+    const [updated] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
+    // Balance cleared → the order is now fully paid; issue its invoice.
+    void maybeIssueInvoiceForOrder(orderId);
+    return updated ?? null;
+}
 export async function setPaymentProviderRef(orderId, ref) {
     const db = getShopDb();
     await db

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

@@ -0,0 +1,35 @@
+import type { DepositAmount, PaymentPolicy } from '../types.js';
+/**
+ * @public
+ * Result of resolving a per-line payment amount under a `PaymentPolicy`.
+ * `amountToPay` is the minor-unit amount to charge now; `balanceAmount` is
+ * what will still be owed under deposit policy (0 for full / clamped deposit).
+ */
+export interface ResolvedPaymentAmount {
+    amountToPay: number;
+    kind: 'full' | 'deposit';
+    balanceAmount: number;
+}
+/**
+ * @internal
+ * Compute the deposit minor-unit amount from a `DepositAmount` spec. Percent
+ * floors `(base * value / 100)`; fixed amount is clamped to `base` to prevent
+ * collecting more than the line total. Caller is responsible for validating
+ * the spec (see {@link validatePaymentPolicy}).
+ */
+export declare function computeDepositAmount(spec: DepositAmount, base: number): number;
+/**
+ * @public
+ * Resolve a `PaymentPolicy` against a line gross total. Returns the immediate
+ * `amountToPay` (deposit when applicable), the `kind` for payment row tagging
+ * (`'full' | 'deposit'`), and the `balanceAmount` still owed. Null / `full`
+ * policies short-circuit to a normal full charge with `balanceAmount = 0`.
+ */
+export declare function resolvePaymentAmount(policy: PaymentPolicy | null, lineGross: number): ResolvedPaymentAmount;
+/**
+ * @internal
+ * Validate a `PaymentPolicy` configuration. Throws a `RangeError` when the
+ * spec is structurally invalid (percent out of (0, 100], amount ≤ 0, etc).
+ * Called from `upsertShopData` before persisting the policy on the product.
+ */
+export declare function validatePaymentPolicy(policy: PaymentPolicy): void;