@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/ecommerce/order-saga-state-machine.md

@@ -0,0 +1,336 @@
+# Order Saga Pattern + State Machine
+
+> Model order lifecycle as a finite state machine with saga-pattern compensating transactions for distributed processing.
+
+**When to use:** Building any order processing system — especially those involving payment capture, inventory reservation, and fulfillment coordination across services.
+**Stack:** Node.js/Express, PostgreSQL/MySQL, optional message queue (BullMQ, SQS)
+
+---
+
+## Order State Machine
+
+```
+                    ┌──────────────────────────────────────────────┐
+                    │                                                │
+  ┌────────┐    ┌───▼─────┐    ┌──────────┐    ┌──────────┐    ┌───┴──────┐
+  │ CREATED│───▶│CONFIRMED│───▶│PROCESSING│───▶│ SHIPPED  │───▶│DELIVERED │
+  └───┬────┘    └───┬─────┘    └────┬─────┘    └────┬─────┘    └──────────┘
+      │             │               │               │
+      │         ┌───▼─────┐    ┌────▼─────┐    ┌────▼─────┐
+      └────────▶│CANCELLED│    │  FAILED  │    │ RETURNED │
+                └─────────┘    └──────────┘    └──────────┘
+                                    │
+                               ┌────▼─────┐
+                               │ REFUNDED │
+                               └──────────┘
+```
+
+### State Definitions
+
+```javascript
+const ORDER_STATES = {
+  CREATED: 'created',           // Order placed, awaiting payment
+  CONFIRMED: 'confirmed',       // Payment captured successfully
+  PROCESSING: 'processing',     // Being prepared for fulfillment
+  SHIPPED: 'shipped',           // Handed to carrier
+  DELIVERED: 'delivered',       // Confirmed delivered
+  CANCELLED: 'cancelled',       // Cancelled before shipment
+  FAILED: 'failed',             // Payment or processing failed
+  RETURNED: 'returned',         // Customer returned the order
+  REFUNDED: 'refunded',         // Refund issued
+};
+
+const VALID_TRANSITIONS = {
+  created:    ['confirmed', 'cancelled', 'failed'],
+  confirmed:  ['processing', 'cancelled', 'refunded'],
+  processing: ['shipped', 'cancelled', 'failed'],
+  shipped:    ['delivered', 'returned'],
+  delivered:  ['returned'],
+  returned:   ['refunded'],
+  cancelled:  [],  // Terminal state
+  failed:     ['created'],  // Allow retry
+  refunded:   [],  // Terminal state
+};
+```
+
+### Transition Enforcement
+
+```javascript
+async function transitionOrder(orderId, newStatus, metadata = {}) {
+  const order = await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
+  if (!order.rows[0]) throw new Error(`Order ${orderId} not found`);
+
+  const currentStatus = order.rows[0].status;
+  const allowed = VALID_TRANSITIONS[currentStatus];
+
+  if (!allowed || !allowed.includes(newStatus)) {
+    throw new Error(
+      `Invalid transition: ${currentStatus} → ${newStatus}. ` +
+      `Allowed: ${allowed?.join(', ') || 'none (terminal state)'}`
+    );
+  }
+
+  // Record transition in history
+  await db.query(
+    `INSERT INTO order_status_history (order_id, from_status, to_status, metadata, created_at)
+     VALUES ($1, $2, $3, $4, NOW())`,
+    [orderId, currentStatus, newStatus, JSON.stringify(metadata)]
+  );
+
+  // Update order
+  await db.query(
+    'UPDATE orders SET status = $1, updated_at = NOW() WHERE id = $2',
+    [newStatus, orderId]
+  );
+
+  // Emit event for side effects
+  await emitOrderEvent(orderId, newStatus, metadata);
+}
+```
+
+---
+
+## Checkout Saga (Orchestrated)
+
+The checkout process is a saga — a sequence of steps where each step has a compensating action for rollback:
+
+```javascript
+async function executeCheckoutSaga(orderId, cartId, paymentMethodId) {
+  const saga = new SagaOrchestrator();
+
+  // Step 1: Validate cart
+  saga.addStep({
+    name: 'validate_cart',
+    execute: async () => {
+      const validation = await validateCartForCheckout(cartId);
+      if (!validation.valid) throw new Error(`Cart invalid: ${validation.issues[0].message}`);
+      return validation;
+    },
+    compensate: async () => {
+      // Nothing to roll back — validation is read-only
+    },
+  });
+
+  // Step 2: Reserve inventory
+  saga.addStep({
+    name: 'reserve_inventory',
+    execute: async (ctx) => {
+      const items = await getCartItems(cartId);
+      for (const item of items) {
+        await reserveStock(item.product_id, item.variant_id, item.quantity, orderId);
+      }
+      return { items };
+    },
+    compensate: async (ctx) => {
+      // COMPENSATE: Release reserved inventory
+      const items = await getCartItems(cartId);
+      for (const item of items) {
+        await releaseStock(item.product_id, item.variant_id, item.quantity, orderId);
+      }
+    },
+  });
+
+  // Step 3: Capture payment
+  saga.addStep({
+    name: 'capture_payment',
+    execute: async (ctx) => {
+      const paymentIntent = await stripe.paymentIntents.create({
+        amount: ctx.validate_cart.subtotal * 100,
+        currency: 'usd',
+        payment_method: paymentMethodId,
+        confirm: true,
+        metadata: { order_id: orderId },
+      }, {
+        idempotencyKey: `checkout-${orderId}`,
+      });
+      return { paymentIntent };
+    },
+    compensate: async (ctx) => {
+      // COMPENSATE: Refund payment
+      if (ctx.capture_payment?.paymentIntent) {
+        await stripe.refunds.create({
+          payment_intent: ctx.capture_payment.paymentIntent.id,
+        });
+      }
+    },
+  });
+
+  // Step 4: Create order record
+  saga.addStep({
+    name: 'create_order',
+    execute: async (ctx) => {
+      await transitionOrder(orderId, 'confirmed', {
+        payment_intent_id: ctx.capture_payment.paymentIntent.id,
+      });
+      return { confirmed: true };
+    },
+    compensate: async (ctx) => {
+      // COMPENSATE: Mark order as failed
+      await transitionOrder(orderId, 'failed', { reason: 'saga_rollback' });
+    },
+  });
+
+  // Step 5: Clear cart
+  saga.addStep({
+    name: 'clear_cart',
+    execute: async () => {
+      await db.query("UPDATE carts SET status = 'converted' WHERE id = $1", [cartId]);
+    },
+    compensate: async () => {
+      await db.query("UPDATE carts SET status = 'active' WHERE id = $1", [cartId]);
+    },
+  });
+
+  // Execute saga
+  try {
+    const result = await saga.run();
+    return { success: true, order_id: orderId, ...result };
+  } catch (err) {
+    // Saga automatically runs compensating actions in reverse order
+    return { success: false, error: err.message, rollback: saga.getCompensationLog() };
+  }
+}
+```
+
+### Saga Orchestrator Implementation
+
+```javascript
+class SagaOrchestrator {
+  constructor() {
+    this.steps = [];
+    this.context = {};
+    this.completedSteps = [];
+    this.compensationLog = [];
+  }
+
+  addStep({ name, execute, compensate }) {
+    this.steps.push({ name, execute, compensate });
+  }
+
+  async run() {
+    for (const step of this.steps) {
+      try {
+        const result = await step.execute(this.context);
+        this.context[step.name] = result;
+        this.completedSteps.push(step);
+      } catch (err) {
+        // Run compensating actions in REVERSE order
+        for (const completed of [...this.completedSteps].reverse()) {
+          try {
+            await completed.compensate(this.context);
+            this.compensationLog.push({ step: completed.name, status: 'compensated' });
+          } catch (compErr) {
+            this.compensationLog.push({
+              step: completed.name, status: 'compensation_failed',
+              error: compErr.message
+            });
+            // Log but continue — try to compensate remaining steps
+          }
+        }
+        throw new Error(`Saga failed at ${step.name}: ${err.message}`);
+      }
+    }
+    return this.context;
+  }
+
+  getCompensationLog() { return this.compensationLog; }
+}
+```
+
+---
+
+## Database Schema
+
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  status VARCHAR(20) NOT NULL DEFAULT 'created',
+  subtotal DECIMAL(10,2) NOT NULL,
+  tax DECIMAL(10,2) DEFAULT 0,
+  shipping DECIMAL(10,2) DEFAULT 0,
+  total DECIMAL(10,2) NOT NULL,
+  payment_intent_id VARCHAR(255),
+  shipping_address JSONB,
+  notes TEXT,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE order_items (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id UUID NOT NULL REFERENCES orders(id),
+  product_id UUID NOT NULL REFERENCES products(id),
+  variant_id UUID REFERENCES product_variants(id),
+  quantity INTEGER NOT NULL,
+  unit_price DECIMAL(10,2) NOT NULL,
+  total_price DECIMAL(10,2) NOT NULL
+);
+
+CREATE TABLE order_status_history (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  order_id UUID NOT NULL REFERENCES orders(id),
+  from_status VARCHAR(20),
+  to_status VARCHAR(20) NOT NULL,
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Inventory reservations (for saga rollback)
+CREATE TABLE inventory_reservations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  product_id UUID NOT NULL,
+  variant_id UUID,
+  quantity INTEGER NOT NULL,
+  order_id UUID NOT NULL,
+  status VARCHAR(20) DEFAULT 'reserved',  -- reserved | committed | released
+  created_at TIMESTAMP DEFAULT NOW(),
+  expires_at TIMESTAMP DEFAULT NOW() + INTERVAL '30 minutes'
+);
+
+CREATE INDEX idx_orders_user ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_order_history ON order_status_history(order_id);
+CREATE INDEX idx_reservations_order ON inventory_reservations(order_id);
+CREATE INDEX idx_reservations_expiry ON inventory_reservations(expires_at)
+  WHERE status = 'reserved';
+```
+
+---
+
+## Event Hooks
+
+```javascript
+async function emitOrderEvent(orderId, newStatus, metadata) {
+  const handlers = {
+    confirmed: [sendOrderConfirmationEmail, notifyFulfillment],
+    processing: [updateInventoryCommit],
+    shipped: [sendShippingNotification, generateTrackingPage],
+    delivered: [sendDeliveryConfirmation, requestReview],
+    cancelled: [sendCancellationEmail, releaseInventory, processRefund],
+    failed: [sendFailureNotification, releaseInventory],
+    returned: [processReturn, sendReturnConfirmation],
+    refunded: [sendRefundConfirmation],
+  };
+
+  const fns = handlers[newStatus] || [];
+  for (const fn of fns) {
+    try {
+      await fn(orderId, metadata);
+    } catch (err) {
+      console.error(`Event handler failed for ${newStatus}:`, err);
+      // Log but don't fail the transition — side effects are secondary
+    }
+  }
+}
+```
+
+---
+
+## Sources
+
+- microservices.io: Saga Pattern (2025)
+- Medusa.js v2: Workflow-based commerce architecture (2025)
+- SagaLLM: Transaction Guarantees for Multi-Agent (VLDB 2025, arXiv:2503.11951)
+- Sylius: State machines in e-commerce modeling (2025)
+- commercetools: Order state machines documentation (2025)

package/skills-library/ecommerce/payment-provider-abstraction.md

@@ -0,0 +1,245 @@
+# Payment Provider Abstraction Layer
+
+> Adapter pattern for swapping payment providers without re-architecting. Supports Stripe, PayPal, and future providers.
+
+**When to use:** Building a payment system that may need to support multiple providers, or creating a provider-agnostic payment API.
+**Stack:** Node.js/Express, TypeScript recommended
+
+---
+
+## The Problem
+
+Without abstraction:
+- Adding a second payment provider requires changing every payment-related file
+- Provider-specific code (Stripe's `client_secret`, PayPal's `order_id`) leaks into business logic
+- Testing requires live provider credentials
+- Switching providers is a rewrite, not a configuration change
+
+---
+
+## Provider Interface
+
+```typescript
+interface PaymentProvider {
+  name: string;
+
+  // Create a payment session (checkout)
+  createPaymentSession(params: {
+    amount: number;          // In smallest currency unit (cents)
+    currency: string;        // ISO 4217 (usd, eur, gbp)
+    customerId?: string;     // Your internal customer ID
+    metadata?: Record<string, string>;
+    successUrl?: string;
+    cancelUrl?: string;
+  }): Promise<PaymentSession>;
+
+  // Capture a previously authorized payment
+  capturePayment(sessionId: string): Promise<PaymentResult>;
+
+  // Refund a completed payment
+  refundPayment(params: {
+    paymentId: string;
+    amount?: number;         // Partial refund (omit for full refund)
+    reason?: string;
+  }): Promise<RefundResult>;
+
+  // Get payment status
+  getPaymentStatus(paymentId: string): Promise<PaymentStatus>;
+
+  // Verify webhook signature
+  verifyWebhook(params: {
+    body: Buffer | string;
+    signature: string;
+    secret: string;
+  }): Promise<WebhookEvent>;
+}
+
+interface PaymentSession {
+  id: string;                // Provider's session/order ID
+  checkoutUrl: string;       // URL to redirect user to
+  expiresAt?: Date;
+  providerData?: any;        // Raw provider response (for debugging)
+}
+
+interface PaymentResult {
+  success: boolean;
+  paymentId: string;         // Provider's payment/transaction ID
+  amount: number;
+  currency: string;
+  status: 'captured' | 'pending' | 'failed';
+}
+
+interface RefundResult {
+  success: boolean;
+  refundId: string;
+  amount: number;
+  status: 'completed' | 'pending' | 'failed';
+}
+
+type PaymentStatus = 'pending' | 'authorized' | 'captured' | 'failed' | 'refunded' | 'cancelled';
+
+interface WebhookEvent {
+  id: string;
+  type: string;              // Normalized event type
+  paymentId?: string;
+  data: Record<string, any>;
+}
+```
+
+---
+
+## Stripe Implementation
+
+```typescript
+import Stripe from 'stripe';
+
+class StripeProvider implements PaymentProvider {
+  name = 'stripe';
+  private stripe: Stripe;
+
+  constructor(secretKey: string) {
+    this.stripe = new Stripe(secretKey);
+  }
+
+  async createPaymentSession(params) {
+    const session = await this.stripe.checkout.sessions.create({
+      payment_method_types: ['card'],
+      line_items: [{
+        price_data: {
+          currency: params.currency,
+          product_data: { name: 'Order' },
+          unit_amount: params.amount,
+        },
+        quantity: 1,
+      }],
+      mode: 'payment',
+      success_url: params.successUrl,
+      cancel_url: params.cancelUrl,
+      metadata: params.metadata,
+    });
+
+    return {
+      id: session.id,
+      checkoutUrl: session.url,
+      expiresAt: new Date(session.expires_at * 1000),
+      providerData: session,
+    };
+  }
+
+  async capturePayment(sessionId) {
+    const session = await this.stripe.checkout.sessions.retrieve(sessionId);
+    return {
+      success: session.payment_status === 'paid',
+      paymentId: session.payment_intent as string,
+      amount: session.amount_total,
+      currency: session.currency,
+      status: session.payment_status === 'paid' ? 'captured' : 'pending',
+    };
+  }
+
+  async refundPayment(params) {
+    const refund = await this.stripe.refunds.create({
+      payment_intent: params.paymentId,
+      amount: params.amount,
+      reason: params.reason as any,
+    });
+    return {
+      success: refund.status === 'succeeded',
+      refundId: refund.id,
+      amount: refund.amount,
+      status: refund.status === 'succeeded' ? 'completed' : 'pending',
+    };
+  }
+
+  async getPaymentStatus(paymentId) {
+    const intent = await this.stripe.paymentIntents.retrieve(paymentId);
+    const statusMap = {
+      succeeded: 'captured',
+      processing: 'pending',
+      requires_payment_method: 'failed',
+      canceled: 'cancelled',
+    };
+    return statusMap[intent.status] || 'pending';
+  }
+
+  async verifyWebhook(params) {
+    const event = this.stripe.webhooks.constructEvent(
+      params.body, params.signature, params.secret
+    );
+    return {
+      id: event.id,
+      type: this.normalizeEventType(event.type),
+      paymentId: (event.data.object as any).payment_intent,
+      data: event.data.object as any,
+    };
+  }
+
+  private normalizeEventType(stripeType: string): string {
+    const map = {
+      'checkout.session.completed': 'payment.completed',
+      'payment_intent.succeeded': 'payment.captured',
+      'payment_intent.payment_failed': 'payment.failed',
+      'charge.refunded': 'payment.refunded',
+    };
+    return map[stripeType] || stripeType;
+  }
+}
+```
+
+---
+
+## Payment Service (Provider-Agnostic)
+
+```typescript
+class PaymentService {
+  private providers: Map<string, PaymentProvider> = new Map();
+  private defaultProvider: string;
+
+  constructor(defaultProvider: string) {
+    this.defaultProvider = defaultProvider;
+  }
+
+  registerProvider(provider: PaymentProvider) {
+    this.providers.set(provider.name, provider);
+  }
+
+  getProvider(name?: string): PaymentProvider {
+    const providerName = name || this.defaultProvider;
+    const provider = this.providers.get(providerName);
+    if (!provider) throw new Error(`Payment provider '${providerName}' not registered`);
+    return provider;
+  }
+
+  // All business logic uses these methods — never calls providers directly
+  async createCheckout(params: { amount: number; currency: string; provider?: string }) {
+    return this.getProvider(params.provider).createPaymentSession(params);
+  }
+
+  async processRefund(params: { paymentId: string; amount?: number; provider?: string }) {
+    return this.getProvider(params.provider).refundPayment(params);
+  }
+}
+
+// Setup
+const paymentService = new PaymentService('stripe');
+paymentService.registerProvider(new StripeProvider(process.env.STRIPE_SECRET_KEY));
+// paymentService.registerProvider(new PayPalProvider(process.env.PAYPAL_CLIENT_ID));
+
+export { paymentService };
+```
+
+---
+
+## Adding a New Provider
+
+1. Implement `PaymentProvider` interface
+2. Call `paymentService.registerProvider(new YourProvider(...))`
+3. Done — all existing business logic works without changes
+
+---
+
+## Sources
+
+- Internal gap analysis: GAP-ECOM-6 (Payment Method Abstraction)
+- Medusa.js v2: Payment Module Provider architecture (2025)
+- Stripe Agent Toolkit: Provider interface patterns (2025)