@buildaureon/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,792 @@
+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;
+}
+declare const silentLogger: AureonLogger;
+declare function createConsoleLogger(prefix?: string): AureonLogger;
+
+/**
+ * @fileoverview Client configuration types for AureonClient.
+ */
+
+interface AureonClientOptions {
+    /**
+     * Base URL of the AUREON API.
+     * Defaults to `https://api.aureonlabs.network`.
+     */
+    baseUrl?: string;
+    /**
+     * Product API key sent as `X-Aureon-Api-Key` on every request.
+     * Required for SDK / CLI / code when keys are enforced and there is no
+     * wallet Bearer yet. The operator utility uses wallet Bearer only.
+     */
+    apiKey?: string | null;
+    /**
+     * Called before each request to resolve the product API key.
+     * Prefer this for automations that load keys from env or a secret store.
+     */
+    getApiKey?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Optional fetch implementation for non-browser runtimes. */
+    fetch?: typeof fetch;
+    /** Optional default headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeoutMs?: number;
+    /**
+     * Static Bearer session token. Prefer `getAccessToken` for apps that refresh
+     * or clear sessions at runtime.
+     */
+    authToken?: string | null;
+    /**
+     * Called before each request to resolve the current Bearer token.
+     * Return null/undefined to send the request without Authorization.
+     */
+    getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Optional structured logger for request lifecycle diagnostics. */
+    logger?: AureonLogger;
+    /**
+     * Extra attempts after the first failure for retryable errors
+     * (network, timeout, 429, 5xx). Defaults to 0.
+     */
+    maxRetries?: number;
+    /** Delay in ms between retries. Defaults to 250. */
+    retryDelayMs?: number;
+}
+
+/**
+ * @fileoverview Execution receipt + restore-plan types.
+ *
+ * Receipts may settle as vault on-chain rebalance (`settlement: "vault"`) or
+ * as a staged capital-book update (`settlement: "staged"`) when the vault
+ * path is unavailable. Wrap/unwrap ETH↔WETH is client-side via RestorePlan.
+ */
+interface ExecutionReceipt {
+    id: string;
+    objectiveId: string;
+    status: "pending" | "submitted" | "confirmed" | "failed";
+    transactionHash: string;
+    action: string;
+    notionalAdjustedUsd: number;
+    result: string;
+    createdAt: string;
+    confirmedAt: string | null;
+    /**
+     * `"vault"`: keeper rebalance confirmed (or pending_vault_* then confirmed).
+     * `"staged"`: capital-book restore only (honest non-finality label).
+     */
+    settlement?: "staged" | "vault";
+}
+/** Client-side restore action: wrap/unwrap ETH↔WETH or keeper vault swap. */
+type RestorePlanKind = "wrap_eth" | "unwrap_weth" | "vault_swap";
+interface RestorePlan {
+    kind: RestorePlanKind;
+    amountHuman: string;
+    approxUsd: number;
+    message: string;
+    sellSymbol?: string;
+    buySymbol?: string;
+}
+/** True when the receipt claims vault (on-chain) settlement. */
+declare function isVaultSettlement(receipt: ExecutionReceipt): boolean;
+
+/**
+ * @fileoverview Health Engine result types.
+ */
+type HealthState = "healthy" | "warning" | "violation" | "paused";
+interface ObjectiveHealth {
+    objectiveId: string;
+    state: HealthState;
+    score: number;
+    currentMetric: number;
+    targetMetric: number;
+    deviation: number;
+    message: string;
+    evaluatedAt: string;
+}
+declare function isHealthState(value: string): value is HealthState;
+declare function pickWorstHealth(records: ObjectiveHealth[]): ObjectiveHealth | null;
+
+/**
+ * @fileoverview Timeline event contracts for append-only operator narratives.
+ */
+type TimelineEventType = "objective_created" | "objective_updated" | "objective_paused" | "objective_resumed" | "health_changed" | "violation_detected" | "evaluation_started" | "execution_started" | "execution_completed" | "market_event_applied" | "objective_restored" | "capital_provisioned" | "capital_cleared" | "capital_synced";
+interface TimelineEvent {
+    id: string;
+    objectiveId: string | null;
+    type: TimelineEventType;
+    message: string;
+    payload: Record<string, unknown>;
+    createdAt: string;
+}
+declare const TIMELINE_EVENT_TYPES: readonly TimelineEventType[];
+declare function isTimelineEventType(value: string): value is TimelineEventType;
+
+/**
+ * @fileoverview Controlled market event types for operator demos and rehearsals.
+ */
+interface MarketEvent {
+    id: string;
+    name: string;
+    description: string;
+    symbol: string;
+    priceChangeRatio: number;
+    appliedAt: string;
+}
+interface MarketPreset {
+    name: string;
+    description: string;
+    symbol: string;
+    priceChangeRatio: number;
+}
+interface ApplyMarketEventInput {
+    name?: string;
+    description?: string;
+    symbol: string;
+    priceChangeRatio: number;
+    autoRestore?: boolean;
+}
+interface DashboardOverview {
+    activeObjectives: number;
+    healthyCount: number;
+    warningCount: number;
+    violationCount: number;
+    pausedCount: number;
+    totalNotionalUsd: number;
+    stableWeight: number;
+    /** Holdings count from the capital book. */
+    assetCount: number;
+    /** Absolute USD change vs prior UTC day snapshot; null when baseline only. */
+    change24hUsd: number | null;
+    /** Fractional change (0.05 = +5%); null when baseline only. */
+    change24hPct: number | null;
+    /** True when no prior-day snapshot exists yet. */
+    change24hBaselineOnly: boolean;
+    /** True when today's snapshot row exists. */
+    change24hHasSnapshot: boolean;
+    /** Average health score across non-paused objectives; null when none. */
+    globalHealthScore: number | null;
+    /** Persisted health samples (oldest → newest), up to ~90 days. */
+    healthHistory: Array<{
+        at: string;
+        score: number;
+    }>;
+    /** warning + violation count. */
+    attentionCount: number;
+    /** Last successful live-mark watchdog evaluation (not overview poll). */
+    lastEvaluationAt: string | null;
+    /** lastEvaluationAt + watchdog interval when continuous monitor is configured. */
+    nextEvaluationAt: string | null;
+    watchdogIntervalMs: number | null;
+    /** Last background/manual watchdog failure message, if any. */
+    lastWatchdogError: string | null;
+    lastSyncedAt: string | null;
+    recentExecutions: ExecutionReceipt[];
+    recentEvents: TimelineEvent[];
+}
+
+/**
+ * @fileoverview Objective domain types for Financial Compass Objectives.
+ */
+/** Lifecycle status for a Financial Compass Objective (FCO). */
+type ObjectiveStatus = "draft" | "validated" | "active" | "paused" | "cancelled" | "completed";
+/** Supported objective kinds for Phase 1 operator workflows. */
+type ObjectiveKind = "stable_allocation" | "balanced_portfolio" | "risk_ceiling" | "reward_reinvestment";
+/** Priority influences evaluation ordering when multiple objectives compete. */
+type ObjectivePriority = "low" | "medium" | "high" | "critical";
+/**
+ * Per-objective restore behaviour as stored on the API.
+ *
+ * SDK / agent integrations create objectives as **Automatic** (default).
+ * `"manual"` exists so the operator utility can require an Approve click;
+ * it is not part of the recommended SDK integration path.
+ */
+type ObjectiveAutomationMode = "manual" | "auto";
+/** Policy rules attached to an objective. */
+interface ObjectivePolicy {
+    targetWeight: number;
+    tolerance: number;
+    maxRiskScore?: number;
+    reinvestRatio?: number;
+    /** Holding symbol when the objective tracks a specific asset weight. */
+    targetSymbol?: string;
+    summary: string;
+}
+/** Financial Compass Objective record. */
+interface Objective {
+    id: string;
+    name: string;
+    kind: ObjectiveKind;
+    status: ObjectiveStatus;
+    priority: ObjectivePriority;
+    /**
+     * Restore mode for this objective.
+     * SDK creates always set `"auto"`. `"manual"` is operator-utility only.
+     */
+    automationMode: ObjectiveAutomationMode;
+    policy: ObjectivePolicy;
+    ownerId: string;
+    createdAt: string;
+    updatedAt: string;
+    lastEvaluatedAt: string | null;
+    lastExecutionId: string | null;
+}
+/**
+ * Input for creating a new objective.
+ *
+ * SDK create always sends `automationMode: "auto"` (Automatic restore).
+ * Manual Approve is an operator-utility concern; do not rely on it in
+ * agent / SDK loops.
+ */
+interface CreateObjectiveInput {
+    name: string;
+    kind: ObjectiveKind;
+    priority?: ObjectivePriority;
+    targetWeight: number;
+    tolerance: number;
+    maxRiskScore?: number;
+    reinvestRatio?: number;
+    targetSymbol?: string | null;
+    /**
+     * @deprecated For SDK integrations omit this; create always uses Automatic.
+     * The operator utility may still pass `"manual"` for Approve UX.
+     */
+    automationMode?: ObjectiveAutomationMode;
+}
+/** Partial update for an existing objective. */
+interface UpdateObjectiveInput {
+    name?: string;
+    priority?: ObjectivePriority;
+    targetWeight?: number;
+    tolerance?: number;
+    maxRiskScore?: number;
+    reinvestRatio?: number;
+    targetSymbol?: string | null;
+    /**
+     * @deprecated Rejected on update; mode is fixed at create to avoid restore-flow issues.
+     * Recreate the objective to switch Manual ↔ Automatic.
+     */
+    automationMode?: never;
+}
+declare const OBJECTIVE_KINDS: readonly ObjectiveKind[];
+declare const OBJECTIVE_PRIORITIES: readonly ObjectivePriority[];
+declare function isObjectiveKind(value: string): value is ObjectiveKind;
+declare function isObjectivePriority(value: string): value is ObjectivePriority;
+
+/**
+ * @fileoverview Portfolio snapshot types used by health evaluation and utility screens.
+ */
+interface PortfolioPosition {
+    id: string;
+    symbol: string;
+    name: string;
+    category: "stable" | "stock_token" | "gas" | "other";
+    quantity: number;
+    markPriceUsd: number;
+    notionalUsd: number;
+    weight: number;
+    updatedAt: string;
+}
+interface PortfolioSnapshot {
+    portfolioId: string;
+    totalNotionalUsd: number;
+    stableWeight: number;
+    stockTokenWeight: number;
+    gasWeight: number;
+    positions: PortfolioPosition[];
+    asOf: string;
+}
+/** Input row for replacing the capital book (no id, server assigns). */
+interface PortfolioPositionInput {
+    symbol: string;
+    name: string;
+    category: PortfolioPosition["category"];
+    quantity: number;
+    markPriceUsd: number;
+}
+
+/**
+ * @fileoverview Vault overview + prepare-tx contracts for AureonVault.
+ *
+ * Reads come from GET /vault and GET /vault/status.
+ * Writes are wallet-signed: prepareDeposit / prepareWithdraw return calldata
+ * steps; the host (or agent signer) broadcasts them; the API never holds
+ * user keys.
+ */
+/** Allowlisted vault token metadata from GET /vault. */
+interface VaultToken {
+    symbol: string;
+    name: string;
+    address: string;
+    decimals: number;
+    category?: string;
+}
+/** Per-token vault balance for the session wallet. */
+interface VaultBalance {
+    symbol: string;
+    name: string;
+    /** ERC-20 token address held inside the vault accounting. */
+    token: string;
+    decimals: number;
+    category?: string;
+    /** Raw integer amount as a decimal string (wei / token base units). */
+    raw: string;
+    quantity: number;
+    markPriceUsd: number | null;
+    notionalUsd: number | null;
+}
+/** Full vault overview for the authenticated wallet. */
+interface VaultOverview {
+    address: string;
+    chainId: number;
+    tokens: VaultToken[];
+    balances: VaultBalance[];
+    poolAddress: string | null;
+    explorerBase: string;
+    keeperAddress: string | null;
+}
+/** Compact funding signal used before restore. */
+interface VaultStatus {
+    empty: boolean;
+    totalNotionalUsd: number;
+    canRestore: boolean;
+}
+/** One wallet-signed step from prepareDeposit / prepareWithdraw. */
+interface VaultPreparedStep {
+    to: string;
+    data: string;
+    /** Native wei as a decimal string (`"0"` for ERC-20 paths). */
+    value: string;
+    functionName: "approve" | "deposit" | "depositETH" | "withdraw";
+    label: string;
+}
+/**
+ * Calldata plan for vault deposit or withdraw.
+ * Sign `steps` in order with the session wallet (and matching `chainId`).
+ */
+interface VaultPrepareResult {
+    chainId: number;
+    vaultAddress: string;
+    explorerBase: string;
+    symbol: string;
+    amountRaw: string;
+    amountHuman: string;
+    steps: VaultPreparedStep[];
+}
+/** Native ETH or any allowlisted vault ERC-20 symbol (WETH, stables, …). */
+type VaultDepositSymbol = string;
+/** Any allowlisted vault ERC-20 (not native ETH, use WETH). */
+type VaultWithdrawSymbol = string;
+
+/**
+ * @fileoverview Watchdog contracts: live marks, breaches, restore suggestions.
+ */
+
+type MarkQuoteSource = "peg" | "coingecko" | "yahoo" | "unchanged";
+interface MarkQuote {
+    symbol: string;
+    priceUsd: number;
+    source: MarkQuoteSource;
+}
+interface RestoreSuggestionAction {
+    side: "buy" | "sell";
+    symbol: string;
+    quantity: number;
+    approxUsd: number;
+}
+interface RestoreSuggestion {
+    objectiveId: string;
+    objectiveName: string;
+    targetStableWeight: number;
+    currentStableWeight: number;
+    deltaStableUsd: number;
+    actions: RestoreSuggestionAction[];
+    note: string;
+}
+interface WatchdogAlertResult {
+    objectiveId: string;
+    sent: boolean;
+    reason?: string;
+}
+interface WatchdogRefreshResult {
+    refreshedAt: string;
+    quotes: MarkQuote[];
+    skippedSymbols: string[];
+    portfolio: PortfolioSnapshot;
+    health: ObjectiveHealth[];
+    breaches: ObjectiveHealth[];
+    suggestions: RestoreSuggestion[];
+    alerts: WatchdogAlertResult[];
+}
+
+/**
+ * @fileoverview AureonClient: primary entry point for @buildaureon/sdk.
+ *
+ * Typed HTTP client for the hosted AUREON API. Wallet Bearer sessions identify
+ * the operator; `apiKey` (`X-Aureon-Api-Key`) unlocks product access.
+ *
+ * Objectives default to Automatic automation mode. Vault deposit and withdraw
+ * are prepare-calldata steps for wallet signing; not server-side broadcasts.
+ * Restorative execution receipts may use `settlement: "vault"` or
+ * `settlement: "staged"` depending on the restore path.
+ */
+
+interface AuthNonceResponse {
+    walletAddress: string;
+    nonce: string;
+    message: string;
+    expiresAt: string;
+}
+interface AuthSessionResponse {
+    token: string;
+    walletAddress: string;
+    expiresAt: string;
+    sessionId: string;
+    mode?: string;
+}
+interface AuthMeResponse {
+    walletAddress: string;
+}
+interface SyncPortfolioResult {
+    portfolio: PortfolioSnapshot;
+    chainId: number;
+    skippedZero: string[];
+}
+interface DeveloperApiKey {
+    id: string;
+    name: string;
+    prefix: string;
+    status: string;
+    createdAt: string;
+    revokedAt: string | null;
+}
+interface CreatedDeveloperApiKey extends DeveloperApiKey {
+    /** Plaintext secret; only returned once at creation. */
+    secret: string;
+}
+/**
+ * High-level SDK client for AUREON operator and developer integrations.
+ */
+declare class AureonClient {
+    private readonly transport;
+    constructor(options?: AureonClientOptions);
+    /** Returns the resolved API base URL. */
+    get baseUrl(): string;
+    /** Health probe for connectivity checks. No auth required. */
+    ping(): Promise<{
+        ok: true;
+        service: string;
+        version: string;
+    }>;
+    /**
+     * Requests a single-use wallet auth nonce/message for the given address.
+     * No Bearer token required.
+     */
+    getAuthNonce(address: string): Promise<AuthNonceResponse>;
+    /**
+     * Verifies a wallet signature and returns a Bearer session.
+     * No Bearer token required on the request itself.
+     */
+    verifyWallet(input: {
+        address: string;
+        message: string;
+        signature: string;
+    }): Promise<AuthSessionResponse>;
+    /**
+     * Local preview login without a wallet signature.
+     * Only succeeds when the backend has `AUREON_ALLOW_DEV_LOGIN=1`.
+     */
+    devLogin(): Promise<AuthSessionResponse>;
+    /** Revokes the current Bearer session on the server. */
+    logout(): Promise<{
+        ok: true;
+    }>;
+    /** Returns the wallet bound to the current Bearer session. Auth required. */
+    me(): Promise<AuthMeResponse>;
+    /**
+     * Creates and activates a Financial Compass Objective (FCO).
+     * SDK / agent path always prefers Automatic (`automationMode` omitted → `"auto"`).
+     * Mode cannot be changed later via `updateObjective`; recreate instead.
+     * Passing `"manual"` is reserved for the operator utility Approve UX.
+     * Auth required.
+     */
+    createObjective(input: CreateObjectiveInput): Promise<Objective>;
+    /** Lists objectives for the authenticated wallet. Auth required. */
+    listObjectives(): Promise<Objective[]>;
+    /** Fetches a single objective by id. Auth required. */
+    getObjective(id: string): Promise<Objective>;
+    /**
+     * Applies a partial update to an objective policy or metadata.
+     * Does **not** accept `automationMode` (mode is locked at create).
+     * Auth required.
+     */
+    updateObjective(id: string, input: UpdateObjectiveInput): Promise<Objective>;
+    /** Pauses continuous evaluation for an objective. Auth required. */
+    pauseObjective(id: string): Promise<Objective>;
+    /** Resumes evaluation for a paused objective. Auth required. */
+    resumeObjective(id: string): Promise<Objective>;
+    /** Returns health for one objective or all objectives when id is omitted. Auth required. */
+    getHealth(objectiveId?: string): Promise<ObjectiveHealth[]>;
+    /** Returns timeline events, optionally filtered by objective. Auth required. */
+    getTimeline(objectiveId?: string): Promise<TimelineEvent[]>;
+    /** Returns the current portfolio snapshot for the wallet. Auth required. */
+    getPortfolio(): Promise<PortfolioSnapshot>;
+    /**
+     * Replaces the wallet capital book with the provided positions.
+     * Auth required. Does not invent holdings: every row must be supplied.
+     */
+    setPortfolio(positions: PortfolioPositionInput[]): Promise<PortfolioSnapshot>;
+    /**
+     * Clears all capital-book positions for the authenticated wallet.
+     * Auth required. Does not invent seeded holdings.
+     */
+    clearPortfolio(): Promise<PortfolioSnapshot>;
+    /**
+     * Replaces the capital book with on-chain balances for the session wallet
+     * (Robinhood Chain via the AUREON API). Vault balances merge into the book.
+     * Requires a wallet Bearer session; SDK clients should also send an API key
+     * when keys are enforced. Does not invent holdings; only positive balances
+     * returned by the API.
+     */
+    syncPortfolio(): Promise<SyncPortfolioResult>;
+    /**
+     * Refreshes portfolio marks from live public market data, re-evaluates
+     * objectives, optionally fires breach webhooks, and returns restore suggestions.
+     * Auth required.
+     */
+    refreshWatchdog(): Promise<WatchdogRefreshResult>;
+    /** Returns dashboard overview aggregates. Auth required. */
+    getOverview(): Promise<DashboardOverview>;
+    /**
+     * Applies a controlled market event to portfolio marks.
+     * When autoRestore is true, the API evaluates health and may run staged restorative execution.
+     * Auth required.
+     */
+    applyMarketEvent(input: ApplyMarketEventInput): Promise<{
+        event: MarketEvent;
+        portfolio: PortfolioSnapshot;
+        health: ObjectiveHealth[];
+        executions: ExecutionReceipt[];
+    }>;
+    /** Lists controlled market event presets. Auth required. */
+    listMarketPresets(): Promise<MarketPreset[]>;
+    /**
+     * Returns the restore plan for an objective (wrap ETH, unwrap WETH, or vault swap).
+     * Auth required.
+     */
+    getRestorePlan(objectiveId: string): Promise<RestorePlan>;
+    /**
+     * Runs restorative execution for an objective currently outside policy.
+     * Vault Sell A→Buy B when configured. ETH↔WETH wrap/unwrap is client-side
+     * via getRestorePlan; this endpoint rejects those with action details.
+     * Auth required.
+     */
+    runExecution(objectiveId: string): Promise<ExecutionReceipt>;
+    /**
+     * Runs vault-backed restorative execution for an objective outside policy.
+     * Auth required.
+     */
+    restoreObjective(objectiveId: string): Promise<ExecutionReceipt>;
+    /** Lists recent execution receipts. Auth required. */
+    listExecutions(objectiveId?: string): Promise<ExecutionReceipt[]>;
+    /** Returns the vault overview for the authenticated wallet. Auth required. */
+    getVault(): Promise<VaultOverview>;
+    /** Returns compact vault funding status before restore. Auth required. */
+    getVaultStatus(): Promise<VaultStatus>;
+    /**
+     * Prepares wallet-signed calldata steps for a vault deposit.
+     * Auth required.
+     */
+    prepareVaultDeposit(input: {
+        symbol: VaultDepositSymbol;
+        amount: string;
+    }): Promise<VaultPrepareResult>;
+    /**
+     * Prepares wallet-signed calldata steps for a vault withdraw (any allowlisted ERC-20).
+     * Auth required.
+     */
+    prepareVaultWithdraw(input: {
+        symbol?: string;
+        amount: string;
+    }): Promise<VaultPrepareResult>;
+    /**
+     * Lists SDK API keys for the authenticated wallet.
+     * Used by the operator utility Developer page.
+     */
+    listApiKeys(): Promise<DeveloperApiKey[]>;
+    /**
+     * Creates an SDK API key. `secret` is returned once; store it immediately.
+     */
+    createApiKey(name: string): Promise<CreatedDeveloperApiKey>;
+    /** Revokes (deletes) an SDK API key owned by this wallet. */
+    revokeApiKey(keyId: string): Promise<DeveloperApiKey>;
+    /** Toggles the status (active/paused) of an SDK API key owned by this wallet. */
+    toggleApiKey(keyId: string): Promise<DeveloperApiKey>;
+}
+
+/**
+ * @fileoverview Factory helpers for constructing AureonClient instances.
+ */
+
+/**
+ * Factory helper preferred by examples and quickstarts.
+ * Defaults to the production AUREON API URL when `baseUrl` is omitted.
+ */
+declare function createAureonClient(options?: AureonClientOptions): AureonClient;
+/**
+ * Creates a client pointed at a local AUREON API process (monorepo operators).
+ * Not advertised in the public README.
+ */
+declare function createLocalAureonClient(overrides?: Partial<AureonClientOptions>): AureonClient;
+
+/**
+ * @fileoverview Mutable bearer token holder for scripts and apps.
+ */
+/** Mutable bearer token holder for scripts and apps. */
+declare function createSessionTokenProvider(initialToken?: string | null): {
+    getAccessToken: () => string | null;
+    setToken: (next: string | null) => void;
+    clear: () => void;
+};
+type SessionTokenProvider = ReturnType<typeof createSessionTokenProvider>;
+
+/**
+ * @fileoverview Stable machine-readable error codes for @buildaureon/sdk.
+ */
+type AureonErrorCode = "NETWORK_ERROR" | "TIMEOUT" | "VALIDATION_ERROR" | "NOT_FOUND" | "CONFLICT" | "UNAUTHORIZED" | "RATE_LIMITED" | "SERVER_ERROR" | "UNEXPECTED_RESPONSE" | "ABORTED";
+
+/**
+ * @fileoverview Base and specialized error classes for the AUREON SDK.
+ */
+
+declare class AureonError extends Error {
+    readonly code: AureonErrorCode;
+    readonly status: number | null;
+    readonly details: Record<string, unknown> | null;
+    constructor(message: string, code: AureonErrorCode, status?: number | null, details?: Record<string, unknown> | null);
+    get retryable(): boolean;
+    toJSON(): Record<string, unknown>;
+}
+declare class AureonValidationError extends AureonError {
+    constructor(message: string, details?: Record<string, unknown> | null);
+}
+declare class AureonNotFoundError extends AureonError {
+    constructor(message: string, details?: Record<string, unknown> | null);
+}
+declare class AureonConflictError extends AureonError {
+    constructor(message: string, details?: Record<string, unknown> | null);
+}
+declare class AureonNetworkError extends AureonError {
+    constructor(message: string, details?: Record<string, unknown> | null);
+}
+declare class AureonTimeoutError extends AureonError {
+    constructor(message?: string, details?: Record<string, unknown> | null);
+}
+
+/**
+ * @fileoverview Maps HTTP responses into typed AureonError instances.
+ */
+
+declare function errorFromHttpStatus(status: number, body: unknown): AureonError;
+declare function isAureonError(value: unknown): value is AureonError;
+
+/**
+ * @fileoverview Validation and normalization for objective create/update payloads.
+ */
+
+declare function buildPolicySummary(kind: CreateObjectiveInput["kind"], targetWeight: number, tolerance: number): string;
+declare function normalizeCreateObjectiveInput(input: CreateObjectiveInput): CreateObjectiveInput;
+declare function normalizeUpdateObjectiveInput(input: UpdateObjectiveInput): UpdateObjectiveInput;
+
+/**
+ * @fileoverview Display helpers shared by utility apps and CLI output.
+ */
+
+declare function formatUsd(value: number): string;
+declare function formatWeight(weight: number): string;
+declare function healthTone(state: HealthState): "positive" | "caution" | "critical" | "neutral";
+declare function formatSignedPercent(ratio: number): string;
+declare function formatIsoTime(iso: string): string;
+
+/**
+ * @fileoverview JSON HTTP transport used by AureonClient.
+ */
+
+interface TransportOptions {
+    baseUrl: string;
+    fetchImpl: typeof fetch;
+    headers: Record<string, string>;
+    timeoutMs: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    logger?: AureonLogger;
+    getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    getApiKey?: () => string | null | undefined | Promise<string | null | undefined>;
+}
+interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+declare function requestJson<T>(transport: TransportOptions, path: string, options?: RequestOptions): Promise<T>;
+
+/**
+ * @fileoverview URL helpers for the AUREON HTTP transport.
+ */
+declare function joinUrl(baseUrl: string, path: string): string;
+declare function assertBaseUrl(baseUrl: string): string;
+declare function withQuery(path: string, query: Record<string, string | undefined>): string;
+
+/**
+ * @fileoverview Default runtime values for SDK clients and examples.
+ */
+/** Production AUREON API (public integrators). */
+declare const DEFAULT_API_BASE_URL = "https://api.aureonlabs.network";
+/** Local monorepo preview only; not for public docs. */
+declare const LOCAL_API_BASE_URL = "http://127.0.0.1:8787";
+declare const DEFAULT_TIMEOUT_MS = 30000;
+declare const SDK_VERSION = "0.1.0";
+declare const SDK_NAME = "@buildaureon/sdk";
+declare const PRODUCT_NAME = "AUREON";
+declare const PRODUCT_TAGLINE = "Financial Compass for Robinhood Chain";
+/** HTTP header for product API keys. */
+declare const API_KEY_HEADER = "X-Aureon-Api-Key";
+
+/**
+ * @fileoverview API path constants for AureonClient methods.
+ */
+declare const ENDPOINTS: {
+    readonly healthz: "/healthz";
+    readonly overview: "/overview";
+    readonly portfolio: "/portfolio";
+    readonly portfolioClear: "/portfolio/clear";
+    readonly portfolioSync: "/portfolio/sync";
+    readonly watchdogRefresh: "/watchdog/refresh";
+    readonly objectives: "/objectives";
+    readonly health: "/health";
+    readonly timeline: "/timeline";
+    readonly executions: "/executions";
+    readonly executionsRun: "/executions/run";
+    readonly marketEvents: "/market/events";
+    readonly marketPresets: "/market/presets";
+    readonly vault: "/vault";
+    readonly vaultStatus: "/vault/status";
+    readonly vaultPrepareDeposit: "/vault/prepare-deposit";
+    readonly vaultPrepareWithdraw: "/vault/prepare-withdraw";
+    readonly authNonce: "/auth/nonce";
+    readonly authVerify: "/auth/verify";
+    readonly authLogout: "/auth/logout";
+    readonly authDevLogin: "/auth/dev-login";
+    readonly authMe: "/auth/me";
+    readonly developerApiKeys: "/developer/api-keys";
+};
+
+/**
+ * @fileoverview Fetch adapter helpers for browser and Node runtimes.
+ */
+type FetchLike = typeof fetch;
+declare function resolveFetch(custom?: FetchLike): FetchLike;
+
+export { API_KEY_HEADER, type ApplyMarketEventInput, AureonClient, type AureonClientOptions, AureonConflictError, AureonError, type AureonErrorCode, AureonNetworkError, AureonNotFoundError, AureonTimeoutError, AureonValidationError, type AuthMeResponse, type AuthNonceResponse, type AuthSessionResponse, type CreateObjectiveInput, type CreatedDeveloperApiKey, DEFAULT_API_BASE_URL, DEFAULT_TIMEOUT_MS, type DashboardOverview, type DeveloperApiKey, ENDPOINTS, type ExecutionReceipt, type HealthState, LOCAL_API_BASE_URL, type MarkQuote, type MarkQuoteSource, type MarketEvent, type MarketPreset, OBJECTIVE_KINDS, OBJECTIVE_PRIORITIES, type Objective, type ObjectiveAutomationMode, type ObjectiveHealth, type ObjectiveKind, type ObjectivePolicy, type ObjectivePriority, type ObjectiveStatus, PRODUCT_NAME, PRODUCT_TAGLINE, type PortfolioPosition, type PortfolioPositionInput, type PortfolioSnapshot, type RestorePlan, type RestorePlanKind, type RestoreSuggestion, type RestoreSuggestionAction, SDK_NAME, SDK_VERSION, type SessionTokenProvider, type SyncPortfolioResult, TIMELINE_EVENT_TYPES, type TimelineEvent, type TimelineEventType, type UpdateObjectiveInput, type VaultBalance, type VaultDepositSymbol, type VaultOverview, type VaultPrepareResult, type VaultPreparedStep, type VaultStatus, type VaultToken, type VaultWithdrawSymbol, type WatchdogAlertResult, type WatchdogRefreshResult, assertBaseUrl, buildPolicySummary, createAureonClient, createConsoleLogger, createLocalAureonClient, createSessionTokenProvider, errorFromHttpStatus, formatIsoTime, formatSignedPercent, formatUsd, formatWeight, healthTone, isAureonError, isHealthState, isObjectiveKind, isObjectivePriority, isTimelineEventType, isVaultSettlement, joinUrl, normalizeCreateObjectiveInput, normalizeUpdateObjectiveInput, pickWorstHealth, requestJson, resolveFetch, silentLogger, withQuery };