@buildaureon/sdk 0.1.0 → 0.1.2

package/docs/transport.md

@@ -1,128 +1,142 @@
-# 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.
+# Transport Layer Reference
+
+HTTP transport for `@buildaureon/sdk` (`src/transport/http.ts`): headers, timeouts, retries, URL helpers, and logging.
+
+---
+
+## 1. Request lifecycle
+
+```mermaid
+flowchart TD
+  Call[Client_method] --> Prep[Join_URL_and_headers]
+  Prep --> Auth[Resolve_API_key_and_Bearer]
+  Auth --> Abort[AbortController_timeout]
+  Abort --> Fetch[fetch_implementation]
+  Fetch --> Ok{HTTP_OK?}
+  Ok -->|Yes| Parse[Parse_JSON]
+  Ok -->|No| Map[Map_to_AureonError]
+  Map --> Retry{Retryable_and_budget?}
+  Retry -->|Yes| Sleep[retryDelayMs]
+  Sleep --> Fetch
+  Retry -->|No| Throw[Throw]
+```
+
+1. Join `baseUrl` + path; attach query string when needed.
+2. Resolve `X-Aureon-Api-Key` from `apiKey` / `getApiKey`.
+3. Resolve `Authorization: Bearer …` from `getAccessToken` / `authToken` (optional).
+4. Apply timeout via `AbortController` (default 30s).
+5. On failure, map status → typed error; retry only if configured and retryable.
+
+---
+
+## 2. Headers
+
+| Header | When | Purpose |
+| --- | --- | --- |
+| `Accept` | Always | `application/json` |
+| `Content-Type` | Body present | `application/json` |
+| `X-Aureon-SDK` | Always | Package identity / version |
+| `X-Aureon-Api-Key` | Key configured | Product access + issued-key identity |
+| `Authorization` | Token configured | Optional Bearer session |
+| Custom `headers` | If set on client | Merged into every request |
+
+Issued developer keys in `X-Aureon-Api-Key` are enough for control-plane identity on the live API. Bearer is optional and wins when both are present.
+
+---
+
+## 3. Client transport options
+
+```ts
+createAureonClient({
+  baseUrl: "https://api.aureonlabs.network",
+  apiKey: process.env.AUREON_API_KEY!,
+  timeoutMs: 30_000,   // per attempt
+  maxRetries: 2,        // extra attempts after first failure
+  retryDelayMs: 500,    // fixed delay between attempts
+  fetch: customFetch,   // optional
+  headers: { "X-Debug": "1" },
+  logger: myLogger,
+});
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `timeoutMs` | `30000` | Must be positive finite |
+| `maxRetries` | `0` | Extra tries after the first failure |
+| `retryDelayMs` | `250` | Fixed sleep between tries |
+| `fetch` | `globalThis.fetch` | Inject for tests / unusual runtimes |
+
+---
+
+## 4. Retry policy
+
+**Retryable:** network failures, timeouts, HTTP 429, HTTP 5xx (when mapped as retryable).
+
+**Not retryable:** 400 validation, 401/403 auth, 404, most 409 conflicts (operator must change state).
+
+Total attempts = `1 + maxRetries`.
+
+---
+
+## 5. URL helpers
+
+### `joinUrl`
+
+Prevents double slashes when combining base + path.
+
+### `withQuery`
+
+Serializes defined query params with `encodeURIComponent`. Omits `null` / `undefined`.
+
+---
+
+## 6. Timeouts and aborts
+
+```ts
+const controller = new AbortController();
+const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+try {
+  return await fetchImpl(url, { ...init, signal: controller.signal });
+} catch (error) {
+  if (error instanceof Error && error.name === "AbortError") {
+    throw /* AureonTimeoutError */;
+  }
+  throw /* AureonNetworkError */;
+} finally {
+  clearTimeout(timeoutId);
+}
+```
+
+For agent loops that call restore + sync, prefer slightly higher `timeoutMs` under load rather than disabling timeouts.
+
+---
+
+## 7. Logger interface
+
+```ts
+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;
+}
+```
+
+Helpers may include console / silent adapters depending on package exports. Never log secrets from context.
+
+---
+
+## 8. Testing transport
+
+- Inject a fake `fetch` that returns controlled status/body.
+- Assert header presence of `X-Aureon-Api-Key` for SDK clients.
+- Assert retries by counting fetch invocations with `maxRetries > 0` and 503 responses.
+
+---
+
+## 9. Related docs
+
+- [Error model](./error-model.md)
+- [Auth](./auth.md)
+- [Client API](./client-api.md)
+- [Security](./security.md)

package/examples/e2e-policy-rebalance/main.ts

@@ -1,12 +1,16 @@
 /**
- * Live e2e: deposit flex + Auto maintain 20% TSLA (surplus sell / deficit buy).
+ * Live e2e: vault deposits + Automatic maintain 20% TSLA against the hosted API.
  *
- *   pnpm --filter @buildaureon/sdk exec tsx examples/e2e-policy-rebalance/main.ts
+ * Env:
+ *   AUREON_API_KEY            issued developer key (required)
+ *   AUREON_WALLET_PRIVATE_KEY 0x… signing key (required)
+ *   AUREON_API_URL            optional (default https://api.aureonlabs.network)
+ *   AUREON_RPC_URL            optional
+ *   AUREON_CHAIN_ID           optional (default 46630)
+ *
+ *   pnpm --filter @buildaureon/sdk example:e2e-policy
  */
 
-import { readFileSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import {
   createPublicClient,
   createWalletClient,
@@ -21,13 +25,10 @@ import { privateKeyToAccount } from "viem/accounts";
 import {
   createAureonClient,
   createSessionTokenProvider,
+  DEFAULT_API_BASE_URL,
   isAureonError,
-  LOCAL_API_BASE_URL,
 } from "../../src/index.js";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const BACKEND = join(__dirname, "../../../backend");
-
 const VAULT_ABI = [
   {
     type: "function",
@@ -41,32 +42,18 @@ const VAULT_ABI = [
   },
 ] as const;
 
-function loadDotEnv(path: string): Record<string, string> {
-  if (!existsSync(path)) return {};
-  const out: Record<string, string> = {};
-  for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const i = trimmed.indexOf("=");
-    if (i < 0) continue;
-    out[trimmed.slice(0, i)] = trimmed.slice(i + 1).trim();
-  }
-  return out;
-}
-
-function firstApiKey(raw?: string): string {
-  const key = raw?.split(",")[0]?.trim();
-  if (!key) throw new Error("AUREON_API_KEYS missing");
-  return key;
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`Set ${name}`);
+  return value;
 }
 
 function loadKey(): Hex {
-  if (process.env.AUREON_E2E_KEY?.startsWith("0x")) {
-    return process.env.AUREON_E2E_KEY as Hex;
+  const key = requireEnv("AUREON_WALLET_PRIVATE_KEY");
+  if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+    throw new Error("AUREON_WALLET_PRIVATE_KEY must be a 0x-prefixed 32-byte hex key");
   }
-  const walletPath = join(BACKEND, ".secrets/robinhood-testnet-wallet.json");
-  const j = JSON.parse(readFileSync(walletPath, "utf8")) as { privateKey: string };
-  return j.privateKey as Hex;
+  return key as Hex;
 }
 
 function log(step: string, data?: unknown) {
@@ -74,11 +61,12 @@ function log(step: string, data?: unknown) {
 }
 
 async function main() {
-  const env = loadDotEnv(join(BACKEND, ".env"));
-  const baseUrl = process.env.AUREON_API_URL ?? LOCAL_API_BASE_URL;
-  const rpcUrl = env.AUREON_RPC_URL ?? "https://rpc.testnet.chain.robinhood.com";
-  const chainId = Number(env.AUREON_CHAIN_ID ?? 46630);
-  const apiKey = firstApiKey(process.env.AUREON_API_KEY ?? env.AUREON_API_KEYS);
+  const baseUrl = process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL;
+  const rpcUrl =
+    process.env.AUREON_RPC_URL?.trim() ||
+    "https://rpc.testnet.chain.robinhood.com";
+  const chainId = Number(process.env.AUREON_CHAIN_ID ?? 46630);
+  const apiKey = requireEnv("AUREON_API_KEY");
 
   const account = privateKeyToAccount(loadKey());
   const publicClient = createPublicClient({ transport: http(rpcUrl) });

package/examples/e2e-policy-rebalance/underrun.ts

@@ -1,9 +1,14 @@
 /**
  * Follow-up: force TSLA underweight → Auto should Sell WETH → Buy TSLA.
+ *
+ * Env:
+ *   AUREON_API_KEY            issued developer key
+ *   AUREON_WALLET_PRIVATE_KEY 0x… signing key
+ *   AUREON_API_URL            optional (default https://api.aureonlabs.network)
+ *   AUREON_RPC_URL            optional
+ *   AUREON_CHAIN_ID           optional (default 46630)
  */
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+
 import {
   createPublicClient,
   createWalletClient,
@@ -15,39 +20,39 @@ import { privateKeyToAccount } from "viem/accounts";
 import {
   createAureonClient,
   createSessionTokenProvider,
+  DEFAULT_API_BASE_URL,
   isAureonError,
-  LOCAL_API_BASE_URL,
 } from "../../src/index.js";
 
-const BACKEND = join(dirname(fileURLToPath(import.meta.url)), "../../../backend");
-const env = Object.fromEntries(
-  readFileSync(join(BACKEND, ".env"), "utf8")
-    .split(/\r?\n/)
-    .filter((l) => l && !l.startsWith("#") && l.includes("="))
-    .map((l) => {
-      const i = l.indexOf("=");
-      return [l.slice(0, i), l.slice(i + 1).trim()] as const;
-    })
-);
-const key = JSON.parse(
-  readFileSync(join(BACKEND, ".secrets/robinhood-testnet-wallet.json"), "utf8")
-).privateKey as Hex;
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`Set ${name}`);
+  return value;
+}
+
+const key = requireEnv("AUREON_WALLET_PRIVATE_KEY") as Hex;
+if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+  throw new Error("AUREON_WALLET_PRIVATE_KEY must be a 0x-prefixed 32-byte hex key");
+}
+
 const account = privateKeyToAccount(key);
-const rpc = env.AUREON_RPC_URL!;
-const chainId = Number(env.AUREON_CHAIN_ID || 46630);
+const rpc =
+  process.env.AUREON_RPC_URL?.trim() ||
+  "https://rpc.testnet.chain.robinhood.com";
+const chainId = Number(process.env.AUREON_CHAIN_ID || 46630);
 const publicClient = createPublicClient({ transport: http(rpc) });
 const walletClient = createWalletClient({ account, transport: http(rpc) });
 const chain = {
   id: chainId,
-  name: "rh",
+  name: "Robinhood Chain Testnet",
   nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
   rpcUrls: { default: { http: [rpc] } },
 } as const;
 
 const session = createSessionTokenProvider(null);
 const aureon = createAureonClient({
-  baseUrl: LOCAL_API_BASE_URL,
-  apiKey: env.AUREON_API_KEYS!.split(",")[0]!.trim(),
+  baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+  apiKey: requireEnv("AUREON_API_KEY"),
   getAccessToken: session.getAccessToken,
 });
 
@@ -100,8 +105,7 @@ for (const step of d.steps) {
 }
 
 const objs = await aureon.listObjectives();
-const obj =
-  objs.find((o) => o.name.includes("E2E 20% TSLA")) ?? objs[0];
+const obj = objs.find((o) => o.name.includes("E2E 20% TSLA")) ?? objs[0];
 if (!obj) throw new Error("no objective");
 console.log("using objective", obj.id, obj.name);
 

package/examples/e2e-policy-rebalance/verify-sizing.ts

@@ -1,9 +1,14 @@
 /**
- * Verify underweight Auto sizing lands near 20% (not 98%).
+ * Verify underweight Automatic sizing lands near 20% (not a blow-up fill).
+ *
+ * Env:
+ *   AUREON_API_KEY            issued developer key
+ *   AUREON_WALLET_PRIVATE_KEY 0x… signing key
+ *   AUREON_API_URL            optional (default https://api.aureonlabs.network)
+ *   AUREON_RPC_URL            optional
+ *   AUREON_CHAIN_ID           optional (default 46630)
  */
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+
 import {
   createPublicClient,
   createWalletClient,
@@ -15,38 +20,38 @@ import { privateKeyToAccount } from "viem/accounts";
 import {
   createAureonClient,
   createSessionTokenProvider,
-  LOCAL_API_BASE_URL,
+  DEFAULT_API_BASE_URL,
 } from "../../src/index.js";
 
-const BACKEND = join(dirname(fileURLToPath(import.meta.url)), "../../../backend");
-const env = Object.fromEntries(
-  readFileSync(join(BACKEND, ".env"), "utf8")
-    .split(/\r?\n/)
-    .filter((l) => l && !l.startsWith("#") && l.includes("="))
-    .map((l) => {
-      const i = l.indexOf("=");
-      return [l.slice(0, i), l.slice(i + 1).trim()] as const;
-    })
-);
-const key = JSON.parse(
-  readFileSync(join(BACKEND, ".secrets/robinhood-testnet-wallet.json"), "utf8")
-).privateKey as Hex;
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`Set ${name}`);
+  return value;
+}
+
+const key = requireEnv("AUREON_WALLET_PRIVATE_KEY") as Hex;
+if (!/^0x[0-9a-fA-F]{64}$/.test(key)) {
+  throw new Error("AUREON_WALLET_PRIVATE_KEY must be a 0x-prefixed 32-byte hex key");
+}
+
 const account = privateKeyToAccount(key);
-const rpc = env.AUREON_RPC_URL!;
-const chainId = Number(env.AUREON_CHAIN_ID || 46630);
+const rpc =
+  process.env.AUREON_RPC_URL?.trim() ||
+  "https://rpc.testnet.chain.robinhood.com";
+const chainId = Number(process.env.AUREON_CHAIN_ID || 46630);
 const publicClient = createPublicClient({ transport: http(rpc) });
 const walletClient = createWalletClient({ account, transport: http(rpc) });
 const chain = {
   id: chainId,
-  name: "rh",
+  name: "Robinhood Chain Testnet",
   nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
   rpcUrls: { default: { http: [rpc] } },
 } as const;
 
 const session = createSessionTokenProvider(null);
 const aureon = createAureonClient({
-  baseUrl: LOCAL_API_BASE_URL,
-  apiKey: env.AUREON_API_KEYS!.split(",")[0]!.trim(),
+  baseUrl: process.env.AUREON_API_URL?.trim() || DEFAULT_API_BASE_URL,
+  apiKey: requireEnv("AUREON_API_KEY"),
   getAccessToken: session.getAccessToken,
 });
 
@@ -61,7 +66,6 @@ session.setToken(
   ).token
 );
 
-// Fresh Auto objective
 const objective = await aureon.createObjective({
   name: `SizeFix 20% TSLA ${Date.now()}`,
   kind: "balanced_portfolio",
@@ -73,7 +77,6 @@ const objective = await aureon.createObjective({
 });
 console.log("objective", objective.id);
 
-// Dump almost all TSLA so we're heavily underweight, keep/add WETH
 const vault = await aureon.getVault();
 console.log(
   "before",
@@ -138,7 +141,7 @@ console.log("health after", {
 });
 
 const weightPct = (h2.currentMetric ?? 0) * 100;
-const ok = weightPct >= 5 && weightPct <= 45; // near 20% with band (was ~98% before)
+const ok = weightPct >= 5 && weightPct <= 45;
 console.log(
   ok
     ? `PASS sizing : TSLA weight ~${weightPct.toFixed(1)}% (want ~20%)`