includio-cms 0.24.0 → 0.25.0

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

@@ -1,7 +1,9 @@
 import { json } from '@sveltejs/kit';
 import { getCMS } from '../../core/cms.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 { checkRateLimit, clientKey } from '../rate-limit.js';
 function shopEnabled() {
     try {
@@ -13,7 +15,13 @@ function shopEnabled() {
 }
 async function respondWithCart(cookies) {
     const items = readCartCookie(cookies);
-    const snapshot = await hydrateCart(items);
+    const couponCode = readCouponCookie(cookies);
+    const snapshot = await hydrateCart(items, { couponCode });
+    // If coupon failed validation server-side (snapshot.coupon undefined despite cookie),
+    // drop the cookie so we don't keep retrying every request.
+    if (couponCode && !snapshot.coupon) {
+        clearCouponCookie(cookies);
+    }
     // If any items were removed during hydration (not-found), purge them from cookie
     const validIds = new Set(snapshot.items.filter((l) => l.issue !== 'not-found').map((l) => l.variantId));
     const cleaned = items.filter((i) => validIds.has(i.variantId));
@@ -81,8 +89,59 @@ export function createCartHandler() {
             }
             else {
                 writeCartCookie(cookies, []);
+                clearCouponCookie(cookies);
             }
             return respondWithCart(cookies);
         }
     };
 }
+/**
+ * Cart coupon endpoints — POST applies a code, DELETE removes it.
+ * Mount at `/api/shop/cart/coupon`.
+ */
+export function createCartCouponHandler() {
+    return {
+        POST: async ({ request, cookies }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            const rule = getCMS().shopConfig?.rateLimit.checkout ?? { limit: 30, windowSec: 60 };
+            const rl = checkRateLimit(clientKey(request, 'coupon-apply'), rule);
+            if (!rl.allowed)
+                return json({ error: 'Rate limit exceeded' }, { status: 429 });
+            const body = (await request.json().catch(() => null));
+            if (!body || typeof body.code !== 'string') {
+                return json({ error: 'code required' }, { status: 400 });
+            }
+            const code = normalizeCouponCode(body.code);
+            if (!isValidCouponCode(code)) {
+                return json({ error: 'invalid_code' }, { status: 400 });
+            }
+            const items = readCartCookie(cookies);
+            const baseSnapshot = await hydrateCart(items);
+            if (baseSnapshot.subtotalNet <= 0) {
+                return json({ error: 'empty_cart' }, { status: 400 });
+            }
+            try {
+                await validateCoupon({
+                    code,
+                    subtotalNet: baseSnapshot.subtotalNet,
+                    subtotalGross: baseSnapshot.subtotalGross
+                });
+            }
+            catch (err) {
+                if (err instanceof CouponError) {
+                    return json({ error: err.code, message: err.message }, { status: 400 });
+                }
+                throw err;
+            }
+            writeCouponCookie(cookies, code);
+            return respondWithCart(cookies);
+        },
+        DELETE: async ({ cookies }) => {
+            if (!shopEnabled())
+                return json({ error: 'Shop not enabled' }, { status: 404 });
+            clearCouponCookie(cookies);
+            return respondWithCart(cookies);
+        }
+    };
+}

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

@@ -1,6 +1,7 @@
 import { json } from '@sveltejs/kit';
 import { getCMS } from '../../core/cms.js';
 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 { getShippingMethod } from '../server/shipping.js';
@@ -89,6 +90,7 @@ export function createCheckoutHandler() {
                 console.error('[shop] carrier validateSelection failed:', err);
                 return json({ error: 'Carrier validation failed.' }, { status: 400 });
             }
+            const couponCode = readCouponCookie(cookies);
             try {
                 const result = await createOrderFromCart({
                     cartItems,
@@ -101,10 +103,12 @@ export function createCheckoutHandler() {
                     paymentMethod,
                     consents: asConsents(body.consents),
                     notes: asString(body.notes, 2000),
-                    language: asString(body.language, 10)
+                    language: asString(body.language, 10),
+                    couponCode: couponCode ?? undefined
                 });
-                // Clear cart on successful order
+                // Clear cart + coupon on successful order
                 writeCartCookie(cookies, []);
+                clearCouponCookie(cookies);
                 // Short-lived cookie for same-browser order view fallback
                 writeOrderTokenCookie(cookies, {
                     number: result.order.number,
@@ -153,7 +157,7 @@ export function createCheckoutHandler() {
                     currency: result.order.currency,
                     paymentStatus: paymentResult?.status ?? 'manual',
                     requiresPaymentRedirect: requiresRedirect,
-                    redirectUrl: requiresRedirect ? paymentResult?.redirectUrl ?? null : null
+                    redirectUrl: requiresRedirect ? (paymentResult?.redirectUrl ?? null) : null
                 });
             }
             catch (err) {

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

@@ -1,4 +1,4 @@
-export { createCartHandler } from './cart-handler.js';
+export { createCartHandler, createCartCouponHandler } from './cart-handler.js';
 export { createShippingMethodsHandler } from './shipping-handler.js';
 export { createCheckoutHandler } from './checkout-handler.js';
 export { createOrderHandler } from './order-handler.js';

package/dist/shop/http/index.js

@@ -1,4 +1,4 @@
-export { createCartHandler } from './cart-handler.js';
+export { createCartHandler, createCartCouponHandler } from './cart-handler.js';
 export { createShippingMethodsHandler } from './shipping-handler.js';
 export { createCheckoutHandler } from './checkout-handler.js';
 export { createOrderHandler } from './order-handler.js';

package/dist/shop/http/retry-payment-handler.js

@@ -92,7 +92,7 @@ export function createRetryPaymentHandler() {
                 status: result.status === 'redirect' ? 'awaitingPayment' : order.status,
                 paymentStatus: result.status,
                 requiresPaymentRedirect: result.status === 'redirect',
-                redirectUrl: result.status === 'redirect' ? result.redirectUrl ?? null : null
+                redirectUrl: result.status === 'redirect' ? (result.redirectUrl ?? null) : null
             });
         }
     };

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

@@ -4,6 +4,7 @@ import { requireShopConfig } from '../server/db.js';
 import { getOrderByNumber, updateOrderStatus } from '../server/orders.js';
 import { checkRateLimit, clientKey } from '../rate-limit.js';
 import { isTerminalStatus, mapEventToStatus } from './webhook-logic.js';
+import { markWebhookEventProcessed, reserveWebhookEvent } from './webhook-idempotency.js';
 function shopEnabled() {
     try {
         return getCMS().shopConfig !== null;
@@ -42,18 +43,33 @@ export function createPaymentWebhookHandler() {
                 // Bad signature / malformed body → 400 (don't encourage retries with 200)
                 return json({ error: 'Invalid webhook' }, { status: 400 });
             }
+            // Idempotency — primary defence: persistent (provider, event_id) log.
+            // Falls through (rowId=null, isNew=true) when the adapter does not
+            // surface an event_id; in that case we still rely on terminal-status
+            // check below.
+            const reservation = await reserveWebhookEvent(provider, event);
+            if (!reservation.isNew) {
+                return json({ received: true, idempotent: true, replay: true });
+            }
             const order = await getOrderByNumber(event.orderNumber);
             if (!order) {
                 // Unknown order — 200 so the provider stops retrying
                 console.warn(`[shop] Webhook for unknown order ${event.orderNumber} (${provider}) — acking.`);
+                if (reservation.rowId)
+                    await markWebhookEventProcessed(reservation.rowId, null);
                 return json({ received: true });
             }
-            // Idempotency — terminal states are no-ops
+            // Secondary idempotency — terminal states are no-ops (covers adapters
+            // that didn't surface eventId).
             if (isTerminalStatus(order.status)) {
+                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 {
@@ -67,6 +83,8 @@ export function createPaymentWebhookHandler() {
                 // Return 500 — provider retry helps
                 return json({ error: 'Processing failed' }, { status: 500 });
             }
+            if (reservation.rowId)
+                await markWebhookEventProcessed(reservation.rowId, order.id);
             return json({ received: true });
         }
     };

package/dist/shop/http/webhook-idempotency.d.ts

@@ -0,0 +1,16 @@
+import type { PaymentEvent } from '../types.js';
+export interface IdempotencyCheckResult {
+    /** True when this is the first time we see this (provider, eventId). */
+    isNew: boolean;
+    /** Internal id of the inserted/existing log row, when known. */
+    rowId: string | null;
+}
+/**
+ * Reserve an idempotency slot for a webhook event. Returns `{ isNew: true }`
+ * exactly once per (provider, eventId) — concurrent calls race on the unique
+ * index and only one wins. When the event has no `eventId`, returns
+ * `{ isNew: true, rowId: null }` and the caller MUST fall back to its own
+ * idempotency check (e.g. terminal-status on the order).
+ */
+export declare function reserveWebhookEvent(provider: string, event: PaymentEvent): Promise<IdempotencyCheckResult>;
+export declare function markWebhookEventProcessed(rowId: string, orderId?: string | null): Promise<void>;

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

@@ -0,0 +1,51 @@
+import { eq } from 'drizzle-orm';
+import { shopWebhookEventsTable } from '../../db-postgres/schema/shop/index.js';
+import { getShopDb } from '../server/db.js';
+/**
+ * Reserve an idempotency slot for a webhook event. Returns `{ isNew: true }`
+ * exactly once per (provider, eventId) — concurrent calls race on the unique
+ * index and only one wins. When the event has no `eventId`, returns
+ * `{ isNew: true, rowId: null }` and the caller MUST fall back to its own
+ * idempotency check (e.g. terminal-status on the order).
+ */
+export async function reserveWebhookEvent(provider, event) {
+    if (!event.eventId)
+        return { isNew: true, rowId: null };
+    const db = getShopDb();
+    try {
+        const [row] = await db
+            .insert(shopWebhookEventsTable)
+            .values({
+            provider,
+            eventId: event.eventId,
+            eventType: event.eventType ?? null,
+            orderNumber: event.orderNumber || null,
+            raw: event.raw
+        })
+            .onConflictDoNothing({
+            target: [shopWebhookEventsTable.provider, shopWebhookEventsTable.eventId]
+        })
+            .returning({ id: shopWebhookEventsTable.id });
+        if (row)
+            return { isNew: true, rowId: row.id };
+        return { isNew: false, rowId: null };
+    }
+    catch (err) {
+        // Defensive — if the unique index races and DB raises before onConflict
+        // kicks in (vendor-specific), treat as duplicate so we don't reprocess.
+        console.warn(`[shop] reserveWebhookEvent insert failed for ${provider}:`, err);
+        return { isNew: false, rowId: null };
+    }
+}
+export async function markWebhookEventProcessed(rowId, orderId) {
+    if (!rowId)
+        return;
+    const db = getShopDb();
+    await db
+        .update(shopWebhookEventsTable)
+        .set({
+        processedAt: new Date(),
+        ...(orderId ? { orderId } : {})
+    })
+        .where(eq(shopWebhookEventsTable.id, rowId));
+}

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

@@ -2,7 +2,8 @@ export const TERMINAL_ORDER_STATUSES = new Set([
     'paid',
     'paymentRejected',
     'cancelled',
-    'done'
+    'done',
+    'refunded'
 ]);
 export function isTerminalStatus(status) {
     return TERMINAL_ORDER_STATUSES.has(status);

package/dist/shop/index.d.ts

@@ -3,6 +3,8 @@ export declare function defineShop(config: ShopConfig): ResolvedShopConfig;
 export { manualAdapter } from './adapters/manual/index.js';
 export { payuAdapter } from './adapters/payu/index.js';
 export type { PayuAdapterOptions } from './adapters/payu/index.js';
+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, CarrierAdapter, CarrierEvent, ShipmentCreateInput, ShipmentCreateResult, ShipmentLabel, ConsentConfig, ShopFeatures, PaymentCreateResult, PaymentEvent, OrderRef, 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 } from './types.js';

package/dist/shop/index.js

@@ -4,7 +4,8 @@ export function defineShop(config) {
         features: {
             variants: config.features?.variants ?? false,
             stock: config.features?.stock ?? false,
-            accounts: config.features?.accounts ?? false
+            accounts: config.features?.accounts ?? false,
+            coupons: config.features?.coupons ?? false
         },
         rateLimit: {
             checkout: config.rateLimit?.checkout ?? { limit: 5, windowSec: 60 },
@@ -17,4 +18,5 @@ export function defineShop(config) {
 }
 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';

package/dist/shop/pricing.d.ts

@@ -17,3 +17,18 @@ export interface Totals {
 }
 export declare function sumTotals(lines: Priceable[]): Totals;
 export declare function resolveI18n(value: Record<string, string> | undefined | null, language: string, fallback?: string): string;
+export interface CouponDiscountInput {
+    type: 'percent' | 'fixed';
+    /** percent: 0-100; fixed: PLN value (precision 20,6). */
+    value: number;
+}
+/**
+ * Compute discount in cents (minor units) applied to a net subtotal.
+ * - `percent`: subtotalNet × (value / 100), rounded to nearest cent.
+ * - `fixed`: PLN value converted to cents, capped at subtotalNet (never negative).
+ *
+ * Discount is calculated on the net subtotal — VAT is then applied to lines
+ * after the discount factor, so the discount appears proportionally on each
+ * line. Result is bounded to `[0, subtotalNet]`.
+ */
+export declare function calculateCouponDiscountNet(subtotalNet: number, coupon: CouponDiscountInput): number;

package/dist/shop/pricing.js

@@ -47,3 +47,25 @@ export function resolveI18n(value, language, fallback) {
     const first = Object.values(value)[0];
     return first ?? fallback ?? '';
 }
+/**
+ * Compute discount in cents (minor units) applied to a net subtotal.
+ * - `percent`: subtotalNet × (value / 100), rounded to nearest cent.
+ * - `fixed`: PLN value converted to cents, capped at subtotalNet (never negative).
+ *
+ * Discount is calculated on the net subtotal — VAT is then applied to lines
+ * after the discount factor, so the discount appears proportionally on each
+ * line. Result is bounded to `[0, subtotalNet]`.
+ */
+export function calculateCouponDiscountNet(subtotalNet, coupon) {
+    if (subtotalNet <= 0)
+        return 0;
+    let raw = 0;
+    if (coupon.type === 'percent') {
+        const pct = Math.max(0, Math.min(100, coupon.value));
+        raw = Math.round(subtotalNet * (pct / 100));
+    }
+    else if (coupon.type === 'fixed') {
+        raw = toCents(Math.max(0, coupon.value));
+    }
+    return Math.max(0, Math.min(raw, subtotalNet));
+}

package/dist/shop/server/cart-hydrate.d.ts

@@ -1,4 +1,5 @@
 import type { CartItemRef, CartSnapshot } from '../cart/types.js';
 export declare function hydrateCart(items: CartItemRef[], opts?: {
     language?: string;
+    couponCode?: string | null;
 }): Promise<CartSnapshot>;

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

@@ -4,7 +4,8 @@ import { entriesTable } from '../../db-postgres/schema/entry.js';
 import { entryVersionsTable } from '../../db-postgres/schema/entryVersion.js';
 import { getCMS } from '../../core/cms.js';
 import { getShopDb, requireShopConfig } from './db.js';
-import { grossPlnFromNetPln, toCents } from '../pricing.js';
+import { grossFromNet, grossPlnFromNetPln, toCents } from '../pricing.js';
+import { buildAppliedCoupon, validateCoupon, CouponError } from './coupons.js';
 export async function hydrateCart(items, opts = {}) {
     const shop = requireShopConfig();
     const cms = getCMS();
@@ -13,6 +14,9 @@ export async function hydrateCart(items, opts = {}) {
         return {
             items: [],
             itemCount: 0,
+            subtotalNet: 0,
+            subtotalGross: 0,
+            subtotalVat: 0,
             totalNet: 0,
             totalGross: 0,
             totalVat: 0,
@@ -27,10 +31,7 @@ export async function hydrateCart(items, opts = {}) {
         .where(inArray(shopProductVariantsTable.id, variantIds));
     const productIds = Array.from(new Set(variants.map((v) => v.productId)));
     const products = productIds.length > 0
-        ? await db
-            .select()
-            .from(shopProductsTable)
-            .where(inArray(shopProductsTable.id, productIds))
+        ? await db.select().from(shopProductsTable).where(inArray(shopProductsTable.id, productIds))
         : [];
     const entryIds = products.map((p) => p.entryId);
     const entries = entryIds.length > 0
@@ -144,13 +145,60 @@ export async function hydrateCart(items, opts = {}) {
         totalGross += lineGross;
     }
     const itemCount = lines.reduce((sum, l) => sum + l.qty, 0);
+    const subtotalNet = totalNet;
+    const subtotalGross = totalGross;
+    let appliedCoupon;
+    let finalLines = lines;
+    let finalTotalNet = totalNet;
+    let finalTotalGross = totalGross;
+    if (opts.couponCode && shop.features.coupons && subtotalNet > 0) {
+        try {
+            const { row, discountNet } = await validateCoupon({
+                code: opts.couponCode,
+                subtotalNet,
+                subtotalGross
+            });
+            if (discountNet > 0) {
+                const factor = (subtotalNet - discountNet) / subtotalNet;
+                finalLines = lines.map((l) => {
+                    if (!l.available)
+                        return l;
+                    const newLineNet = Math.round(l.lineNet * factor);
+                    const newLineGross = grossFromNet(newLineNet, l.vatRate);
+                    return {
+                        ...l,
+                        lineNet: newLineNet,
+                        lineGross: newLineGross,
+                        lineVat: newLineGross - newLineNet
+                    };
+                });
+                finalTotalNet = finalLines.reduce((s, l) => s + l.lineNet, 0);
+                finalTotalGross = finalLines.reduce((s, l) => s + l.lineGross, 0);
+            }
+            appliedCoupon = buildAppliedCoupon(row, discountNet, subtotalNet, subtotalGross);
+        }
+        catch (err) {
+            if (err instanceof CouponError) {
+                // Silently drop invalid coupon — caller can re-validate explicitly
+                // via validateCoupon() to surface the reason to the user.
+                appliedCoupon = undefined;
+            }
+            else {
+                throw err;
+            }
+        }
+    }
     return {
-        items: lines,
+        items: finalLines,
         itemCount,
-        totalNet,
-        totalGross,
-        totalVat: totalGross - totalNet,
-        currency: shop.currency
+        subtotalNet,
+        subtotalGross,
+        subtotalVat: subtotalGross - subtotalNet,
+        totalNet: finalTotalNet,
+        totalGross: finalTotalGross,
+        totalVat: finalTotalGross - finalTotalNet,
+        currency: shop.currency,
+        ...(appliedCoupon ? { coupon: appliedCoupon } : {})
     };
     function makeMissingLine(ref, issue) {
         return {

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

@@ -0,0 +1,53 @@
+import { shopCouponsTable } from '../../db-postgres/schema/shop/index.js';
+import type { AppliedCoupon } from '../cart/types.js';
+export type ShopCouponRow = typeof shopCouponsTable.$inferSelect;
+export declare class CouponError extends Error {
+    readonly code: 'invalid_code' | 'not_found' | 'inactive' | 'expired' | 'exhausted' | 'min_order_not_met' | 'feature_disabled' | 'race_lost';
+    constructor(code: 'invalid_code' | 'not_found' | 'inactive' | 'expired' | 'exhausted' | 'min_order_not_met' | 'feature_disabled' | 'race_lost', message: string);
+}
+export interface ValidateCouponInput {
+    code: string;
+    subtotalNet: number;
+    subtotalGross: number;
+}
+export interface ValidatedCoupon {
+    row: ShopCouponRow;
+    discountNet: number;
+}
+/**
+ * Look up and validate a coupon for a given cart subtotal. Returns row +
+ * computed discount or throws `CouponError`. Does NOT mutate `usedCount`.
+ */
+export declare function validateCoupon(input: ValidateCouponInput): Promise<ValidatedCoupon>;
+/**
+ * Build an `AppliedCoupon` snapshot from a validated coupon and a discount
+ * computed in net. `discountGross` reflects the gross-equivalent (subtotalGross
+ * − totalGrossAfterDiscount). For uniform per-line discount factor:
+ *   factor = (subtotalNet − discountNet) / subtotalNet
+ *   discountGross = subtotalGross × (1 − factor)
+ */
+export declare function buildAppliedCoupon(row: ShopCouponRow, discountNet: number, subtotalNet: number, subtotalGross: number): AppliedCoupon;
+/**
+ * Atomically reserve one redemption slot on a coupon. Returns the updated
+ * `usedCount` on success, throws `CouponError('race_lost')` if the slot was
+ * taken concurrently. Use inside the checkout transaction.
+ *
+ * The UPDATE is conditional on `(maxUses IS NULL OR usedCount < maxUses)` so
+ * concurrent redemptions race at the DB and the loser fails fast.
+ */
+export declare function reserveCouponSlot(couponId: string): Promise<number>;
+/**
+ * Persist the redemption row tying a coupon to an order.
+ * UNIQUE(orderId) means a retried checkout for the same order won't double-redeem.
+ */
+export declare function recordCouponRedemption(input: {
+    couponId: string;
+    orderId: string;
+    discountAmount: number;
+}): Promise<void>;
+/**
+ * Release a previously reserved coupon slot — used to roll back when a
+ * checkout fails after `reserveCouponSlot()` succeeded but before the order
+ * row commits.
+ */
+export declare function releaseCouponSlot(couponId: string): Promise<void>;

package/dist/shop/server/coupons.js

@@ -0,0 +1,117 @@
+import { and, eq, isNull, or, sql } from 'drizzle-orm';
+import { shopCouponRedemptionsTable, shopCouponsTable } from '../../db-postgres/schema/shop/index.js';
+import { getShopDb, requireShopConfig } from './db.js';
+import { calculateCouponDiscountNet } from '../pricing.js';
+import { normalizeCouponCode } from '../cart/coupon-cookie.js';
+export class CouponError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CouponError';
+    }
+}
+/**
+ * Look up and validate a coupon for a given cart subtotal. Returns row +
+ * computed discount or throws `CouponError`. Does NOT mutate `usedCount`.
+ */
+export async function validateCoupon(input) {
+    const shop = requireShopConfig();
+    if (!shop.features.coupons) {
+        throw new CouponError('feature_disabled', 'Coupons are not enabled for this shop');
+    }
+    const code = normalizeCouponCode(input.code);
+    if (!code)
+        throw new CouponError('invalid_code', 'Coupon code is empty');
+    const db = getShopDb();
+    const [row] = await db.select().from(shopCouponsTable).where(eq(shopCouponsTable.code, code));
+    if (!row)
+        throw new CouponError('not_found', `Coupon "${code}" does not exist`);
+    if (!row.isActive)
+        throw new CouponError('inactive', `Coupon "${code}" is not active`);
+    if (row.expiresAt && row.expiresAt.getTime() < Date.now()) {
+        throw new CouponError('expired', `Coupon "${code}" has expired`);
+    }
+    if (row.maxUses !== null && row.usedCount >= row.maxUses) {
+        throw new CouponError('exhausted', `Coupon "${code}" has no more uses`);
+    }
+    if (row.minOrderAmount !== null && input.subtotalGross < row.minOrderAmount) {
+        throw new CouponError('min_order_not_met', `Coupon "${code}" requires minimum order ${row.minOrderAmount}`);
+    }
+    const discountNet = calculateCouponDiscountNet(input.subtotalNet, {
+        type: row.type,
+        value: Number(row.value)
+    });
+    return { row, discountNet };
+}
+/**
+ * Build an `AppliedCoupon` snapshot from a validated coupon and a discount
+ * computed in net. `discountGross` reflects the gross-equivalent (subtotalGross
+ * − totalGrossAfterDiscount). For uniform per-line discount factor:
+ *   factor = (subtotalNet − discountNet) / subtotalNet
+ *   discountGross = subtotalGross × (1 − factor)
+ */
+export function buildAppliedCoupon(row, discountNet, subtotalNet, subtotalGross) {
+    const factor = subtotalNet > 0 ? (subtotalNet - discountNet) / subtotalNet : 1;
+    const discountGross = subtotalGross - Math.round(subtotalGross * factor);
+    return {
+        code: row.code,
+        type: row.type,
+        value: Number(row.value),
+        discountNet,
+        discountGross
+    };
+}
+/**
+ * Atomically reserve one redemption slot on a coupon. Returns the updated
+ * `usedCount` on success, throws `CouponError('race_lost')` if the slot was
+ * taken concurrently. Use inside the checkout transaction.
+ *
+ * The UPDATE is conditional on `(maxUses IS NULL OR usedCount < maxUses)` so
+ * concurrent redemptions race at the DB and the loser fails fast.
+ */
+export async function reserveCouponSlot(couponId) {
+    const db = getShopDb();
+    const result = await db
+        .update(shopCouponsTable)
+        .set({
+        usedCount: sql `${shopCouponsTable.usedCount} + 1`,
+        updatedAt: new Date()
+    })
+        .where(and(eq(shopCouponsTable.id, couponId), or(isNull(shopCouponsTable.maxUses), sql `${shopCouponsTable.usedCount} < ${shopCouponsTable.maxUses}`)))
+        .returning({ usedCount: shopCouponsTable.usedCount });
+    if (result.length === 0) {
+        throw new CouponError('exhausted', 'Coupon slot taken concurrently');
+    }
+    return result[0].usedCount;
+}
+/**
+ * Persist the redemption row tying a coupon to an order.
+ * UNIQUE(orderId) means a retried checkout for the same order won't double-redeem.
+ */
+export async function recordCouponRedemption(input) {
+    const db = getShopDb();
+    await db
+        .insert(shopCouponRedemptionsTable)
+        .values({
+        couponId: input.couponId,
+        orderId: input.orderId,
+        discountAmount: input.discountAmount
+    })
+        .onConflictDoNothing({ target: shopCouponRedemptionsTable.orderId });
+}
+/**
+ * Release a previously reserved coupon slot — used to roll back when a
+ * checkout fails after `reserveCouponSlot()` succeeded but before the order
+ * row commits.
+ */
+export async function releaseCouponSlot(couponId) {
+    const db = getShopDb();
+    await db
+        .update(shopCouponsTable)
+        .set({
+        usedCount: sql `GREATEST(${shopCouponsTable.usedCount} - 1, 0)`,
+        updatedAt: new Date()
+    })
+        .where(eq(shopCouponsTable.id, couponId));
+}

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

@@ -1,2 +1,17 @@
 import type { OrderStatus } from '../types.js';
 export declare function sendOrderStatusEmail(orderId: string, status: OrderStatus): Promise<void>;
+/**
+ * Notify the shop admin that a product crossed its low-stock threshold.
+ * Fire-and-forget — silently no-ops when no `shop.adminEmail` or no email
+ * adapter is configured. Stays inside email.ts to keep the adapter call
+ * site centralised (HTML, escaping, logging behaviour identical to status
+ * emails).
+ *
+ * @internal
+ */
+export declare function sendLowStockEmail(input: {
+    productTitle: string;
+    variantSku: string | null;
+    stock: number;
+    threshold: number;
+}): Promise<void>;