@buildaureon/sdk 0.1.2 → 0.1.8

package/examples/green-vs-plan/main.ts

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Update 2 demo — green portfolio vs failing financial plan.
+ *
+ * Shows objective vs actual before and after a controlled NVDA rally with
+ * auto-restore disabled so the paradox stays visible.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_NETWORK  optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_API_URL  optional override (must match network if both set)
+ *
+ *   pnpm example:green-vs-plan
+ */
+
+import {
+  createAureonClient,
+  resolveAureonNetworkFromEnv,
+  formatWeight,
+  isAureonError,
+  type AllocationComparisonRow,
+  type PortfolioPositionInput,
+} from "../../src/index.js";
+
+const DEMO_POSITIONS: PortfolioPositionInput[] = [
+  {
+    symbol: "USDG",
+    name: "Paxos USDG",
+    category: "stable",
+    quantity: 24_000,
+    markPriceUsd: 1,
+  },
+  {
+    symbol: "NVDA",
+    name: "NVIDIA Stock Token",
+    category: "stock_token",
+    quantity: 45,
+    markPriceUsd: 920,
+  },
+  {
+    symbol: "AAPL",
+    name: "Apple Stock Token",
+    category: "stock_token",
+    quantity: 80,
+    markPriceUsd: 210,
+  },
+  {
+    symbol: "ETH",
+    name: "Ether",
+    category: "gas",
+    quantity: 8.5,
+    markPriceUsd: 3400,
+  },
+];
+
+function printRows(rows: AllocationComparisonRow[]): void {
+  if (rows.length === 0) {
+    console.log("  (no active objectives)");
+    return;
+  }
+  for (const row of rows) {
+    const label = row.targetSymbol ?? row.name.slice(0, 20);
+    console.log(
+      `  ${label.padEnd(16)} current ${formatWeight(row.currentMetric)}  target ${formatWeight(row.targetWeight)}  ${row.state}`
+    );
+  }
+}
+
+async function main(): Promise<void> {
+  const apiKey = process.env.AUREON_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("Set AUREON_API_KEY to an issued developer key.");
+  }
+
+  const resolved = resolveAureonNetworkFromEnv();
+  const aureon = createAureonClient({
+    network: resolved.network,
+    baseUrl: resolved.baseUrl,
+    apiKey,
+  });
+
+  console.log("\n=== AUREON Update 2 — Green vs plan ===\n");
+
+  console.log("1. Seed capital book (~20% stables)…");
+  await aureon.setPortfolio(DEMO_POSITIONS);
+
+  console.log("2. Create stable allocation objective (20% ± 2%)…");
+  const objective = await aureon.createObjective({
+    name: "Maintain 20% Stable Assets",
+    kind: "stable_allocation",
+    targetWeight: 0.2,
+    tolerance: 0.02,
+  });
+
+  console.log("3. Baseline — objective vs actual:\n");
+  let snapshot = await aureon.getAllocationVsTarget();
+  printRows(snapshot.rows);
+  console.log(`\n  Book: $${snapshot.overview.totalNotionalUsd.toLocaleString()}`);
+  console.log(`  Paradox: ${snapshot.paradox.message}\n`);
+
+  console.log("4. Apply NVDA rally (+45%), autoRestore: false…");
+  const market = await aureon.applyMarketEvent({
+    name: "NVDA Stock Token Rally",
+    description: "Controlled mark move — Update 2 paradox demo",
+    symbol: "NVDA",
+    priceChangeRatio: 0.45,
+    autoRestore: false,
+  });
+
+  console.log("5. After shock — objective vs actual:\n");
+  snapshot = await aureon.getAllocationVsTarget();
+  printRows(snapshot.rows);
+
+  const stable = snapshot.rows.find((r) => r.objectiveId === objective.id);
+  const bookBefore = snapshot.overview.totalNotionalUsd;
+  const bookAfter = market.portfolio.totalNotionalUsd;
+
+  console.log(`\n  Book before shock: $${bookBefore.toLocaleString()}`);
+  console.log(`  Book after shock:  $${bookAfter.toLocaleString()}`);
+  console.log(`  Book moved up:     ${bookAfter >= bookBefore ? "yes" : "no"}`);
+  if (stable) {
+    console.log(
+      `  Stable objective:  ${formatWeight(stable.currentMetric)} vs ${formatWeight(stable.targetWeight)} target — ${stable.state}`
+    );
+  }
+  console.log(`\n  Paradox detected:  ${snapshot.paradox.detected}`);
+  console.log(`  ${snapshot.paradox.message}\n`);
+
+  if (!snapshot.paradox.detected && stable && stable.state !== "healthy") {
+    console.log(
+      "  Note: paradox flag needs book-up signal; objective is still off-plan.\n"
+    );
+  }
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

package/examples/market-event/main.ts

@@ -3,14 +3,15 @@
  *
  * Env:
  *   AUREON_API_KEY  issued developer key (required)
- *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *   AUREON_NETWORK  optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_API_URL  optional override (must match network if both set)
  *
  *   pnpm --filter @buildaureon/sdk example:market
  */
 
 import {
   createAureonClient,
-  DEFAULT_API_BASE_URL,
+  resolveAureonNetworkFromEnv,
   isAureonError,
 } from "../../src/index.js";
 
@@ -20,8 +21,10 @@ async function main(): Promise<void> {
     throw new Error("Set AUREON_API_KEY to an issued developer key.");
   }
 
+  const resolved = resolveAureonNetworkFromEnv();
   const aureon = createAureonClient({
-    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    network: resolved.network,
+    baseUrl: resolved.baseUrl,
     apiKey,
   });
 
@@ -37,6 +40,8 @@ async function main(): Promise<void> {
     description: "Controlled mark appreciation on NVIDIA Stock Token",
     symbol: "NVDA",
     priceChangeRatio: 0.45,
+    // autoRestore: true runs restorative execution when objectives breach —
+    // use autoRestore: false for the green-vs-plan paradox demo (see example:green-vs-plan).
     autoRestore: true,
   });
 

package/examples/portfolio-watch/main.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview demo — portfolio watch while away (agent-in-host).
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_NETWORK  optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_API_URL  optional override (must match network if both set)
+ *
+ *   pnpm example:portfolio-watch
+ */
+
+import {
+  createAureonClient,
+  resolveAureonNetworkFromEnv,
+  formatWeight,
+  isAureonError,
+  type PortfolioWatchFlow,
+} from "../../src/index.js";
+
+function printFlow(flow: PortfolioWatchFlow): void {
+  console.log("\n=== AUREON — Watch while away (Cursor / Claude + MCP) ===\n");
+
+  console.log(`User brief: "${flow.userBrief}"`);
+  console.log(`Agent host: ${flow.host}\n`);
+
+  console.log("1. Register watch — intent → Automatic objective");
+  console.log(`   Objective:  ${flow.phases.register.objectiveName}`);
+  console.log(`   Mode:       ${flow.phases.register.automationMode}`);
+  console.log(`   Policy:     ${flow.phases.register.policySummary}`);
+  console.log(
+    `   Health:     ${flow.phases.register.health.state} — ${formatWeight(flow.phases.register.health.currentMetric ?? 0)} vs ${formatWeight(flow.phases.register.health.targetMetric ?? 0.2)} target`
+  );
+
+  if (flow.phases.whileAway) {
+    console.log("\n2. While away — market moved, Automatic mode acted");
+    console.log(
+      `   Event:      ${flow.phases.whileAway.marketEventName} (${flow.phases.whileAway.symbol} ${(flow.phases.whileAway.priceChangeRatio * 100).toFixed(0)}%)`
+    );
+    console.log(
+      `   Health:     ${flow.phases.whileAway.healthBefore.state} → ${flow.phases.whileAway.healthAfter.state}`
+    );
+    console.log(
+      `   Auto restore: ${flow.phases.whileAway.autoRestored ? "yes" : "no"}`
+    );
+    if (flow.phases.whileAway.receipt) {
+      console.log(
+        `   Receipt:    ${flow.phases.whileAway.receipt.settlement} — ${flow.phases.whileAway.receipt.id}`
+      );
+    }
+  }
+
+  console.log("\n3. Return briefing — what to tell the user");
+  for (const line of flow.phases.briefing.summaryLines) {
+    console.log(`   • ${line}`);
+  }
+
+  console.log(`\n${flow.message}`);
+  console.log(
+    "\nYou don't hand the agent a blank check — you register a rule, then read the briefing when you're back.\n"
+  );
+}
+
+async function main(): Promise<void> {
+  const apiKey = process.env.AUREON_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("Set AUREON_API_KEY to an issued developer key.");
+  }
+
+  const resolved = resolveAureonNetworkFromEnv();
+  const aureon = createAureonClient({
+    network: resolved.network,
+    baseUrl: resolved.baseUrl,
+    apiKey,
+  });
+
+  const flow = await aureon.runPortfolioWatchDemo({ host: "cursor" });
+  printFlow(flow);
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

package/examples/quickstart/main.ts

@@ -2,17 +2,18 @@
  * @fileoverview Quickstart — control-plane calls with an issued developer API key.
  *
  * Env (required for integrators — nothing else):
- *   AUREON_API_KEY  issued key from https://app.aureonlabs.network → Developers
- *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *   AUREON_API_KEY     issued key from Developers
+ *   AUREON_NETWORK     optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_API_URL     optional override (must match network if both set)
  *
  *   pnpm --filter @buildaureon/sdk example:quickstart
  */
 
 import {
   createAureonClient,
-  DEFAULT_API_BASE_URL,
   formatWeight,
   isAureonError,
+  resolveAureonNetworkFromEnv,
 } from "../../src/index.js";
 
 async function main(): Promise<void> {
@@ -23,8 +24,10 @@ async function main(): Promise<void> {
     );
   }
 
+  const resolved = resolveAureonNetworkFromEnv();
   const aureon = createAureonClient({
-    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    network: resolved.network,
+    baseUrl: resolved.baseUrl,
     apiKey,
   });
 
@@ -58,7 +61,7 @@ async function main(): Promise<void> {
   );
 
   console.log(
-    "hint: private key is only needed later to broadcast prepare-deposit / prepare-withdraw steps"
+    "hint: empty vault restore is 409. prepare-deposit is unsigned — the user broadcasts when they fund. Agents do not."
   );
 }
 

package/examples/receipt-verification/main.ts

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview receipt → verification.
+ *
+ * Shows claim vs validation vs settlement proof after a restore.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_NETWORK  optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_API_URL  optional override (must match network if both set)
+ *
+ *   pnpm example:receipt-verification
+ */
+
+import {
+  createAureonClient,
+  resolveAureonNetworkFromEnv,
+  isAureonError,
+  type ReceiptVerificationFlow,
+} from "../../src/index.js";
+
+function printFlow(flow: ReceiptVerificationFlow): void {
+  console.log("\n=== AUREON — Receipt → verification ===\n");
+
+  console.log("1. Claim — what the API/agent would call 'success'");
+  console.log(`   Status:     ${flow.phases.claimed.status}`);
+  console.log(`   Result:     ${flow.phases.claimed.result}`);
+  console.log(`   Settlement: ${flow.phases.claimed.settlement}`);
+  console.log(`   Summary:    ${flow.phases.claimed.summary}\n`);
+
+  console.log("2. Validate — local honesty check (schema + settlement rules)");
+  console.log(`   Valid:      ${flow.phases.validation.valid}`);
+  if (!flow.phases.validation.valid) {
+    for (const issue of flow.phases.validation.issues) {
+      console.log(`   - ${issue.code}: ${issue.message}`);
+    }
+  }
+  console.log(`   Proof tier: ${flow.proofTier}\n`);
+
+  console.log("3. Verify — independent settlement lookup (vault only)");
+  const settlement = flow.phases.settlement;
+  if (settlement) {
+    console.log(`   On-chain:   ${settlement.verifiedOnChain ? "yes" : "no"}`);
+    if (settlement.settlement) {
+      console.log(`   Block:      ${settlement.settlement.blockNumber}`);
+      console.log(`   Explorer:   ${settlement.settlement.explorerUrl}`);
+    } else {
+      console.log("   Record:     (none yet — vault submitted but not observed)");
+    }
+  } else if (flow.receipt.settlement === "staged") {
+    console.log("   Staged receipt — schema-valid, not chain-verified by design.");
+  } else {
+    console.log("   Settlement lookup unavailable for this receipt.");
+  }
+
+  const timelineCount = flow.phases.timelineEvents?.length ?? 0;
+  if (timelineCount > 0) {
+    console.log(`\n   Timeline:   ${timelineCount} linked event(s)`);
+  }
+
+  console.log(`\n${flow.message}`);
+  console.log(
+    "\nSuccess text is a claim. Validation and settlement records are how you verify it.\n"
+  );
+}
+
+async function main(): Promise<void> {
+  const apiKey = process.env.AUREON_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("Set AUREON_API_KEY to an issued developer key.");
+  }
+
+  const resolved = resolveAureonNetworkFromEnv();
+  const aureon = createAureonClient({
+    network: resolved.network,
+    baseUrl: resolved.baseUrl,
+    apiKey,
+  });
+
+  const flow = await aureon.runReceiptVerificationDemo();
+  printFlow(flow);
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

package/examples/sdk-demo-terminal/main.ts

@@ -3,7 +3,8 @@
  *
  * Env:
  *   AUREON_API_KEY  issued developer key (required)
- *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *   AUREON_NETWORK  optional; omit for mainnet (4663 / 8788); set testnet for public host (still 46630)
+ *   AUREON_API_URL  optional override (must match network if both set)
  *
  *   pnpm --filter @buildaureon/sdk example:sdk-demo-terminal
  *   pnpm --filter @buildaureon/sdk example:sdk-demo-terminal -- --create-only
@@ -11,7 +12,7 @@
 
 import {
   createAureonClient,
-  DEFAULT_API_BASE_URL,
+  resolveAureonNetworkFromEnv,
   formatWeight,
   isAureonError,
   type PortfolioPositionInput,
@@ -74,7 +75,8 @@ async function main(): Promise<void> {
     throw new Error("Set AUREON_API_KEY to an issued developer key.");
   }
 
-  const baseUrl = process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL;
+  const resolved = resolveAureonNetworkFromEnv();
+  const baseUrl = resolved.baseUrl;
   line(
     "meta",
     CREATE_ONLY
@@ -82,7 +84,7 @@ async function main(): Promise<void> {
       : `@buildaureon/sdk · Automatic demo loop · ${baseUrl}`
   );
 
-  const aureon = createAureonClient({ baseUrl, apiKey });
+  const aureon = createAureonClient({ network: resolved.network, baseUrl, apiKey });
 
   line("cmd", "aureon.ping()");
   const ping = await aureon.ping();

package/fixtures/reference-objectives.json

@@ -1,18 +1,18 @@
-{
-  "objectives": [
-    {
-      "name": "Maintain 20% Stable Assets",
-      "kind": "stable_allocation",
-      "targetWeight": 0.2,
-      "tolerance": 0.02,
-      "priority": "high"
-    },
-    {
-      "name": "Balanced Stock Token Sleeve",
-      "kind": "balanced_portfolio",
-      "targetWeight": 0.55,
-      "tolerance": 0.05,
-      "priority": "medium"
-    }
-  ]
-}
+{
+  "objectives": [
+    {
+      "name": "Maintain 20% Stable Assets",
+      "kind": "stable_allocation",
+      "targetWeight": 0.2,
+      "tolerance": 0.02,
+      "priority": "high"
+    },
+    {
+      "name": "Balanced Stock Token Sleeve",
+      "kind": "balanced_portfolio",
+      "targetWeight": 0.55,
+      "tolerance": 0.05,
+      "priority": "medium"
+    }
+  ]
+}

package/fixtures/reference-portfolio.json

@@ -1,10 +1,10 @@
-{
-  "portfolioId": "portfolio_operator_primary",
-  "positions": [
-    { "symbol": "USDG", "category": "stable", "quantity": 24000, "markPriceUsd": 1 },
-    { "symbol": "NVDA", "category": "stock_token", "quantity": 45, "markPriceUsd": 920 },
-    { "symbol": "AAPL", "category": "stock_token", "quantity": 80, "markPriceUsd": 210 },
-    { "symbol": "GOOGL", "category": "stock_token", "quantity": 60, "markPriceUsd": 175 },
-    { "symbol": "ETH", "category": "gas", "quantity": 8.5, "markPriceUsd": 3400 }
-  ]
-}
+{
+  "portfolioId": "portfolio_operator_primary",
+  "positions": [
+    { "symbol": "USDG", "category": "stable", "quantity": 24000, "markPriceUsd": 1 },
+    { "symbol": "NVDA", "category": "stock_token", "quantity": 45, "markPriceUsd": 920 },
+    { "symbol": "AAPL", "category": "stock_token", "quantity": 80, "markPriceUsd": 210 },
+    { "symbol": "GOOGL", "category": "stock_token", "quantity": 60, "markPriceUsd": 175 },
+    { "symbol": "ETH", "category": "gas", "quantity": 8.5, "markPriceUsd": 3400 }
+  ]
+}

package/package.json

@@ -1,61 +1,70 @@
-{
-  "name": "@buildaureon/sdk",
-  "version": "0.1.2",
-  "description": "Official TypeScript SDK for AUREON Financial Compass on Robinhood Chain",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "docs",
-    "examples",
-    "config",
-    "fixtures"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test tests/**/*.test.ts",
-    "bench": "tsx benchmarks/client-throughput.ts",
-    "example:quickstart": "tsx examples/quickstart/main.ts",
-    "example:market": "tsx examples/market-event/main.ts",
-    "example:sdk-demo-terminal": "tsx examples/sdk-demo-terminal/main.ts",
-    "example:e2e": "tsx examples/e2e-vault-flow/main.ts",
-    "example:e2e-policy": "tsx examples/e2e-policy-rebalance/main.ts",
-    "cli": "tsx cli/aureon-cli.ts",
-    "prepublishOnly": "pnpm build"
-  },
-  "keywords": [
-    "aureon",
-    "robinhood-chain",
-    "fco",
-    "financial-compass",
-    "sdk",
-    "typescript"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/buildaureon/aureon-sdk"
-  },
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "@types/node": "^22.13.10",
-    "tsup": "^8.4.0",
-    "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
-    "viem": "^2.55.1"
-  }
-}
+{
+  "name": "@buildaureon/sdk",
+  "version": "0.1.8",
+  "description": "Official TypeScript SDK for AUREON Financial Compass on Robinhood Chain",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "examples",
+    "config",
+    "fixtures"
+  ],
+  "keywords": [
+    "aureon",
+    "robinhood-chain",
+    "fco",
+    "financial-compass",
+    "sdk",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildaureon/aureon-sdk"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "viem": "^2.55.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "bench": "tsx benchmarks/client-throughput.ts",
+    "example:quickstart": "tsx examples/quickstart/main.ts",
+    "example:market": "tsx examples/market-event/main.ts",
+    "example:green-vs-plan": "tsx examples/green-vs-plan/main.ts",
+    "example:ai-to-objective-to-portfolio": "tsx examples/ai-to-objective-to-portfolio/main.ts",
+    "example:drift-detect-restore": "tsx examples/drift-detect-restore/main.ts",
+    "example:receipt-verification": "tsx examples/receipt-verification/main.ts",
+    "example:portfolio-watch": "tsx examples/portfolio-watch/main.ts",
+    "example:full-aureon-loop": "tsx examples/full-aureon-loop/main.ts",
+    "example:audit-trail": "tsx examples/audit-trail/main.ts",
+    "example:sdk-demo-terminal": "tsx examples/sdk-demo-terminal/main.ts",
+    "example:e2e": "tsx examples/e2e-vault-flow/main.ts",
+    "example:e2e-policy": "tsx examples/e2e-policy-rebalance/main.ts",
+    "cli": "tsx cli/aureon-cli.ts"
+  }
+}