reqon-dsl 0.2.0

package/examples/xero/invoices.vague

@@ -0,0 +1,189 @@
+// Xero Invoice Sync Mission
+// Fetches all invoices from Xero, hydrates them, and normalizes to a standard schema
+// Demonstrates: OAuth2, pagination, hydration, error handling with match steps
+
+mission SyncXeroInvoices {
+  // Define the API source
+  source Xero {
+    auth: oauth2,
+    base: "https://api.xero.com/api.xro/2.0"
+  }
+
+  // Define storage destinations
+  store invoices_cache: sql("invoices")
+  store invoices_normalized: sql("invoices_normalized")
+  store failed_invoices: memory("failed_invoices")
+
+  // ============================================================
+  // SCHEMAS - For response type matching
+  // ============================================================
+
+  schema XeroInvoiceList {
+    Invoices: array,
+    Status: string?
+  }
+
+  schema XeroInvoiceDetail {
+    Invoices: array
+  }
+
+  schema XeroRateLimitError {
+    Message: string,
+    Type: string
+  }
+
+  schema XeroNotFoundError {
+    Message: string,
+    Type: string
+  }
+
+  schema XeroUnauthorizedError {
+    Message: string,
+    Type: string
+  }
+
+  // ============================================================
+  // Step 1: Fetch list of invoices (shallow/summary data)
+  // ============================================================
+
+  action FetchInvoiceList {
+    get "/Invoices" {
+      paginate: offset(page, 100),
+      until: length(response.Invoices) == 0
+    }
+
+    // Handle different response scenarios
+    match response {
+      XeroInvoiceList -> {
+        validate response {
+          assume length(.Invoices) > 0
+        }
+
+        store response.Invoices -> invoices_cache {
+          key: .InvoiceID,
+          partial: true
+        }
+      },
+
+      XeroRateLimitError -> retry {
+        maxAttempts: 5,
+        backoff: exponential,
+        initialDelay: 60000,
+        maxDelay: 300000
+      },
+
+      XeroUnauthorizedError -> jump RefreshToken then retry,
+
+      _ -> abort "Unexpected response from Xero API"
+    }
+  }
+
+  // ============================================================
+  // Step 2: Hydrate each invoice with full details
+  // ============================================================
+
+  action HydrateInvoices {
+    for invoice in invoices_cache where ._partial == true {
+      get "/Invoices/{invoice.InvoiceID}"
+
+      // Handle individual invoice fetch responses
+      match response {
+        XeroInvoiceDetail -> {
+          validate response {
+            assume length(.Invoices) == 1
+          }
+
+          store response.Invoices -> invoices_cache {
+            key: .InvoiceID,
+            partial: false,
+            upsert: true
+          }
+        },
+
+        XeroNotFoundError -> {
+          // Invoice deleted since list was fetched - log and skip
+          store {
+            invoice_id: invoice.InvoiceID,
+            error: "Invoice not found during hydration",
+            timestamp: now()
+          } -> failed_invoices { key: invoice.InvoiceID }
+        },
+
+        XeroRateLimitError -> retry {
+          maxAttempts: 3,
+          backoff: exponential,
+          initialDelay: 30000
+        },
+
+        XeroUnauthorizedError -> jump RefreshToken then retry,
+
+        // Unknown error - queue for manual review
+        _ -> queue failed_invoices
+      }
+    }
+  }
+
+  // ============================================================
+  // Step 3: Refresh OAuth token (called via jump directive)
+  // ============================================================
+
+  action RefreshToken {
+    post "/oauth2/token" {
+      source: Xero,
+      body: {
+        "grant_type": "refresh_token",
+        "refresh_token": env("XERO_REFRESH_TOKEN")
+      }
+    }
+
+    // Token refresh is critical - abort on failure
+    match response {
+      _ where .access_token != null -> continue,
+      _ -> abort "Failed to refresh Xero OAuth token"
+    }
+  }
+
+  // ============================================================
+  // Step 4: Map to standard schema
+  // ============================================================
+
+  action NormalizeInvoices {
+    for invoice in invoices_cache where ._partial == false {
+      map invoice -> StandardInvoice {
+        id: .InvoiceID,
+        vendor: "xero",
+        external_id: .InvoiceNumber,
+        amount: .Total,
+        currency: .CurrencyCode,
+        status: match .Status {
+          "PAID" => "paid",
+          "AUTHORISED" => "approved",
+          "SUBMITTED" => "pending",
+          "DRAFT" => "draft",
+          "VOIDED" => "voided",
+          _ => "unknown"
+        },
+        issued_at: .Date,
+        due_at: .DueDate,
+        customer_name: .Contact.Name,
+        line_items_count: length(.LineItems)
+      }
+
+      validate response {
+        assume .amount >= 0
+      }
+
+      store response -> invoices_normalized {
+        key: .id
+      }
+    }
+  }
+
+  // ============================================================
+  // Pipeline: run actions in sequence
+  // ============================================================
+
+  run FetchInvoiceList
+    then HydrateInvoices
+    then NormalizeInvoices
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "reqon-dsl",
+  "version": "0.2.0",
+  "description": "A DSL framework for fetch, map, validate pipelines - built on Vague",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "reqon": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "bench": "npx tsx src/benchmark/index.ts",
+    "bench:lexer": "npx tsx src/benchmark/index.ts --suite lexer",
+    "bench:parser": "npx tsx src/benchmark/index.ts --suite parser",
+    "bench:evaluator": "npx tsx src/benchmark/index.ts --suite evaluator",
+    "bench:store": "npx tsx src/benchmark/index.ts --suite store",
+    "bench:resilience": "npx tsx src/benchmark/index.ts --suite resilience",
+    "bench:e2e": "npx tsx src/benchmark/index.ts --suite e2e"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Max Clayton Clowes <max@mcclowes.com>",
+  "license": "ISC",
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "vague-lang": "file:../vague"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}