includio-cms 0.27.0 → 0.28.0

package/dist/db-postgres/schema/shop/order.d.ts

@@ -124,6 +124,40 @@ export declare const shopOrdersTable: import("drizzle-orm/pg-core/table", { with
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        customerNip: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "customer_nip";
+            tableName: "shop_orders";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        customerCompanyName: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "customer_company_name";
+            tableName: "shop_orders";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         shippingAddress: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
             name: "shipping_address";
             tableName: "shop_orders";
@@ -143,6 +177,42 @@ export declare const shopOrdersTable: import("drizzle-orm/pg-core/table", { with
         }, {}, {
             $type: Record<string, string>;
         }>;
+        billingAddress: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "billing_address";
+            tableName: "shop_orders";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, string>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, string>;
+        }>;
+        invoiceRequested: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
+            name: "invoice_requested";
+            tableName: "shop_orders";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         totalNet: import("drizzle-orm/pg-core", { with: { "resolution-mode": "require" } }).PgColumn<{
             name: "total_net";
             tableName: "shop_orders";

package/dist/db-postgres/schema/shop/order.js

@@ -8,7 +8,11 @@ export const shopOrdersTable = pgTable('shop_orders', {
     customerEmail: text('customer_email').notNull(),
     customerName: text('customer_name'),
     customerPhone: text('customer_phone'),
+    customerNip: text('customer_nip'),
+    customerCompanyName: text('customer_company_name'),
     shippingAddress: jsonb('shipping_address').$type(),
+    billingAddress: jsonb('billing_address').$type(),
+    invoiceRequested: boolean('invoice_requested').default(false).notNull(),
     totalNet: integer('total_net').notNull(),
     totalGross: integer('total_gross').notNull(),
     vatAmount: integer('vat_amount').notNull(),

package/dist/shop/adapters/fakturownia/client.d.ts

@@ -0,0 +1,28 @@
+import type { FakturowniaInvoiceBody } from './payload.js';
+export interface FakturowniaClientOptions {
+    /** Account subdomain (`acme`) or full host/URL (`acme.fakturownia.pl`) — normalised either way. */
+    domain: string;
+    apiToken: string;
+    fetch?: typeof fetch;
+}
+export interface FakturowniaInvoice {
+    id: number | string;
+    number?: string;
+    view_url?: string;
+    [key: string]: unknown;
+}
+export declare class FakturowniaApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+export declare class FakturowniaClient {
+    private readonly base;
+    private readonly apiToken;
+    private readonly fetchFn;
+    constructor(opts: FakturowniaClientOptions);
+    createInvoice(invoice: FakturowniaInvoiceBody): Promise<FakturowniaInvoice>;
+    sendByEmail(id: number | string): Promise<void>;
+    private postRaw;
+    private post;
+}

package/dist/shop/adapters/fakturownia/client.js

@@ -0,0 +1,67 @@
+export class FakturowniaApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'FakturowniaApiError';
+    }
+}
+export class FakturowniaClient {
+    base;
+    apiToken;
+    fetchFn;
+    constructor(opts) {
+        if (!opts.domain)
+            throw new Error('FakturowniaClient: domain required.');
+        if (!opts.apiToken)
+            throw new Error('FakturowniaClient: apiToken required.');
+        // Accept a bare subdomain (`acme`) as well as a full host or URL
+        // (`acme.fakturownia.pl`, `https://acme.fakturownia.pl/`) — strip protocol,
+        // the `.fakturownia.pl` suffix and trailing slashes so we never double it.
+        const subdomain = opts.domain
+            .trim()
+            .replace(/^https?:\/\//i, '')
+            .replace(/\/+$/, '')
+            .replace(/\.fakturownia\.pl$/i, '');
+        this.base = `https://${subdomain}.fakturownia.pl`;
+        this.apiToken = opts.apiToken;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async createInvoice(invoice) {
+        return this.post('/invoices.json', {
+            api_token: this.apiToken,
+            invoice
+        });
+    }
+    async sendByEmail(id) {
+        await this.postRaw(`/invoices/${encodeURIComponent(String(id))}/send_by_email.json`, {
+            api_token: this.apiToken
+        });
+    }
+    async postRaw(path, payload) {
+        const res = await this.fetchFn(`${this.base}${path}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify(payload)
+        });
+        if (!res.ok) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                body = await res.text().catch(() => undefined);
+            }
+            const raw = body == null ? '' : typeof body === 'string' ? body : JSON.stringify(body);
+            const detail = raw ? `: ${raw.slice(0, 400)}` : '';
+            throw new FakturowniaApiError(`Fakturownia ${path} → ${res.status}${detail}`, res.status, body);
+        }
+        return res;
+    }
+    async post(path, payload) {
+        const res = await this.postRaw(path, payload);
+        return (await res.json());
+    }
+}

package/dist/shop/adapters/fakturownia/index.d.ts

@@ -0,0 +1,27 @@
+import type { InvoiceIssuePolicy, InvoicingAdapter } from '../../types.js';
+export interface FakturowniaAdapterOptions {
+    /** Account subdomain (`acme`) or full host (`acme.fakturownia.pl`). Required. */
+    domain: string;
+    /** Fakturownia API token. Required. Pass from `$env/dynamic/private`. */
+    apiToken: string;
+    /** Adapter id. Default `fakturownia`. */
+    id?: string;
+    /** Invoice kind sent to Fakturownia. Default `vat`. */
+    kind?: string;
+    /** Unit of measure per line — KSeF list: szt, godz, dni, mc, m2, kg. Default `szt`. */
+    unit?: string;
+    /** When to issue automatically. Default (server-side) `b2bAndOnRequest`. */
+    issueWhen?: InvoiceIssuePolicy;
+    /** E-mail the invoice to the buyer via Fakturownia. Default `true`. */
+    sendEmail?: boolean;
+    /** Override fetch — primarily for testing. */
+    fetch?: typeof fetch;
+}
+/**
+ * Invoicing adapter backed by Fakturownia (fakturownia.pl). Issues a paid VAT
+ * invoice from a fully-paid order and (by default) e-mails the PDF to the buyer
+ * provider-side. Seller data and numbering are managed in the Fakturownia
+ * account; the NIP is validated upstream at checkout.
+ * @public
+ */
+export declare function fakturowniaAdapter(opts: FakturowniaAdapterOptions): InvoicingAdapter;

package/dist/shop/adapters/fakturownia/index.js

@@ -0,0 +1,36 @@
+import { FakturowniaClient } from './client.js';
+import { buildFakturowniaInvoice } from './payload.js';
+/**
+ * Invoicing adapter backed by Fakturownia (fakturownia.pl). Issues a paid VAT
+ * invoice from a fully-paid order and (by default) e-mails the PDF to the buyer
+ * provider-side. Seller data and numbering are managed in the Fakturownia
+ * account; the NIP is validated upstream at checkout.
+ * @public
+ */
+export function fakturowniaAdapter(opts) {
+    const client = new FakturowniaClient({
+        domain: opts.domain,
+        apiToken: opts.apiToken,
+        fetch: opts.fetch
+    });
+    const adapter = {
+        id: opts.id ?? 'fakturownia',
+        issueWhen: opts.issueWhen,
+        async createInvoice(payload) {
+            const body = buildFakturowniaInvoice(payload, { kind: opts.kind, unit: opts.unit });
+            const inv = await client.createInvoice(body);
+            return {
+                externalId: String(inv.id),
+                number: inv.number,
+                pdfUrl: inv.view_url,
+                raw: inv
+            };
+        }
+    };
+    if (opts.sendEmail !== false) {
+        adapter.send = async (externalId, _ctx) => {
+            await client.sendByEmail(externalId);
+        };
+    }
+    return adapter;
+}

package/dist/shop/adapters/fakturownia/payload.d.ts

@@ -0,0 +1,35 @@
+import type { InvoicePayload } from '../../types.js';
+export interface FakturowniaPosition {
+    name: string;
+    quantity: number;
+    /** Total gross price of the line (unit × quantity) in the major unit (PLN). */
+    total_price_gross: number;
+    /** VAT rate as a plain percentage (e.g. 23). */
+    tax: number;
+    /** Unit of measure — KSeF requires one of: szt, godz, dni, mc, m2, kg. */
+    quantity_unit: string;
+}
+export interface FakturowniaInvoiceBody {
+    kind: string;
+    status: 'paid';
+    issue_date: string;
+    sell_date: string;
+    paid_date: string;
+    currency: string;
+    buyer_name: string;
+    buyer_email: string;
+    buyer_tax_no?: string;
+    buyer_street?: string;
+    buyer_city?: string;
+    buyer_post_code?: string;
+    buyer_country?: string;
+    positions: FakturowniaPosition[];
+}
+/**
+ * Map an {@link InvoicePayload} onto the Fakturownia `invoice` object. Pure —
+ * no network. The NIP is assumed already validated upstream (checkout).
+ */
+export declare function buildFakturowniaInvoice(payload: InvoicePayload, opts?: {
+    kind?: string;
+    unit?: string;
+}): FakturowniaInvoiceBody;

package/dist/shop/adapters/fakturownia/payload.js

@@ -0,0 +1,45 @@
+/** Minor units (grosze) → major units (PLN) with 2-decimal precision. */
+function toMajor(minor) {
+    return Math.round(minor) / 100;
+}
+function pick(addr, ...keys) {
+    if (!addr)
+        return undefined;
+    for (const k of keys) {
+        if (addr[k])
+            return addr[k];
+    }
+    return undefined;
+}
+/**
+ * Map an {@link InvoicePayload} onto the Fakturownia `invoice` object. Pure —
+ * no network. The NIP is assumed already validated upstream (checkout).
+ */
+export function buildFakturowniaInvoice(payload, opts = {}) {
+    const date = payload.paidAt.slice(0, 10);
+    const { buyer } = payload;
+    return {
+        kind: opts.kind ?? 'vat',
+        status: 'paid',
+        issue_date: date,
+        sell_date: date,
+        paid_date: date,
+        currency: payload.currency,
+        buyer_name: buyer.companyName || buyer.name,
+        buyer_email: buyer.email,
+        ...(buyer.nip ? { buyer_tax_no: buyer.nip } : {}),
+        ...(pick(buyer.address, 'street') ? { buyer_street: pick(buyer.address, 'street') } : {}),
+        ...(pick(buyer.address, 'city') ? { buyer_city: pick(buyer.address, 'city') } : {}),
+        ...(pick(buyer.address, 'postCode', 'zip', 'postalCode')
+            ? { buyer_post_code: pick(buyer.address, 'postCode', 'zip', 'postalCode') }
+            : {}),
+        ...(pick(buyer.address, 'country') ? { buyer_country: pick(buyer.address, 'country') } : {}),
+        positions: payload.items.map((item) => ({
+            name: item.name,
+            quantity: item.quantity,
+            total_price_gross: toMajor(item.unitPriceGross * item.quantity),
+            tax: item.vatRate,
+            quantity_unit: opts.unit ?? 'szt'
+        }))
+    };
+}

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

@@ -39,7 +39,14 @@ export interface CheckoutInput {
     customerEmail: string;
     customerName?: string;
     customerPhone?: string;
+    /** Optional tax id (NIP). Validated server-side; invalid → checkout 400. */
+    customerNip?: string;
+    customerCompanyName?: string;
     shippingAddress?: Record<string, string>;
+    /** Separate billing address for the invoice; falls back to shipping. */
+    billingAddress?: Record<string, string>;
+    /** B2C opt-in: request an invoice even without a NIP. */
+    invoiceRequested?: boolean;
     shippingMethodId: string;
     carrierRef?: string;
     paymentMethod: string;

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

@@ -8,6 +8,7 @@ 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;
@@ -66,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 });
@@ -98,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,

package/dist/shop/index.d.ts

@@ -9,5 +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, VariantAttribute, VariantAttributeText, VariantAttributeNumber, VariantAttributeDatetime, VariantAttributeSelect, VariantAttributeBoolean, VariantAttributeImage, VariantAttributeEntry, VariantAttributeSlug, VariantLabelConfig, VariantExpiryConfig, PaymentPolicy, DepositAmount, PartialPayment } 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,6 +12,7 @@ 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}',
         variantAttributes: config.variantAttributes ?? {},
@@ -25,4 +26,6 @@ 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/invoices.d.ts

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