includio-cms 0.26.0 → 0.28.0

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

@@ -0,0 +1,91 @@
+import { json } from '@sveltejs/kit';
+import { getCMS } from '../../core/cms.js';
+import { createBalanceSession, requireBalanceTokenSecret, verifyBalanceToken } from '../server/balance-payment.js';
+import { getOrderByNumber } from '../server/orders.js';
+function shopEnabled() {
+    try {
+        return getCMS().shopConfig !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * @experimental
+ * HTTP handlers for the balance-payment flow. Mount at
+ * `/api/shop/orders/[number]/balance` (or any URL containing `number` +
+ * `?token=...`).
+ *
+ * - `GET` returns the minimal public order view (amount due, currency)
+ *   when the token + balanceOwed check passes.
+ * - `POST` initiates a payment session for the outstanding balance using
+ *   the order's original payment adapter and returns `{ redirectUrl,
+ *   status }`.
+ *
+ * Both verbs return 403 when the token is invalid OR `balanceOwed` is
+ * false (no oracle distinction — we don't tell the caller which gate failed).
+ */
+export function createBalanceHandler() {
+    return {
+        GET: async ({ params, url }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            const orderNumber = params.number;
+            if (!orderNumber)
+                return json({ error: 'Order number required' }, { status: 400 });
+            const token = url.searchParams.get('token') ?? '';
+            const order = await getOrderByNumber(orderNumber);
+            if (!order)
+                return json({ error: 'Order not found' }, { status: 404 });
+            if (!order.balanceOwed || !order.partialPayment) {
+                return json({ error: 'No outstanding balance' }, { status: 403 });
+            }
+            const secret = requireBalanceTokenSecret();
+            if (!verifyBalanceToken(token, order.id, secret)) {
+                return json({ error: 'Invalid token' }, { status: 403 });
+            }
+            const pp = order.partialPayment;
+            return json({
+                orderNumber: order.number,
+                currency: order.currency,
+                totalGross: order.totalGross,
+                amountToPay: pp.balanceAmount,
+                paidAmount: pp.paidAmount,
+                paymentMethod: order.paymentMethod,
+                language: order.language
+            });
+        },
+        POST: async ({ params, url, request, getClientAddress }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            const orderNumber = params.number;
+            if (!orderNumber)
+                return json({ error: 'Order number required' }, { status: 400 });
+            const token = url.searchParams.get('token') ?? '';
+            let customerIp;
+            try {
+                customerIp = getClientAddress();
+            }
+            catch {
+                customerIp = undefined;
+            }
+            const body = (await request.json().catch(() => ({})));
+            const language = typeof body.language === 'string' ? body.language : undefined;
+            try {
+                const result = await createBalanceSession(orderNumber, token, { customerIp, language });
+                return json({
+                    status: result.status,
+                    redirectUrl: result.redirectUrl ?? null,
+                    requiresPaymentRedirect: result.status === 'redirect'
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'Balance payment failed';
+                const code = message === 'Invalid balance token' || message === 'Order has no outstanding balance'
+                    ? 403
+                    : 400;
+                return json({ error: message }, { status: code });
+            }
+        }
+    };
+}

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,9 +4,11 @@ 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';
+import { isValidNip } from '../nip.js';
 function shopEnabled() {
     try {
         return getCMS().shopConfig !== null;
@@ -65,6 +67,12 @@ export function createCheckoutHandler() {
                 return json({ error: 'shippingMethodId required' }, { status: 400 });
             if (!paymentMethod)
                 return json({ error: 'paymentMethod required' }, { status: 400 });
+            // Validate the NIP up front — Fakturownia rejects an invalid one and the
+            // invoice later goes to KSeF, so we never persist a malformed tax id.
+            const customerNip = asString(body.customerNip, 20);
+            if (customerNip && !isValidNip(customerNip)) {
+                return json({ error: 'Podany NIP jest nieprawidłowy.' }, { status: 400 });
+            }
             const cartItems = readCartCookie(cookies);
             if (cartItems.length === 0) {
                 return json({ error: 'Cart is empty' }, { status: 400 });
@@ -97,7 +105,11 @@ export function createCheckoutHandler() {
                     customerEmail,
                     customerName: asString(body.customerName, 200),
                     customerPhone: asString(body.customerPhone, 40),
+                    customerNip,
+                    customerCompanyName: asString(body.customerCompanyName, 200),
                     shippingAddress: asStringRecord(body.shippingAddress),
+                    billingAddress: asStringRecord(body.billingAddress),
+                    invoiceRequested: body.invoiceRequested === true,
                     shippingMethodId,
                     carrierRef,
                     paymentMethod,
@@ -119,10 +131,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 +159,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,8 @@ 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 { fakturowniaAdapter } from './adapters/fakturownia/index.js';
+export type { FakturowniaAdapterOptions } from './adapters/fakturownia/index.js';
+export { isValidNip } from './nip.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, InvoicingAdapter, InvoiceIssuePolicy, InvoiceBuyer, InvoiceLineItem, InvoicePayload, InvoiceCreateResult, InvoiceContext } from './types.js';
+export { interpolateTemplate } from './template.js';

package/dist/shop/index.js

@@ -12,11 +12,20 @@ export function defineShop(config) {
             webhook: config.rateLimit?.webhook ?? { limit: 60, windowSec: 60 }
         },
         carriers: config.carriers ?? [],
+        invoicing: config.invoicing ?? null,
         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 { fakturowniaAdapter } from './adapters/fakturownia/index.js';
+export { isValidNip } from './nip.js';
+export { interpolateTemplate } from './template.js';

package/dist/shop/nip.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Validate a Polish NIP (tax id) — 10 digits with a weighted checksum.
+ *
+ * Accepts dashes, spaces and an optional `PL` prefix; these are stripped before
+ * validation. Returns `false` for any malformed input rather than throwing.
+ *
+ * Validation is intentionally strict: an invoice issued with an invalid NIP is
+ * rejected by Fakturownia and would later fail KSeF submission, so the buyer's
+ * NIP is verified at checkout time before it ever reaches the adapter.
+ * @public
+ */
+export declare function isValidNip(nip: string): boolean;

package/dist/shop/nip.js

@@ -0,0 +1,23 @@
+const NIP_WEIGHTS = [6, 5, 7, 2, 3, 4, 5, 6, 7];
+/**
+ * Validate a Polish NIP (tax id) — 10 digits with a weighted checksum.
+ *
+ * Accepts dashes, spaces and an optional `PL` prefix; these are stripped before
+ * validation. Returns `false` for any malformed input rather than throwing.
+ *
+ * Validation is intentionally strict: an invoice issued with an invalid NIP is
+ * rejected by Fakturownia and would later fail KSeF submission, so the buyer's
+ * NIP is verified at checkout time before it ever reaches the adapter.
+ * @public
+ */
+export function isValidNip(nip) {
+    const normalized = nip.replace(/^PL/i, '').replace(/[\s-]/g, '');
+    if (!/^\d{10}$/.test(normalized))
+        return false;
+    const digits = normalized.split('').map(Number);
+    const sum = NIP_WEIGHTS.reduce((acc, weight, i) => acc + weight * digits[i], 0);
+    const checksum = sum % 11;
+    if (checksum === 10)
+        return false;
+    return checksum === digits[9];
+}

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,