reqon-dsl 0.2.0 → 0.3.0

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

@@ -1,129 +0,0 @@
-// 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

@@ -1,130 +0,0 @@
-// 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

@@ -1,262 +0,0 @@
-// 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

@@ -1,88 +0,0 @@
-# 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"
-}
-```