xcomponent-ai 0.3.2 → 0.4.2

package/examples/subscription-lifecycle/component.yaml

@@ -0,0 +1,279 @@
+# Subscription Lifecycle Management
+#
+# Ce composant gère le cycle de vie d'un abonnement SaaS:
+# - Période d'essai
+# - Activation et renouvellement
+# - Suspension pour non-paiement
+# - Mise à niveau / rétrogradation
+# - Annulation avec période de grâce
+#
+# Pattern: Lifecycle avec états récurrents
+
+name: SubscriptionLifecycle
+entryMachine: Subscription
+
+stateMachines:
+  - name: Subscription
+    initialState: Trial
+    publicMemberType: Subscription
+
+    contextSchema:
+      subscriptionId:
+        type: string
+        label: "Subscription ID"
+        required: true
+        placeholder: "SUB-001"
+      customerId:
+        type: string
+        label: "Customer ID"
+        required: true
+      customerEmail:
+        type: string
+        label: "Customer Email"
+        required: true
+      plan:
+        type: select
+        label: "Plan"
+        required: true
+        options:
+          - value: starter
+            label: "Starter - 9€/month"
+          - value: professional
+            label: "Professional - 29€/month"
+          - value: enterprise
+            label: "Enterprise - 99€/month"
+      billingCycle:
+        type: select
+        label: "Billing Cycle"
+        options:
+          - value: monthly
+            label: "Monthly"
+          - value: yearly
+            label: "Yearly (2 months free)"
+
+    states:
+      - name: Trial
+        type: entry
+        description: "Free trial period (14 days)"
+        onEntry: sendWelcomeEmail
+
+      - name: TrialExpiring
+        description: "Trial about to expire (3 days left)"
+        onEntry: sendTrialExpiringReminder
+
+      - name: Active
+        description: "Subscription is active and paid"
+        onEntry: provisionResources
+
+      - name: PastDue
+        description: "Payment failed, grace period"
+        onEntry: sendPaymentFailedNotification
+
+      - name: Suspended
+        description: "Service suspended due to non-payment"
+        onEntry: suspendService
+
+      - name: Cancelled
+        description: "Subscription cancelled, access until period end"
+        onEntry: scheduleCancellation
+
+      - name: Expired
+        type: final
+        description: "Subscription has ended"
+        onEntry: deprovisionResources
+
+      - name: Churned
+        type: final
+        description: "Customer churned (no reactivation)"
+        onEntry: recordChurn
+
+    transitions:
+      # Trial flow
+      - from: Trial
+        to: TrialExpiring
+        event: TRIAL_EXPIRING_SOON
+        type: timeout
+        timeoutMs: 950400000  # 11 days (14 - 3)
+
+      - from: Trial
+        to: Active
+        event: SUBSCRIBE
+        triggeredMethod: createInitialInvoice
+
+      - from: Trial
+        to: Expired
+        event: TRIAL_ENDED
+        type: timeout
+        timeoutMs: 1209600000  # 14 days
+
+      - from: TrialExpiring
+        to: Active
+        event: SUBSCRIBE
+        triggeredMethod: createInitialInvoice
+
+      - from: TrialExpiring
+        to: Expired
+        event: TRIAL_ENDED
+        type: timeout
+        timeoutMs: 259200000  # 3 days
+
+      # Active subscription
+      - from: Active
+        to: Active
+        event: PAYMENT_SUCCESS
+        type: internal
+        triggeredMethod: extendSubscription
+
+      - from: Active
+        to: Active
+        event: PLAN_CHANGED
+        type: internal
+        triggeredMethod: handlePlanChange
+
+      - from: Active
+        to: PastDue
+        event: PAYMENT_FAILED
+        triggeredMethod: scheduleRetryPayment
+
+      - from: Active
+        to: Cancelled
+        event: CANCEL
+        triggeredMethod: calculateEndDate
+
+      # Past due (grace period)
+      - from: PastDue
+        to: Active
+        event: PAYMENT_SUCCESS
+        triggeredMethod: clearPastDueStatus
+
+      - from: PastDue
+        to: PastDue
+        event: PAYMENT_FAILED
+        type: internal
+        triggeredMethod: scheduleRetryPayment
+        guard:
+          expression: "context.retryCount < 3"
+
+      - from: PastDue
+        to: Suspended
+        event: PAYMENT_FAILED
+        guard:
+          expression: "context.retryCount >= 3"
+
+      - from: PastDue
+        to: Suspended
+        event: GRACE_PERIOD_ENDED
+        type: timeout
+        timeoutMs: 1209600000  # 14 days grace period
+
+      - from: PastDue
+        to: Cancelled
+        event: CANCEL
+
+      # Suspended
+      - from: Suspended
+        to: Active
+        event: PAYMENT_SUCCESS
+        triggeredMethod: reactivateService
+
+      - from: Suspended
+        to: Churned
+        event: SUSPENSION_TIMEOUT
+        type: timeout
+        timeoutMs: 2592000000  # 30 days
+
+      - from: Suspended
+        to: Cancelled
+        event: CANCEL
+
+      # Cancelled (access until period end)
+      - from: Cancelled
+        to: Expired
+        event: PERIOD_ENDED
+        description: "Triggered when current billing period ends"
+
+      - from: Cancelled
+        to: Active
+        event: REACTIVATE
+        triggeredMethod: resumeSubscription
+
+  # Billing processor (handles recurring payments)
+  - name: BillingCycle
+    initialState: Scheduled
+    publicMemberType: Invoice
+
+    contextSchema:
+      invoiceId:
+        type: string
+        label: "Invoice ID"
+        required: true
+      subscriptionId:
+        type: string
+        label: "Subscription ID"
+        required: true
+      amount:
+        type: number
+        label: "Amount"
+        required: true
+
+    states:
+      - name: Scheduled
+        type: entry
+        description: "Invoice scheduled for future date"
+
+      - name: Pending
+        description: "Invoice due, awaiting payment"
+        onEntry: chargePaymentMethod
+
+      - name: Processing
+        description: "Payment being processed"
+
+      - name: Paid
+        type: final
+        description: "Invoice paid successfully"
+        onEntry: notifySubscriptionPaymentSuccess
+
+      - name: Failed
+        description: "Payment failed"
+        onEntry: notifySubscriptionPaymentFailed
+
+      - name: Voided
+        type: final
+        description: "Invoice cancelled/voided"
+
+    transitions:
+      - from: Scheduled
+        to: Pending
+        event: DUE_DATE_REACHED
+        type: timeout
+        timeoutMs: 2592000000  # Configurable billing date
+
+      - from: Pending
+        to: Processing
+        event: CHARGE_INITIATED
+
+      - from: Processing
+        to: Paid
+        event: CHARGE_SUCCESS
+
+      - from: Processing
+        to: Failed
+        event: CHARGE_FAILED
+
+      - from: Failed
+        to: Processing
+        event: RETRY_CHARGE
+        guard:
+          expression: "context.attempts < 3"
+
+      - from: Failed
+        to: Voided
+        event: MAX_RETRIES_REACHED
+
+      - from: Scheduled
+        to: Voided
+        event: SUBSCRIPTION_CANCELLED
+
+      - from: Pending
+        to: Voided
+        event: SUBSCRIPTION_CANCELLED

package/examples/xcomponent-pattern-demo.yaml

@@ -0,0 +1,218 @@
+# XComponent Pattern Demo
+# Demonstrates the XComponent pattern with:
+# - Entry point machine (OrderManager) that persists
+# - Inter-machine transitions that create new instances
+# - Auto-deallocation of completed instances (except entry point)
+# - Component-level orchestration
+
+name: OrderProcessingXComponent
+version: 1.0.0
+metadata:
+  description: XComponent pattern demo - orchestration of multiple state machines
+  domain: fintech
+
+# Entry point - automatically created when component starts
+entryMachine: OrderManager
+
+# Optional layout configuration for dashboard visualization
+layout:
+  algorithm: grid  # auto-layout algorithm: grid, force, hierarchical
+  # machines:  # manual positioning (overrides algorithm)
+  #   OrderManager: { x: 100, y: 100 }
+  #   OrderExecution: { x: 400, y: 100 }
+  #   Settlement: { x: 700, y: 100 }
+
+stateMachines:
+  # Entry Point: OrderManager
+  # This machine is created automatically and persists even in final state
+  # It orchestrates the creation of other machines via inter_machine transitions
+  - name: OrderManager
+    initialState: Ready
+    metadata:
+      description: Entry point - orchestrates order processing lifecycle
+
+    states:
+      - name: Ready
+        type: entry
+        metadata:
+          description: Ready to receive new orders
+
+      - name: OrderReceived
+        type: regular
+        metadata:
+          description: Order received, creating execution instance
+
+      - name: Processing
+        type: regular
+        metadata:
+          description: Order being processed
+
+      - name: Completed
+        type: final
+        metadata:
+          description: All orders completed (stays alive as entry point)
+
+    transitions:
+      # Receive new order - normal transition
+      - from: Ready
+        to: OrderReceived
+        event: NEW_ORDER
+        type: triggerable
+
+      # Create OrderExecution instance via inter_machine transition
+      - from: OrderReceived
+        to: Processing
+        event: START_EXECUTION
+        type: inter_machine
+        targetMachine: OrderExecution
+        metadata:
+          description: Creates new OrderExecution instance
+
+      # Back to ready for next order
+      - from: Processing
+        to: Ready
+        event: EXECUTION_COMPLETE
+        type: triggerable
+
+      # Shutdown entry point (but instance persists)
+      - from: Ready
+        to: Completed
+        event: SHUTDOWN
+        type: triggerable
+
+  # OrderExecution: Created dynamically by OrderManager
+  # Handles the execution of a single order
+  # Auto-deallocated when it reaches final state
+  - name: OrderExecution
+    initialState: Created
+    metadata:
+      description: Handles execution of a single order (auto-deallocated when complete)
+
+    contextSchema:
+      orderId:
+        type: text
+        required: true
+      symbol:
+        type: text
+        required: true
+      quantity:
+        type: number
+        required: true
+      executedQuantity:
+        type: number
+        default: 0
+
+    states:
+      - name: Created
+        type: entry
+        metadata:
+          description: Execution instance created
+
+      - name: Validating
+        type: regular
+        metadata:
+          description: Validating order parameters
+
+      - name: Executing
+        type: regular
+        metadata:
+          description: Executing on market
+
+      - name: Executed
+        type: regular
+        metadata:
+          description: Order executed, starting settlement
+
+      - name: Settled
+        type: final
+        metadata:
+          description: Order settled and complete (instance auto-deallocated)
+
+      - name: Failed
+        type: error
+        metadata:
+          description: Execution failed (instance auto-deallocated)
+
+    transitions:
+      - from: Created
+        to: Validating
+        event: VALIDATE
+        type: triggerable
+
+      - from: Validating
+        to: Executing
+        event: VALIDATION_OK
+        type: triggerable
+
+      - from: Validating
+        to: Failed
+        event: VALIDATION_FAILED
+        type: triggerable
+
+      - from: Executing
+        to: Executed
+        event: EXECUTION_OK
+        type: triggerable
+
+      - from: Executing
+        to: Failed
+        event: EXECUTION_FAILED
+        type: triggerable
+
+      # Create Settlement instance via inter_machine transition
+      - from: Executed
+        to: Settled
+        event: START_SETTLEMENT
+        type: inter_machine
+        targetMachine: Settlement
+        metadata:
+          description: Creates Settlement instance and completes execution
+
+  # Settlement: Created dynamically by OrderExecution
+  # Handles settlement process
+  # Auto-deallocated when complete
+  - name: Settlement
+    initialState: Pending
+    metadata:
+      description: Handles settlement (auto-deallocated when complete)
+
+    contextSchema:
+      orderId:
+        type: text
+        required: true
+      amount:
+        type: number
+        required: true
+
+    states:
+      - name: Pending
+        type: entry
+        metadata:
+          description: Settlement pending
+
+      - name: Confirmed
+        type: final
+        metadata:
+          description: Settlement confirmed (instance auto-deallocated)
+
+      - name: Failed
+        type: error
+        metadata:
+          description: Settlement failed (instance auto-deallocated)
+
+    transitions:
+      - from: Pending
+        to: Confirmed
+        event: SETTLEMENT_CONFIRMED
+        type: triggerable
+
+      - from: Pending
+        to: Failed
+        event: SETTLEMENT_FAILED
+        type: triggerable
+
+      - from: Pending
+        to: Failed
+        event: TIMEOUT
+        type: timeout
+        timeoutMs: 30000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xcomponent-ai",
-  "version": "0.3.2",
+  "version": "0.4.2",
   "description": "LLM-first framework for AI agents (Claude, GPT) to build apps with sanctuarized business logic. Event-driven FSM runtime with multi-instance state machines, cross-component communication, event sourcing, and production-ready persistence (PostgreSQL, MongoDB)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,7 +33,7 @@
     "test:ci": "jest --coverage --ci --maxWorkers=2",
     "cli": "ts-node src/cli.ts",
     "api": "ts-node src/api.ts",
-    "doc": "typedoc --out docs src",
+    "doc": "typedoc --out docs/api src",
     "lint": "eslint src/**/*.ts",
     "prepare": "npm run build",
     "prepublishOnly": "npm run clean && npm run build && npm test",