@aetherwealth/sdk 0.1.32

package/dist/client.js

@@ -0,0 +1,429 @@
+/**
+ * AetherClient — typed HTTP client for the AetherWealth **public API**
+ * (`/api/public/v1/<domain>/<action>`, POST-RPC, `{success, <key>}` envelopes).
+ *
+ * Auth: every public route is authenticated with a public API key sent as
+ * `Authorization: Bearer aw_live_…`. Configure it via
+ * `auth: {type: 'apiKey', apiKey}`. `auth` is a discriminated union so an
+ * `oauth`/`hmac` member can be added later without breaking existing callers.
+ *
+ * The HTTP transport is pluggable via `fetchImpl` so tests assert wire shape
+ * without touching the network.
+ */
+import { AetherApiError, AetherNetworkError, AetherTimeoutError, classifyError } from './errors.js';
+import { createAccountsResource } from './resources/accounts.js';
+import { createAlertsResource } from './resources/alerts.js';
+import { createDiaryResource } from './resources/diary.js';
+import { createMarketResource } from './resources/market.js';
+import { createStatsResource } from './resources/stats.js';
+import { createTradesResource } from './resources/trades.js';
+/** Loopback hosts are TLS-exempt (local dev backend). Mirrors client-core. */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** Default per-request timeout budget (ms). */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** Production public API base URL — used when `baseUrl` is omitted. */
+export const DEFAULT_BASE_URL = 'https://api.aetherwealth.ai';
+/**
+ * True when running in a browser-like environment. Reads through `globalThis`
+ * (typed, always defined) rather than a bare `window` reference so it also
+ * type-checks in DOM-less Node/Bun/edge type setups. `window.document` is the
+ * discriminator — a Node global named `window` (rare) won't have `document`.
+ */
+function isBrowserLike() {
+    const g = globalThis;
+    return typeof g.window !== 'undefined' && typeof g.window.document !== 'undefined';
+}
+/**
+ * Refuse to construct in a browser unless explicitly allowed. The API key is a
+ * long-lived server secret; a key shipped to a browser is visible in the bundle
+ * and DevTools and must be treated as compromised. Mirrors the OpenAI SDK's
+ * `dangerouslyAllowBrowser` escape hatch.
+ */
+function assertNotBrowserUnlessAllowed(dangerouslyAllowBrowser) {
+    if (dangerouslyAllowBrowser || !isBrowserLike())
+        return;
+    throw new Error('AetherClient: refusing to run in a browser-like environment. The API key ' +
+        '(aw_live_…) is a server-side secret — exposing it to a browser leaks it to ' +
+        'every end user (bundle + DevTools). Call the API from your server instead. ' +
+        'If you are certain this is a trusted non-browser runtime, set ' +
+        'dangerouslyAllowBrowser: true.');
+}
+/**
+ * Transport-security guard. This SDK attaches a long-lived API key to every
+ * request, so the transport MUST be https unless the host is loopback (local
+ * dev). Asserted at construction — rather than trusting each consumer to check
+ * — so a misconfigured `http://` base URL can't silently leak the key in
+ * cleartext. Mirrors client-core's `assertHttpsUnlessLoopback`.
+ */
+function assertHttpsUnlessLoopback(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`AetherClient: invalid baseUrl: "${baseUrl}"`);
+    }
+    // A scheme-less input like "localhost:9006" parses with protocol "localhost:";
+    // catch that here so the error names the real problem (missing scheme).
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`AetherClient: baseUrl must start with https:// (or http:// for loopback): "${baseUrl}"`);
+    }
+    if (url.protocol !== 'https:' && !LOOPBACK_HOSTS.has(url.hostname)) {
+        throw new Error(`AetherClient: baseUrl must use https (loopback hosts exempt): "${baseUrl}"`);
+    }
+    // Request URLs are built as `baseUrl + path`, so a query/fragment/credentials
+    // in the base would corrupt every path (and could smuggle a secret into the
+    // query string). Reject them up front.
+    if (url.search || url.hash || url.username || url.password) {
+        throw new Error(`AetherClient: baseUrl must not contain a query, fragment, or credentials: "${baseUrl}"`);
+    }
+}
+/** Append one query entry, skipping null/undefined and repeating array values. */
+function appendQueryParam(params, key, value) {
+    if (value === undefined || value === null)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (item !== undefined && item !== null)
+                params.append(key, String(item));
+        }
+        return;
+    }
+    params.set(key, String(value));
+}
+function buildQueryString(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        appendQueryParam(params, key, value);
+    }
+    const s = params.toString();
+    return s ? `?${s}` : '';
+}
+/** Sentinel that replaces the API key wherever it is scrubbed from a body. */
+const REDACTED = '[REDACTED]';
+/**
+ * Recursively replace every occurrence of the API key — both raw and as a
+ * `Bearer <key>` token — with {@link REDACTED}, returning a NEW structure so the
+ * caller's parsed body is never mutated. Used to scrub an error body BEFORE it
+ * is copied onto a thrown error: a proxy/WAF that echoes the `Authorization`
+ * header into a 4xx JSON body must not leak the key via `err.message` /
+ * `err.responseBody`. A blank secret is a no-op (nothing to redact).
+ */
+function redactSecret(value, secret) {
+    if (secret.length === 0)
+        return value;
+    if (typeof value === 'string') {
+        // `Bearer <key>` first so the whole token collapses to one sentinel,
+        // then any standalone raw key. `replaceAll` with a string is literal
+        // (no regex), so a key with special chars is matched verbatim.
+        return value.replaceAll(`Bearer ${secret}`, REDACTED).replaceAll(secret, REDACTED);
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => redactSecret(item, secret));
+    }
+    if (value !== null && typeof value === 'object') {
+        const redacted = {};
+        for (const [key, item] of Object.entries(value)) {
+            // Redact the key name too — a body echoing the key AS a property
+            // name is pathological but cheap to close.
+            redacted[redactSecret(key, secret)] = redactSecret(item, secret);
+        }
+        return redacted;
+    }
+    return value;
+}
+/**
+ * Redact the API key from a thrown `cause` before it is attached to an
+ * `AetherNetworkError`/`AetherTimeoutError`. `redactSecret` can't handle an
+ * `Error` (its `message`/`stack` are non-enumerable), so clone it — preserve
+ * `name`, redact `message` + `stack`. Non-`Error` causes go through
+ * `redactSecret`.
+ */
+function redactCause(cause, secret) {
+    if (cause instanceof Error) {
+        const clone = new Error(redactSecret(cause.message, secret));
+        clone.name = cause.name;
+        if (cause.stack)
+            clone.stack = redactSecret(cause.stack, secret);
+        return clone;
+    }
+    return redactSecret(cause, secret);
+}
+/**
+ * Compose an internal timeout with an optional caller-supplied `AbortSignal`
+ * into one signal for `fetch`: the request aborts when EITHER fires. `timedOut`
+ * distinguishes the two afterwards so the caller can throw the right error.
+ *
+ * A `timeoutMs` of 0 (or non-finite) disables the internal timeout — only the
+ * caller's signal (if any) can then abort.
+ */
+function armAbort(callerSignal, timeoutMs) {
+    const controller = new AbortController();
+    let didTimeout = false;
+    let didCallerAbort = false;
+    let timer;
+    const clearInternalTimer = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    let onCallerAbort;
+    if (callerSignal) {
+        if (callerSignal.aborted) {
+            // Already aborted at construction — record it now so no later timer
+            // can flip this into a (wrong) timeout classification.
+            didCallerAbort = true;
+            controller.abort(callerSignal.reason);
+        }
+        else {
+            onCallerAbort = () => {
+                didCallerAbort = true;
+                // Kill the internal timer so a caller abort that races it can
+                // never be read back as `timedOut()` in the catch classifier.
+                clearInternalTimer();
+                controller.abort(callerSignal.reason);
+            };
+            callerSignal.addEventListener('abort', onCallerAbort, { once: true });
+        }
+    }
+    // No point arming a timeout if the caller already cancelled.
+    if (!didCallerAbort && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+        timer = setTimeout(() => {
+            didTimeout = true;
+            controller.abort();
+        }, timeoutMs);
+    }
+    return {
+        signal: controller.signal,
+        timedOut: () => didTimeout,
+        callerAborted: () => didCallerAbort,
+        cleanup: () => {
+            clearInternalTimer();
+            if (callerSignal && onCallerAbort) {
+                callerSignal.removeEventListener('abort', onCallerAbort);
+            }
+        }
+    };
+}
+export class AetherClient {
+    trades;
+    accounts;
+    stats;
+    alerts;
+    market;
+    diary;
+    /**
+     * When `true`, resources validate responses with their Zod parser before
+     * returning. Exposed (readonly) so resource factories can read it.
+     */
+    validateResponses;
+    config;
+    fetchImpl;
+    timeoutMs;
+    constructor(config) {
+        // Browser guard first: never even reach the point of holding a secret in
+        // a context that would leak it.
+        assertNotBrowserUnlessAllowed(config.dangerouslyAllowBrowser ?? false);
+        // Reject a blank OR whitespace-only key. The short-circuit order matters:
+        // `!config.auth.apiKey` guards `''`/undefined before `.trim()` runs. The
+        // key is validated, NOT trimmed — a whitespace key is a caller config bug
+        // to surface, not silently paper over.
+        if (!config.auth ||
+            config.auth.type !== 'apiKey' ||
+            !config.auth.apiKey ||
+            config.auth.apiKey.trim().length === 0) {
+            throw new Error('AetherClient: auth.apiKey is required');
+        }
+        // Default to the production API; only override for staging or local dev.
+        const baseUrl = (config.baseUrl?.trim() || DEFAULT_BASE_URL).replace(/\/$/, '');
+        assertHttpsUnlessLoopback(baseUrl);
+        this.config = { ...config, baseUrl };
+        this.fetchImpl = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.validateResponses = config.validateResponses ?? false;
+        this.trades = createTradesResource(this);
+        this.accounts = createAccountsResource(this);
+        this.stats = createStatsResource(this);
+        this.alerts = createAlertsResource(this);
+        this.market = createMarketResource(this);
+        this.diary = createDiaryResource(this);
+    }
+    /**
+     * 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}`.
+     */
+    async request(path, init = {}) {
+        const method = init.method ?? 'GET';
+        const url = `${this.config.baseUrl}${path}${buildQueryString(init.query)}`;
+        const headers = this.buildHeaders(init);
+        const fetchInit = { method, headers };
+        if (init.body !== undefined) {
+            fetchInit.body = JSON.stringify(init.body);
+        }
+        const timeoutMs = init.timeoutMs ?? this.timeoutMs;
+        const abort = armAbort(init.signal, timeoutMs);
+        fetchInit.signal = abort.signal;
+        this.config.onRequest?.({ method, url });
+        const startedAt = this.tick();
+        try {
+            const response = await this.fetchImpl(url, fetchInit);
+            this.config.onResponse?.({
+                method,
+                url,
+                status: response.status,
+                ms: this.tick() - startedAt
+            });
+            // Read + classify the body while STILL inside the abort-covered scope
+            // so a stalled body (or a caller-abort during the read) is caught by
+            // the classifier below instead of hanging past the timeout. `return
+            // await` (not a bare `return`) keeps the read inside this `try`, so
+            // `finally` cannot tear down the timer/listener mid-read.
+            return await this.parseResponse(response, path, method);
+        }
+        catch (error) {
+            this.throwRequestError({
+                error,
+                abort,
+                callerSignal: init.signal,
+                path,
+                method,
+                timeoutMs,
+                startedAt
+            });
+        }
+        finally {
+            // Release the timer + abort listener once the body is fully read
+            // (success) or the request has errored — never before.
+            abort.cleanup();
+        }
+    }
+    /**
+     * 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).
+     */
+    throwRequestError(args) {
+        const { error, abort, callerSignal, path, method, timeoutMs, startedAt } = args;
+        // Check the internal timeout FIRST: a caller-abort clears the timer, so
+        // `timedOut()` is true only when the timeout fired first — checking it
+        // ahead of the caller-abort stops a tight timeout→cancel race from being
+        // mis-reported as a caller cancellation.
+        if (abort.timedOut()) {
+            throw new AetherTimeoutError({
+                message: `Request ${method} ${path} timed out after ${timeoutMs}ms`,
+                cause: redactCause(error, this.redactionSecret()),
+                path,
+                method,
+                timeoutMs,
+                elapsedMs: Math.round(this.tick() - startedAt)
+            });
+        }
+        // Caller cancelled: re-throw their reason unwrapped (non-retryable —
+        // `withRetry` must not retry a deliberate cancel).
+        if (abort.callerAborted() || callerSignal?.aborted) {
+            throw callerSignal?.reason ?? error;
+        }
+        if (error instanceof AetherApiError)
+            throw error;
+        throw new AetherNetworkError({
+            message: `Network error calling ${method} ${path}`,
+            cause: redactCause(error, this.redactionSecret()),
+            path,
+            method
+        });
+    }
+    /**
+     * 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`.
+     */
+    async parseResponse(response, path, method) {
+        const text = await response.text();
+        let parsed;
+        if (text.length > 0) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!response.ok) {
+            this.throwClassifiedError(parsed, response, path, method);
+        }
+        if (response.status === 204)
+            return undefined;
+        if (parsed === undefined) {
+            throw new AetherApiError(`Empty response body from ${method} ${path}`, {
+                status: response.status,
+                code: 'EMPTY_BODY',
+                path,
+                method,
+                responseBody: text
+            });
+        }
+        if (typeof parsed !== 'object' || parsed === null)
+            return parsed;
+        const envelope = parsed;
+        if (envelope.success === false) {
+            this.throwClassifiedError(parsed, response, path, method);
+        }
+        // `{success, data}` → unwrap `data`; any other `{success, <key>}`
+        // envelope is returned whole for the resource to `pluck`.
+        if ('data' in envelope)
+            return envelope.data;
+        return parsed;
+    }
+    /**
+     * 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.
+     */
+    throwClassifiedError(parsed, response, path, method) {
+        throw classifyError({
+            status: response.status,
+            body: redactSecret(parsed, this.redactionSecret()),
+            path,
+            method,
+            headers: response.headers
+        });
+    }
+    /** The API key to scrub from error bodies (empty when auth carries no key). */
+    redactionSecret() {
+        return this.config.auth.type === 'apiKey' ? this.config.auth.apiKey : '';
+    }
+    buildHeaders(init) {
+        const headers = {
+            'content-type': 'application/json',
+            accept: 'application/json'
+        };
+        if (this.config.auth.type === 'apiKey') {
+            headers['authorization'] = `Bearer ${this.config.auth.apiKey}`;
+        }
+        if (this.config.userAgent) {
+            headers['user-agent'] = this.config.userAgent;
+        }
+        if (init?.idempotencyKey) {
+            headers['idempotency-key'] = init.idempotencyKey;
+        }
+        return headers;
+    }
+    tick() {
+        return typeof performance !== 'undefined' && typeof performance.now === 'function'
+            ? performance.now()
+            : Date.now();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Typed error hierarchy for the AetherWealth SDK.
+ *
+ * All HTTP errors thrown by `AetherClient` are subclasses of
+ * `AetherApiError`, so callers can do
+ * `catch (err) { if (err instanceof AetherApiError) … }`. The 4xx
+ * subtypes let callers branch without sniffing status codes.
+ *
+ * `AetherNetworkError` is intentionally NOT a subclass of
+ * `AetherApiError` — it has no HTTP status because the request never
+ * reached the server (DNS failure, connection refused, TLS rejection).
+ */
+export declare class AetherApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly path: string;
+    readonly method: string;
+    readonly responseBody: unknown;
+    constructor(message: string, opts: {
+        status: number;
+        code: string;
+        path: string;
+        method: string;
+        responseBody?: unknown;
+    });
+}
+export declare class AetherAuthError extends AetherApiError {
+    readonly status: 401;
+    constructor(opts: {
+        message: string;
+        code: string;
+        path: string;
+        method: string;
+        responseBody?: unknown;
+    });
+}
+export declare class AetherForbiddenError extends AetherApiError {
+    readonly status: 403;
+    constructor(opts: {
+        message: string;
+        code: string;
+        path: string;
+        method: string;
+        responseBody?: unknown;
+    });
+}
+export declare class AetherNotFoundError extends AetherApiError {
+    readonly status: 404;
+    constructor(opts: {
+        message: string;
+        code: string;
+        path: string;
+        method: string;
+        responseBody?: unknown;
+    });
+}
+export declare class AetherValidationError extends AetherApiError {
+    constructor(opts: {
+        message: string;
+        code: string;
+        path: string;
+        method: string;
+        responseBody?: unknown;
+        status?: 400 | 422;
+    });
+}
+export declare class AetherRateLimitError extends AetherApiError {
+    readonly status: 429;
+    readonly retryAfterSeconds: number | null;
+    constructor(opts: {
+        message: string;
+        code: string;
+        path: string;
+        method: string;
+        retryAfterSeconds: number | null;
+        responseBody?: unknown;
+    });
+}
+export declare class AetherNetworkError extends Error {
+    readonly cause: unknown;
+    readonly path: string;
+    readonly method: string;
+    constructor(opts: {
+        message: string;
+        cause: unknown;
+        path: string;
+        method: string;
+    });
+}
+/**
+ * Thrown when a request is aborted by the client's own timeout (not by a
+ * caller-supplied signal). Subclasses `AetherNetworkError` so existing
+ * `catch (e) { if (e instanceof AetherNetworkError) … }` blocks — and
+ * `withRetry` — treat a timeout as the transient network condition it is.
+ *
+ * `timeoutMs` is the configured budget; `elapsedMs` is how long the request
+ * actually ran before the abort fired (useful for logging/telemetry).
+ */
+export declare class AetherTimeoutError extends AetherNetworkError {
+    readonly timeoutMs: number;
+    readonly elapsedMs: number;
+    constructor(opts: {
+        message: string;
+        cause: unknown;
+        path: string;
+        method: string;
+        timeoutMs: number;
+        elapsedMs: number;
+    });
+}
+/**
+ * Parse the `Retry-After` header. Per RFC 7231 the value may be either:
+ *  - a decimal number of seconds (`Retry-After: 120`), or
+ *  - an HTTP-date (`Retry-After: Sat, 25 Apr 2026 12:00:00 GMT`).
+ * Returns the number of seconds from now, or null if absent/unparseable.
+ * The `now` argument is injectable for deterministic tests.
+ */
+export declare function parseRetryAfter(headerValue: string | null | undefined, now?: () => number): number | null;
+/**
+ * Factory: map an HTTP response into the most specific subtype.
+ * Preserves the response envelope so callers can inspect `responseBody`,
+ * and reads `Retry-After` for 429s when headers are available.
+ */
+export declare function classifyError(args: {
+    status: number;
+    body: unknown;
+    path: string;
+    method: string;
+    headers?: Headers | null;
+    now?: () => number;
+}): AetherApiError;