includio-cms 0.24.0 → 0.25.0

package/dist/shop/types.d.ts

@@ -1,6 +1,6 @@
 import type { Language } from '../types/languages.js';
 export type Currency = 'PLN';
-export type OrderStatus = 'new' | 'awaitingPayment' | 'paid' | 'preparing' | 'sent' | 'done' | 'cancelled' | 'paymentRejected';
+export type OrderStatus = 'new' | 'awaitingPayment' | 'paid' | 'preparing' | 'sent' | 'done' | 'cancelled' | 'paymentRejected' | 'refunded';
 export type I18nText = {
     [lang: string]: string;
 };
@@ -8,6 +8,7 @@ export interface ShopFeatures {
     variants?: boolean;
     stock?: boolean;
     accounts?: boolean;
+    coupons?: boolean;
 }
 export interface RateLimitRule {
     limit: number;
@@ -37,6 +38,27 @@ export interface PaymentAdapter {
      * returned as `PaymentCreateResult.providerRef`.
      */
     getStatus?(providerRef: string): Promise<PaymentEvent>;
+    /**
+     * Refund a captured payment. Optional — adapters that omit this method are
+     * treated as "refund not supported" by `refundOrder()`. `amount` is the
+     * gross amount in minor currency units (e.g. grosze for PLN); when omitted
+     * the adapter MUST refund the full remaining captured amount.
+     *
+     * Throws on provider error. The server records pending refund row before
+     * calling, transitions to `succeeded` on resolve or `failed` on reject.
+     */
+    refund?(input: PaymentRefundInput): Promise<PaymentRefundResult>;
+}
+export interface PaymentRefundInput {
+    providerRef: string;
+    amount?: number;
+    currency: Currency;
+    reason?: string;
+}
+export interface PaymentRefundResult {
+    providerRef: string;
+    amount: number;
+    raw?: unknown;
 }
 export interface CarrierAdapter {
     id: string;
@@ -111,6 +133,19 @@ export interface PaymentEvent {
     status: 'paid' | 'paymentRejected' | 'pending';
     providerRef: string;
     raw: unknown;
+    /**
+     * Provider-assigned event id used for webhook idempotency. Stripe `event.id`,
+     * PayU `notify_id` (header), InPost message id. When omitted, the handler
+     * falls back to terminal-status idempotency only (replay-safety best-effort).
+     */
+    eventId?: string;
+    eventType?: string;
+}
+export interface CouponRef {
+    code: string;
+    type: 'percent' | 'fixed';
+    value: number;
+    discountAmount: number;
 }
 export interface ShopConfig {
     currency: Currency;
@@ -128,6 +163,11 @@ export interface ShopConfig {
      * Default when omitted: `/shop/order/{orderNumber}?token={accessToken}`.
      */
     orderViewUrl?: string;
+    /**
+     * Admin notification email address. Used by low-stock alerts and other
+     * automatic admin notifications. Omitted = those alerts are no-ops.
+     */
+    adminEmail?: string;
 }
 export interface ResolvedShopConfig extends ShopConfig {
     features: Required<ShopFeatures>;

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

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

package/dist/updates/0.25.0/index.js

@@ -0,0 +1,89 @@
+export const update = {
+    version: '0.25.0',
+    date: '2026-05-06',
+    description: 'Faza 11.5 — Shop polish. Stripe payment adapter (Checkout Session flow z native webhook signature verify), refund infrastructure (full + partial, cross-adapter Stripe + PayU), webhook idempotency table (`shop_webhook_events` z UNIQUE(provider, event_id)), coupons (% / fixed PLN, expiresAt, maxUses, minOrderAmount, OCC race-safe redemption), low-stock email alert (per-product `lowStockThreshold`), order export CSV w admin, default email templates rozszerzone o `refunded` status, SDK `applyCoupon`/`removeCoupon` + JSDoc body + `@public` tagi, pełna dokumentacja shopa (DOCS.md + adapter guides + cURL examples + Stripe/Coupons/Refund pages). Shop = `@public` w v1.0.',
+    features: [
+        '`stripeAdapter()` — Stripe Checkout Session flow. `createPayment()` → `stripe.checkout.sessions.create` (zwraca redirect URL); `handleWebhook()` → natywny `stripe.webhooks.constructEvent` (sig + timestamp skew); `getStatus()` → `checkout.sessions.retrieve` poll fallback dla lost webhooks; `refund()` → resolve session → payment_intent → `stripe.refunds.create({ amount? })`. Stripe SDK = optional peer (lazy import + caching). Status mapping: `complete + paid → paid`, `expired → paymentRejected`. Eksport: `stripeAdapter`, `StripeAdapterOptions`.',
+        '**Refund infrastructure** (cross-adapter, full + partial). `PaymentAdapter.refund?(input)` opcjonalna metoda interfejsu (`PaymentRefundInput` / `PaymentRefundResult`). Server: `refundOrder({ orderId, amount?, reason?, createdBy })` w `src/lib/shop/server/refund.ts` — walidacja eligibility (status `paid|preparing|sent|done`, `paymentProviderRef`, adapter wsparcie, `amount <= remaining`), insert pending row, call adapter, update do `succeeded`/`failed`, full refund → `updateOrderStatus(refunded)`. PayU `client.refundOrder()` + `payuAdapter().refund()`. Stripe refund built-in. DB: nowa tabela `shop_refunds` (orderId FK, paymentId FK?, provider, providerRef, amount cents, currency, reason, status, createdBy, createdAt). `getRefundedAmount()` + `listRefunds()` helpers.',
+        '**Webhook idempotency table** (`shop_webhook_events`). UNIQUE(provider, event_id) — duplikaty short-circuit z 200 + `replay: true` przed mutacją state. PayU `notify_id` (lub fallback `${orderId}:${status}`), Stripe natywny `event.id`. `reserveWebhookEvent()` + `markWebhookEventProcessed()` w `src/lib/shop/http/webhook-idempotency.ts`. Stara terminal-status check zachowana jako fallback dla adapterów bez `eventId`.',
+        '**Coupons** — code-based discounts. DB: `shop_coupons` (code UNIQUE uppercase, type `percent|fixed`, value numeric 20,6, minOrderAmount cents, maxUses, usedCount, expiresAt, isActive) + `shop_coupon_redemptions` (couponId FK, orderId FK UNIQUE, discountAmount, redeemedAt). Server: `validateCoupon()` (feature flag + lookup + isActive + expiresAt + maxUses + minOrderAmount), `reserveCouponSlot()` z OCC `WHERE max_uses IS NULL OR used_count < max_uses`, `recordCouponRedemption()` `onConflictDoNothing(orderId)`, `releaseCouponSlot()`. Pricing: discount przed VAT, uniform per-line factor (`calculateCouponDiscountNet()` + line-level factor w `cart-hydrate`). REST: `POST/DELETE /api/shop/cart/coupon` (`createCartCouponHandler()`), separate cookie `aria_shop_coupon` (7d TTL, `[A-Z0-9_-]{1,64}`). SDK: `cart.applyCoupon(code)` / `cart.removeCoupon()`. Admin UI: lista kodów + new/edit form, walidacja kodu (uppercase, alfanumeryczny). Feature flag: `defineShop({ features: { coupons: true } })`.',
+        '**Low-stock email alert.** Per-produkt `lowStockThreshold: int?` w `shop_products`. Hook po `updateOrderStatus(paid)` decrement: jeśli `stock <= threshold` AND `stock + qty > threshold` (boundary cross), `sendLowStockEmail()` (PL) → `shop.adminEmail`. Brak `adminEmail` lub brak email adaptera = no-op.',
+        '**Order export CSV** (admin). `exportOrdersCsv(filters)` query w `shop.remote.ts` — RFC 4180 escape (commas, quotes, newlines), BOM dla Excel UTF-8. Button "Eksport CSV" na orders list page (honors current `status` + `email` filters). Kolumny: number, status, customerEmail, customerName, totalGross, currency, shippingGross, paymentMethod, createdAt.',
+        '**Default email templates** — `OrderStatus` += `refunded` (terminal w webhook-logic, propagacja: `STATUS_SUBJECTS`/`STATUS_INTRO` PL/EN, customer-facing labels, admin Zod schema, admin detail page styles). Plus low-stock template dla admina.',
+        '**SDK polish** — `createShopClient()` + `ShopClient` + `ShopClientOptions` z pełnym JSDoc body (description + @param + @returns + @example). Per-method docs dla `cart.{get,add,update,remove,clear,applyCoupon,removeCoupon}`, `shipping.list`, `checkout.submit`, `orders.{get,refreshPayment,retryPayment}`. Wszystkie eksporty `@public`.',
+        '**Dokumentacja** — pełna sekcja Shop w `DOCS.md` (overview rozszerzony o Coupons/Refunds/Stripe/Low-stock/CSV export, sekcja "cURL examples" + "Error codes"), 5 nowych stron: `/docs/shop/{stripe,coupons,refund,payment-adapter,carrier-adapter}`. `payment-adapter` guide pokazuje pełen interfejs + lazy peer pattern + signature verify + idempotency via eventId + lost-webhook recovery + refund. Update `nav.ts`.',
+        '**Admin UI**. Order detail: sidebar "Zwroty" (lista refund rows + aggregate refunded/remaining + `RefundDialog` modal z full/partial mode + reason). Orders list: "Eksport CSV" button. Coupons CRUD: `/admin/shop/coupons` lista + `/new` + `/[id]` edit (validacja code uppercase + alfanumeryczny). Nav-shop link. Refunded status w STATUS_STYLES.'
+    ],
+    fixes: [],
+    breakingChanges: [
+        '`OrderStatus` typ rozszerzony o `"refunded"` (terminal status). Custom UI/email logic używające `Record<OrderStatus, …>` musi dodać entry. Zaktualizowane in-tree: email templates, `svelte/labels.ts` `DEFAULT_LABELS_PL`, admin detail page, admin Zod schema, webhook-logic terminal set.',
+        '`PaymentAdapter` interface += optional `refund?(input)` method i optional `eventId?` / `eventType?` fields w `PaymentEvent`. Custom adaptery działają bez zmian (`refund` opcjonalne; brak `eventId` skutkuje fallback do terminal-status idempotency).',
+        '`CartSnapshot` rozszerzony o `subtotalNet`/`subtotalGross`/`subtotalVat` + opcjonalny `coupon: AppliedCoupon`. `totalNet`/`totalGross` teraz reprezentują wartość PO odjęciu discountu. Storefronty czytające tylko `total*` działają bez zmian dla cartów bez coupons; kod renderujący detal pre-discount musi czytać `subtotal*`.',
+        '`ShopFeatures` += opcjonalny `coupons?: boolean` (default `false`). `ShopConfig` += opcjonalny `adminEmail?: string` (default brak — low-stock alert no-op). Backward compatible defaults.'
+    ],
+    sql: `-- 0.25.0 — Shop polish DB additions
+-- Run via drizzle-kit push or apply manually before deploying 0.25.0.
+
+-- Refunds — one row per refund attempt (succeeded / pending / failed)
+CREATE TABLE IF NOT EXISTS shop_refunds (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id uuid NOT NULL REFERENCES shop_orders(id) ON DELETE CASCADE,
+  payment_id uuid REFERENCES shop_payments(id) ON DELETE SET NULL,
+  provider text NOT NULL,
+  provider_ref text,
+  amount integer NOT NULL,
+  currency text NOT NULL,
+  reason text,
+  status text NOT NULL DEFAULT 'pending',
+  created_by text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Webhook idempotency log — UNIQUE(provider, event_id) prevents replay
+CREATE TABLE IF NOT EXISTS shop_webhook_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  provider text NOT NULL,
+  event_id text NOT NULL,
+  event_type text,
+  order_id uuid REFERENCES shop_orders(id) ON DELETE SET NULL,
+  order_number text,
+  payload_hash text,
+  raw jsonb,
+  received_at timestamptz NOT NULL DEFAULT now(),
+  processed_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS shop_webhook_events_provider_event_unique
+  ON shop_webhook_events (provider, event_id);
+
+-- Coupons
+CREATE TABLE IF NOT EXISTS shop_coupons (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  code text NOT NULL,
+  type text NOT NULL,
+  value numeric(20,6) NOT NULL,
+  min_order_amount integer,
+  max_uses integer,
+  used_count integer NOT NULL DEFAULT 0,
+  expires_at timestamptz,
+  is_active boolean NOT NULL DEFAULT true,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS shop_coupons_code_unique ON shop_coupons (code);
+
+-- Coupon redemptions — UNIQUE(order_id) prevents double-redeem on retry
+CREATE TABLE IF NOT EXISTS shop_coupon_redemptions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  coupon_id uuid NOT NULL REFERENCES shop_coupons(id) ON DELETE CASCADE,
+  order_id uuid NOT NULL REFERENCES shop_orders(id) ON DELETE CASCADE,
+  discount_amount integer NOT NULL,
+  redeemed_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS shop_coupon_redemptions_order_unique
+  ON shop_coupon_redemptions (order_id);
+
+-- Low-stock alert column
+ALTER TABLE shop_products ADD COLUMN IF NOT EXISTS low_stock_threshold integer;`,
+    notes: 'Migracja czysto additive — istniejące zamówienia pozostają nietknięte, refunded jest nową gałęzią graph statusów. Stripe SDK trzeba zainstalować osobno (`pnpm add stripe`) jeśli używa się `stripeAdapter()` — `optionalDependencies` + `peerDependenciesMeta`. Coupons opt-in via `features: { coupons: true }`. Low-stock email wymaga `shop.adminEmail` w `defineShop` + skonfigurowanego email adaptera. Webhook idempotency table jest backwards-compatible: adaptery które nie surface eventId nadal działają poprzez terminal-status fallback. Test coverage 1053/1053 unit tests zielone (37 nowych: Stripe sig verify 4, getStatus 1, refund 3, payload 6, status-map 10, pricing-coupon 5, coupon-cookie 8). DoD: gap analysis vs Woo/Presta zatwierdzona, MUST-v1 (Stripe + Refund + Idempotency + Coupons) wdrożone, NICE-v1 (Low-stock + CSV export) wdrożone, dokumentacja shopa pełna.'
+};

package/dist/updates/index.js

@@ -58,7 +58,70 @@ import { update as update0210 } from './0.21.0/index.js';
 import { update as update0220 } from './0.22.0/index.js';
 import { update as update0230 } from './0.23.0/index.js';
 import { update as update0240 } from './0.24.0/index.js';
-export const updates = [update0065, update0066, update0067, update0068, update0069, update010, update011, update012, update013, update014, update015, update020, update022, update050, update051, update052, update053, update054, update055, update056, update057, update058, update060, update061, update062, update070, update071, update072, update073, update080, update090, update0100, update0110, update0120, update0130, update0131, update0132, update0133, update0134, update0140, update0141, update0142, update0143, update0144, update0145, update0146, update0150, update0151, update0152, update0153, update0154, update0155, update0160, update0180, update0190, update0200, update0210, update0220, update0230, update0240];
+import { update as update0250 } from './0.25.0/index.js';
+export const updates = [
+    update0065,
+    update0066,
+    update0067,
+    update0068,
+    update0069,
+    update010,
+    update011,
+    update012,
+    update013,
+    update014,
+    update015,
+    update020,
+    update022,
+    update050,
+    update051,
+    update052,
+    update053,
+    update054,
+    update055,
+    update056,
+    update057,
+    update058,
+    update060,
+    update061,
+    update062,
+    update070,
+    update071,
+    update072,
+    update073,
+    update080,
+    update090,
+    update0100,
+    update0110,
+    update0120,
+    update0130,
+    update0131,
+    update0132,
+    update0133,
+    update0134,
+    update0140,
+    update0141,
+    update0142,
+    update0143,
+    update0144,
+    update0145,
+    update0146,
+    update0150,
+    update0151,
+    update0152,
+    update0153,
+    update0154,
+    update0155,
+    update0160,
+    update0180,
+    update0190,
+    update0200,
+    update0210,
+    update0220,
+    update0230,
+    update0240,
+    update0250
+];
 export const getUpdatesFrom = (fromVersion) => {
     const fromParts = fromVersion.split('.').map(Number);
     return updates.filter((update) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "includio-cms",
-	"version": "0.24.0",
+	"version": "0.25.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -141,6 +141,7 @@
 		"postgres": "^3.4.5",
 		"runed": "^0.35.1",
 		"sharp": "^0.34.2",
+		"stripe": ">=17.0.0",
 		"svelte": "^5.43.0",
 		"svelte-sonner": "^1.0.5",
 		"svelte-tiptap": "^3.0.1",
@@ -160,6 +161,9 @@
 		"openai": {
 			"optional": true
 		},
+		"stripe": {
+			"optional": true
+		},
 		"svelte-tiptap": {
 			"optional": true
 		},
@@ -220,6 +224,7 @@
 		"prettier-plugin-svelte": "^3.3.3",
 		"prettier-plugin-tailwindcss": "^0.6.11",
 		"publint": "^0.3.2",
+		"stripe": "^17.0.0",
 		"rehype-autolink-headings": "^7.1.0",
 		"rehype-slug": "^6.0.0",
 		"remark-gfm": "^4.0.1",