@aetherwealth/sdk 0.1.32

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aether Wealth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @aetherwealth/sdk
+
+Typed TypeScript client for the **Aether Wealth** public API. Programmatic
+access to your trading journal, accounts, analytics, alerts, market data, and
+diary over the public REST surface (`/api/public/v1/…`).
+
+> **Keep your API key secret.** Authentication uses a public API key
+> (`aw_live_…`) sent as a bearer token. Treat it like a password — never commit
+> it or ship it to an untrusted client.
+
+## Install
+
+```bash
+npm install @aetherwealth/sdk
+```
+
+## Quickstart
+
+```ts
+import { AetherClient } from '@aetherwealth/sdk'
+
+const client = new AetherClient({
+  auth: { type: 'apiKey', apiKey: process.env.AETHER_API_KEY! },
+  // baseUrl defaults to the production API (https://api.aetherwealth.ai).
+  // Set it only to target staging or a local dev backend.
+})
+
+// Every call is authenticated with your API key.
+const { data: openTrades } = await client.trades.list({ status: 'OPEN' })
+const stats = await client.stats.summary({ pair: 'EURUSD' })
+```
+
+## Authentication
+
+Each request sends your public API key as `Authorization: Bearer <apiKey>`. The
+key scopes every operation to its owner — you never pass `userId` in a request
+body. `auth` is a discriminated union (one member today, `apiKey`) so future
+auth modes can be added without breaking existing callers.
+
+```ts
+new AetherClient({
+  baseUrl,
+  auth: { type: 'apiKey', apiKey },
+  fetchImpl,             // optional — inject a custom fetch (tests, proxies)
+  userAgent,             // optional
+  timeoutMs: 30_000,     // optional — per-request timeout (default 30s; 0 disables)
+  validateResponses: false, // optional — opt-in Zod validation of responses
+  dangerouslyAllowBrowser: false, // optional — see "Browser use" below
+  onRequest, onResponse, // optional diagnostics hooks
+})
+```
+
+The diagnostics hooks receive only `{ method, url, status, ms }` — your API key
+travels solely on the `Authorization` header and never appears in a hook
+payload, a thrown error, or the request URL.
+
+### Browser use is blocked by default
+
+The API key is a **server-side secret**. Constructing the client in a
+browser-like environment (`window.document` present) throws — a key shipped to a
+browser is visible in the bundle and DevTools and must be treated as public.
+Call the API from your server. If you are certain you are in a trusted
+non-browser runtime that happens to define `window`, set
+`dangerouslyAllowBrowser: true` (mirrors the OpenAI SDK).
+
+## Resources
+
+| Resource | Methods |
+| --- | --- |
+| `client.trades` | `list` · `get` · `create` · `update` · `close` · `delete` · `pages` · `listAll` |
+| `client.accounts` | `list` · `create` · `update` · `delete` · `trades` · `tradesAll` |
+| `client.stats` | `summary` |
+| `client.alerts` | `list` · `createPrice` · `createTrendline` · `update` · `delete` · `listIndicator` · `createIndicator` · `updateIndicator` · `deleteIndicator` |
+| `client.market` | `config` · `calendar` · `macroSeries` · `macro` |
+| `client.diary` | `list` · `get` · `upsert` · `delete` · `pages` · `listAll` |
+
+List methods return `{ data, pagination }`; single-item methods return the
+object directly. All response fields are camelCase.
+
+## Pagination
+
+`pages()` and `listAll()` async-iterate a paginated resource, auto-advancing
+`page` until the last page (or an empty page), with an infinite-loop backstop:
+
+```ts
+// One page at a time (keeps pagination metadata):
+for await (const page of client.trades.pages({ status: 'CLOSED', limit: 100 })) {
+  console.log(page.pagination.page, page.data.length)
+}
+
+// Every item, flattened across all pages:
+for await (const trade of client.trades.listAll({ pair: 'EURUSD' })) {
+  handle(trade)
+}
+
+// Also: client.diary.pages/listAll and client.accounts.tradesAll(accountId)
+```
+
+Iteration starts at `query.page` if given, else page 1.
+
+## Timeouts & cancellation
+
+Every request is bounded by `timeoutMs` (default 30s), overridable per call. A
+timeout aborts the request and rejects with `AetherTimeoutError` (a subclass of
+`AetherNetworkError`, so it's retryable and caught by existing network-error
+handlers). You can also pass your own `AbortSignal` — the request aborts when
+either the timeout or your signal fires:
+
+```ts
+// Client-wide default (30s) or a per-request override via the low-level request():
+const slow = new AetherClient({ baseUrl, auth, timeoutMs: 60_000 })
+await client.request('/api/public/v1/trades/list', { method: 'POST', body: {}, timeoutMs: 5_000 })
+
+// Caller cancellation (e.g. a UI "cancel" button or request budget):
+const controller = new AbortController()
+setTimeout(() => controller.abort(new Error('cancelled')), 1_000)
+await client.request('/api/public/v1/stats/stats', { method: 'POST', body: {}, signal: controller.signal })
+```
+
+A timeout throws `AetherTimeoutError`; a caller-initiated abort surfaces your
+signal's own reason (it is *not* treated as a transient error to retry).
+
+## Idempotency & safe retries
+
+Each create — `trades.create`, `accounts.create`, `alerts.createPrice`,
+`alerts.createTrendline`, `alerts.createIndicator` — sends an `Idempotency-Key`
+header so a create that the server committed but whose response you never saw
+won't duplicate on a re-send. If you don't pass one, the SDK generates a fresh
+key **per call**:
+
+```ts
+await client.trades.create(input) // auto Idempotency-Key, protects this one call
+```
+
+An auto per-call key protects a single invocation. It does **not** make a create
+retry-safe: a new key each attempt means the backend can't dedup. To retry a
+create safely, pass a **stable** key so every attempt targets the same record:
+
+```ts
+import { withRetry } from '@aetherwealth/sdk'
+
+const idempotencyKey = crypto.randomUUID() // generated ONCE, outside the retry
+const trade = await withRetry(
+  () => client.trades.create(input, { idempotencyKey }),
+  { maxAttempts: 3 },
+)
+```
+
+> Do **not** generate the key inside the retried closure — each attempt would
+> get a different key and dedup would be lost. `withRetry` only retries
+> transient failures (`AetherRateLimitError`, `AetherNetworkError`,
+> `AetherTimeoutError`); retrying a mutation is only safe with a stable key.
+
+## Errors
+
+Non-2xx responses (and `{ success: false }` envelopes) throw a typed
+`AetherApiError` subclass so you can branch on the failure mode:
+
+```ts
+import {
+  AetherRateLimitError,
+  AetherNotFoundError,
+  AetherAuthError,
+  AetherTimeoutError,
+} from '@aetherwealth/sdk'
+
+try {
+  await client.trades.get(id)
+} catch (err) {
+  if (err instanceof AetherNotFoundError) { /* 404 */ }
+  else if (err instanceof AetherRateLimitError) { /* 429 — err.retryAfterSeconds */ }
+  else if (err instanceof AetherAuthError) { /* 401 — invalid or missing API key */ }
+  else if (err instanceof AetherTimeoutError) { /* client timeout — err.timeoutMs / err.elapsedMs */ }
+  else throw err
+}
+```
+
+`AetherTimeoutError` and `AetherNetworkError` (its parent) never reached the
+server; they carry no HTTP status. All HTTP failures are `AetherApiError`
+subclasses.
+
+## Optional runtime validation
+
+Compile-time types come from the SDK. Runtime validation is **off by default**
+for performance and additive-field tolerance (a backend that adds a field won't
+break older SDK consumers). Turn it on two ways:
+
+Whole-client — every resource validates its response with a Zod parser and
+throws a `ZodError` on shape drift (unknown fields are still tolerated):
+
+```ts
+const client = new AetherClient({ baseUrl, auth, validateResponses: true })
+```
+
+Per-call — import a parser and validate a single response:
+
+```ts
+import { parseTrade } from '@aetherwealth/sdk'
+const trade = parseTrade(await client.trades.get(id)) // throws on shape drift
+```
+
+## Not covered
+
+Live candles and AI chat conversations are streamed/tRPC-only on the backend
+and are intentionally **not** part of this REST SDK — reach them through
+`@aetherwealth/client-core` (used by the CLI and MCP server). API-key
+management is likewise out of scope: an API key can't provision other keys.

package/dist/client.d.ts

@@ -0,0 +1,130 @@
+import type { AccountsResource, AlertsResource, DiaryResource, MarketResource, StatsResource, TradesResource } from './types.js';
+export type AetherFetchInit = {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE' | 'PUT';
+    query?: Record<string, string | number | boolean | undefined | null | string[]>;
+    body?: unknown;
+    /** Per-request timeout override (ms). Falls back to the client's `timeoutMs`. */
+    timeoutMs?: number;
+    /**
+     * Caller-supplied cancellation signal, composed with the internal timeout —
+     * the request aborts when EITHER fires. A caller-initiated abort surfaces as
+     * the signal's reason; a timeout throws {@link AetherTimeoutError}.
+     */
+    signal?: AbortSignal;
+    /** When set, sent as the `Idempotency-Key` header so a retried create dedups. */
+    idempotencyKey?: string;
+};
+/** API-key auth: a public key (`aw_live_…`) sent as `Authorization: Bearer`. */
+export type ApiKeyAuth = {
+    type: 'apiKey';
+    apiKey: string;
+};
+/**
+ * Supported auth modes. A discriminated union with one member today; keeping
+ * it a union means an `oauth`/`hmac` member can be added later without changing
+ * this type's shape or breaking callers that pass `{type: 'apiKey', …}`.
+ */
+export type AetherAuth = ApiKeyAuth;
+export type AetherClientConfig = {
+    /**
+     * Backend base URL. Optional — defaults to the production API
+     * ({@link DEFAULT_BASE_URL}). Only set it to target staging or a local dev
+     * backend (e.g. `http://127.0.0.1:9006`).
+     */
+    baseUrl?: string;
+    /** Auth credential — required. API-key mode sends `Authorization: Bearer`. */
+    auth: AetherAuth;
+    /** Override the global `fetch`. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Optional default `User-Agent`. */
+    userAgent?: string;
+    /**
+     * Default per-request timeout in ms (default {@link DEFAULT_TIMEOUT_MS}).
+     * A request that exceeds this is aborted and rejects with
+     * {@link AetherTimeoutError}. Set `0` (or a non-finite value) to disable.
+     * Overridable per call via `request({timeoutMs})`.
+     */
+    timeoutMs?: number;
+    /**
+     * Escape hatch to run in a browser-like environment. Default `false` — the
+     * constructor throws in a browser because the API key is a server secret
+     * and any bundled/DevTools-visible key is effectively public. Only enable
+     * for a trusted non-browser runtime that happens to define `window`.
+     */
+    dangerouslyAllowBrowser?: boolean;
+    /**
+     * When `true`, each resource runs its Zod parser over the response before
+     * returning (throwing `ZodError` on shape drift). Default `false` for
+     * performance and additive-field tolerance.
+     */
+    validateResponses?: boolean;
+    /** Optional per-request diagnostics hook (e.g. debug logging). */
+    onRequest?: (req: {
+        method: string;
+        url: string;
+    }) => void;
+    onResponse?: (res: {
+        method: string;
+        url: string;
+        status: number;
+        ms: number;
+    }) => void;
+};
+/** Default per-request timeout budget (ms). */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Production public API base URL — used when `baseUrl` is omitted. */
+export declare const DEFAULT_BASE_URL = "https://api.aetherwealth.ai";
+export declare class AetherClient {
+    readonly trades: TradesResource;
+    readonly accounts: AccountsResource;
+    readonly stats: StatsResource;
+    readonly alerts: AlertsResource;
+    readonly market: MarketResource;
+    readonly diary: DiaryResource;
+    /**
+     * When `true`, resources validate responses with their Zod parser before
+     * returning. Exposed (readonly) so resource factories can read it.
+     */
+    readonly validateResponses: boolean;
+    private readonly config;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(config: AetherClientConfig);
+    /**
+     * Low-level request used by resource implementations and as an escape hatch
+     * for routes the SDK doesn't model. Returns the parsed `data` field when the
+     * envelope has one (e.g. `{success, data}`), otherwise the whole parsed
+     * object (so resources can `pluck` their named key). Throws a typed
+     * `AetherApiError` subclass on any non-2xx or `{success: false}`.
+     */
+    request<T>(path: string, init?: AetherFetchInit): Promise<T>;
+    /**
+     * Classify a thrown request error, in priority order:
+     *  (a) caller-initiated cancellation → re-throw the caller's reason as-is
+     *      (unwrapped, non-retryable: `withRetry` must not retry a cancel);
+     *  (b) our internal timeout fired → {@link AetherTimeoutError};
+     *  (c) a typed API error from `parseResponse` (4xx / `{success:false}`) →
+     *      propagate unchanged (an application error, not a transport/abort one);
+     *  (d) anything else → {@link AetherNetworkError} (DNS/TCP/TLS, stalled read).
+     */
+    private throwRequestError;
+    /**
+     * Turn a fetched `Response` into the resolved value or a typed throw:
+     * classifies non-2xx / `{success:false}`, unwraps a literal `data` envelope,
+     * and otherwise returns the whole parsed object for the resource to `pluck`.
+     */
+    private parseResponse;
+    /**
+     * Redact the API key from the parsed error body, then classify it into the
+     * most specific {@link AetherApiError} subtype. Redaction happens HERE — the
+     * single choke point for turning a response body into a thrown error — so a
+     * key echoed back by a proxy/WAF can never reach `err.message` or
+     * `err.responseBody`. The redacted body is a fresh structure; `parsed` (the
+     * caller's success-path value) is left untouched.
+     */
+    private throwClassifiedError;
+    /** The API key to scrub from error bodies (empty when auth carries no key). */
+    private redactionSecret;
+    private buildHeaders;
+    private tick;
+}