includio-cms 0.26.0 → 0.27.0

package/dist/shop/server/orders.js

@@ -7,7 +7,24 @@ 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 { 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 +114,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 +174,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;
@@ -171,7 +249,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 +317,9 @@ export async function createOrderFromCart(input) {
     return {
         order,
         items,
-        requiresPaymentRedirect: false
+        requiresPaymentRedirect: false,
+        amountToPay,
+        paymentKind
     };
 }
 export async function updateOrderStatus(orderId, status, opts = {}) {
@@ -248,6 +330,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() })
@@ -324,6 +432,37 @@ export async function updateOrderStatus(orderId, status, opts = {}) {
     void sendOrderStatusEmail(orderId, status);
     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));
+    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;

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

@@ -0,0 +1,55 @@
+/**
+ * @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 function computeDepositAmount(spec, base) {
+    if (spec.type === 'percent') {
+        return Math.floor((base * spec.value) / 100);
+    }
+    return Math.min(spec.value, base);
+}
+/**
+ * @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 function resolvePaymentAmount(policy, lineGross) {
+    if (!policy || policy.type === 'full') {
+        return { amountToPay: lineGross, kind: 'full', balanceAmount: 0 };
+    }
+    const amountToPay = computeDepositAmount(policy.depositAmount, lineGross);
+    return {
+        amountToPay,
+        kind: 'deposit',
+        balanceAmount: Math.max(0, lineGross - amountToPay)
+    };
+}
+/**
+ * @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 function validatePaymentPolicy(policy) {
+    if (policy.type === 'full')
+        return;
+    const d = policy.depositAmount;
+    if (d.type === 'percent') {
+        if (!Number.isFinite(d.value) || d.value <= 0 || d.value > 100) {
+            throw new RangeError('Deposit percent must be in (0, 100].');
+        }
+        return;
+    }
+    if (d.type === 'amount') {
+        if (!Number.isInteger(d.value) || d.value <= 0) {
+            throw new RangeError('Deposit amount must be a positive integer (minor units).');
+        }
+        return;
+    }
+    throw new RangeError(`Unknown depositAmount.type: ${d.type}`);
+}

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

@@ -0,0 +1,29 @@
+import { shopPaymentsTable, type ShopPaymentKind } from '../../db-postgres/schema/shop/index.js';
+export type ShopPaymentRow = typeof shopPaymentsTable.$inferSelect;
+/**
+ * @internal
+ * Insert a new `shop_payments` row tagged with `kind` (`full | deposit |
+ * balance`). Called at checkout / balance link initiation, before the
+ * adapter takes the customer to the provider — `providerRef` may be null
+ * when the adapter is asynchronous about producing one.
+ */
+export declare function insertPaymentRow(input: {
+    orderId: string;
+    provider: string;
+    providerRef?: string | null;
+    kind: ShopPaymentKind;
+    amount: number;
+    currency: string;
+}): Promise<ShopPaymentRow>;
+/** @internal Look up a payment row by provider + providerRef (webhook entry point). */
+export declare function findPaymentByProviderRef(provider: string, providerRef: string): Promise<ShopPaymentRow | null>;
+/** @internal Mark a payment row as paid (idempotent — no-op if already paid). */
+export declare function markPaymentPaid(paymentId: string): Promise<void>;
+/** @internal Mark a payment row as failed (rejected webhook). */
+export declare function markPaymentFailed(paymentId: string): Promise<void>;
+/**
+ * @internal
+ * List payment rows for an order, ordered by createdAt ascending. Used by
+ * refundOrder() when distinguishing which row to refund under per-kind refund.
+ */
+export declare function listOrderPayments(orderId: string): Promise<ShopPaymentRow[]>;

package/dist/shop/server/payments.js

@@ -0,0 +1,64 @@
+import { and, eq } from 'drizzle-orm';
+import { shopPaymentsTable } from '../../db-postgres/schema/shop/index.js';
+import { getShopDb } from './db.js';
+/**
+ * @internal
+ * Insert a new `shop_payments` row tagged with `kind` (`full | deposit |
+ * balance`). Called at checkout / balance link initiation, before the
+ * adapter takes the customer to the provider — `providerRef` may be null
+ * when the adapter is asynchronous about producing one.
+ */
+export async function insertPaymentRow(input) {
+    const db = getShopDb();
+    const [row] = await db
+        .insert(shopPaymentsTable)
+        .values({
+        orderId: input.orderId,
+        provider: input.provider,
+        providerRef: input.providerRef ?? null,
+        kind: input.kind,
+        amount: input.amount,
+        currency: input.currency,
+        status: 'pending'
+    })
+        .returning();
+    return row;
+}
+/** @internal Look up a payment row by provider + providerRef (webhook entry point). */
+export async function findPaymentByProviderRef(provider, providerRef) {
+    const db = getShopDb();
+    const [row] = await db
+        .select()
+        .from(shopPaymentsTable)
+        .where(and(eq(shopPaymentsTable.provider, provider), eq(shopPaymentsTable.providerRef, providerRef)));
+    return row ?? null;
+}
+/** @internal Mark a payment row as paid (idempotent — no-op if already paid). */
+export async function markPaymentPaid(paymentId) {
+    const db = getShopDb();
+    await db
+        .update(shopPaymentsTable)
+        .set({ status: 'paid', updatedAt: new Date() })
+        .where(eq(shopPaymentsTable.id, paymentId));
+}
+/** @internal Mark a payment row as failed (rejected webhook). */
+export async function markPaymentFailed(paymentId) {
+    const db = getShopDb();
+    await db
+        .update(shopPaymentsTable)
+        .set({ status: 'failed', updatedAt: new Date() })
+        .where(eq(shopPaymentsTable.id, paymentId));
+}
+/**
+ * @internal
+ * List payment rows for an order, ordered by createdAt ascending. Used by
+ * refundOrder() when distinguishing which row to refund under per-kind refund.
+ */
+export async function listOrderPayments(orderId) {
+    const db = getShopDb();
+    return db
+        .select()
+        .from(shopPaymentsTable)
+        .where(eq(shopPaymentsTable.orderId, orderId))
+        .orderBy(shopPaymentsTable.createdAt);
+}

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

@@ -12,7 +12,7 @@ export interface PopulatedShopField {
         /** Netto delta w PLN (number, ≤6dp). Od 0.15.2. */
         priceDelta: number;
         stock: number | null;
-        attributes: Record<string, string> | null;
+        attributes: Record<string, unknown> | null;
     }>;
 }
 export declare function resolveShopFields(data: Record<string, unknown>, fields: Field[], ctx: PopulateCtx): Promise<Record<string, unknown>>;

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

@@ -1,9 +1,9 @@
-import { shopRefundsTable } from '../../db-postgres/schema/shop/index.js';
+import { shopRefundsTable, type ShopPaymentKind } from '../../db-postgres/schema/shop/index.js';
 export type ShopRefundRow = typeof shopRefundsTable.$inferSelect;
 export declare class RefundError extends Error {
-    readonly code: 'order_not_found' | 'order_not_paid' | 'no_provider_ref' | 'unknown_provider' | 'refund_unsupported' | 'invalid_amount' | 'amount_exceeds_remaining' | 'provider_error';
+    readonly code: 'order_not_found' | 'order_not_paid' | 'no_provider_ref' | 'unknown_provider' | 'refund_unsupported' | 'invalid_amount' | 'amount_exceeds_remaining' | 'provider_error' | 'no_payment_kind';
     readonly cause?: unknown | undefined;
-    constructor(code: 'order_not_found' | 'order_not_paid' | 'no_provider_ref' | 'unknown_provider' | 'refund_unsupported' | 'invalid_amount' | 'amount_exceeds_remaining' | 'provider_error', message: string, cause?: unknown | undefined);
+    constructor(code: 'order_not_found' | 'order_not_paid' | 'no_provider_ref' | 'unknown_provider' | 'refund_unsupported' | 'invalid_amount' | 'amount_exceeds_remaining' | 'provider_error' | 'no_payment_kind', message: string, cause?: unknown | undefined);
 }
 export interface RefundOrderInput {
     orderId: string;
@@ -11,6 +11,20 @@ export interface RefundOrderInput {
     amount?: number;
     reason?: string;
     createdBy?: string;
+    /**
+     * Which payment row to refund under deposit `paymentPolicy`. Defaults to
+     * `'full'`. When the order has only a `deposit` or `balance` row, that
+     * row is used regardless of this hint (back-compat). Per-kind refunds
+     * cap `amount` to the matched payment row's amount, never the full
+     * order total.
+     */
+    kind?: ShopPaymentKind;
+    /**
+     * Re-increment variant stock for each order item when the refund
+     * succeeds. Default `false` to preserve legacy refund behavior; set
+     * `true` from the admin UI when the goods are not being delivered.
+     */
+    releaseStock?: boolean;
 }
 export interface RefundOrderResult {
     refund: ShopRefundRow;
@@ -20,13 +34,4 @@ export interface RefundOrderResult {
 /** Sum of succeeded refunds for the given order, in minor units. */
 export declare function getRefundedAmount(orderId: string): Promise<number>;
 export declare function listRefunds(orderId: string): Promise<ShopRefundRow[]>;
-/**
- * Refund an order — full or partial. Validates eligibility, records a pending
- * row, calls the adapter, transitions the row to succeeded/failed and the
- * order status to `refunded` when the full captured amount has been refunded.
- *
- * Throws `RefundError` on validation failures and provider errors. The
- * `pending` refund row is marked `failed` on provider error so admin can see
- * what was attempted.
- */
 export declare function refundOrder(input: RefundOrderInput): Promise<RefundOrderResult>;

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>;