@buildaureon/sdk 0.1.2 → 0.1.7

package/examples/drift-detect-restore/main.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview demo — drift → detection → restore.
+ *
+ * Shows the full loop: rule set, controlled drift, restore plan, receipt, health.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm example:drift-detect-restore
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  formatWeight,
+  isAureonError,
+  type DriftRestoreFlow,
+} from "../../src/index.js";
+
+function printPhase(label: string, healthState: string, metric?: number, target?: number): void {
+  const metricStr =
+    metric !== undefined && target !== undefined
+      ? ` — ${formatWeight(metric)} vs ${formatWeight(target)} target`
+      : "";
+  console.log(`  ${label}: ${healthState}${metricStr}`);
+}
+
+function printFlow(flow: DriftRestoreFlow): void {
+  console.log(`\nRule: ${flow.rule.summary}\n`);
+
+  console.log("1. Rule — aligned on policy");
+  printPhase(
+    "   Health",
+    flow.phases.aligned.health.state,
+    flow.phases.aligned.health.currentMetric,
+    flow.phases.aligned.health.targetMetric
+  );
+
+  console.log("\n2. Drift — NVDA rally broke the stable sleeve");
+  printPhase(
+    "   Health",
+    flow.phases.drift.health.state,
+    flow.phases.drift.health.currentMetric,
+    flow.phases.drift.health.targetMetric
+  );
+  if (flow.phases.drift.restorePlan) {
+    console.log(`   Restore plan: ${flow.phases.drift.restorePlan.message}`);
+  }
+
+  if (flow.phases.restored) {
+    console.log("\n3. Restore — back within policy");
+    printPhase(
+      "   Health",
+      flow.phases.restored.health.state,
+      flow.phases.restored.health.currentMetric,
+      flow.phases.restored.health.targetMetric
+    );
+    if (flow.phases.restored.receipt) {
+      console.log(
+        `   Receipt: ${flow.phases.restored.receipt.action} — settlement ${flow.phases.restored.receipt.settlement}`
+      );
+    }
+  }
+
+  console.log(`\n${flow.message}`);
+  console.log(
+    "\nWe broke the rule on purpose. AUREON detected it and restored the policy.\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 aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    apiKey,
+  });
+
+  console.log("\n=== AUREON — Drift → detection → restore ===\n");
+
+  const flow = await aureon.runDriftRestoreDemo();
+  printFlow(flow);
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

package/examples/full-aureon-loop/main.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview full AUREON loop (not a portfolio tracker).
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm example:full-aureon-loop
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  formatWeight,
+  isAureonError,
+  type FullAureonLoopFlow,
+} from "../../src/index.js";
+
+function printFlow(flow: FullAureonLoopFlow): void {
+  console.log("\n=== AUREON — Full loop (not a portfolio tracker) ===\n");
+
+  console.log(`User brief: "${flow.userBrief}"\n`);
+
+  console.log("1. Intent → objective");
+  console.log(`   Objective:  ${flow.phases.intent.objectiveName}`);
+  console.log(`   Policy:     ${flow.phases.intent.policySummary}`);
+  console.log(`   Mode:       ${flow.phases.intent.automationMode}`);
+  console.log(
+    `   Baseline:   ${flow.phases.intent.health.state} — ${formatWeight(flow.phases.intent.health.currentMetric)} vs ${formatWeight(flow.phases.intent.health.targetMetric)}`
+  );
+
+  console.log("\n2. Plan check — green book can still fail the plan");
+  console.log(
+    `   After shock: ${flow.phases.planCheck.afterShock.health.state} — ${formatWeight(flow.phases.planCheck.afterShock.health.currentMetric)} vs ${formatWeight(flow.phases.planCheck.afterShock.health.targetMetric)}`
+  );
+  console.log(
+    `   Paradox:     ${flow.phases.planCheck.afterShock.paradox.detected ? "yes" : "no"} — ${flow.phases.planCheck.afterShock.paradox.message}`
+  );
+
+  console.log("\n3. Drift → restore");
+  console.log(
+    `   Health:      ${flow.phases.driftRestore.healthBefore.state} → ${flow.phases.driftRestore.healthAfter.state}`
+  );
+  console.log(
+    `   Receipt:     ${flow.phases.driftRestore.settlement} — ${flow.phases.driftRestore.receipt.id}`
+  );
+
+  console.log("\n4. Receipt → verification");
+  console.log(
+    `   Valid:       ${flow.phases.verification.phases.validation.valid}`
+  );
+  console.log(`   Proof tier:  ${flow.phases.verification.proofTier}`);
+  console.log(`   Claim:       ${flow.phases.verification.phases.claimed.result}`);
+
+  console.log(`\n${flow.message}`);
+  console.log(
+    "\nWe're not building another portfolio tracker. Intent → plan → restore → verify.\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 aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    apiKey,
+  });
+
+  const flow = await aureon.runFullAureonLoopDemo();
+  printFlow(flow);
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,139 @@
+/**
+ * @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_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm example:green-vs-plan
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  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 aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    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

@@ -37,6 +37,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,84 @@
+/**
+ * @fileoverview demo — portfolio watch while away (agent-in-host).
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm example:portfolio-watch
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  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 aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    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/receipt-verification/main.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview receipt → verification.
+ *
+ * Shows claim vs validation vs settlement proof after a restore.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm example:receipt-verification
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  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 aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+    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/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 }
+  ]
+}