includio-cms 0.27.0 → 0.28.0

package/dist/shop/server/invoices.js

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

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

@@ -25,7 +25,11 @@ export interface CreateOrderInput {
     customerEmail: string;
     customerName?: string;
     customerPhone?: string;
+    customerNip?: string;
+    customerCompanyName?: string;
     shippingAddress?: Record<string, string>;
+    billingAddress?: Record<string, string>;
+    invoiceRequested?: boolean;
     shippingMethodId: string;
     carrierRef?: string;
     paymentMethod: string;

package/dist/shop/server/orders.js

@@ -9,6 +9,7 @@ import { sendLowStockEmail, sendOrderStatusEmail } from './email.js';
 import { isPaymentMethodAllowed } from './payment-compat.js';
 import { isVariantExpired, VariantExpiredError } from '../expiry.js';
 import { resolvePaymentAmount } from './payment-policy.js';
+import { maybeIssueInvoiceForOrder } from './invoices.js';
 import { CouponError, recordCouponRedemption, releaseCouponSlot, reserveCouponSlot, validateCoupon } from './coupons.js';
 /**
  * @public
@@ -237,7 +238,11 @@ export async function createOrderFromCart(input) {
             customerEmail: input.customerEmail,
             customerName: input.customerName ?? null,
             customerPhone: input.customerPhone ?? null,
+            customerNip: input.customerNip ?? null,
+            customerCompanyName: input.customerCompanyName ?? null,
             shippingAddress: input.shippingAddress ?? null,
+            billingAddress: input.billingAddress ?? null,
+            invoiceRequested: input.invoiceRequested ?? false,
             totalNet,
             totalGross,
             vatAmount: totalVat,
@@ -430,6 +435,10 @@ export async function updateOrderStatus(orderId, status, opts = {}) {
     }
     const [updated] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
     void sendOrderStatusEmail(orderId, status);
+    // Auto-issue an invoice once the order is paid. Fail-open / fire-and-forget —
+    // the guard inside skips deposit orders that still owe a balance.
+    if (status === 'paid')
+        void maybeIssueInvoiceForOrder(orderId);
     return updated;
 }
 /**
@@ -461,6 +470,8 @@ export async function markBalancePaid(orderId) {
     })
         .where(eq(shopOrdersTable.id, orderId));
     const [updated] = await db.select().from(shopOrdersTable).where(eq(shopOrdersTable.id, orderId));
+    // Balance cleared → the order is now fully paid; issue its invoice.
+    void maybeIssueInvoiceForOrder(orderId);
     return updated ?? null;
 }
 export async function setPaymentProviderRef(orderId, ref) {

package/dist/shop/types.d.ts

@@ -265,11 +265,76 @@ export interface VariantExpiryConfig {
     source: string;
     offsetDays: number;
 }
+/**
+ * When an invoice should be issued automatically after an order is fully paid.
+ * - `b2bAndOnRequest` (default): only when the order carries a NIP (B2B) or the
+ *   customer explicitly requested an invoice (`invoiceRequested`).
+ * - `always`: for every fully-paid order regardless of NIP / request.
+ * @public
+ */
+export type InvoiceIssuePolicy = 'b2bAndOnRequest' | 'always';
+/** @public */
+export interface InvoiceBuyer {
+    name: string;
+    email: string;
+    nip?: string | null;
+    companyName?: string | null;
+    address?: Record<string, string> | null;
+}
+/** @public */
+export interface InvoiceLineItem {
+    name: string;
+    quantity: number;
+    /** Gross unit price in minor units (grosze for PLN). */
+    unitPriceGross: number;
+    /** VAT rate as a plain percentage (e.g. `23` for 23%). */
+    vatRate: number;
+}
+/** @public */
+export interface InvoicePayload {
+    orderNumber: string;
+    currency: Currency;
+    buyer: InvoiceBuyer;
+    items: InvoiceLineItem[];
+    /** ISO timestamp the payment was confirmed — used as issue / paid date. */
+    paidAt: string;
+}
+/** @public */
+export interface InvoiceCreateResult {
+    externalId: string;
+    number?: string;
+    pdfUrl?: string;
+    raw?: unknown;
+}
+/** @public */
+export interface InvoiceContext {
+    language?: string | null;
+}
+/**
+ * Adapter that issues invoices with an external provider (e.g. Fakturownia).
+ * Registered via `defineShop({ invoicing })`. `createInvoice` is called once an
+ * order is fully paid and qualifies under `issueWhen`; `send` (optional) e-mails
+ * the issued invoice to the buyer provider-side.
+ * @public
+ */
+export interface InvoicingAdapter {
+    id: string;
+    /** Trigger policy. Default `b2bAndOnRequest`. */
+    issueWhen?: InvoiceIssuePolicy;
+    createInvoice(payload: InvoicePayload, ctx?: InvoiceContext): Promise<InvoiceCreateResult>;
+    send?(externalId: string, ctx?: InvoiceContext): Promise<void>;
+}
 export interface ShopConfig {
     currency: Currency;
     vatRates: number[];
     payment: PaymentAdapter[];
     carriers?: CarrierAdapter[];
+    /**
+     * Optional invoicing adapter — issues invoices automatically once an order is
+     * fully paid. Omitted = no invoicing.
+     * @public
+     */
+    invoicing?: InvoicingAdapter | null;
     features?: ShopFeatures;
     rateLimit?: ShopRateLimit;
     consents?: ConsentConfig[];
@@ -306,11 +371,12 @@ export interface ShopConfig {
      */
     variantExpiry?: VariantExpiryConfig;
 }
-export interface ResolvedShopConfig extends Omit<ShopConfig, 'variantLabel' | 'variantExpiry'> {
+export interface ResolvedShopConfig extends Omit<ShopConfig, 'variantLabel' | 'variantExpiry' | 'invoicing'> {
     features: Required<ShopFeatures>;
     rateLimit: Required<ShopRateLimit>;
     carriers: CarrierAdapter[];
     consents: ConsentConfig[];
+    invoicing: InvoicingAdapter | null;
     orderViewUrl: string;
     variantAttributes: Record<string, VariantAttribute>;
     variantLabel: VariantLabelConfig | null;

package/dist/updates/0.28.0/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.28.0/index.js

@@ -0,0 +1,38 @@
+export const update = {
+    version: '0.28.0',
+    date: '2026-06-01',
+    description: 'Fakturowanie — integracja sklepu z Fakturownią: automatyczne wystawianie i wysyłka faktury po opłaceniu zamówienia. Nowy generyczny `InvoicingAdapter` (spójny z payment/carrier) + `fakturowniaAdapter()` jako pierwsza implementacja. Faktura wystawiana fire-and-forget gdy zamówienie jest w pełni opłacone (`!balanceOwed` — zaliczki czekają na dopłatę balansu), wysyłana przez Fakturownię (`send_by_email`). Trigger konfigurowalny per-adapter (`issueWhen`: `b2bAndOnRequest` domyślnie / `always`). Checkout zbiera dane B2B (NIP z twardą walidacją sumy kontrolnej, nazwa firmy, adres do faktury, opt-in „chcę fakturę"). Idempotencja przez `shop_invoices` (unikat per zamówienie); ręczny retry w adminie. Additive only — żadnych breaking zmian.',
+    features: [
+        '`defineShop({ invoicing })` (`includio-cms/shop`) — nowy opcjonalny slot adaptera fakturowania, analogiczny do `payment` / `carriers`. `InvoicingAdapter { id, issueWhen?, createInvoice(payload, ctx), send?(externalId, ctx) }` + typy payloadu (`InvoicePayload`, `InvoiceBuyer`, `InvoiceLineItem`, `InvoiceCreateResult`, `InvoiceContext`, `InvoiceIssuePolicy`) wyeksportowane jako `@public` z `includio-cms/shop`.',
+        '`fakturowniaAdapter({ domain, apiToken, kind?, issueWhen?, sendEmail? })` (`includio-cms/shop`, `@public`) — adapter dla Fakturowni (fakturownia.pl). `createInvoice` mapuje zamówienie na fakturę VAT oznaczoną jako opłacona (`paid_date` = data potwierdzenia płatności), `send` woła `send_by_email` (domyślnie włączone). Numeracja i dane sprzedawcy zarządzane po stronie konta Fakturowni. Sekret `apiToken` przekazywany przez konsumenta z `$env/dynamic/private` (jak `STRIPE_SECRET_KEY`).',
+        'Auto-faktura po opłaceniu — `maybeIssueInvoiceForOrder(orderId)` (`$lib/shop/server/invoices.ts`) wołane fire-and-forget z `updateOrderStatus` (przy `paid`) oraz z `markBalancePaid` (po dopłacie balansu). Fail-open: błąd providera nie blokuje webhooka płatności. Guard wystawia fakturę tylko gdy zamówienie w pełni opłacone (`status ∈ {paid, preparing, sent, done}` && `!balanceOwed`) — deposit czeka na dopłatę.',
+        'Konfigurowalny trigger `issueWhen`: `b2bAndOnRequest` (domyślny — faktura gdy podano NIP lub zaznaczono „chcę fakturę") albo `always` (każde opłacone zamówienie, np. dla klienta wymagającego faktur również dla osób fizycznych).',
+        '`shop_invoices` (nowa tabela) — jedna faktura per zamówienie (`order_id` UNIQUE → idempotencja). Pola `status` (`pending`/`issued`/`sent`/`failed`), `external_id`, `number`, `pdf_url`, `attempts`, `next_retry_at`, `last_error`, `raw`. Kolumny `attempts`/`next_retry_at` zarezerwowane pod przyszły automatyczny retry (obecnie tylko ręczny).',
+        'Checkout B2B — `shop_orders` dostaje kolumny `customer_nip`, `customer_company_name`, `billing_address` (jsonb), `invoice_requested` (boolean). `createOrderFromCart` / `checkout-handler` przyjmują i zapisują te pola; `CheckoutInput` (`includio-cms/shop/client`) rozszerzony. Storefront form (pola NIP/firma/checkbox/adres) = warstwa konsumenta.',
+        '`isValidNip(nip)` (`includio-cms/shop`, `@public`) — twarda walidacja polskiego NIP (10 cyfr + suma kontrolna, wagi `[6,5,7,2,3,4,5,6,7]`). Checkout odrzuca nieprawidłowy NIP (400) zanim trafi do bazy — Fakturownia odrzuciłaby błędny NIP, a faktura idzie dalej do KSeF, więc walidujemy u źródła.',
+        '`getOrderInvoiceAdmin` (query) + `issueInvoiceCmd` (command) — admin remote functions (`includio-cms/admin/remote`). `shop-order-detail-page.svelte` zyskuje sekcję „Faktura": numer, link do PDF, status, przycisk „Wystaw fakturę" / „Wystaw ponownie" (ręczny retry, `force`). Auth-protected (`requireAuth`).'
+    ],
+    fixes: [],
+    breakingChanges: [],
+    sql: `CREATE TABLE IF NOT EXISTS shop_invoices (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id uuid NOT NULL UNIQUE REFERENCES shop_orders(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  external_id text,
+  number text,
+  pdf_url text,
+  kind text NOT NULL DEFAULT 'vat',
+  status text NOT NULL DEFAULT 'pending',
+  attempts integer NOT NULL DEFAULT 0,
+  next_retry_at timestamptz,
+  last_error text,
+  raw jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS customer_nip text;
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS customer_company_name text;
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS billing_address jsonb;
+ALTER TABLE shop_orders ADD COLUMN IF NOT EXISTS invoice_requested boolean NOT NULL DEFAULT false;`
+};

package/dist/updates/index.js

@@ -62,6 +62,7 @@ import { update as update0250 } from './0.25.0/index.js';
 import { update as update0260 } from './0.26.0/index.js';
 import { update as update0261 } from './0.26.1/index.js';
 import { update as update0270 } from './0.27.0/index.js';
+import { update as update0280 } from './0.28.0/index.js';
 export const updates = [
     update0065,
     update0066,
@@ -126,7 +127,8 @@ export const updates = [
     update0250,
     update0260,
     update0261,
-    update0270
+    update0270,
+    update0280
 ];
 export const getUpdatesFrom = (fromVersion) => {
     const fromParts = fromVersion.split('.').map(Number);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "includio-cms",
-	"version": "0.27.0",
+	"version": "0.28.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",