includio-cms 0.24.0 → 0.25.0

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

@@ -0,0 +1,169 @@
+import { requireShopConfig } from '../../server/db.js';
+import { getOrderById } from '../../server/orders.js';
+import { buildOrderViewUrl } from '../../server/order-access-url.js';
+import { buildStripeCheckoutPayload } from './payload.js';
+import { mapStripeEventType, mapStripeSessionStatus } from './status-map.js';
+const DEFAULT_LABEL = { pl: 'Karta płatnicza (Stripe)', en: 'Card payment (Stripe)' };
+const DEFAULT_PRODUCT_NAME = { pl: 'Zamówienie {number}', en: 'Order {number}' };
+const DEFAULT_API_VERSION = '2024-11-20.acacia';
+function pickI18n(text, language, fallback = 'pl') {
+    if (language && text[language])
+        return text[language];
+    return text[fallback] ?? Object.values(text)[0] ?? '';
+}
+/**
+ * Stripe payment adapter (Checkout Session flow).
+ *
+ * `stripe` is an **optional peer dependency** — install it in your project
+ * (`pnpm add stripe`) when using this adapter. The SDK is lazy-loaded on first
+ * `createPayment()` / `getStatus()` / `refund()` / `handleWebhook()` call;
+ * a missing peer throws a clear error.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { stripeAdapter } from 'includio-cms/shop';
+ *
+ * const stripe = stripeAdapter({
+ *   secretKey: process.env.STRIPE_SECRET_KEY!,
+ *   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+ *   successUrl: 'https://example.com/shop/order/{orderNumber}?token={accessToken}',
+ *   cancelUrl: 'https://example.com/shop/cancelled'
+ * });
+ * ```
+ */
+export function stripeAdapter(opts) {
+    const id = opts.id ?? 'stripe';
+    const apiVersion = opts.apiVersion ?? DEFAULT_API_VERSION;
+    let cachedClient = null;
+    let cachedStripeNs = null;
+    async function loadStripeNs() {
+        if (cachedStripeNs)
+            return cachedStripeNs;
+        const importer = opts.stripeImport ?? (() => import('stripe'));
+        try {
+            cachedStripeNs = await importer();
+        }
+        catch {
+            throw new Error('stripe SDK is required for stripeAdapter — install it with `pnpm add stripe`');
+        }
+        return cachedStripeNs;
+    }
+    async function getClient() {
+        if (cachedClient)
+            return cachedClient;
+        const ns = await loadStripeNs();
+        const Ctor = ns.default;
+        cachedClient = new Ctor(opts.secretKey, {
+            apiVersion: apiVersion
+        });
+        return cachedClient;
+    }
+    return {
+        id,
+        label: opts.label ?? DEFAULT_LABEL,
+        async createPayment(order, ctx) {
+            const shop = requireShopConfig();
+            const successTemplate = opts.successUrl ?? shop.orderViewUrl;
+            const cancelTemplate = opts.cancelUrl ?? successTemplate;
+            if (!/^https?:\/\//i.test(successTemplate)) {
+                throw new Error('stripeAdapter: successUrl (or shop.orderViewUrl) must be an absolute URL.');
+            }
+            if (!/^https?:\/\//i.test(cancelTemplate)) {
+                throw new Error('stripeAdapter: cancelUrl must be an absolute URL.');
+            }
+            const full = await getOrderById(order.id);
+            const language = ctx?.language ?? full?.language ?? null;
+            const successUrl = buildOrderViewUrl(successTemplate, {
+                orderNumber: order.number,
+                orderId: order.id,
+                accessToken: full?.accessToken ?? '',
+                language
+            });
+            const cancelUrl = buildOrderViewUrl(cancelTemplate, {
+                orderNumber: order.number,
+                orderId: order.id,
+                accessToken: full?.accessToken ?? '',
+                language
+            });
+            const productNameTpl = pickI18n(opts.productName ?? DEFAULT_PRODUCT_NAME, language);
+            const productName = productNameTpl.replace('{number}', order.number);
+            const payload = buildStripeCheckoutPayload({
+                order,
+                successUrl,
+                cancelUrl,
+                productName,
+                language
+            });
+            const client = await getClient();
+            const session = await client.checkout.sessions.create(payload);
+            if (!session.url) {
+                throw new Error('Stripe Checkout Session created without redirect URL.');
+            }
+            return {
+                status: 'redirect',
+                redirectUrl: session.url,
+                providerRef: session.id
+            };
+        },
+        async getStatus(providerRef) {
+            const client = await getClient();
+            const session = await client.checkout.sessions.retrieve(providerRef);
+            const orderNumber = session.metadata?.orderNumber ?? session.client_reference_id ?? '';
+            return {
+                orderNumber,
+                status: mapStripeSessionStatus(session.status, session.payment_status),
+                providerRef: session.id,
+                raw: session
+            };
+        },
+        async handleWebhook(req) {
+            const rawBody = await req.text();
+            const signature = req.headers.get('stripe-signature');
+            if (!signature)
+                throw new Error('Stripe webhook missing Stripe-Signature header');
+            const ns = await loadStripeNs();
+            const client = await getClient();
+            let event;
+            try {
+                event = client.webhooks.constructEvent(rawBody, signature, opts.webhookSecret);
+            }
+            catch (err) {
+                throw new Error(`Stripe webhook signature verification failed: ${err.message}`);
+            }
+            void ns; // satisfy unused warning when stripeImport mocks `default`
+            const session = event.data?.object ?? null;
+            const orderNumber = session?.metadata?.orderNumber ?? session?.client_reference_id ?? '';
+            const mapped = mapStripeEventType(event.type, session?.status ?? null, session?.payment_status ?? null);
+            return {
+                orderNumber,
+                status: mapped ?? 'pending',
+                providerRef: session?.id ?? event.id,
+                raw: event,
+                eventId: event.id,
+                eventType: event.type
+            };
+        },
+        async refund(input) {
+            const client = await getClient();
+            // providerRef is the Checkout Session id; resolve to PaymentIntent for refund.
+            const session = await client.checkout.sessions.retrieve(input.providerRef);
+            const paymentIntent = typeof session.payment_intent === 'string'
+                ? session.payment_intent
+                : (session.payment_intent?.id ?? null);
+            if (!paymentIntent) {
+                throw new Error(`Stripe refund: no payment_intent attached to session ${input.providerRef}`);
+            }
+            const refund = await client.refunds.create({
+                payment_intent: paymentIntent,
+                ...(input.amount !== undefined ? { amount: input.amount } : {}),
+                ...(input.reason ? { metadata: { reason: input.reason } } : {})
+            });
+            return {
+                providerRef: refund.id,
+                amount: typeof refund.amount === 'number' ? refund.amount : (input.amount ?? 0),
+                raw: refund
+            };
+        }
+    };
+}

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

@@ -0,0 +1,38 @@
+import type { OrderRef } from '../../types.js';
+export interface StripeCheckoutPayload {
+    mode: 'payment';
+    line_items: Array<{
+        price_data: {
+            currency: string;
+            product_data: {
+                name: string;
+            };
+            unit_amount: number;
+        };
+        quantity: number;
+    }>;
+    success_url: string;
+    cancel_url: string;
+    customer_email?: string;
+    client_reference_id: string;
+    metadata: Record<string, string>;
+    payment_intent_data?: {
+        metadata: Record<string, string>;
+    };
+    locale?: string;
+}
+export declare function normalizeStripeLocale(input: string | null | undefined): string | undefined;
+export interface BuildStripeCheckoutPayloadInput {
+    order: OrderRef;
+    successUrl: string;
+    cancelUrl: string;
+    productName: string;
+    language?: string | null;
+    metadata?: Record<string, string>;
+}
+/**
+ * Build a Checkout Session create payload representing the order as a single
+ * line item (full gross). We intentionally do NOT itemise — the order snapshot
+ * already lives in our DB; Stripe's job is collect payment for `totalGross`.
+ */
+export declare function buildStripeCheckoutPayload(input: BuildStripeCheckoutPayloadInput): StripeCheckoutPayload;

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

@@ -0,0 +1,90 @@
+// All entries lowercase; we normalize input to lowercase before lookup.
+const STRIPE_LOCALES = new Set([
+    'auto',
+    'bg',
+    'cs',
+    'da',
+    'de',
+    'el',
+    'en',
+    'en-gb',
+    'es',
+    'es-419',
+    'et',
+    'fi',
+    'fil',
+    'fr',
+    'fr-ca',
+    'hr',
+    'hu',
+    'id',
+    'it',
+    'ja',
+    'ko',
+    'lt',
+    'lv',
+    'ms',
+    'mt',
+    'nb',
+    'nl',
+    'pl',
+    'pt',
+    'pt-br',
+    'ro',
+    'ru',
+    'sk',
+    'sl',
+    'sv',
+    'th',
+    'tr',
+    'vi',
+    'zh',
+    'zh-hk',
+    'zh-tw'
+]);
+export function normalizeStripeLocale(input) {
+    if (!input)
+        return undefined;
+    const lower = input.toLowerCase();
+    if (STRIPE_LOCALES.has(lower))
+        return lower;
+    const root = lower.split('-')[0];
+    if (STRIPE_LOCALES.has(root))
+        return root;
+    return undefined;
+}
+/**
+ * Build a Checkout Session create payload representing the order as a single
+ * line item (full gross). We intentionally do NOT itemise — the order snapshot
+ * already lives in our DB; Stripe's job is collect payment for `totalGross`.
+ */
+export function buildStripeCheckoutPayload(input) {
+    const metadata = {
+        orderNumber: input.order.number,
+        orderId: input.order.id,
+        ...input.metadata
+    };
+    const payload = {
+        mode: 'payment',
+        line_items: [
+            {
+                price_data: {
+                    currency: input.order.currency.toLowerCase(),
+                    product_data: { name: input.productName },
+                    unit_amount: input.order.totalGross
+                },
+                quantity: 1
+            }
+        ],
+        success_url: input.successUrl,
+        cancel_url: input.cancelUrl,
+        customer_email: input.order.customerEmail,
+        client_reference_id: input.order.number,
+        metadata,
+        payment_intent_data: { metadata }
+    };
+    const locale = normalizeStripeLocale(input.language);
+    if (locale)
+        payload.locale = locale;
+    return payload;
+}

package/dist/shop/adapters/stripe/status-map.d.ts

@@ -0,0 +1,11 @@
+import type { PaymentEvent } from '../../types.js';
+/**
+ * Map a Stripe Checkout Session payment_status (paid / unpaid / no_payment_required)
+ * combined with session.status (open / complete / expired) into our PaymentEvent.status.
+ */
+export declare function mapStripeSessionStatus(sessionStatus: string | null | undefined, paymentStatus: string | null | undefined): PaymentEvent['status'];
+/**
+ * Map a Stripe webhook event type to a PaymentEvent.status.
+ * Returns null when the event is not relevant to order status (e.g. fulfilment-only).
+ */
+export declare function mapStripeEventType(eventType: string, sessionStatus: string | null | undefined, paymentStatus: string | null | undefined): PaymentEvent['status'] | null;

package/dist/shop/adapters/stripe/status-map.js

@@ -0,0 +1,31 @@
+/**
+ * Map a Stripe Checkout Session payment_status (paid / unpaid / no_payment_required)
+ * combined with session.status (open / complete / expired) into our PaymentEvent.status.
+ */
+export function mapStripeSessionStatus(sessionStatus, paymentStatus) {
+    if (sessionStatus === 'expired')
+        return 'paymentRejected';
+    if (sessionStatus === 'complete') {
+        if (paymentStatus === 'paid' || paymentStatus === 'no_payment_required')
+            return 'paid';
+        // async pending (e.g. SEPA) — keep order in pending until follow-up event
+        return 'pending';
+    }
+    return 'pending';
+}
+/**
+ * Map a Stripe webhook event type to a PaymentEvent.status.
+ * Returns null when the event is not relevant to order status (e.g. fulfilment-only).
+ */
+export function mapStripeEventType(eventType, sessionStatus, paymentStatus) {
+    switch (eventType) {
+        case 'checkout.session.completed':
+        case 'checkout.session.async_payment_succeeded':
+            return mapStripeSessionStatus(sessionStatus, paymentStatus);
+        case 'checkout.session.expired':
+        case 'checkout.session.async_payment_failed':
+            return 'paymentRejected';
+        default:
+            return null;
+    }
+}

package/dist/shop/cart/coupon-cookie.d.ts

@@ -0,0 +1,7 @@
+import type { CartCookies } from './types.js';
+export declare const COUPON_COOKIE_NAME = "aria_shop_coupon";
+export declare function normalizeCouponCode(input: string): string;
+export declare function isValidCouponCode(code: string): boolean;
+export declare function readCouponCookie(cookies: CartCookies): string | null;
+export declare function writeCouponCookie(cookies: CartCookies, code: string): void;
+export declare function clearCouponCookie(cookies: CartCookies): void;

package/dist/shop/cart/coupon-cookie.js

@@ -0,0 +1,32 @@
+export const COUPON_COOKIE_NAME = 'aria_shop_coupon';
+const MAX_AGE_SECONDS = 60 * 60 * 24 * 7; // 7 days — shorter than cart TTL by design
+const MAX_LEN = 64;
+const VALID = /^[A-Z0-9_-]{1,64}$/;
+export function normalizeCouponCode(input) {
+    return input.trim().toUpperCase();
+}
+export function isValidCouponCode(code) {
+    return code.length > 0 && code.length <= MAX_LEN && VALID.test(code);
+}
+export function readCouponCookie(cookies) {
+    const raw = cookies.get(COUPON_COOKIE_NAME);
+    if (!raw)
+        return null;
+    const code = normalizeCouponCode(raw);
+    return isValidCouponCode(code) ? code : null;
+}
+export function writeCouponCookie(cookies, code) {
+    const normalized = normalizeCouponCode(code);
+    if (!isValidCouponCode(normalized))
+        return;
+    cookies.set(COUPON_COOKIE_NAME, normalized, {
+        path: '/',
+        maxAge: MAX_AGE_SECONDS,
+        httpOnly: false,
+        sameSite: 'lax',
+        secure: false
+    });
+}
+export function clearCouponCookie(cookies) {
+    cookies.delete(COUPON_COOKIE_NAME, { path: '/' });
+}

package/dist/shop/cart/types.d.ts

@@ -19,13 +19,25 @@ export interface CartLine extends CartItemRef {
     available: boolean;
     issue?: 'not-found' | 'inactive' | 'out-of-stock' | 'qty-adjusted';
 }
+export interface AppliedCoupon {
+    code: string;
+    type: 'percent' | 'fixed';
+    value: number;
+    discountNet: number;
+    discountGross: number;
+}
 export interface CartSnapshot {
     items: CartLine[];
     itemCount: number;
+    /** Subtotal before coupon (sum of lines). When no coupon, equals totalNet. */
+    subtotalNet: number;
+    subtotalGross: number;
+    subtotalVat: number;
     totalNet: number;
     totalGross: number;
     totalVat: number;
     currency: Currency;
+    coupon?: AppliedCoupon;
 }
 export interface CartCookies {
     get(name: string): string | undefined;

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

@@ -1,7 +1,22 @@
 import type { CartSnapshot } from '../cart/types.js';
 import type { OrderStatus } from '../types.js';
+/**
+ * Options for `createShopClient()`.
+ *
+ * @public
+ */
 export interface ShopClientOptions {
+    /**
+     * Base URL for the shop REST API. Empty string (default) means same-origin —
+     * paths like `/api/shop/cart` resolve relative to the current document.
+     * Provide an absolute URL when calling from a different origin (e.g. a
+     * mobile app or static site hitting your CMS over HTTPS).
+     */
     baseUrl?: string;
+    /**
+     * Custom `fetch` implementation. Defaults to `globalThis.fetch`. Override
+     * to inject auth headers, request logging, or to use `node-fetch` in tests.
+     */
     fetch?: typeof fetch;
 }
 export interface ShippingMethodPublic {
@@ -99,28 +114,131 @@ export interface RetryPaymentResult {
     requiresPaymentRedirect: boolean;
     redirectUrl: string | null;
 }
+/**
+ * Headless shop SDK surface returned by `createShopClient()`.
+ *
+ * Every method maps 1:1 to a REST endpoint mounted by the shop HTTP handlers.
+ * The shape is stable across patch versions; new methods may be added under
+ * existing namespaces in minor releases.
+ *
+ * @public
+ */
 export interface ShopClient {
+    /** Cart operations — read state and mutate items / coupon. */
     cart: {
+        /**
+         * Get the current cart snapshot, including hydrated line totals,
+         * subtotal, and any applied coupon.
+         *
+         * @returns Server-authoritative cart snapshot.
+         */
         get(): Promise<CartSnapshot>;
+        /**
+         * Add `qty` units of a variant to the cart. Existing entries for the
+         * same `variantId` are merged (qty summed, capped at server max).
+         *
+         * @param variantId - The product variant id.
+         * @param qty - Quantity to add. Defaults to 1.
+         */
         add(variantId: string, qty?: number): Promise<CartSnapshot>;
+        /**
+         * Set the absolute quantity of an existing line. `qty <= 0` removes
+         * the line.
+         */
         update(variantId: string, qty: number): Promise<CartSnapshot>;
+        /** Remove a single variant from the cart. */
         remove(variantId: string): Promise<CartSnapshot>;
+        /** Empty the cart and drop any applied coupon. */
         clear(): Promise<CartSnapshot>;
+        /**
+         * Apply a coupon code to the current cart. Codes are case-insensitive
+         * and validated server-side (existence, expiry, max-uses, min-order).
+         * Throws on invalid codes — use a try/catch and surface the message.
+         *
+         * @param code - The coupon code (e.g. `"ARIA10"`).
+         */
+        applyCoupon(code: string): Promise<CartSnapshot>;
+        /** Remove the currently-applied coupon (if any). Always succeeds. */
+        removeCoupon(): Promise<CartSnapshot>;
     };
+    /** Shipping method discovery. */
     shipping: {
+        /**
+         * List all active shipping methods configured by the shop, with
+         * pricing and carrier metadata. Public — usable on the storefront.
+         */
         list(): Promise<{
             items: ShippingMethodPublic[];
         }>;
     };
+    /** Checkout flow — converts the cart into an order. */
     checkout: {
+        /**
+         * Submit the cart as an order. Validates consents, stock, coupons,
+         * carrier selection, and initiates the chosen payment adapter. Returns
+         * a redirect URL when the payment provider needs to take over (e.g.
+         * Stripe Checkout, PayU), or `paymentStatus: 'manual'` for manual
+         * methods (bank transfer).
+         */
         submit(input: CheckoutInput): Promise<CheckoutResult>;
     };
+    /** Order lookup + payment retry/refresh from the customer side. */
     orders: {
+        /**
+         * Fetch full order detail. Pass the customer's `accessToken` (returned
+         * from checkout) to bypass the same-browser cookie fallback.
+         */
         get(orderNumber: string, token?: string): Promise<OrderDetailResponse>;
+        /**
+         * Re-poll the payment provider for the latest status — useful when a
+         * webhook is lost or the customer returns from a redirect before the
+         * status webhook arrived.
+         */
         refreshPayment(orderNumber: string, token?: string): Promise<RefreshPaymentResult>;
+        /**
+         * Initiate a fresh payment attempt for an unpaid order — typical use
+         * is recovering from `paymentRejected` without making the customer
+         * re-fill the checkout form.
+         */
         retryPayment(orderNumber: string, token?: string): Promise<RetryPaymentResult>;
     };
 }
+/**
+ * Create a typed, isomorphic shop SDK client.
+ *
+ * The client is a thin REST wrapper — every call hits an HTTP endpoint
+ * mounted by the shop handlers (`createCartHandler`, `createCheckoutHandler`,
+ * etc.). Use it from SvelteKit pages, server endpoints, mobile apps, or any
+ * environment with a `fetch` implementation.
+ *
+ * Errors from the shop API are surfaced as `Error` with the server-provided
+ * `error` field as the message.
+ *
+ * @param options - Optional `baseUrl` (default same-origin) and custom `fetch`.
+ * @returns A `ShopClient` with `.cart`, `.shipping`, `.checkout`, `.orders`.
+ * @public
+ * @example
+ * ```ts
+ * import { createShopClient } from 'includio-cms/shop/client';
+ *
+ * const shop = createShopClient({ baseUrl: '' });
+ *
+ * await shop.cart.add(variantId);
+ * await shop.cart.applyCoupon('ARIA10');
+ * const cart = await shop.cart.get();
+ *
+ * const result = await shop.checkout.submit({
+ *   customerEmail: 'buyer@example.com',
+ *   shippingMethodId,
+ *   paymentMethod: 'stripe',
+ *   consents: [{ id: 'tos', accepted: true }]
+ * });
+ *
+ * if (result.requiresPaymentRedirect && result.redirectUrl) {
+ *   window.location.href = result.redirectUrl;
+ * }
+ * ```
+ */
 export declare function createShopClient(options?: ShopClientOptions): ShopClient;
 export type { CartSnapshot, CartLine, CartItemRef } from '../cart/types.js';
 export { createOrderState } from './use-order.svelte.js';

package/dist/shop/client/index.js

@@ -1,3 +1,39 @@
+/**
+ * Create a typed, isomorphic shop SDK client.
+ *
+ * The client is a thin REST wrapper — every call hits an HTTP endpoint
+ * mounted by the shop handlers (`createCartHandler`, `createCheckoutHandler`,
+ * etc.). Use it from SvelteKit pages, server endpoints, mobile apps, or any
+ * environment with a `fetch` implementation.
+ *
+ * Errors from the shop API are surfaced as `Error` with the server-provided
+ * `error` field as the message.
+ *
+ * @param options - Optional `baseUrl` (default same-origin) and custom `fetch`.
+ * @returns A `ShopClient` with `.cart`, `.shipping`, `.checkout`, `.orders`.
+ * @public
+ * @example
+ * ```ts
+ * import { createShopClient } from 'includio-cms/shop/client';
+ *
+ * const shop = createShopClient({ baseUrl: '' });
+ *
+ * await shop.cart.add(variantId);
+ * await shop.cart.applyCoupon('ARIA10');
+ * const cart = await shop.cart.get();
+ *
+ * const result = await shop.checkout.submit({
+ *   customerEmail: 'buyer@example.com',
+ *   shippingMethodId,
+ *   paymentMethod: 'stripe',
+ *   consents: [{ id: 'tos', accepted: true }]
+ * });
+ *
+ * if (result.requiresPaymentRedirect && result.redirectUrl) {
+ *   window.location.href = result.redirectUrl;
+ * }
+ * ```
+ */
 export function createShopClient(options = {}) {
     const base = (options.baseUrl ?? '').replace(/\/$/, '');
     const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
@@ -28,7 +64,9 @@ export function createShopClient(options = {}) {
             add: (variantId, qty = 1) => call('POST', '/api/shop/cart', { variantId, qty }),
             update: (variantId, qty) => call('PATCH', '/api/shop/cart', { variantId, qty }),
             remove: (variantId) => call('DELETE', `/api/shop/cart?variantId=${encodeURIComponent(variantId)}`),
-            clear: () => call('DELETE', '/api/shop/cart')
+            clear: () => call('DELETE', '/api/shop/cart'),
+            applyCoupon: (code) => call('POST', '/api/shop/cart/coupon', { code }),
+            removeCoupon: () => call('DELETE', '/api/shop/cart/coupon')
         },
         shipping: {
             list: () => call('GET', '/api/shop/shipping-methods')

package/dist/shop/http/cart-handler.d.ts

@@ -5,3 +5,11 @@ export declare function createCartHandler(): {
     PATCH: RequestHandler;
     DELETE: RequestHandler;
 };
+/**
+ * Cart coupon endpoints — POST applies a code, DELETE removes it.
+ * Mount at `/api/shop/cart/coupon`.
+ */
+export declare function createCartCouponHandler(): {
+    POST: RequestHandler;
+    DELETE: RequestHandler;
+};