reqon-dsl 0.2.0

package/examples/temporal-comparison/temporal/types/index.ts

@@ -0,0 +1,129 @@
+// Type definitions for the order reconciliation workflow
+// Temporal requires explicit type definitions for all data structures
+
+export interface ShopifyOrder {
+  id: string;
+  customer: {
+    email: string;
+    first_name: string;
+    last_name: string;
+  };
+  total_price: string;
+  currency: string;
+  status: string;
+  financial_status: string;
+  fulfillment_status: string | null;
+  created_at: string;
+  updated_at: string;
+  line_items: Array<{
+    id: string;
+    title: string;
+    quantity: number;
+    price: string;
+  }>;
+}
+
+export interface StripePaymentIntent {
+  id: string;
+  amount: number;
+  currency: string;
+  status: string;
+  payment_method_types: string[];
+  metadata: {
+    shopify_order_id?: string;
+  };
+  charges: {
+    data: Array<{
+      id: string;
+      amount: number;
+      amount_refunded: number;
+      created: number;
+    }>;
+  };
+}
+
+export interface ShipStationShipment {
+  shipmentId: number;
+  orderNumber: string;
+  carrierCode: string;
+  trackingNumber: string | null;
+  voided: boolean;
+  shipDate: string;
+  deliveryDate: string | null;
+}
+
+export interface UnifiedOrder {
+  order_id: string;
+  external_id: string;
+  source: string;
+  customer_email: string;
+  total_amount: number;
+  currency: string;
+  status: string;
+  created_at: Date;
+  line_items_count: number;
+  payment_status: string;
+  fulfillment_status: string;
+  synced_at: Date;
+}
+
+export interface UnifiedPayment {
+  payment_id: string;
+  order_id: string;
+  amount: number;
+  currency: string;
+  status: string;
+  method: string;
+  captured_at: Date;
+  refunded_amount: number;
+}
+
+export interface UnifiedShipment {
+  shipment_id: string;
+  order_id: string;
+  carrier: string;
+  tracking_number: string | null;
+  status: string;
+  shipped_at: Date;
+  delivered_at: Date | null;
+}
+
+export interface Discrepancy {
+  id: string;
+  order_id: string;
+  type: DiscrepancyType;
+  severity: Severity;
+  description: string;
+  shopify_value: string | null;
+  stripe_value: string | null;
+  shipstation_value: string | null;
+  detected_at: Date;
+}
+
+export type DiscrepancyType =
+  | 'missing_payment'
+  | 'amount_mismatch'
+  | 'missing_shipment_record'
+  | 'refund_status_mismatch';
+
+export type Severity = 'low' | 'medium' | 'high' | 'critical';
+
+export interface SyncCheckpoint {
+  key: string;
+  value: string;
+  updated_at: Date;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  hasMore: boolean;
+  nextCursor?: string;
+}
+
+export interface ReconciliationResult {
+  ordersProcessed: number;
+  paymentsProcessed: number;
+  shipmentsProcessed: number;
+  discrepanciesFound: number;
+  duration: number;
+}

package/examples/temporal-comparison/temporal/workers/main.ts

@@ -0,0 +1,130 @@
+// Temporal Worker Setup
+// This is infrastructure code that Reqon doesn't require at all
+// Reqon runs as a simple CLI or library - no workers, no server cluster
+
+import { NativeConnection, Worker } from '@temporalio/worker';
+import * as activities from '../activities';
+
+// Worker configuration
+const TASK_QUEUE = 'order-reconciliation';
+const TEMPORAL_ADDRESS = process.env.TEMPORAL_ADDRESS || 'localhost:7233';
+const TEMPORAL_NAMESPACE = process.env.TEMPORAL_NAMESPACE || 'default';
+
+async function run() {
+  console.log('Starting Order Reconciliation Worker...');
+  console.log(`Connecting to Temporal at ${TEMPORAL_ADDRESS}`);
+  console.log(`Namespace: ${TEMPORAL_NAMESPACE}`);
+
+  // Connect to Temporal server
+  const connection = await NativeConnection.connect({
+    address: TEMPORAL_ADDRESS,
+  });
+
+  try {
+    // Create worker
+    const worker = await Worker.create({
+      connection,
+      namespace: TEMPORAL_NAMESPACE,
+      taskQueue: TASK_QUEUE,
+      workflowsPath: require.resolve('../workflows/orderReconciliation'),
+      activities,
+      // Worker tuning options
+      maxConcurrentWorkflowTaskExecutions: 10,
+      maxConcurrentActivityTaskExecutions: 20,
+      maxCachedWorkflows: 100,
+      // Sticky execution options
+      stickyQueueScheduleToStartTimeout: '10s',
+    });
+
+    console.log(`Worker listening on task queue: ${TASK_QUEUE}`);
+
+    // Register shutdown handlers
+    const shutdown = async () => {
+      console.log('Shutting down worker...');
+      await worker.shutdown();
+      await connection.close();
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+
+    // Start the worker
+    await worker.run();
+  } catch (error) {
+    console.error('Worker error:', error);
+    await connection.close();
+    process.exit(1);
+  }
+}
+
+run().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});
+
+/*
+ * INFRASTRUCTURE REQUIREMENTS FOR TEMPORAL:
+ *
+ * 1. Temporal Server Cluster:
+ *    - Frontend service (gRPC API)
+ *    - History service (workflow state)
+ *    - Matching service (task routing)
+ *    - Worker service (internal tasks)
+ *
+ * 2. Database:
+ *    - PostgreSQL, MySQL, or Cassandra
+ *    - For workflow history and visibility
+ *
+ * 3. Elasticsearch (optional):
+ *    - For advanced workflow search
+ *
+ * 4. Prometheus + Grafana (recommended):
+ *    - For metrics and monitoring
+ *
+ * 5. Docker Compose or Kubernetes:
+ *    - For orchestrating all services
+ *
+ * Example docker-compose.yml (simplified):
+ *
+ * version: '3.8'
+ * services:
+ *   postgresql:
+ *     image: postgres:13
+ *     environment:
+ *       POSTGRES_PASSWORD: temporal
+ *       POSTGRES_USER: temporal
+ *       POSTGRES_DB: temporal
+ *
+ *   temporal:
+ *     image: temporalio/auto-setup:latest
+ *     depends_on:
+ *       - postgresql
+ *     environment:
+ *       - DB=postgresql
+ *       - DB_PORT=5432
+ *       - POSTGRES_USER=temporal
+ *       - POSTGRES_PWD=temporal
+ *       - POSTGRES_SEEDS=postgresql
+ *     ports:
+ *       - "7233:7233"
+ *
+ *   temporal-admin-tools:
+ *     image: temporalio/admin-tools:latest
+ *     depends_on:
+ *       - temporal
+ *
+ *   temporal-ui:
+ *     image: temporalio/ui:latest
+ *     depends_on:
+ *       - temporal
+ *     ports:
+ *       - "8080:8080"
+ *
+ * COMPARE TO REQON:
+ *
+ *   $ reqon reconciliation.vague --auth ./credentials.json
+ *
+ * That's it. No infrastructure. No workers. No database setup.
+ * Just a single command that runs anywhere Node.js is available.
+ */

package/examples/temporal-comparison/temporal/workflows/orderReconciliation.ts

@@ -0,0 +1,262 @@
+// Order Reconciliation Workflow
+// This is the Temporal equivalent of:
+//   run SyncShopifyOrders
+//     then SyncStripePayments
+//     then SyncShipStationShipments
+//     then ValidateReconciliation
+//
+// Notice how much ceremony is required compared to Reqon's declarative approach
+
+import {
+  proxyActivities,
+  defineQuery,
+  defineSignal,
+  setHandler,
+  condition,
+  sleep,
+  workflowInfo,
+  ApplicationFailure,
+} from '@temporalio/workflow';
+
+import type * as shopifyActivities from '../activities/shopify';
+import type * as stripeActivities from '../activities/stripe';
+import type * as shipstationActivities from '../activities/shipstation';
+import type * as validationActivities from '../activities/validation';
+import type * as storageActivities from '../activities/storage';
+
+import {
+  shopifyActivityOptions,
+  stripeActivityOptions,
+  shipStationActivityOptions,
+  databaseActivityOptions,
+  validationActivityOptions,
+} from '../config/retry';
+
+import { ReconciliationResult, UnifiedOrder, UnifiedPayment, UnifiedShipment } from '../types';
+
+// Proxy activities with their respective retry policies
+const shopify = proxyActivities<typeof shopifyActivities>(shopifyActivityOptions);
+const stripe = proxyActivities<typeof stripeActivities>(stripeActivityOptions);
+const shipstation = proxyActivities<typeof shipstationActivities>(shipStationActivityOptions);
+const validation = proxyActivities<typeof validationActivities>(validationActivityOptions);
+const storage = proxyActivities<typeof storageActivities>(databaseActivityOptions);
+
+// Workflow state
+interface WorkflowState {
+  status: 'pending' | 'syncing_shopify' | 'syncing_stripe' | 'syncing_shipstation' | 'validating' | 'completed' | 'failed';
+  ordersProcessed: number;
+  paymentsProcessed: number;
+  shipmentsProcessed: number;
+  discrepanciesFound: number;
+  error?: string;
+  startedAt: Date;
+  completedAt?: Date;
+}
+
+// Define queries to check workflow status
+export const getStatusQuery = defineQuery<WorkflowState>('getStatus');
+
+// Define signals to control workflow
+export const cancelSignal = defineSignal('cancel');
+export const pauseSignal = defineSignal('pause');
+export const resumeSignal = defineSignal('resume');
+
+// Main workflow
+export async function orderReconciliationWorkflow(): Promise<ReconciliationResult> {
+  const startTime = Date.now();
+  let cancelled = false;
+  let paused = false;
+
+  // Initialize workflow state
+  const state: WorkflowState = {
+    status: 'pending',
+    ordersProcessed: 0,
+    paymentsProcessed: 0,
+    shipmentsProcessed: 0,
+    discrepanciesFound: 0,
+    startedAt: new Date(),
+  };
+
+  // Set up query handler
+  setHandler(getStatusQuery, () => state);
+
+  // Set up signal handlers
+  setHandler(cancelSignal, () => {
+    cancelled = true;
+  });
+
+  setHandler(pauseSignal, () => {
+    paused = true;
+  });
+
+  setHandler(resumeSignal, () => {
+    paused = false;
+  });
+
+  // Helper to check for cancellation/pause
+  const checkPauseAndCancel = async () => {
+    if (cancelled) {
+      throw ApplicationFailure.nonRetryable('Workflow cancelled by user');
+    }
+    while (paused) {
+      await condition(() => !paused || cancelled, '1m');
+      if (cancelled) {
+        throw ApplicationFailure.nonRetryable('Workflow cancelled by user');
+      }
+    }
+  };
+
+  try {
+    // ========================================
+    // STEP 1: Sync Shopify Orders
+    // ========================================
+    state.status = 'syncing_shopify';
+    await checkPauseAndCancel();
+
+    // Get last sync checkpoint
+    const shopifyLastSync = await storage.getCheckpoint('shopify_orders_last_sync');
+
+    // Fetch all orders (with automatic pagination handled in activity)
+    const orders = await shopify.fetchAllShopifyOrders(shopifyLastSync);
+
+    // Store orders
+    state.ordersProcessed = await storage.upsertOrders(orders);
+
+    // Update checkpoint
+    await storage.setCheckpoint('shopify_orders_last_sync', new Date().toISOString());
+
+    console.log(`Synced ${state.ordersProcessed} Shopify orders`);
+
+    // ========================================
+    // STEP 2: Sync Stripe Payments
+    // ========================================
+    state.status = 'syncing_stripe';
+    await checkPauseAndCancel();
+
+    // Get last sync checkpoint (as Unix timestamp for Stripe)
+    const stripeLastSyncStr = await storage.getCheckpoint('stripe_payments_last_sync');
+    const stripeLastSync = stripeLastSyncStr
+      ? Math.floor(new Date(stripeLastSyncStr).getTime() / 1000)
+      : null;
+
+    // Fetch all payments
+    const payments = await stripe.fetchAllStripePayments(stripeLastSync);
+
+    // Store payments
+    state.paymentsProcessed = await storage.upsertPayments(payments);
+
+    // Update checkpoint
+    await storage.setCheckpoint('stripe_payments_last_sync', new Date().toISOString());
+
+    console.log(`Synced ${state.paymentsProcessed} Stripe payments`);
+
+    // ========================================
+    // STEP 3: Sync ShipStation Shipments
+    // ========================================
+    state.status = 'syncing_shipstation';
+    await checkPauseAndCancel();
+
+    // Get last sync checkpoint
+    const shipstationLastSync = await storage.getCheckpoint('shipstation_last_sync');
+
+    // Fetch all shipments
+    const shipments = await shipstation.fetchAllShipStationShipments(shipstationLastSync);
+
+    // Store shipments
+    state.shipmentsProcessed = await storage.upsertShipments(shipments);
+
+    // Update checkpoint
+    await storage.setCheckpoint('shipstation_last_sync', new Date().toISOString());
+
+    console.log(`Synced ${state.shipmentsProcessed} ShipStation shipments`);
+
+    // ========================================
+    // STEP 4: Validate and Reconcile
+    // ========================================
+    state.status = 'validating';
+    await checkPauseAndCancel();
+
+    // Get all data for validation
+    const allOrders = await storage.getAllOrders();
+    const allPayments = await storage.getAllPayments();
+    const allShipments = await storage.getAllShipments();
+
+    // Run all validations
+    const validationResult = await validation.runAllValidations(
+      allOrders,
+      allPayments,
+      allShipments
+    );
+
+    // Store discrepancies
+    state.discrepanciesFound = await storage.upsertDiscrepancies(
+      validationResult.discrepancies
+    );
+
+    console.log(`Found ${state.discrepanciesFound} discrepancies`);
+
+    // ========================================
+    // Complete
+    // ========================================
+    state.status = 'completed';
+    state.completedAt = new Date();
+
+    const duration = Date.now() - startTime;
+
+    return {
+      ordersProcessed: state.ordersProcessed,
+      paymentsProcessed: state.paymentsProcessed,
+      shipmentsProcessed: state.shipmentsProcessed,
+      discrepanciesFound: state.discrepanciesFound,
+      duration,
+    };
+  } catch (error) {
+    state.status = 'failed';
+    state.error = error instanceof Error ? error.message : String(error);
+    throw error;
+  }
+}
+
+// Child workflow for parallel sync (alternative approach)
+export async function parallelSyncWorkflow(): Promise<{
+  orders: UnifiedOrder[];
+  payments: UnifiedPayment[];
+  shipments: UnifiedShipment[];
+}> {
+  // Get all checkpoints in parallel
+  const [shopifyLastSync, stripeLastSyncStr, shipstationLastSync] =
+    await Promise.all([
+      storage.getCheckpoint('shopify_orders_last_sync'),
+      storage.getCheckpoint('stripe_payments_last_sync'),
+      storage.getCheckpoint('shipstation_last_sync'),
+    ]);
+
+  const stripeLastSync = stripeLastSyncStr
+    ? Math.floor(new Date(stripeLastSyncStr).getTime() / 1000)
+    : null;
+
+  // Fetch from all sources in parallel
+  // Note: This is more efficient but harder to debug than sequential
+  const [orders, payments, shipments] = await Promise.all([
+    shopify.fetchAllShopifyOrders(shopifyLastSync),
+    stripe.fetchAllStripePayments(stripeLastSync),
+    shipstation.fetchAllShipStationShipments(shipstationLastSync),
+  ]);
+
+  // Store all in parallel
+  await Promise.all([
+    storage.upsertOrders(orders),
+    storage.upsertPayments(payments),
+    storage.upsertShipments(shipments),
+  ]);
+
+  // Update all checkpoints
+  const now = new Date().toISOString();
+  await Promise.all([
+    storage.setCheckpoint('shopify_orders_last_sync', now),
+    storage.setCheckpoint('stripe_payments_last_sync', now),
+    storage.setCheckpoint('shipstation_last_sync', now),
+  ]);
+
+  return { orders, payments, shipments };
+}

package/examples/xero/README.md

@@ -0,0 +1,88 @@
+# Xero Invoice Sync Example
+
+Demonstrates a real-world sync pipeline with OAuth2 authentication, pagination, hydration, normalization, and comprehensive error handling.
+
+## What it does
+
+1. **FetchInvoiceList**: Fetches paginated invoice summaries with error handling
+2. **HydrateInvoices**: Fetches full details for each invoice, handling individual failures
+3. **RefreshToken**: OAuth token refresh (called via `jump` directive on auth errors)
+4. **NormalizeInvoices**: Maps Xero schema to a vendor-agnostic `StandardInvoice` format
+
+## Run
+
+```bash
+node dist/cli.js examples/xero/invoices.vague --auth credentials.json --verbose
+```
+
+Requires a `credentials.json`:
+```json
+{
+  "Xero": {
+    "type": "oauth2",
+    "accessToken": "your-xero-access-token"
+  }
+}
+```
+
+## Features demonstrated
+
+### OAuth2 Authentication
+```vague
+source Xero {
+  auth: oauth2,
+  base: "https://api.xero.com/api.xro/2.0"
+}
+```
+
+### Pagination with Until Condition
+```vague
+get "/Invoices" {
+  paginate: offset(page, 100),
+  until: length(response.Invoices) == 0
+}
+```
+
+### Schema Overloading with Match Steps
+Handle different API response types declaratively:
+```vague
+match response {
+  XeroInvoiceList -> { store response.Invoices -> cache },
+  XeroRateLimitError -> retry { maxAttempts: 5, backoff: exponential },
+  XeroUnauthorizedError -> jump RefreshToken then retry,
+  _ -> abort "Unexpected response"
+}
+```
+
+### Flow Control Directives
+
+| Directive | Usage | Description |
+|-----------|-------|-------------|
+| `continue` | `Schema -> continue` | Proceed to next step |
+| `skip` | `Schema -> skip` | Skip remaining steps in action |
+| `abort` | `Schema -> abort "message"` | Halt mission with error |
+| `retry` | `Schema -> retry { ... }` | Retry with backoff config |
+| `queue` | `Schema -> queue target` | Send to dead-letter queue |
+| `jump` | `Schema -> jump Action then retry` | Execute action, then continue |
+
+### Partial Record Hydration
+```vague
+store response.Invoices -> invoices_cache {
+  key: .InvoiceID,
+  partial: true  // Mark as needing hydration
+}
+
+for invoice in invoices_cache where ._partial == true {
+  // Fetch full details
+}
+```
+
+### Match Expressions for Field Mapping
+```vague
+status: match .Status {
+  "PAID" => "paid",
+  "AUTHORISED" => "approved",
+  "SUBMITTED" => "pending",
+  _ => "unknown"
+}
+```