@aetherwealth/sdk 0.1.32

package/dist/types.d.ts

@@ -0,0 +1,528 @@
+/**
+ * Wire types mirroring the AetherWealth **aether-backend** REST API.
+ *
+ * The backend exposes a uniform POST-RPC surface: `POST /api/<domain>/<action>`
+ * returning `{success, <namedKey>}` (never a generic `{data}`). All response
+ * fields are **camelCase** (`userId`, `entryPrice`, `keyPrefix`). Resources
+ * pluck their named key from the envelope (see `resources/envelope.ts`).
+ *
+ * Only fields the backend Zod schemas actually emit are modeled; version-
+ * tolerant blobs stay `Record<string, unknown>`.
+ */
+export type ApiEnvelope<T> = {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+};
+export type PaginationMeta = {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+};
+/**
+ * A paginated list result: the items plus their pagination metadata. There is
+ * no `success` flag — `client.request` throws a typed error on any failure, so
+ * a resolved `PaginatedResponse` is always a success.
+ */
+export type PaginatedResponse<T> = {
+    data: T[];
+    pagination: PaginationMeta;
+};
+/**
+ * Per-call options for create methods.
+ *
+ * `idempotencyKey` is sent as the `Idempotency-Key` header so a retried create
+ * dedups to a single backend record. When omitted, the SDK generates a fresh
+ * key per call — which protects one call but is NOT retry-safe. To make a
+ * create retry-safe, pass a STABLE key so every attempt reuses it:
+ *
+ * ```ts
+ * const key = crypto.randomUUID()
+ * await withRetry(() => client.trades.create(input, {idempotencyKey: key}))
+ * ```
+ */
+export type IdempotencyOptions = {
+    idempotencyKey?: string;
+};
+export type TradeDirection = 'LONG' | 'SHORT';
+export type TradeStatus = 'OPEN' | 'CLOSED' | 'CANCELLED';
+export type TradeStatusFilter = TradeStatus | 'ALL';
+/** A trade as returned by aether-backend (`tradeSchema`, camelCase). */
+export type Trade = {
+    id: string;
+    userId: string;
+    accountId: string;
+    pair: string;
+    direction: TradeDirection;
+    entryPrice: number;
+    exitPrice: number | null;
+    stopLoss: number | null;
+    takeProfit: number | null;
+    lotSize: number;
+    entryTime: string;
+    exitTime: string | null;
+    status: TradeStatus;
+    pnl: number | null;
+    pnlPercent: number | null;
+    pnlPips: number | null;
+    fees: number;
+    swap: number;
+    notes: string | null;
+    setupNotes: string | null;
+    emotionalTag: string | null;
+    timeframe: string | null;
+    screenshotUrl: string | null;
+    riskPercent: number | null;
+    initialRisk: number | null;
+    rMultiple: number | null;
+    notesFormat: string | null;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type TradeListQuery = {
+    accountId?: string;
+    status?: TradeStatusFilter;
+    pair?: string;
+    from?: string;
+    to?: string;
+    page?: number;
+    limit?: number;
+};
+export type CreateTradeInput = {
+    accountId: string;
+    pair: string;
+    direction: TradeDirection;
+    entryPrice: number;
+    entryTime: string;
+    stopLoss?: number;
+    takeProfit?: number;
+    lotSize?: number;
+    notes?: string;
+    setupNotes?: string;
+    emotionalTag?: string;
+    timeframe?: string;
+    tags?: string[];
+    riskPercent?: number;
+    initialRisk?: number;
+    notesFormat?: string;
+    screenshotUrl?: string;
+};
+export type UpdateTradeInput = {
+    accountId?: string;
+    pair?: string;
+    direction?: TradeDirection;
+    entryPrice?: number;
+    entryTime?: string;
+    stopLoss?: number;
+    takeProfit?: number;
+    lotSize?: number;
+    notes?: string;
+    setupNotes?: string;
+    emotionalTag?: string;
+    timeframe?: string;
+    tags?: string[];
+    riskPercent?: number;
+    initialRisk?: number;
+    notesFormat?: string;
+    screenshotUrl?: string;
+};
+export type CloseTradeInput = {
+    exitPrice: number;
+    exitTime: string;
+    notes?: string;
+    fees?: number;
+    swap?: number;
+};
+export interface TradesResource {
+    list(query?: TradeListQuery): Promise<PaginatedResponse<Trade>>;
+    get(tradeId: string): Promise<Trade>;
+    /**
+     * Create a trade. Sends an `Idempotency-Key` header (auto-generated per call
+     * unless `opts.idempotencyKey` is given). Pass a STABLE key to make the call
+     * retry-safe under `withRetry`.
+     */
+    create(input: CreateTradeInput, opts?: IdempotencyOptions): Promise<Trade>;
+    update(tradeId: string, input: UpdateTradeInput): Promise<Trade>;
+    close(tradeId: string, input: CloseTradeInput): Promise<Trade>;
+    /** Resolves on success; throws `AetherNotFoundError` if the trade is absent. */
+    delete(tradeId: string): Promise<void>;
+    /**
+     * Async-iterate every page of the trade list, auto-advancing `page` until
+     * the last page (or an empty page). Starts at `query.page` if given, else 1.
+     */
+    pages(query?: TradeListQuery): AsyncIterableIterator<PaginatedResponse<Trade>>;
+    /** Async-iterate every trade across all pages (flattened {@link pages}). */
+    listAll(query?: TradeListQuery): AsyncIterableIterator<Trade>;
+}
+export type Account = {
+    id: string;
+    userId: string;
+    name: string;
+    broker: string | null;
+    accountType: string;
+    initialBalance: number;
+    currency: string;
+    notes: string | null;
+    isActive: boolean;
+    defaultRiskAmount: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreateAccountInput = {
+    name: string;
+    broker?: string;
+    accountType?: string;
+    initialBalance?: number;
+    currency?: string;
+    notes?: string;
+    defaultRiskAmount?: number;
+};
+export type UpdateAccountInput = {
+    name?: string;
+    broker?: string;
+    accountType?: string;
+    initialBalance?: number;
+    currency?: string;
+    notes?: string;
+    defaultRiskAmount?: number;
+    isActive?: boolean;
+};
+export interface AccountsResource {
+    list(): Promise<Account[]>;
+    /**
+     * Create an account. Sends an `Idempotency-Key` header (auto-generated per
+     * call unless `opts.idempotencyKey` is given). Pass a STABLE key to make the
+     * call retry-safe under `withRetry`.
+     */
+    create(input: CreateAccountInput, opts?: IdempotencyOptions): Promise<Account>;
+    update(accountId: string, input: UpdateAccountInput): Promise<Account>;
+    /** Resolves on success; throws `AetherNotFoundError` if the account is absent. */
+    delete(accountId: string): Promise<void>;
+    /** Convenience: trades on an account (delegates to `trades.list({accountId})`). */
+    trades(accountId: string, query?: Omit<TradeListQuery, 'accountId'>): Promise<PaginatedResponse<Trade>>;
+    /** Async-iterate every trade on an account across all pages. */
+    tradesAll(accountId: string, query?: Omit<TradeListQuery, 'accountId'>): AsyncIterableIterator<Trade>;
+}
+export type TradingStats = {
+    totalTrades: number;
+    winRate: number;
+    profitFactor: number;
+    totalPnl: number;
+    totalPnlPips: number;
+    avgWin: number;
+    avgLoss: number;
+    maxDrawdown: number;
+    sharpeRatio: number | null;
+    riskRewardAvg: number | null;
+    bestPair: string | null;
+    worstPair: string | null;
+    avgHoldTimeMinutes: number;
+    avgR: number | null;
+    expectancyR: number | null;
+    sqn: number | null;
+    consecutiveWins: number;
+    consecutiveLosses: number;
+};
+export type StatsQuery = {
+    accountId?: string;
+    pair?: string;
+    from?: string;
+    to?: string;
+};
+export interface StatsResource {
+    summary(query?: StatsQuery): Promise<TradingStats>;
+}
+export type PriceCondition = 'above' | 'below' | 'crosses';
+export type TriggerType = 'close' | 'wick';
+export type DedupMode = 'edge' | 'continuous';
+export type AlertType = 'price' | 'trendline';
+export type Alert = {
+    id: string;
+    userId: string;
+    pair: string;
+    timeframe: string;
+    alertType: AlertType;
+    price: number | null;
+    price1: number | null;
+    time1: string | null;
+    price2: number | null;
+    time2: string | null;
+    slope: number | null;
+    intercept: number | null;
+    condition: PriceCondition | null;
+    triggerType: TriggerType;
+    isPersistent: boolean;
+    isActive: boolean;
+    isArchived: boolean;
+    notifyEmail: boolean;
+    notifyPush: boolean;
+    message: string | null;
+    triggeredAt: string | null;
+    triggeredPrice: number | null;
+    triggerCount: number;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ThresholdOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'crosses_above' | 'crosses_below';
+export type SeriesOp = 'gt_series' | 'lt_series' | 'crosses_above_series' | 'crosses_below_series';
+/** Indicator-alert condition DSL: threshold ops carry a number, series ops a peer series. */
+export type IndicatorCondition = {
+    op: ThresholdOp;
+    threshold: number;
+} | {
+    op: SeriesOp;
+    other: string;
+};
+export type IndicatorAlert = {
+    id: string;
+    userId: string;
+    pair: string;
+    timeframe: string;
+    indicatorType: string;
+    indicatorParams: Record<string, unknown>;
+    customIndicatorId: string | null;
+    customIndicatorVersion: number | null;
+    outputSeries: string | null;
+    condition: IndicatorCondition | null;
+    triggerType: TriggerType;
+    dedupMode: DedupMode;
+    isActive: boolean;
+    isArchived: boolean;
+    isTriggered: boolean;
+    isPersistent: boolean;
+    notifyEmail: boolean;
+    notifyPush: boolean;
+    message: string | null;
+    triggeredAt: string | null;
+    triggeredPrice: number | null;
+    triggerCount: number;
+    lastConditionState: string | null;
+    lastTriggeredValue: number | null;
+    lastEvaluatedAt: string | null;
+    lastError: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CreatePriceAlertInput = {
+    pair: string;
+    timeframe: string;
+    price: number;
+    condition: PriceCondition;
+    triggerType: TriggerType;
+    isPersistent: boolean;
+    notifyEmail: boolean;
+    notifyPush: boolean;
+    message?: string;
+    expiresAt?: string | null;
+};
+export type CreateTrendlineAlertInput = {
+    pair: string;
+    timeframe: string;
+    price1: number;
+    time1: string;
+    price2: number;
+    time2: string;
+    condition: PriceCondition;
+    triggerType: TriggerType;
+    isPersistent: boolean;
+    notifyEmail: boolean;
+    notifyPush: boolean;
+    message?: string;
+    expiresAt?: string | null;
+};
+export type UpdateAlertInput = {
+    price?: number;
+    price1?: number;
+    price2?: number;
+    time1?: string;
+    time2?: string;
+    condition?: PriceCondition;
+    triggerType?: TriggerType;
+    timeframe?: string;
+    isActive?: boolean;
+    isArchived?: boolean;
+    isPersistent?: boolean;
+    notifyEmail?: boolean;
+    notifyPush?: boolean;
+    message?: string;
+    expiresAt?: string | null;
+};
+export type ListAlertsQuery = {
+    includeArchived?: boolean;
+    pair?: string;
+};
+export type CreateIndicatorAlertInput = {
+    pair: string;
+    timeframe: string;
+    indicatorType: string;
+    indicatorParams: Record<string, unknown>;
+    outputSeries: string;
+    condition: IndicatorCondition;
+    triggerType: TriggerType;
+    dedupMode: DedupMode;
+    isPersistent: boolean;
+    notifyEmail: boolean;
+    notifyPush: boolean;
+    customIndicatorId?: string;
+    customIndicatorVersion?: number;
+    message?: string;
+    expiresAt?: string | null;
+};
+export type UpdateIndicatorAlertInput = {
+    condition?: IndicatorCondition;
+    dedupMode?: DedupMode;
+    triggerType?: TriggerType;
+    isActive?: boolean;
+    isArchived?: boolean;
+    isPersistent?: boolean;
+    notifyEmail?: boolean;
+    notifyPush?: boolean;
+    message?: string;
+    expiresAt?: string | null;
+};
+export interface AlertsResource {
+    list(query?: ListAlertsQuery): Promise<Alert[]>;
+    /** Create a price alert. Sends an `Idempotency-Key` header (see {@link IdempotencyOptions}). */
+    createPrice(input: CreatePriceAlertInput, opts?: IdempotencyOptions): Promise<Alert>;
+    /** Create a trendline alert. Sends an `Idempotency-Key` header (see {@link IdempotencyOptions}). */
+    createTrendline(input: CreateTrendlineAlertInput, opts?: IdempotencyOptions): Promise<Alert>;
+    update(alertId: string, input: UpdateAlertInput): Promise<Alert>;
+    /** Resolves on success; throws `AetherNotFoundError` if the alert is absent. */
+    delete(alertId: string): Promise<void>;
+    listIndicator(query?: ListAlertsQuery): Promise<IndicatorAlert[]>;
+    /** Create an indicator alert. Sends an `Idempotency-Key` header (see {@link IdempotencyOptions}). */
+    createIndicator(input: CreateIndicatorAlertInput, opts?: IdempotencyOptions): Promise<IndicatorAlert>;
+    updateIndicator(alertId: string, input: UpdateIndicatorAlertInput): Promise<IndicatorAlert>;
+    /** Resolves on success; throws `AetherNotFoundError` if the alert is absent. */
+    deleteIndicator(alertId: string): Promise<void>;
+}
+/** Nested instrument metadata keys are snake_case (emitted literally by the backend). */
+export type MarketConfig = {
+    supportedTAPairs: Record<string, Record<string, unknown>>;
+    supportedFAPairs: Record<string, unknown>;
+    supportedTimeframes: string[];
+    supportedFACurrencies: string[];
+};
+export type EconomicEventMinimal = {
+    id: string;
+    currency: string;
+    release: string;
+    eventName: string;
+    announcementUnix: number;
+    impact: number;
+    actual: number | null;
+    forecast: number | null;
+    previous: number | null;
+};
+export type EconomicEventRich = EconomicEventMinimal & {
+    releaseDateLocal: string | null;
+    currencyTimezone: string | null;
+    changeMom: number | null;
+    changeQoq: number | null;
+    changeYoy: number | null;
+    surpriseDelta: number | null;
+    surpriseDirection: string | null;
+    trend: string | null;
+    revisionCount: number | null;
+    unit: string | null;
+};
+export type EconomicEvent = EconomicEventMinimal | EconomicEventRich;
+export type CalendarQuery = {
+    currency?: string[];
+    from?: string;
+    to?: string;
+    indicator?: string;
+    impactMin?: number;
+    view?: 'minimal' | 'rich';
+};
+export type CalendarResult = {
+    events: EconomicEvent[];
+    view: string;
+};
+export type MacroSeriesQuery = {
+    currency: string;
+    indicator: string;
+    from?: string;
+    to?: string;
+    limit?: number;
+};
+/**
+ * Raw fxmacrodata series passed through by `/api/macro/:currency/:indicator`.
+ * `has_official_forecast`, `announcement_datetime`, and `cb_target` are
+ * snake_case because the upstream `fxmacrodata-client` emits them that way and
+ * the backend forwards them untransformed — same reasoning as `MarketConfig`.
+ */
+export type MacroSeriesResult = {
+    currency: string;
+    indicator: string;
+    unit?: string;
+    frequency?: string;
+    has_official_forecast?: boolean;
+    series: {
+        date: string;
+        val: number;
+        announcement_datetime: number;
+    }[];
+    cb_target?: Record<string, unknown>;
+    cachedAt?: number;
+};
+export type MacroRange = '3m' | '6m' | '12m' | '24m' | 'all';
+/** Args for `market.macro` — an object (not positional) so the two same-typed
+ *  `currency`/`indicator` strings can't be silently transposed. */
+export type MacroQuery = {
+    /** 3-letter currency code, e.g. `USD`. */
+    currency: string;
+    /** Indicator slug (letters/digits/underscores), e.g. `cpi`. */
+    indicator: string;
+    range?: MacroRange;
+};
+export interface MarketResource {
+    config(): Promise<MarketConfig>;
+    calendar(query?: CalendarQuery): Promise<CalendarResult>;
+    /** Economic-calendar rich events for a currency+indicator (`/api/public/v1/market/macro-series`). */
+    macroSeries(query: MacroSeriesQuery): Promise<EconomicEventRich[]>;
+    /** fxmacrodata time series for a currency+indicator (`/api/public/v1/market/macro`). */
+    macro(query: MacroQuery): Promise<MacroSeriesResult | null>;
+}
+export type DiaryEntry = {
+    id: string;
+    date: string;
+    content: string;
+    mood: string | null;
+    rating: number | null;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type DiaryListQuery = {
+    from?: string;
+    to?: string;
+    page?: number;
+    limit?: number;
+};
+export type UpsertDiaryInput = {
+    date: string;
+    content: string;
+    mood?: string | null;
+    rating?: number | null;
+    tags?: string[];
+};
+export interface DiaryResource {
+    list(query?: DiaryListQuery): Promise<PaginatedResponse<DiaryEntry>>;
+    get(date: string): Promise<DiaryEntry>;
+    upsert(input: UpsertDiaryInput): Promise<DiaryEntry>;
+    /** Resolves on success; throws `AetherNotFoundError` if the entry is absent. */
+    delete(date: string): Promise<void>;
+    /**
+     * Async-iterate every page of diary entries, auto-advancing `page` until the
+     * last page (or an empty page). Starts at `query.page` if given, else 1.
+     */
+    pages(query?: DiaryListQuery): AsyncIterableIterator<PaginatedResponse<DiaryEntry>>;
+    /** Async-iterate every diary entry across all pages (flattened {@link pages}). */
+    listAll(query?: DiaryListQuery): AsyncIterableIterator<DiaryEntry>;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Wire types mirroring the AetherWealth **aether-backend** REST API.
+ *
+ * The backend exposes a uniform POST-RPC surface: `POST /api/<domain>/<action>`
+ * returning `{success, <namedKey>}` (never a generic `{data}`). All response
+ * fields are **camelCase** (`userId`, `entryPrice`, `keyPrefix`). Resources
+ * pluck their named key from the envelope (see `resources/envelope.ts`).
+ *
+ * Only fields the backend Zod schemas actually emit are modeled; version-
+ * tolerant blobs stay `Record<string, unknown>`.
+ */
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@aetherwealth/sdk",
+    "version": "0.1.32",
+    "description": "Official Aether Wealth SDK: a typed TypeScript client for the Aether Wealth public API — trades, accounts, analytics, alerts, market data, macro calendar, and diary.",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "dependencies": {
+        "zod": "^4.4.3"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "aether wealth",
+        "aetherwealth",
+        "sdk",
+        "trading",
+        "trading journal",
+        "trading api",
+        "api client",
+        "forex",
+        "market data",
+        "technical indicators"
+    ],
+    "author": "Aether Wealth <support@aetherwealth.ai>",
+    "license": "MIT",
+    "homepage": "https://aetherwealth.ai/sdk",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Opus-Aether-AI/webapp.git",
+        "directory": "packages/sdk"
+    },
+    "bugs": {
+        "url": "https://github.com/Opus-Aether-AI/webapp/issues"
+    }
+}