@aetherwealth/sdk 0.1.32

package/dist/errors.js

@@ -0,0 +1,178 @@
+/**
+ * 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 class AetherApiError extends Error {
+    status;
+    code;
+    path;
+    method;
+    responseBody;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'AetherApiError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.path = opts.path;
+        this.method = opts.method;
+        this.responseBody = opts.responseBody;
+    }
+}
+export class AetherAuthError extends AetherApiError {
+    status = 401;
+    constructor(opts) {
+        super(opts.message, {
+            status: 401,
+            code: opts.code,
+            path: opts.path,
+            method: opts.method,
+            responseBody: opts.responseBody
+        });
+        this.name = 'AetherAuthError';
+    }
+}
+export class AetherForbiddenError extends AetherApiError {
+    status = 403;
+    constructor(opts) {
+        super(opts.message, {
+            status: 403,
+            code: opts.code,
+            path: opts.path,
+            method: opts.method,
+            responseBody: opts.responseBody
+        });
+        this.name = 'AetherForbiddenError';
+    }
+}
+export class AetherNotFoundError extends AetherApiError {
+    status = 404;
+    constructor(opts) {
+        super(opts.message, {
+            status: 404,
+            code: opts.code,
+            path: opts.path,
+            method: opts.method,
+            responseBody: opts.responseBody
+        });
+        this.name = 'AetherNotFoundError';
+    }
+}
+export class AetherValidationError extends AetherApiError {
+    constructor(opts) {
+        super(opts.message, {
+            status: opts.status ?? 400,
+            code: opts.code,
+            path: opts.path,
+            method: opts.method,
+            responseBody: opts.responseBody
+        });
+        this.name = 'AetherValidationError';
+    }
+}
+export class AetherRateLimitError extends AetherApiError {
+    status = 429;
+    retryAfterSeconds;
+    constructor(opts) {
+        super(opts.message, {
+            status: 429,
+            code: opts.code,
+            path: opts.path,
+            method: opts.method,
+            responseBody: opts.responseBody
+        });
+        this.name = 'AetherRateLimitError';
+        this.retryAfterSeconds = opts.retryAfterSeconds;
+    }
+}
+export class AetherNetworkError extends Error {
+    cause;
+    path;
+    method;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'AetherNetworkError';
+        this.cause = opts.cause;
+        this.path = opts.path;
+        this.method = opts.method;
+    }
+}
+/**
+ * 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 class AetherTimeoutError extends AetherNetworkError {
+    timeoutMs;
+    elapsedMs;
+    constructor(opts) {
+        super({ message: opts.message, cause: opts.cause, path: opts.path, method: opts.method });
+        this.name = 'AetherTimeoutError';
+        this.timeoutMs = opts.timeoutMs;
+        this.elapsedMs = opts.elapsedMs;
+    }
+}
+/**
+ * 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 function parseRetryAfter(headerValue, now = Date.now) {
+    if (!headerValue)
+        return null;
+    const trimmed = headerValue.trim();
+    if (trimmed.length === 0)
+        return null;
+    const asInt = Number(trimmed);
+    if (Number.isFinite(asInt)) {
+        return Math.max(0, Math.floor(asInt));
+    }
+    const asDate = Date.parse(trimmed);
+    if (!Number.isFinite(asDate))
+        return null;
+    return Math.max(0, Math.floor((asDate - now()) / 1000));
+}
+/**
+ * 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 function classifyError(args) {
+    const { status, body, path, method, headers } = args;
+    const envelope = body && typeof body === 'object' && body !== null ? body : {};
+    // Backend convention: {success: false, error: "CODE", message: "human"}.
+    // Some Express defaults flip these (error string is the human message)
+    // — fall back gracefully when message is missing.
+    const rawMessage = typeof envelope['message'] === 'string' ? envelope['message'] : null;
+    const rawCode = typeof envelope['error'] === 'string' ? envelope['error'] : null;
+    const message = rawMessage ?? rawCode ?? `Request failed with status ${status}`;
+    const code = rawCode ?? `HTTP_${status}`;
+    const opts = { message, code, path, method, responseBody: body };
+    if (status === 401)
+        return new AetherAuthError(opts);
+    if (status === 403)
+        return new AetherForbiddenError(opts);
+    if (status === 404)
+        return new AetherNotFoundError(opts);
+    if (status === 400 || status === 422) {
+        return new AetherValidationError({ ...opts, status: status });
+    }
+    if (status === 429) {
+        const retryAfterSeconds = parseRetryAfter(headers?.get('retry-after') ?? null, args.now);
+        return new AetherRateLimitError({ ...opts, retryAfterSeconds });
+    }
+    return new AetherApiError(message, { status, code, path, method, responseBody: body });
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @aetherwealth/sdk
+ *
+ * Typed TypeScript client for the AetherWealth **public API**
+ * (`/api/public/v1/<domain>/<action>`). Reusable in any Node/Bun/edge runtime
+ * that needs programmatic access to AetherWealth data.
+ *
+ * Auth — every public route is authenticated with a **public API key**
+ * (`aw_live_…`) sent as `Authorization: Bearer …`:
+ *
+ * ```ts
+ * const client = new AetherClient({
+ *   auth: {type: 'apiKey', apiKey: process.env.AETHER_API_KEY!}
+ *   // baseUrl defaults to the production API; set it only for staging/local dev.
+ * })
+ * ```
+ *
+ * `auth` is a discriminated union (one member today, `apiKey`) so future
+ * modes can be added without breaking callers. See the README for setup.
+ */
+export type { AetherAuth, AetherClientConfig, AetherFetchInit, ApiKeyAuth } from './client.js';
+export { AetherClient, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from './client.js';
+export { AetherApiError, AetherAuthError, AetherForbiddenError, AetherNetworkError, AetherNotFoundError, AetherRateLimitError, AetherTimeoutError, AetherValidationError, classifyError, parseRetryAfter } from './errors.js';
+export type { RetryOptions } from './retry.js';
+export { computeDelay, withRetry } from './retry.js';
+export { accountSchema, alertSchema, dedupModeSchema, diaryEntrySchema, economicEventSchema, indicatorAlertSchema, indicatorConditionSchema, macroSeriesPointSchema, macroSeriesResultSchema, marketConfigSchema, paginationSchema, parseAccount, parseAlert, parseDiaryEntry, parseEconomicEvent, parseIndicatorAlert, parseMacroSeriesResult, parseMarketConfig, parseTrade, parseTradingStats, priceConditionSchema, tradeDirectionSchema, tradeSchema, tradeStatusSchema, tradingStatsSchema, triggerTypeSchema } from './schemas.js';
+export type { Account, AccountsResource, Alert, AlertsResource, AlertType, ApiEnvelope, CalendarQuery, CalendarResult, CloseTradeInput, CreateAccountInput, CreateIndicatorAlertInput, CreatePriceAlertInput, CreateTradeInput, CreateTrendlineAlertInput, DedupMode, DiaryEntry, DiaryListQuery, DiaryResource, EconomicEvent, EconomicEventMinimal, EconomicEventRich, IdempotencyOptions, IndicatorAlert, IndicatorCondition, ListAlertsQuery, MacroQuery, MacroRange, MacroSeriesQuery, MacroSeriesResult, MarketConfig, MarketResource, PaginatedResponse, PaginationMeta, PriceCondition, SeriesOp, StatsQuery, StatsResource, ThresholdOp, Trade, TradeDirection, TradeListQuery, TradeStatus, TradeStatusFilter, TradesResource, TradingStats, TriggerType, UpdateAccountInput, UpdateAlertInput, UpdateIndicatorAlertInput, UpdateTradeInput, UpsertDiaryInput } from './types.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @aetherwealth/sdk
+ *
+ * Typed TypeScript client for the AetherWealth **public API**
+ * (`/api/public/v1/<domain>/<action>`). Reusable in any Node/Bun/edge runtime
+ * that needs programmatic access to AetherWealth data.
+ *
+ * Auth — every public route is authenticated with a **public API key**
+ * (`aw_live_…`) sent as `Authorization: Bearer …`:
+ *
+ * ```ts
+ * const client = new AetherClient({
+ *   auth: {type: 'apiKey', apiKey: process.env.AETHER_API_KEY!}
+ *   // baseUrl defaults to the production API; set it only for staging/local dev.
+ * })
+ * ```
+ *
+ * `auth` is a discriminated union (one member today, `apiKey`) so future
+ * modes can be added without breaking callers. See the README for setup.
+ */
+export { AetherClient, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from './client.js';
+export { AetherApiError, AetherAuthError, AetherForbiddenError, AetherNetworkError, AetherNotFoundError, AetherRateLimitError, AetherTimeoutError, AetherValidationError, classifyError, parseRetryAfter } from './errors.js';
+export { computeDelay, withRetry } from './retry.js';
+export { accountSchema, alertSchema, dedupModeSchema, diaryEntrySchema, economicEventSchema, indicatorAlertSchema, indicatorConditionSchema, macroSeriesPointSchema, macroSeriesResultSchema, marketConfigSchema, paginationSchema, parseAccount, parseAlert, parseDiaryEntry, parseEconomicEvent, parseIndicatorAlert, parseMacroSeriesResult, parseMarketConfig, parseTrade, parseTradingStats, priceConditionSchema, tradeDirectionSchema, tradeSchema, tradeStatusSchema, tradingStatsSchema, triggerTypeSchema } from './schemas.js';

package/dist/resources/accounts.d.ts

@@ -0,0 +1,8 @@
+import type { AetherClient } from '../client.js';
+import type { AccountsResource } from '../types.js';
+/**
+ * `accounts` — public API `POST /api/public/v1/accounts/*`. `trades()` is a
+ * convenience wrapper over the trades-list endpoint filtered by account (there
+ * is no dedicated per-account trades route).
+ */
+export declare function createAccountsResource(client: AetherClient): AccountsResource;

package/dist/resources/accounts.js

@@ -0,0 +1,84 @@
+import { parseAccount, 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';
+/**
+ * `accounts` — public API `POST /api/public/v1/accounts/*`. `trades()` is a
+ * convenience wrapper over the trades-list endpoint filtered by account (there
+ * is no dedicated per-account trades route).
+ */
+export function createAccountsResource(client) {
+    const resource = {
+        async list() {
+            const env = await client.request('/api/public/v1/accounts/list', {
+                method: 'POST',
+                body: {}
+            });
+            return assertEachShape(client.validateResponses, parseAccount, pluck(env, 'accounts'));
+        },
+        async create(input, opts) {
+            if (!input.name || input.name.trim().length === 0) {
+                throw new Error('accounts.create: name is required');
+            }
+            const env = await client.request('/api/public/v1/accounts/create', {
+                method: 'POST',
+                body: input,
+                idempotencyKey: resolveIdempotencyKey(opts)
+            });
+            return assertShape(client.validateResponses, parseAccount, pluck(env, 'account'));
+        },
+        async update(accountId, input) {
+            if (!accountId)
+                throw new Error('accounts.update: accountId is required');
+            const env = await client.request('/api/public/v1/accounts/update', {
+                method: 'POST',
+                body: { id: accountId, ...input }
+            });
+            return assertShape(client.validateResponses, parseAccount, pluck(env, 'account'));
+        },
+        async delete(accountId) {
+            if (!accountId)
+                throw new Error('accounts.delete: accountId is required');
+            // Resolves on 2xx; a missing account throws AetherNotFoundError upstream.
+            await client.request('/api/public/v1/accounts/delete', {
+                method: 'POST',
+                body: { id: accountId }
+            });
+        },
+        async trades(accountId, query) {
+            if (!accountId)
+                throw new Error('accounts.trades: accountId is required');
+            const body = { accountId };
+            // 'ALL' is a "no filter" sentinel; the backend rejects it (enum is
+            // OPEN|CLOSED|CANCELLED), so omit it.
+            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')
+            };
+        },
+        tradesAll(accountId, query) {
+            if (!accountId)
+                throw new Error('accounts.tradesAll: accountId is required');
+            return flatten(paginate(page => resource.trades(accountId, { ...query, page }), query?.page ?? 1));
+        }
+    };
+    return resource;
+}

package/dist/resources/alerts.d.ts

@@ -0,0 +1,8 @@
+import type { AetherClient } from '../client.js';
+import type { AlertsResource } from '../types.js';
+/**
+ * `alerts` — public API `POST /api/public/v1/alerts/*`. Price and trendline
+ * alerts share the `alerts` surface; indicator alerts live under the
+ * `indicator/*` sub-paths and return the `indicatorAlerts`/`indicatorAlert` key.
+ */
+export declare function createAlertsResource(client: AetherClient): AlertsResource;

package/dist/resources/alerts.js

@@ -0,0 +1,178 @@
+import { parseAlert, parseIndicatorAlert } from '../schemas.js';
+import { pluck } from './envelope.js';
+import { resolveIdempotencyKey } from './idempotency.js';
+import { assertEachShape, assertShape } from './validate.js';
+const PRICE_CONDITIONS = new Set(['above', 'below', 'crosses']);
+const TRIGGER_TYPES = new Set(['close', 'wick']);
+const DEDUP_MODES = new Set(['edge', 'continuous']);
+const SERIES_OPS = new Set([
+    'gt_series',
+    'lt_series',
+    'crosses_above_series',
+    'crosses_below_series'
+]);
+function listBody(query) {
+    const body = {};
+    if (query?.includeArchived !== undefined)
+        body['includeArchived'] = query.includeArchived;
+    if (query?.pair !== undefined)
+        body['pair'] = query.pair;
+    return body;
+}
+/** Required scalar fields + enum checks shared by every indicator-alert create. */
+function assertIndicatorBase(input) {
+    if (!input.pair)
+        throw new Error('alerts.createIndicator: pair is required');
+    if (!input.timeframe)
+        throw new Error('alerts.createIndicator: timeframe is required');
+    if (!input.indicatorType) {
+        throw new Error('alerts.createIndicator: indicatorType is required');
+    }
+    if (!input.outputSeries) {
+        throw new Error('alerts.createIndicator: outputSeries is required');
+    }
+    if (!TRIGGER_TYPES.has(input.triggerType)) {
+        throw new Error('alerts.createIndicator: triggerType must be close or wick');
+    }
+    if (!DEDUP_MODES.has(input.dedupMode)) {
+        throw new Error('alerts.createIndicator: dedupMode must be edge or continuous');
+    }
+}
+/**
+ * The threshold/series split is load-bearing: a series op with a stray
+ * `threshold` (or a threshold op missing one) makes the evaluator read an
+ * undefined value and the alert silently never fires.
+ */
+function assertIndicatorCondition(condition) {
+    const cond = condition;
+    if (!cond || !cond.op) {
+        throw new Error('alerts.createIndicator: condition.op is required');
+    }
+    if (SERIES_OPS.has(cond.op)) {
+        if (!cond.other) {
+            throw new Error(`alerts.createIndicator: series op "${cond.op}" requires a non-empty "other" series`);
+        }
+        return;
+    }
+    if (!Number.isFinite(cond.threshold)) {
+        throw new Error(`alerts.createIndicator: threshold op "${cond.op}" requires a numeric "threshold"`);
+    }
+}
+/**
+ * `alerts` — public API `POST /api/public/v1/alerts/*`. Price and trendline
+ * alerts share the `alerts` surface; indicator alerts live under the
+ * `indicator/*` sub-paths and return the `indicatorAlerts`/`indicatorAlert` key.
+ */
+export function createAlertsResource(client) {
+    return {
+        async list(query) {
+            const env = await client.request('/api/public/v1/alerts/list', {
+                method: 'POST',
+                body: listBody(query)
+            });
+            return assertEachShape(client.validateResponses, parseAlert, pluck(env, 'alerts'));
+        },
+        async createPrice(input, opts) {
+            if (!input.pair)
+                throw new Error('alerts.createPrice: pair is required');
+            if (!input.timeframe)
+                throw new Error('alerts.createPrice: timeframe is required');
+            if (!Number.isFinite(input.price)) {
+                throw new Error('alerts.createPrice: price must be a finite number');
+            }
+            if (!PRICE_CONDITIONS.has(input.condition)) {
+                throw new Error('alerts.createPrice: condition must be above, below, or crosses');
+            }
+            if (!TRIGGER_TYPES.has(input.triggerType)) {
+                throw new Error('alerts.createPrice: triggerType must be close or wick');
+            }
+            const env = await client.request('/api/public/v1/alerts/price/create', {
+                method: 'POST',
+                body: input,
+                idempotencyKey: resolveIdempotencyKey(opts)
+            });
+            return assertShape(client.validateResponses, parseAlert, pluck(env, 'alert'));
+        },
+        async createTrendline(input, opts) {
+            if (!input.pair)
+                throw new Error('alerts.createTrendline: pair is required');
+            if (!input.timeframe)
+                throw new Error('alerts.createTrendline: timeframe is required');
+            if (!Number.isFinite(input.price1) || !Number.isFinite(input.price2)) {
+                throw new Error('alerts.createTrendline: price1 and price2 must be finite numbers');
+            }
+            if (!input.time1 || !input.time2) {
+                throw new Error('alerts.createTrendline: time1 and time2 are required');
+            }
+            if (!PRICE_CONDITIONS.has(input.condition)) {
+                throw new Error('alerts.createTrendline: condition must be above, below, or crosses');
+            }
+            if (!TRIGGER_TYPES.has(input.triggerType)) {
+                throw new Error('alerts.createTrendline: triggerType must be close or wick');
+            }
+            const env = await client.request('/api/public/v1/alerts/trendline/create', {
+                method: 'POST',
+                body: input,
+                idempotencyKey: resolveIdempotencyKey(opts)
+            });
+            return assertShape(client.validateResponses, parseAlert, pluck(env, 'alert'));
+        },
+        async update(alertId, input) {
+            if (!alertId)
+                throw new Error('alerts.update: alertId is required');
+            const env = await client.request('/api/public/v1/alerts/update', {
+                method: 'POST',
+                body: { id: alertId, ...input }
+            });
+            return assertShape(client.validateResponses, parseAlert, pluck(env, 'alert'));
+        },
+        async delete(alertId) {
+            if (!alertId)
+                throw new Error('alerts.delete: alertId is required');
+            // Resolves on 2xx; a missing alert throws AetherNotFoundError upstream.
+            await client.request('/api/public/v1/alerts/delete', {
+                method: 'POST',
+                body: { id: alertId }
+            });
+        },
+        async listIndicator(query) {
+            const env = await client.request('/api/public/v1/alerts/indicator/list', {
+                method: 'POST',
+                body: listBody(query)
+            });
+            return assertEachShape(client.validateResponses, parseIndicatorAlert, pluck(env, 'indicatorAlerts'));
+        },
+        async createIndicator(input, opts) {
+            assertIndicatorBase(input);
+            assertIndicatorCondition(input.condition);
+            const env = await client.request('/api/public/v1/alerts/indicator/create', {
+                method: 'POST',
+                body: input,
+                idempotencyKey: resolveIdempotencyKey(opts)
+            });
+            return assertShape(client.validateResponses, parseIndicatorAlert, pluck(env, 'indicatorAlert'));
+        },
+        async updateIndicator(alertId, input) {
+            if (!alertId)
+                throw new Error('alerts.updateIndicator: alertId is required');
+            // Same load-bearing threshold/series split as create — but only when
+            // the caller is actually changing the condition (update is partial).
+            if (input.condition !== undefined)
+                assertIndicatorCondition(input.condition);
+            const env = await client.request('/api/public/v1/alerts/indicator/update', {
+                method: 'POST',
+                body: { id: alertId, ...input }
+            });
+            return assertShape(client.validateResponses, parseIndicatorAlert, pluck(env, 'indicatorAlert'));
+        },
+        async deleteIndicator(alertId) {
+            if (!alertId)
+                throw new Error('alerts.deleteIndicator: alertId is required');
+            // Resolves on 2xx; a missing alert throws AetherNotFoundError upstream.
+            await client.request('/api/public/v1/alerts/indicator/delete', {
+                method: 'POST',
+                body: { id: alertId }
+            });
+        }
+    };
+}

package/dist/resources/diary.d.ts

@@ -0,0 +1,8 @@
+import type { AetherClient } from '../client.js';
+import type { DiaryResource } from '../types.js';
+/**
+ * `diary` — public API `POST /api/public/v1/diary/*`. Entries are keyed by
+ * calendar date (`YYYY-MM-DD`); `upsert` creates or replaces the entry for a
+ * date.
+ */
+export declare function createDiaryResource(client: AetherClient): DiaryResource;

package/dist/resources/diary.js

@@ -0,0 +1,75 @@
+import { parseDiaryEntry } from '../schemas.js';
+import { pluck } from './envelope.js';
+import { flatten, paginate } from './paginate.js';
+import { assertEachShape, assertShape } from './validate.js';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * `diary` — public API `POST /api/public/v1/diary/*`. Entries are keyed by
+ * calendar date (`YYYY-MM-DD`); `upsert` creates or replaces the entry for a
+ * date.
+ */
+export function createDiaryResource(client) {
+    const resource = {
+        async list(query) {
+            const body = {};
+            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/diary/list', {
+                method: 'POST',
+                body
+            });
+            return {
+                data: assertEachShape(client.validateResponses, parseDiaryEntry, pluck(env, 'entries')),
+                pagination: pluck(env, 'pagination')
+            };
+        },
+        async get(date) {
+            if (!ISO_DATE.test(date))
+                throw new Error('diary.get: date must be YYYY-MM-DD');
+            const env = await client.request('/api/public/v1/diary/get', {
+                method: 'POST',
+                body: { date }
+            });
+            return assertShape(client.validateResponses, parseDiaryEntry, pluck(env, 'entry'));
+        },
+        async upsert(input) {
+            if (!ISO_DATE.test(input.date))
+                throw new Error('diary.upsert: date must be YYYY-MM-DD');
+            if (!input.content || input.content.trim().length === 0) {
+                throw new Error('diary.upsert: content is required');
+            }
+            if (input.rating !== undefined &&
+                input.rating !== null &&
+                (input.rating < 1 || input.rating > 5)) {
+                throw new Error('diary.upsert: rating must be between 1 and 5');
+            }
+            const env = await client.request('/api/public/v1/diary/upsert', {
+                method: 'POST',
+                body: input
+            });
+            return assertShape(client.validateResponses, parseDiaryEntry, pluck(env, 'entry'));
+        },
+        async delete(date) {
+            if (!ISO_DATE.test(date))
+                throw new Error('diary.delete: date must be YYYY-MM-DD');
+            // Resolves on 2xx; a missing entry throws AetherNotFoundError upstream.
+            await client.request('/api/public/v1/diary/delete', {
+                method: 'POST',
+                body: { date }
+            });
+        },
+        pages(query) {
+            return paginate(page => resource.list({ ...query, page }), query?.page ?? 1);
+        },
+        listAll(query) {
+            return flatten(resource.pages(query));
+        }
+    };
+    return resource;
+}

package/dist/resources/envelope.d.ts

@@ -0,0 +1,7 @@
+/**
+ * aether-backend responses are `{success: true, <namedKey>: payload}` envelopes
+ * (e.g. `{success, alerts}`, `{success, trade}`, `{success, deleted}`) rather
+ * than a generic `{data}`. `client.request` returns the whole object for these
+ * (it only auto-unwraps a literal `data` key); resources pluck their named key.
+ */
+export declare function pluck<T>(envelope: unknown, key: string): T;

package/dist/resources/envelope.js

@@ -0,0 +1,15 @@
+/**
+ * aether-backend responses are `{success: true, <namedKey>: payload}` envelopes
+ * (e.g. `{success, alerts}`, `{success, trade}`, `{success, deleted}`) rather
+ * than a generic `{data}`. `client.request` returns the whole object for these
+ * (it only auto-unwraps a literal `data` key); resources pluck their named key.
+ */
+export function pluck(envelope, key) {
+    // `Object.hasOwn` (not `key in envelope`) so an unwrapped array can't match
+    // an `Array.prototype` method — e.g. `'entries' in [x]` is `true`, which
+    // would otherwise return `Array.prototype.entries` instead of throwing.
+    if (typeof envelope !== 'object' || envelope === null || !Object.hasOwn(envelope, key)) {
+        throw new Error(`AetherWealth SDK: malformed response — expected "${key}" in the response envelope`);
+    }
+    return envelope[key];
+}

package/dist/resources/idempotency.d.ts

@@ -0,0 +1,15 @@
+import type { IdempotencyOptions } from '../types.js';
+/**
+ * Resolve the `Idempotency-Key` for a create call.
+ *
+ * - Caller-supplied key → used **verbatim**. Pass a STABLE key to make a retry
+ *   safe: every attempt then dedups to the same backend record
+ *   (`withRetry(() => trades.create(input, {idempotencyKey: key}))`).
+ * - No key → a fresh `crypto.randomUUID()` per call. This protects a single
+ *   call (a network hiccup after the server committed won't create a duplicate
+ *   on a manual re-invoke), but is NOT retry-safe on its own — do not generate
+ *   inside a retried closure, or each attempt gets a new key and dedup is lost.
+ *
+ * Empty strings are treated as "absent" (a blank key can never dedup).
+ */
+export declare function resolveIdempotencyKey(opts?: IdempotencyOptions): string;

package/dist/resources/idempotency.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve the `Idempotency-Key` for a create call.
+ *
+ * - Caller-supplied key → used **verbatim**. Pass a STABLE key to make a retry
+ *   safe: every attempt then dedups to the same backend record
+ *   (`withRetry(() => trades.create(input, {idempotencyKey: key}))`).
+ * - No key → a fresh `crypto.randomUUID()` per call. This protects a single
+ *   call (a network hiccup after the server committed won't create a duplicate
+ *   on a manual re-invoke), but is NOT retry-safe on its own — do not generate
+ *   inside a retried closure, or each attempt gets a new key and dedup is lost.
+ *
+ * Empty strings are treated as "absent" (a blank key can never dedup).
+ */
+export function resolveIdempotencyKey(opts) {
+    if (opts?.idempotencyKey && opts.idempotencyKey.length > 0) {
+        return opts.idempotencyKey;
+    }
+    return crypto.randomUUID();
+}