@buildaureon/sdk 0.1.1 → 0.1.7

package/examples/ai-to-objective-to-portfolio/main.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Update 3 demo — AI → objective → portfolio.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm example:ai-to-objective-to-portfolio
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  formatWeight,
+  isAureonError,
+  parseFinancialIntent,
+  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,
+  },
+];
+
+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 userBrief =
+    "I want to keep about 20% of my portfolio in stable assets.";
+
+  console.log("\n=== AUREON Update 3 — AI → objective → portfolio ===\n");
+  console.log("USER (simulated agent input):");
+  console.log(`  "${userBrief}"\n`);
+
+  console.log("AI — structured intent:");
+  const intent = parseFinancialIntent(userBrief);
+  console.log(
+    JSON.stringify(
+      {
+        kind: intent.kind,
+        targetWeight: intent.targetWeight,
+        tolerance: intent.tolerance,
+      },
+      null,
+      2
+    )
+  );
+
+  console.log("\n1. Seed capital book…");
+  await aureon.setPortfolio(DEMO_POSITIONS);
+
+  console.log("2. Apply financial intent → create objective…");
+  const flow = await aureon.applyFinancialIntent(intent);
+
+  console.log("\n--- Intent ---");
+  console.log(`  Brief:   ${flow.intent.brief}`);
+  console.log(`  Policy:  ${flow.intent.policySummary}`);
+
+  console.log("\n--- Objective ---");
+  console.log(`  ID:      ${flow.objective.id}`);
+  console.log(`  Kind:    ${flow.objective.kind}`);
+  console.log(`  Mode:    ${flow.objective.automationMode}`);
+  console.log(
+    `  Target:  ${formatWeight(flow.objective.policy.targetWeight)}`
+  );
+
+  console.log("\n--- Portfolio ---");
+  console.log(
+    `  Book:    $${flow.portfolio.totalNotionalUsd.toLocaleString()}`
+  );
+  console.log(
+    `  Stables: ${formatWeight(flow.portfolio.stableWeight)}`
+  );
+  if (flow.health) {
+    console.log(
+      `  Health:  ${flow.health.state} — current ${formatWeight(flow.health.currentMetric)} vs target ${formatWeight(flow.health.targetMetric)}`
+    );
+  }
+
+  console.log(`\n${flow.message}`);
+  console.log(
+    "\nThe portfolio now has a reason — not just positions.\n"
+  );
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

package/examples/audit-trail/main.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Phase 2 audit trail export — objective → proof.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional
+ *   AUREON_OBJECTIVE_ID  optional (defaults to first objective)
+ *
+ *   pnpm example:audit-trail
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  formatAuditTrailLines,
+  isAureonError,
+} from "../../src/index.js";
+
+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 requested = process.env.AUREON_OBJECTIVE_ID?.trim();
+  const objectiveId =
+    requested || (await aureon.listObjectives())[0]?.id;
+  if (!objectiveId) {
+    throw new Error("No objectives on this wallet. Create one first.");
+  }
+
+  const trail = await aureon.getAuditTrail(objectiveId);
+
+  console.log("\n=== AUREON Phase 2 — Financial audit trail ===\n");
+  for (const line of formatAuditTrailLines(trail)) {
+    console.log(line);
+  }
+  console.log("");
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

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

@@ -1,65 +1,67 @@
-/**
- * @fileoverview Controlled market-event rehearsal against the live AUREON API.
- *
- * Env:
- *   AUREON_API_KEY  issued developer key (required)
- *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
- *
- *   pnpm --filter @buildaureon/sdk example:market
- */
-
-import {
-  createAureonClient,
-  DEFAULT_API_BASE_URL,
-  isAureonError,
-} from "../../src/index.js";
-
-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 objective = await aureon.createObjective({
-    name: "Maintain 20% Stable Assets",
-    kind: "stable_allocation",
-    targetWeight: 0.2,
-    tolerance: 0.02,
-  });
-
-  const result = await aureon.applyMarketEvent({
-    name: "NVDA Stock Token Rally",
-    description: "Controlled mark appreciation on NVIDIA Stock Token",
-    symbol: "NVDA",
-    priceChangeRatio: 0.45,
-    autoRestore: true,
-  });
-
-  console.log(
-    JSON.stringify(
-      {
-        objectiveId: objective.id,
-        eventId: result.event.id,
-        executions: result.executions.length,
-        settlement: result.executions[0]?.settlement ?? null,
-        health: result.health.find((h) => h.objectiveId === objective.id)?.state,
-      },
-      null,
-      2
-    )
-  );
-}
-
-main().catch((error) => {
-  if (isAureonError(error)) {
-    console.error(`${error.code}: ${error.message}`);
-  } else {
-    console.error(error);
-  }
-  process.exitCode = 1;
-});
+/**
+ * @fileoverview Controlled market-event rehearsal against the live AUREON API.
+ *
+ * Env:
+ *   AUREON_API_KEY  issued developer key (required)
+ *   AUREON_API_URL  optional (default https://api.aureonlabs.network)
+ *
+ *   pnpm --filter @buildaureon/sdk example:market
+ */
+
+import {
+  createAureonClient,
+  DEFAULT_API_BASE_URL,
+  isAureonError,
+} from "../../src/index.js";
+
+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 objective = await aureon.createObjective({
+    name: "Maintain 20% Stable Assets",
+    kind: "stable_allocation",
+    targetWeight: 0.2,
+    tolerance: 0.02,
+  });
+
+  const result = await aureon.applyMarketEvent({
+    name: "NVDA Stock Token Rally",
+    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,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        objectiveId: objective.id,
+        eventId: result.event.id,
+        executions: result.executions.length,
+        settlement: result.executions[0]?.settlement ?? null,
+        health: result.health.find((h) => h.objectiveId === objective.id)?.state,
+      },
+      null,
+      2
+    )
+  );
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});