@buildaureon/sdk 0.1.0

package/docs/error-model.md

@@ -0,0 +1,182 @@
+# Detailed Error Model and Diagnostics
+
+This document outlines the error classification system used by `@buildaureon/sdk`. It provides field specifications, JSON payloads returned by the hosted API, and diagnostic patterns for production environments.
+
+---
+
+## 1. Core Exception Classes
+
+All custom exceptions thrown by the SDK extend the base class `AureonError`. The classes are organized to allow granular catch blocks based on failure categories.
+
+```mermaid
+graph TD
+  Error[native Error] --> AureonError[AureonError Base]
+  AureonError --> AureonValidationError[AureonValidationError HTTP 400]
+  AureonError --> AureonNotFoundError[AureonNotFoundError HTTP 404]
+  AureonError --> AureonConflictError[AureonConflictError HTTP 409]
+  AureonError --> AureonNetworkError[AureonNetworkError DNS / Connect]
+  AureonError --> AureonTimeoutError[AureonTimeoutError Abort / Limit]
+```
+
+### Property Reference
+
+```ts
+export class AureonError extends Error {
+  /** Stable error code string. Use this for programmatic branching. */
+  readonly code: AureonErrorCode;
+  /** HTTP status code from the server, or null for network failures. */
+  readonly status: number | null;
+  /** Additional key-value metadata returned by the API (e.g. form fields validation). */
+  readonly details: Record<string, unknown> | null;
+  /** Indicates whether the request can be retried immediately. */
+  readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    code: AureonErrorCode,
+    status: number | null = null,
+    details: Record<string, unknown> | null = null
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.retryable = isRetryableCode(code);
+
+    // Capture stack trace, preserving original V8 exception stack where supported
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+```
+
+---
+
+## 2. API JSON Error Payload Formats
+
+When an API request fails, the gateway returns a structured JSON payload. The SDK's HTTP transport layer automatically parses this payload and maps it to the appropriate error class.
+
+### 2.1 Validation Error Payload (HTTP 400)
+Returned when objective creation weights, names, or tolerances violate system rules.
+
+```json
+{
+  "code": "VALIDATION_ERROR",
+  "message": "Create objective parameters failed validation checks",
+  "details": {
+    "name": "Objective display name must be at least 3 characters long",
+    "targetWeight": "Weight must be a number between 0.0 and 1.0",
+    "tolerance": "Tolerance must be a number between 0.0 and 0.5"
+  }
+}
+```
+
+### 2.2 Conflict Error Payload (HTTP 409)
+Returned when modifying a resource that is currently locked or undergoing execution.
+
+```json
+{
+  "code": "CONFLICT",
+  "message": "Cannot modify objective state while rebalance swap is processing",
+  "details": {
+    "objectiveId": "obj_01h8v12x8p8p3z2v1q45r3m2e1",
+    "executionId": "exec_01h8v5t7p8p3z2v1q45r3m2e99",
+    "status": "pending_confirmation"
+  }
+}
+```
+
+### 2.3 Rate Limit Payload (HTTP 429)
+Returned when requests exceed rate limits.
+
+```json
+{
+  "code": "RATE_LIMITED",
+  "message": "Too many requests. Please slow down.",
+  "details": {
+    "retryAfterSeconds": 15,
+    "limit": 100,
+    "windowMs": 60000
+  }
+}
+```
+
+---
+
+## 3. Custom Diagnostics and Logging Hooks
+
+Integrators can register a logger interface during client construction to track network requests, retries, and errors in production.
+
+```ts
+import { createAureonClient, AureonLogger } from "@buildaureon/sdk";
+
+const productionLogger: AureonLogger = {
+  debug(msg, ctx) { console.debug(`[DEBUG] ${msg}`, ctx || ""); },
+  info(msg, ctx) { console.info(`[INFO] ${msg}`, ctx || ""); },
+  warn(msg, ctx) { console.warn(`[WARN] ${msg}`, ctx || ""); },
+  error(msg, ctx) {
+    // Send critical anomalies to third-party alert services
+    if (ctx?.code === "SERVER_ERROR" || ctx?.code === "CONFLICT") {
+      sendToSentry(msg, ctx);
+    }
+    console.error(`[ERROR] ${msg}`, ctx || "");
+  }
+};
+
+const aureon = createAureonClient({
+  apiKey: process.env.AUREON_API_KEY,
+  logger: productionLogger
+});
+```
+
+---
+
+## 4. Operational Recovery Patterns
+
+```mermaid
+flowchart TD
+  Catch[Catch AureonError] --> CodeBranch{Switch error.code}
+
+  CodeBranch -->|UNAUTHORIZED| HandleAuth[Clear storage and restart EIP-191 signature challenge]
+  CodeBranch -->|VALIDATION_ERROR| HandleValidation[Parse details dictionary and highlight fields in UI]
+  CodeBranch -->|NOT_FOUND| HandleNotFound[Redirect to list and show warning toast]
+  CodeBranch -->|RATE_LIMITED| HandleRate[Wait retryAfterSeconds or exponential backoff then retry]
+  CodeBranch -->|TIMEOUT| HandleTimeout[Increase timeoutMs client configuration and retry]
+  CodeBranch -->|SERVER_ERROR| HandleServer[Alert ops team and fallback to staged settlement]
+```
+
+---
+
+## 5. Unit Testing and Mocking Guide
+
+When writing tests for your agent rebalancing scripts, you can assert error handling behavior using mock response status codes.
+
+```ts
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { AureonClient, AureonValidationError, isAureonError } from "@buildaureon/sdk";
+
+describe("SDK Error Handling Tests", () => {
+  it("should throw AureonValidationError on empty objective name", async () => {
+    const client = new AureonClient({ baseUrl: "https://api.aureonlabs.network" });
+
+    try {
+      await client.createObjective({
+        name: "  ", // Empty string
+        kind: "stable_allocation",
+        targetWeight: 0.2,
+        tolerance: 0.02
+      });
+      assert.fail("Should have failed pre-flight validation");
+    } catch (err) {
+      assert.ok(isAureonError(err));
+      assert.strictEqual(err.code, "VALIDATION_ERROR");
+      assert.ok(err instanceof AureonValidationError);
+      assert.match(err.message, /length/);
+    }
+  });
+});
+```
+Using programmatic switches on `error.code` ensures your code resists backend modifications.

package/docs/integration-guide.md

@@ -0,0 +1,196 @@
+# Production Integration Guide
+
+This guide details how to integrate `@buildaureon/sdk` into server-side agents, automated rebalancing scripts, and frontend user interfaces.
+
+---
+
+## 1. End-to-End Integration Plan
+
+Follow this six-step sequence to configure and start the automated rebalancing loop.
+
+```mermaid
+flowchart TD
+  Client[1. Client Init] --> Auth[2. Sign Handshake]
+  Auth --> Sync[3. Sync Capital Book]
+  Sync --> Deposit[4. Fund Vault]
+  Deposit --> Objective[5. Add Objective]
+  Objective --> Watchdog[6. Run Heartbeat Loop]
+  Watchdog --> Watchdog
+```
+
+### Step 1: Client Construction
+Set up the client, leveraging environment variables for configuration options.
+
+```ts
+import { createAureonClient, createSessionTokenProvider } from "@buildaureon/sdk";
+
+const session = createSessionTokenProvider(
+  typeof localStorage !== "undefined"
+    ? localStorage.getItem("aureon_bearer_token")
+    : process.env.AUREON_TOKEN ?? null
+);
+
+export const aureon = createAureonClient({
+  baseUrl: process.env.AUREON_API_URL || "https://api.aureonlabs.network",
+  apiKey: process.env.AUREON_API_KEY ?? null,
+  getAccessToken: session.getAccessToken
+});
+```
+
+### Step 2: EIP-191 Cryptographic Verification
+Authenticate session tokens using cryptographic challenge-response verification.
+
+```ts
+async function authenticate(walletAddress: string, signerFn: (msg: string) => Promise<string>) {
+  // 1. Fetch challenge message
+  const { message } = await aureon.getAuthNonce(walletAddress);
+
+  // 2. Sign EIP-191 personal message locally
+  const signature = await signerFn(message);
+
+  // 3. Post verification payload
+  const { token } = await aureon.verifyWallet({
+    address: walletAddress,
+    message,
+    signature
+  });
+
+  session.setToken(token);
+  return token;
+}
+```
+
+### Step 3: Align the Capital Book
+Populate local assets into the gateway database.
+
+```ts
+const { portfolio, chainId } = await aureon.syncPortfolio();
+console.log(`Portfolios aligned for Chain ID ${chainId}. Total Valuation: $${portfolio.totalNotionalUsd}`);
+```
+
+### Step 4: Fund the Smart Vault
+Automated objectives rebalance tokens held in your Smart Vault on the Robinhood Chain. Allocate capital into the vault before creating rules.
+
+```ts
+async function ensureVaultFunded(symbol: string, amount: string, executeTx: (step: any) => Promise<string>) {
+  const status = await aureon.getVaultStatus();
+  if (status.empty) {
+    const prep = await aureon.prepareVaultDeposit({ symbol, amount });
+    for (const step of prep.steps) {
+      console.log(`Executing step: ${step.label}`);
+      const txHash = await executeTx(step);
+      console.log(`Step complete. Hash: ${txHash}`);
+    }
+  }
+}
+```
+
+### Step 5: Register the Objective
+Create the objective. SDK integrations default to `automationMode: "auto"`.
+
+```ts
+const objective = await aureon.createObjective({
+  name: "Liquid Stable Reserves",
+  kind: "stable_allocation",
+  targetWeight: 0.30,
+  tolerance: 0.03
+});
+console.log(`Objective ${objective.name} registered. Status: ${objective.status}`);
+```
+
+### Step 6: Execute the Watchdog Loop
+Poll the gateway regularly to check policy health and execute restorations.
+
+```ts
+async function watchdogHeartbeat() {
+  try {
+    const result = await aureon.refreshWatchdog();
+    console.log(`Watchdog completed at ${result.refreshedAt}. System state: ${result.breaches.length} breaches.`);
+
+    for (const breach of result.breaches) {
+      const plan = await aureon.getRestorePlan(breach.objectiveId);
+      if (plan.kind === "vault_swap") {
+        const receipt = await aureon.restoreObjective(breach.objectiveId);
+        console.log(`Rebalance executed. Settlement: ${receipt.settlement}, Hash: ${receipt.transactionHash}`);
+      }
+    }
+  } catch (error) {
+    console.error("Watchdog heartbeat failed:", error);
+  }
+}
+```
+
+---
+
+## 2. Advanced Scripting Guidelines
+
+### 2.1 Implementing daemon runners
+For long-running processes, wrap the heartbeat logic in daemon controllers like PM2 or run them as systemd services.
+
+#### PM2 Configuration (`ecosystem.config.js`)
+```js
+module.exports = {
+  apps: [{
+    name: "aureon-agent-loop",
+    script: "./dist/index.js",
+    instances: 1,
+    autorestart: true,
+    watch: false,
+    env: {
+      NODE_ENV: "production",
+      AUREON_API_URL: "https://api.aureonlabs.network"
+    }
+  }]
+};
+```
+
+#### Systemd Service (`/etc/systemd/system/aureon.service`)
+```ini
+[Unit]
+Description=Aureon Rebalance Watchdog Daemon
+After=network.target
+
+[Service]
+Type=simple
+User=node
+WorkingDirectory=/home/node/app
+ExecStart=/usr/bin/node dist/index.js
+Restart=on-failure
+RestartSec=10
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 2.2 Server-Side Logger Configuration (Pino / Winston)
+Log JSON payloads to persistent logging collectors.
+
+```ts
+import winston from "winston";
+import { createAureonClient } from "@buildaureon/sdk";
+
+const logger = winston.createLogger({
+  level: "info",
+  format: winston.format.json(),
+  transports: [new winston.transports.File({ filename: "aureon-combined.log" })]
+});
+
+const aureon = createAureonClient({
+  apiKey: process.env.AUREON_API_KEY,
+  logger: {
+    debug: (msg, ctx) => logger.debug(msg, ctx),
+    info: (msg, ctx) => logger.info(msg, ctx),
+    warn: (msg, ctx) => logger.warn(msg, ctx),
+    error: (msg, ctx) => logger.error(msg, ctx)
+  }
+});
+```
+
+---
+
+## 3. Frontend Deployment (SPA/Vite Environments)
+
+*   **Credential Leakage Prevention**: Never commit `AUREON_API_KEY` to public repositories. Deploy client credentials via backend server API proxy routes.
+*   **CORS Configurations**: The production gateway allows request origins matching allowlisted domains configured in the Developer console. For local development, localhost calls are permitted.
+*   **Decoupled loop execution**: Frontend interfaces should only allow users to manage objectives and inspect histories. Keep the active rebalancing loops (`refreshWatchdog` and `restoreObjective`) on secure server-side cron loops.

package/docs/security.md

@@ -0,0 +1,74 @@
+# Security Model and Practices
+
+This document outlines the security architecture of `@buildaureon/sdk`, its integration with Smart Vault smart contracts, and practices for secure production environments.
+
+---
+
+## 1. Gateway Trust Boundaries
+
+AUREON operates on a non-custodial gateway model. The API acts as an analytical policy engine, price indexer, and coordinator, but does not control asset custody.
+
+```mermaid
+flowchart TD
+  Host[Host Application Boundary] -->|1. Request Calldata| Gateway[Aureon API Gateway]
+  Gateway -->|2. Generate Unsigned Steps| Host
+  Host -->|3. Sign Locally| Wallet[Private Key / HSM / KMS]
+  Wallet -->|4. Broadcast Tx| Chain[Robinhood Chain RPC]
+
+  subgraph OnChain [Smart Contract Controls]
+    Vault[Smart Vault Contract]
+    DX[Decentralized Exchanges]
+    Vault -->|Only allowlisted actions| DX
+  end
+  Wallet -.->|Call deposit / withdraw| Vault
+```
+
+### 1.1 Private Key Isolation
+The SDK provides no features for loading or storing private keys or mnemonics. The host application handles transaction signing locally using EIP-191 signatures or raw transaction serializers. Because private keys are never transmitted to the AUREON API, a gateway breach cannot compromise user keys.
+
+### 1.2 Unsigned Calldata Generation
+Endpoints like `prepareVaultDeposit` and `prepareVaultWithdraw` return structured calldata. You can decode and verify this data against open-source contract ABIs before signing and broadcasting.
+
+---
+
+## 2. Smart Contract Access Control
+
+The AUREON Smart Vault contracts on the Robinhood Chain enforce strict permission boundaries:
+
+*   **Owner Gate**: Only the address that deployed the vault (or was assigned ownership) can execute direct withdrawals.
+*   **Allowlisted Keepers**: Swap routes can only be executed by registered keeper addresses. The keeper cannot withdraw tokens to external third-party addresses; they are restricted to swapping allowlisted assets within the vault.
+*   **Limits and Slippage**: The contracts enforce maximum slippage tolerances on swaps to prevent sandwich attacks and price manipulation.
+
+---
+
+## 3. Credentials and API Keys Management
+
+*   **Zero Commits**: Never check API keys into git repositories. Load keys from environment variables or secure stores (e.g. AWS Secrets Manager, HashiCorp Vault).
+*   **CI/CD Configuration**: If you run tests in automated pipelines (e.g., GitHub Actions, GitLab CI), store credentials as encrypted secrets.
+*   **Frontend Mitigation**: Frontends should query an intermediate backend service instead of exposing API keys directly to the client bundle.
+*   **Key Rotation**: Generate replacement credentials and deprecate compromised tokens in the developer console immediately if a breach is suspected.
+
+---
+
+## 4. Understanding Staged Settlement
+
+AUREON receipts contain a `settlement` field:
+
+*   **Vault Settlement (`vault`)**: Transactions are settled on-chain on the Robinhood Chain. These have a real transaction hash and are verifiable via explorer.
+*   **Staged Settlement (`staged`)**: Simulated rebalances that update gateway database states without broadcasting transactions. This is used during rehearsals and testing.
+
+> [!WARNING]
+> Do not display staged rebalances as completed on-chain transactions in your dashboards. Always check the `settlement` attribute before presenting transaction confirmations to operators.
+
+---
+
+## 5. Production Checklist
+
+Review this security checklist before deploying your rebalancing daemon to production:
+
+- [ ] **Private Key Isolation**: Confirm that private keys are stored in environment variables or KMS, and are never logged or exposed.
+- [ ] **EIP-191 Handshake**: Ensure all user logins use the cryptographic challenge-response flow (`verifyWallet`).
+- [ ] **Scope Checks**: Verify that the API Key has the minimum permissions needed to run the target agent.
+- [ ] **Gas Auditing**: Maintain a gas reserve on the signing wallet to cover deposit and withdrawal transactions on the Robinhood Chain.
+- [ ] **Staged Handling**: Confirm your user interface clearly distinguishes between staged and vault settlements.
+- [ ] **Slippage Bounds**: Configure appropriate slippage tolerances on objectives to prevent execution failure during market volatility.

package/docs/transport.md

@@ -0,0 +1,128 @@
+# Transport Layer Reference
+
+This document describes the transport layer of `@buildaureon/sdk`, implemented in `src/transport/http.ts`.
+
+---
+
+## 1. Network Request Lifecycle
+
+Every SDK client call delegates network execution to the `requestJson` helper.
+
+```mermaid
+flowchart TD
+  Call[Client Method Call] --> Prep[Join URL & Compile Headers]
+  Prep --> Auth[Resolve Bearer Token]
+  Auth --> Abort[Set AbortController Timer]
+  Abort --> Fetch[Execute fetchImpl]
+  Fetch --> Code{HTTP Status OK?}
+  Code -->|Yes| Parse[Parse Response JSON]
+  Code -->|No| Map[map Status to AureonError]
+  Map --> Retry{Is Error Retryable?}
+  Retry -->|Yes| Sleep[Sleep retryDelayMs]
+  Sleep --> Fetch
+  Retry -->|No| Throw[Throw Custom Exception]
+```
+
+1.  **URL Join and Query Compilation**: The transport engine normalizes the base URL and path string, then serializes any query parameters.
+2.  **Bearer Token Resolution**: The `getAccessToken` async function evaluates the current session token to attach the `Authorization` header.
+3.  **Timeout Guard Configuration**: An `AbortController` handles request timeouts, defaulting to 30 seconds.
+4.  **Execution and Error Mapping**: The client fires the request. If the gateway returns an error, it is converted to a typed `AureonError` subclass.
+5.  **Bounded Retry**: The client retries the request if it encountered a transient failure (e.g. rate limit, gateway timeout) and retry budget is remaining.
+
+---
+
+## 2. Standard Header Layout
+
+Every HTTP request sent by the SDK contains these default headers:
+
+| Header | Required | Typical Value | Purpose |
+|--------|----------|---------------|---------|
+| `Accept` | Yes | `application/json` | Specifies the accepted media type. |
+| `Content-Type` | Optional | `application/json` | Specifies the payload format (attached if a request body is present). |
+| `X-Aureon-SDK` | Yes | `@buildaureon/sdk/0.1.0` | Identifies client package version. |
+| `X-Aureon-Api-Key` | Optional | `api_key_abc123` | Sent if the client is configured with an API key. |
+| `Authorization` | Optional | `Bearer token_xyz` | Session JWT, attached if a token provider is active. |
+
+---
+
+## 3. URL Utility Implementations
+
+### 3.1 `joinUrl`
+Normalizes base URLs and paths to prevent double slashes at joining boundaries:
+```ts
+function joinUrl(base: string, path: string): string {
+  const cleanBase = base.endsWith("/") ? base.slice(0, -1) : base;
+  const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+  return `${cleanBase}/${cleanPath}`;
+}
+```
+
+### 3.2 `withQuery`
+Serializes query parameter dictionaries into standard URL format:
+```ts
+function withQuery(path: string, query?: Record<string, any>): string {
+  if (!query) return path;
+  const parts = Object.entries(query)
+    .filter(([_, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+  if (parts.length === 0) return path;
+  const separator = path.includes("?") ? "&" : "?";
+  return `${path}${separator}${parts.join("&")}`;
+}
+```
+
+---
+
+## 4. Timeout Budgets and Request Aborts
+
+The transport engine protects applications from hanging sockets using the Fetch API's `AbortController` signal.
+
+```ts
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+
+try {
+  const response = await options.fetchImpl(url, {
+    ...init,
+    signal: controller.signal
+  });
+  return response;
+} catch (error) {
+  if (error instanceof Error && error.name === "AbortError") {
+    throw new AureonTimeoutError("Request timed out", options.timeoutMs);
+  }
+  throw new AureonNetworkError(error instanceof Error ? error.message : String(error));
+} finally {
+  clearTimeout(timeoutId);
+}
+```
+
+*   **Configuring Timeout**: Pass `timeoutMs` (in milliseconds) when instantiating `createAureonClient`.
+*   **Custom Abort Signals**: You can pass a custom `AbortSignal` in `RequestOptions` to cancel requests manually based on user actions.
+
+---
+
+## 5. Retry Loop and Backoff Configurations
+
+The SDK implements a retry mechanism for transient exceptions:
+
+*   **Retryable Failures**: `NETWORK_ERROR`, `TIMEOUT`, `RATE_LIMITED` (HTTP 429), and `SERVER_ERROR` (HTTP 5xx).
+*   **Default Behavior**: `maxRetries` is 0. If you configure `maxRetries: 2` and `retryDelayMs: 500`, the client will try the request up to 3 times, waiting 500ms between attempts.
+
+---
+
+## 6. Built-in Logger Adapters
+
+Integrate with internal request diagnostics using the `AureonLogger` interface:
+
+```ts
+export interface AureonLogger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+```
+
+*   `createConsoleLogger(prefix)`: Logs requests, attempts, and errors to the developer console.
+*   `silentLogger`: Suppresses logs.