@aetherwealth/sdk 0.1.32

package/dist/resources/market.d.ts

@@ -0,0 +1,8 @@
+import type { AetherClient } from '../client.js';
+import type { MarketResource } from '../types.js';
+/**
+ * `market` — read-only market context via the public API
+ * `POST /api/public/v1/market/*`. Live candles are NOT available over REST
+ * (tRPC-only) and are intentionally absent from the SDK.
+ */
+export declare function createMarketResource(client: AetherClient): MarketResource;

package/dist/resources/market.js

@@ -0,0 +1,90 @@
+import { parseEconomicEvent, parseMacroSeriesResult, parseMarketConfig } from '../schemas.js';
+import { pluck } from './envelope.js';
+import { assertEachShape, assertShape } from './validate.js';
+const MACRO_RANGES = ['3m', '6m', '12m', '24m', 'all'];
+/**
+ * `market` — read-only market context via the public API
+ * `POST /api/public/v1/market/*`. Live candles are NOT available over REST
+ * (tRPC-only) and are intentionally absent from the SDK.
+ */
+export function createMarketResource(client) {
+    return {
+        async config() {
+            // `{success, data}` — client.request unwraps `data`.
+            const config = await client.request('/api/public/v1/market/config', {
+                method: 'POST',
+                body: {}
+            });
+            return assertShape(client.validateResponses, parseMarketConfig, config);
+        },
+        async calendar(query) {
+            const body = {};
+            if (query?.currency !== undefined)
+                body['currency'] = query.currency;
+            if (query?.from !== undefined)
+                body['from'] = query.from;
+            if (query?.to !== undefined)
+                body['to'] = query.to;
+            if (query?.indicator !== undefined)
+                body['indicator'] = query.indicator;
+            if (query?.impactMin !== undefined)
+                body['impactMin'] = query.impactMin;
+            if (query?.view !== undefined)
+                body['view'] = query.view;
+            const env = await client.request('/api/public/v1/market/calendar/list', { method: 'POST', body });
+            return {
+                events: assertEachShape(client.validateResponses, parseEconomicEvent, env.events),
+                view: env.view
+            };
+        },
+        async macroSeries(query) {
+            if (!query.currency || query.currency.length !== 3) {
+                throw new Error('market.macroSeries: currency must be a 3-letter code');
+            }
+            if (!query.indicator)
+                throw new Error('market.macroSeries: indicator is required');
+            if (query.limit !== undefined && (query.limit < 1 || query.limit > 1000)) {
+                throw new Error('market.macroSeries: limit must be between 1 and 1000');
+            }
+            const body = {
+                currency: query.currency,
+                indicator: query.indicator
+            };
+            if (query.from !== undefined)
+                body['from'] = query.from;
+            if (query.to !== undefined)
+                body['to'] = query.to;
+            if (query.limit !== undefined)
+                body['limit'] = query.limit;
+            const env = await client.request('/api/public/v1/market/macro-series', {
+                method: 'POST',
+                body
+            });
+            return assertEachShape(client.validateResponses, parseEconomicEvent, pluck(env, 'series'));
+        },
+        async macro(query) {
+            const { currency, indicator, range } = query;
+            // Fail-fast client validation mirroring the backend's accepted shapes.
+            if (!/^[A-Za-z]{3}$/.test(currency)) {
+                throw new Error('market.macro: currency must be a 3-letter code');
+            }
+            if (!/^[a-z0-9_]+$/i.test(indicator)) {
+                throw new Error('market.macro: indicator must be a slug (letters, digits, underscores)');
+            }
+            if (range !== undefined && !MACRO_RANGES.includes(range)) {
+                throw new Error(`market.macro: range must be one of ${MACRO_RANGES.join(', ')}`);
+            }
+            const body = {
+                currency: currency.toUpperCase(),
+                indicator: indicator.toLowerCase()
+            };
+            if (range !== undefined)
+                body['range'] = range;
+            // `{success, data, metadata}` — client.request unwraps `data`; the
+            // `metadata` sidecar is intentionally ignored (return type is the series).
+            const result = await client.request('/api/public/v1/market/macro', { method: 'POST', body });
+            // `null` (no series) passes through; a present series is shape-checked.
+            return assertShape(client.validateResponses, parseMacroSeriesResult, result);
+        }
+    };
+}

package/dist/resources/paginate.d.ts

@@ -0,0 +1,15 @@
+import type { PaginatedResponse } from '../types.js';
+/**
+ * Async iterator over paginated pages. Calls `fetchPage(page)` for successive
+ * pages starting at `startPage`, yielding each `PaginatedResponse` until the
+ * backend reports the last page (`page >= pagination.totalPages`) or returns an
+ * empty page — whichever comes first.
+ *
+ * Two independent stop conditions guard against an infinite loop even if a
+ * backend misreports `totalPages`:
+ *   1. an empty `data` array (nothing more to page through), or
+ *   2. the locally-tracked page number reaching `totalPages`.
+ */
+export declare function paginate<T>(fetchPage: (page: number) => Promise<PaginatedResponse<T>>, startPage?: number): AsyncIterableIterator<PaginatedResponse<T>>;
+/** Flatten a stream of pages into a stream of the individual items. */
+export declare function flatten<T>(pages: AsyncIterableIterator<PaginatedResponse<T>>): AsyncIterableIterator<T>;

package/dist/resources/paginate.js

@@ -0,0 +1,41 @@
+/**
+ * Async iterator over paginated pages. Calls `fetchPage(page)` for successive
+ * pages starting at `startPage`, yielding each `PaginatedResponse` until the
+ * backend reports the last page (`page >= pagination.totalPages`) or returns an
+ * empty page — whichever comes first.
+ *
+ * Two independent stop conditions guard against an infinite loop even if a
+ * backend misreports `totalPages`:
+ *   1. an empty `data` array (nothing more to page through), or
+ *   2. the locally-tracked page number reaching `totalPages`.
+ */
+export async function* paginate(fetchPage, startPage = 1) {
+    // Normalize to a finite positive integer. A `NaN`/`Infinity`/≤0 startPage
+    // would otherwise serialize as `page:null` AND leave the local counter
+    // non-finite (`NaN + 1 === NaN`), so `page >= totalPages` never trips and
+    // the loop spins forever.
+    let page = Number.isFinite(startPage) && startPage > 0 ? Math.floor(startPage) : 1;
+    while (true) {
+        const result = await fetchPage(page);
+        yield result;
+        // Empty page → nothing further to fetch.
+        if (result.data.length === 0)
+            return;
+        // A non-finite or ≤0 `totalPages` can't bound the loop — stop after this
+        // page rather than spin waiting to "reach" an unreachable count.
+        const { totalPages } = result.pagination;
+        if (!(Number.isFinite(totalPages) && totalPages > 0))
+            return;
+        if (page >= totalPages)
+            return;
+        page += 1;
+    }
+}
+/** Flatten a stream of pages into a stream of the individual items. */
+export async function* flatten(pages) {
+    for await (const pageResult of pages) {
+        for (const item of pageResult.data) {
+            yield item;
+        }
+    }
+}

package/dist/resources/stats.d.ts

@@ -0,0 +1,8 @@
+import type { AetherClient } from '../client.js';
+import type { StatsResource } from '../types.js';
+/**
+ * `stats` — aggregate trading analytics via the public API
+ * `POST /api/public/v1/stats/stats`. Filter by account, pair, and/or date
+ * range (ISO datetimes).
+ */
+export declare function createStatsResource(client: AetherClient): StatsResource;

package/dist/resources/stats.js

@@ -0,0 +1,28 @@
+import { parseTradingStats } from '../schemas.js';
+import { pluck } from './envelope.js';
+import { assertShape } from './validate.js';
+/**
+ * `stats` — aggregate trading analytics via the public API
+ * `POST /api/public/v1/stats/stats`. Filter by account, pair, and/or date
+ * range (ISO datetimes).
+ */
+export function createStatsResource(client) {
+    return {
+        async summary(query) {
+            const body = {};
+            if (query?.accountId !== undefined)
+                body['accountId'] = query.accountId;
+            if (query?.pair !== undefined)
+                body['pair'] = query.pair;
+            if (query?.from !== undefined)
+                body['from'] = query.from;
+            if (query?.to !== undefined)
+                body['to'] = query.to;
+            const env = await client.request('/api/public/v1/stats/stats', {
+                method: 'POST',
+                body
+            });
+            return assertShape(client.validateResponses, parseTradingStats, pluck(env, 'stats'));
+        }
+    };
+}

package/dist/resources/trades.d.ts

@@ -0,0 +1,8 @@
+import type { AetherClient } from '../client.js';
+import type { TradesResource } from '../types.js';
+/**
+ * `trades` — public API `POST /api/public/v1/trades/*`. The API key scopes
+ * every call to its owner; never send `userId` in the body. Responses are
+ * `{success, trade|trades}`.
+ */
+export declare function createTradesResource(client: AetherClient): TradesResource;

package/dist/resources/trades.js

@@ -0,0 +1,113 @@
+import { parseTrade } from '../schemas.js';
+import { pluck } from './envelope.js';
+import { resolveIdempotencyKey } from './idempotency.js';
+import { flatten, paginate } from './paginate.js';
+import { assertEachShape, assertShape } from './validate.js';
+/**
+ * `trades` — public API `POST /api/public/v1/trades/*`. The API key scopes
+ * every call to its owner; never send `userId` in the body. Responses are
+ * `{success, trade|trades}`.
+ */
+export function createTradesResource(client) {
+    const resource = {
+        async list(query) {
+            const body = {};
+            if (query?.accountId !== undefined)
+                body['accountId'] = query.accountId;
+            // 'ALL' is a client-side "no filter" sentinel — the backend status
+            // enum only accepts OPEN|CLOSED|CANCELLED, so omit it when ALL.
+            if (query?.status !== undefined && query.status !== 'ALL') {
+                body['status'] = query.status;
+            }
+            if (query?.pair !== undefined)
+                body['pair'] = query.pair;
+            if (query?.from !== undefined)
+                body['from'] = query.from;
+            if (query?.to !== undefined)
+                body['to'] = query.to;
+            if (query?.page !== undefined)
+                body['page'] = query.page;
+            if (query?.limit !== undefined)
+                body['limit'] = query.limit;
+            const env = await client.request('/api/public/v1/trades/list', {
+                method: 'POST',
+                body
+            });
+            return {
+                data: assertEachShape(client.validateResponses, parseTrade, pluck(env, 'trades')),
+                pagination: pluck(env, 'pagination')
+            };
+        },
+        async get(tradeId) {
+            if (!tradeId)
+                throw new Error('trades.get: tradeId is required');
+            const env = await client.request('/api/public/v1/trades/get', {
+                method: 'POST',
+                body: { id: tradeId }
+            });
+            return assertShape(client.validateResponses, parseTrade, pluck(env, 'trade'));
+        },
+        async create(input, opts) {
+            if (!input.accountId)
+                throw new Error('trades.create: accountId is required');
+            if (!input.pair)
+                throw new Error('trades.create: pair is required');
+            if (input.direction !== 'LONG' && input.direction !== 'SHORT') {
+                throw new Error('trades.create: direction must be LONG or SHORT');
+            }
+            // Backend `createTradeInputSchema.entryPrice` is `z.number().finite()`
+            // (not `.positive()`): zero/negative-priced instruments are valid.
+            if (!Number.isFinite(input.entryPrice)) {
+                throw new Error('trades.create: entryPrice must be a finite number');
+            }
+            if (!input.entryTime)
+                throw new Error('trades.create: entryTime is required');
+            const env = await client.request('/api/public/v1/trades/create', {
+                method: 'POST',
+                body: input,
+                idempotencyKey: resolveIdempotencyKey(opts)
+            });
+            return assertShape(client.validateResponses, parseTrade, pluck(env, 'trade'));
+        },
+        async update(tradeId, input) {
+            if (!tradeId)
+                throw new Error('trades.update: tradeId is required');
+            const env = await client.request('/api/public/v1/trades/update', {
+                method: 'POST',
+                body: { id: tradeId, ...input }
+            });
+            return assertShape(client.validateResponses, parseTrade, pluck(env, 'trade'));
+        },
+        async close(tradeId, input) {
+            if (!tradeId)
+                throw new Error('trades.close: tradeId is required');
+            // Backend `closeTradeInputSchema.exitPrice` is `z.number().finite()`.
+            if (!Number.isFinite(input.exitPrice)) {
+                throw new Error('trades.close: exitPrice must be a finite number');
+            }
+            if (!input.exitTime)
+                throw new Error('trades.close: exitTime is required');
+            const env = await client.request('/api/public/v1/trades/close', {
+                method: 'POST',
+                body: { id: tradeId, ...input }
+            });
+            return assertShape(client.validateResponses, parseTrade, pluck(env, 'trade'));
+        },
+        async delete(tradeId) {
+            if (!tradeId)
+                throw new Error('trades.delete: tradeId is required');
+            // Resolves on 2xx; a missing trade throws AetherNotFoundError upstream.
+            await client.request('/api/public/v1/trades/delete', {
+                method: 'POST',
+                body: { id: tradeId }
+            });
+        },
+        pages(query) {
+            return paginate(page => resource.list({ ...query, page }), query?.page ?? 1);
+        },
+        listAll(query) {
+            return flatten(resource.pages(query));
+        }
+    };
+    return resource;
+}

package/dist/resources/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Opt-in response validation helpers.
+ *
+ * When `enabled` (the client's `validateResponses` flag), the Zod `parser` runs
+ * purely for its throwing side-effect — a `ZodError` on shape drift. The
+ * ORIGINAL value is always returned untouched, so additive backend fields
+ * survive and object identity is preserved (the parser is a gate, not a
+ * transform). When disabled, this is a zero-cost pass-through.
+ */
+export declare function assertShape<T>(enabled: boolean, parser: (value: unknown) => unknown, value: T): T;
+/** Same as {@link assertShape}, applied to every item of a list. */
+export declare function assertEachShape<T>(enabled: boolean, parser: (value: unknown) => unknown, values: T[]): T[];

package/dist/resources/validate.js

@@ -0,0 +1,22 @@
+/**
+ * Opt-in response validation helpers.
+ *
+ * When `enabled` (the client's `validateResponses` flag), the Zod `parser` runs
+ * purely for its throwing side-effect — a `ZodError` on shape drift. The
+ * ORIGINAL value is always returned untouched, so additive backend fields
+ * survive and object identity is preserved (the parser is a gate, not a
+ * transform). When disabled, this is a zero-cost pass-through.
+ */
+export function assertShape(enabled, parser, value) {
+    if (enabled)
+        parser(value);
+    return value;
+}
+/** Same as {@link assertShape}, applied to every item of a list. */
+export function assertEachShape(enabled, parser, values) {
+    if (enabled) {
+        for (const value of values)
+            parser(value);
+    }
+    return values;
+}

package/dist/retry.d.ts

@@ -0,0 +1,40 @@
+export type RetryOptions = {
+    /** Maximum number of attempts (including the first). Default 3. */
+    maxAttempts?: number;
+    /** Base backoff delay in ms (used for the first retry). Default 250. */
+    baseDelayMs?: number;
+    /** Cap on a single sleep, regardless of backoff or `Retry-After`. Default 30_000. */
+    maxDelayMs?: number;
+    /** Override the default error-class predicate. */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /**
+     * Sleep implementation — overridable for tests. Receives the
+     * computed delay (already clamped) and returns a promise that
+     * resolves after that delay.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /** Random source for jitter. Defaults to `Math.random`. */
+    random?: () => number;
+    /** Notification hook fired before each retry sleep. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+};
+/**
+ * Run `fn`, retrying transient failures with exponential-jittered
+ * backoff. Re-throws the last error after exhausting attempts.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+/**
+ * Decide how long to sleep before the next attempt. Exposed for tests
+ * and for callers that want to compose their own retry policy.
+ */
+export declare function computeDelay(args: {
+    attempt: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    error: unknown;
+    random: () => number;
+}): number;

package/dist/retry.js

@@ -0,0 +1,110 @@
+/**
+ * Opt-in retry helper for AetherClient calls.
+ *
+ * Why opt-in: the SDK can't decide for callers whether a 429 should
+ * pause or whether a transient network error should retry — that's a
+ * domain decision (e.g. CLI: yes; webhook handler: probably no, the
+ * outer system retries). So the client itself never retries; callers
+ * wrap individual calls with `withRetry()` when they want it.
+ *
+ * Retries on:
+ *   - `AetherRateLimitError` (429), respecting `Retry-After`.
+ *   - `AetherNetworkError` (DNS/TCP/TLS failures, no HTTP response).
+ *   - `AetherTimeoutError` (client-side timeout abort) — a subclass of
+ *     `AetherNetworkError`, so already covered, but called out here because a
+ *     timeout is a transient network condition worth retrying.
+ *
+ * Does NOT retry on:
+ *   - `AetherAuthError`/`AetherForbiddenError` — credentials won't fix
+ *     themselves by trying again.
+ *   - `AetherNotFoundError`/`AetherValidationError` — caller bug.
+ *   - 5xx server errors that don't subclass to a retryable error — open
+ *     question whether 502/503/504 should retry; default is no, callers
+ *     can override via `shouldRetry`.
+ *
+ * **Retrying mutations is only safe with a stable idempotency key.** A create
+ * (`trades.create`, `accounts.create`, `alerts.create*`) auto-generates a fresh
+ * `Idempotency-Key` per call, which does NOT dedup across retries. To retry a
+ * create safely, pass a STABLE key so every attempt targets the same record:
+ * `withRetry(() => trades.create(input, {idempotencyKey: key}))`. Do NOT
+ * generate the key inside the retried closure.
+ *
+ * Backoff: exponential with full jitter, capped at `maxDelayMs`. When
+ * the server sends `Retry-After`, we honor it (clamped to maxDelayMs).
+ */
+import { AetherNetworkError, AetherRateLimitError, AetherTimeoutError } from './errors.js';
+const DEFAULTS = {
+    maxAttempts: 3,
+    baseDelayMs: 250,
+    maxDelayMs: 30_000
+};
+function defaultSleep(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+function defaultShouldRetry(error) {
+    if (error instanceof AetherRateLimitError)
+        return true;
+    // AetherTimeoutError extends AetherNetworkError, so the next check already
+    // covers it; listed explicitly to document that timeouts are retryable.
+    if (error instanceof AetherTimeoutError)
+        return true;
+    if (error instanceof AetherNetworkError)
+        return true;
+    return false;
+}
+/**
+ * Run `fn`, retrying transient failures with exponential-jittered
+ * backoff. Re-throws the last error after exhausting attempts.
+ */
+export async function withRetry(fn, opts = {}) {
+    const maxAttempts = Math.max(1, opts.maxAttempts ?? DEFAULTS.maxAttempts);
+    const baseDelayMs = Math.max(0, opts.baseDelayMs ?? DEFAULTS.baseDelayMs);
+    const maxDelayMs = Math.max(baseDelayMs, opts.maxDelayMs ?? DEFAULTS.maxDelayMs);
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    let lastError = undefined;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts)
+                break;
+            if (!shouldRetry(error, attempt))
+                break;
+            const delayMs = computeDelay({
+                attempt,
+                baseDelayMs,
+                maxDelayMs,
+                error,
+                random
+            });
+            opts.onRetry?.({ attempt, delayMs, error });
+            await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Decide how long to sleep before the next attempt. Exposed for tests
+ * and for callers that want to compose their own retry policy.
+ */
+export function computeDelay(args) {
+    const { attempt, baseDelayMs, maxDelayMs, error, random } = args;
+    // Honor Retry-After when present and finite. Backend sends seconds;
+    // convert to ms and clamp to maxDelayMs to prevent a hostile or
+    // mis-configured server from pinning the client for an hour.
+    if (error instanceof AetherRateLimitError && error.retryAfterSeconds !== null) {
+        const requested = error.retryAfterSeconds * 1000;
+        return Math.min(maxDelayMs, Math.max(0, requested));
+    }
+    // Exponential with full jitter: random in [0, base * 2^(attempt-1)].
+    // Full jitter (vs equal jitter) is preferred for high-throughput
+    // clients to spread retries; see AWS Architecture Blog.
+    const cap = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+    return Math.floor(random() * cap);
+}