@wheelium/client 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+The SDK has independent versions from the CLI and the private web application.
+Default SemVer: **patch** for fixes only; **minor** for backward-compatible
+capabilities or installation/onboarding/distribution improvements; **major** for
+breaking API, transport, authentication, supported-runtime or wire-type behavior.
+Update this changelog for each release. A manifest version is not publication.
+
+## 0.1.0 — 2026-10-09
+
+- Browser/Node >=24 ESM fetch client, shared by web app, integrations and CLI.
+- Typed existing read, tracker/share/order, settings, invitation and key methods.
+- Dynamic session token provider or static scoped-key credential, origin-bound
+  authenticated transport and explicitly unauthenticated public snapshots.
+- Structured safe errors, abort/overall timeout, bounded safe-read retries,
+  preserved nullable/date/money wire types; no automatic mutation retries.
+- Generated declarations, server-derived synthetic wire fixtures, OpenAPI drift
+  validation and clean local pack/install verification.

package/LICENSE

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

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @wheelium/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small ESM client for supported browsers and Node >=24, using native `fetch`. This package has no runtime dependencies and does not read environment variables, storage or browser globals. It is not a login/OAuth SDK. Package publication is a separate release step.
+
+Install with `npm install @wheelium/client` once the initial registry release is published.
+Use Node >=24. Publication is verified against npm, not inferred from a manifest.
+The package version and release history are in [CHANGELOG.md](CHANGELOG.md).
+
+Source [API contract](https://github.com/davidguttman/trade-tracker/blob/main/docs/reference/scoped-api.md)
+and [integration guide](https://github.com/davidguttman/trade-tracker/blob/main/docs/scoped-api-integrations.md)
+require repository access: the application's source repository is private.
+The public package includes its usage documentation and generated declarations.
+Independent release policy/history: [CHANGELOG.md](CHANGELOG.md), [LICENSE](LICENSE).
+
+## Local source and packed installation
+
+With Node 24 on PATH, from repository root: `npm run test:api-contract`,
+`npm run test:sdk`, `node examples/scoped-client.mjs --synthetic`, and
+`npm run pack:public`. The last command prints the exact SDK/CLI tarball paths in
+a unique TEMP directory. In a new consumer directory run `npm init -y`, then
+`npm install --offline --ignore-scripts --no-audit --no-fund /exact/printed/wheelium-client-0.1.0.tgz`.
+Import `@wheelium/client` there. Install both printed tarballs together if using
+the CLI, whose SDK dependency is exact. No registry publication/global install is
+performed. The source example's `--synthetic` uses fake metadata/money/empty trades
+without network access; actual controlled reads require an explicit runtime key
+and managed development base from the caller's own secret/config adapter.
+
+```js
+import { createClient, WheeliumError } from '@wheelium/client'
+const wheelium = createClient({ apiKey: 'YOUR_KEY' })
+const identity = await wheelium.me()
+const portfolio = await wheelium.portfolio.get({ includeGreeks: true })
+const quotes = await wheelium.market.quotes({ optionSymbols: ['AAPL270115P00200000'] })
+```
+
+Provide **exactly one** of `apiKey` or sync/async `getToken`. The provider runs for every request/attempt; returning null/undefined intentionally makes an unauthenticated request (useful for session adapters). Wheelium's server, not this package, decides authorization. Browser key management requires a session; existing session-only methods do not become API-key capabilities merely because they are exposed here.
+
+Default `baseUrl`: `https://api.wheelium.app`. Explicit HTTPS development origins (including jump.sh) are supported. Relative bases are resolved by the browser adapter before creating the client; the library never accesses `window`. HTTP is allowed only for explicit loopback (`localhost`, `127.0.0.1`, `[::1]`) development/test bases. Embedded URL credentials and fragments are rejected. Authenticated requests cannot escape their configured base or follow redirects. `shares.publicSnapshot(httpsStorageUrl)` is explicitly unauthenticated, omits cookies, and rejects redirects; it never sends bearer credentials to storage.
+
+Domain groups: `trades`, `portfolio`, `market`, `advisor`, `account`, `orders`, `shares`, `settingsAlpaca`, `invitations`, `keys`, and `backtest`; `me()` returns identity/scopes/broker metadata. Methods preserve server JSON exactly: dates stay strings, nullable values stay null, and broker account cash/buying power stay strings. Portfolio math stays on the server. Generated declarations document each method's input/output and support typed consumers. Flexible provider fields are represented as unknown, not `any`.
+
+## Failures, cancellation and retries
+
+`WheeliumError` has `status` (0 for transport failures), `code`, `requestId`, and `requiredScopes`. HTTP payloads preserve safe legacy error messages; non-JSON error bodies are never exposed. Stable transport codes include `network_error`, `invalid_response`, `timeout`, `aborted`, `unsafe_url`, and `unsafe_redirect`. Errors do not retain raw response bodies, headers or credentials. There is no SDK logging. UI redirects/logout are exclusively the web adapter's behavior.
+
+All methods accept a final `{ signal }` option. `timeoutMs` (default 30 seconds) bounds the entire operation, including dynamic token resolution, response body consumption and retries. Aborted body readers are cancelled and timers/listeners are cleaned up.
+
+Only explicitly classified ordinary reads and the quote/earnings batch POST reads retry transient network failures or 408/429/500/502/503/504. Default `maxRetries` is 2; supported range 0–3. `Retry-After` is respected; otherwise exponential delays include jitter (`retryDelayMs` defaults to 250). The overall timeout still bounds waiting. 401/403 never retry. Backtests, credential testing, uploads, tracker mutations, publication and all order mutations never automatically retry, even if a caller passes a retry flag.
+
+**Order outcome can be uncertain:** a timeout, network error or failed response does not prove the broker rejected an order. Reconcile the existing broker order/account/trade state (and `clientOrderId` where supported) before resubmitting. The library does not promise exactly-once execution or automatic idempotency. `orders.list()` is the existing equity-order listing; no option-order listing endpoint is invented.
+
+`request(path, options)` is a transitional typed low-level escape hatch. `rawResponse: true` returns a buffered Response for legacy consumers, covering body consumption with the same timeout. JSON calls return undefined for 204/empty bodies. Passing FormData preserves its multipart boundary rather than forcing JSON Content-Type.
+
+## Repository verification
+
+From the repository root: `npm run client:types`, `npm run test:client-types`, and `npm run test:sdk`. Declaration artifacts are generated from the JS public entry's JSDoc and `types.ts` wire contracts. `test:client-types` detects source/declaration drift and validates typed usage, including forbidden credential combinations and incorrect money/order inputs. The web app imports the same `packages/client/index.js` entry that this package exports; no root workspace or file dependency is required.
+
+Declaration drift checks compare generated files to handwritten types; they do not prove the server contract. `test/client/wire.test.mjs` separately executes the actual server trade/position builders and earnings assembly with synthetic offline inputs, pins their JSON against typed fixtures, and checks SDK pass-through. Read trades may have null fills/tickers or missing persisted metadata; pair trades may come from broker positions without an ID. Write inputs and persisted get/create/update results keep their stricter record types. Earnings history remains an array of date strings.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Exactly one credential source; token providers are evaluated for each attempt.
+ * Only domain methods explicitly marked safe may retry (never mutations/backtests).
+ * @param {ClientOptions} options
+ * @returns {WheeliumClient}
+ */
+export function createClient(options: ClientOptions): WheeliumClient;
+/** @import { RequestOptions } from './types.js' */
+/** An HTTP or transport failure. Bodies, headers and credentials are never retained. */
+export class WheeliumError extends Error {
+    /** @param {string} message @param {{status?: number, code?: string, requestId?: string, requiredScopes?: string[]}} [details] */
+    constructor(message: string, details?: {
+        status?: number;
+        code?: string;
+        requestId?: string;
+        requiredScopes?: string[];
+    });
+    status: number;
+    code: string;
+    requestId: string | undefined;
+    requiredScopes: string[];
+}
+export type ClientOptions = import("./types.js").ClientOptions;
+export type WheeliumClient = import("./types.js").WheeliumClient;
+export type Trade = import("./types.js").Trade;
+export type Scope = import("./types.js").Scope;
+export type CallOptions = import("./types.js").CallOptions;

package/dist/types.d.ts

@@ -0,0 +1,664 @@
+export type Scope = 'trades:read' | 'portfolio:read' | 'market:read' | 'advisor:read' | 'account:read' | 'orders:read' | 'shares:read' | 'backtests:run' | 'trades:write' | 'shares:write' | 'orders:write' | 'orders:cancel';
+export type BrokerMode = 'paper' | 'live';
+export type OptionType = 'PUT' | 'CALL';
+export type TradeAction = 'STO' | 'BTC' | 'ASSIGN' | 'CALLED' | 'SELL_STOCK' | 'BUY_STOCK';
+export interface WireObject {
+    [key: string]: unknown;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+}
+export interface RequestOptions extends CallOptions {
+    method?: string;
+    headers?: HeadersInit;
+    body?: BodyInit;
+    authenticated?: boolean;
+    rawResponse?: boolean;
+    safeRetry?: boolean;
+}
+export type ClientOptions = {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+} & ({
+    apiKey: string;
+    getToken?: never;
+} | {
+    apiKey?: never;
+    getToken: () => string | null | undefined | Promise<string | null | undefined>;
+});
+export interface Me {
+    type: 'session' | 'api_key';
+    userId: string;
+    email: string;
+    scopes: Scope[];
+    expiresAt: string | null;
+    broker: {
+        configured: boolean;
+        mode: BrokerMode | null;
+        allowedMode: BrokerMode | null;
+    };
+}
+export interface Greeks {
+    delta: number | null;
+    gamma: number | null;
+    theta: number | null;
+    vega: number | null;
+}
+export interface TradeInput {
+    symbol: string;
+    action: TradeAction;
+    date: string;
+    contracts: number;
+    fillPrice: number;
+    strike: number;
+    type?: OptionType | null;
+    expiration?: string | null;
+    optionSymbol?: string | null;
+    ticker?: string;
+    notes?: string | null;
+    source?: string;
+    alpacaOrderId?: string | null;
+    clientOrderId?: string | null;
+    underlyingPrice?: number | null;
+    greeks?: Greeks | null;
+    impliedVolatility?: number | null;
+}
+export interface ReadTrade extends WireObject {
+    symbol: string;
+    action: TradeAction;
+    date: string;
+    contracts: number;
+    strike: number;
+    fillPrice: number | null;
+    type?: OptionType | null;
+    expiration?: string | null;
+    optionSymbol?: string | null;
+    ticker?: string | null;
+    notes?: string | null;
+    source?: string;
+    userKey?: string | null;
+    premium?: number | null;
+    leverage?: number;
+    underlyingPrice?: number | null;
+    greeks?: Greeks | null;
+    impliedVolatility?: number | null;
+    _id?: string;
+    side?: 'buy' | 'sell';
+    positionEffect?: 'open' | 'close';
+    dateCreated?: string | null;
+    dateUpdated?: string | null;
+    alpacaStatus?: string | null;
+    alpacaOrderId?: string | null;
+    clientOrderId?: string | null;
+}
+export interface PersistedTrade extends ReadTrade {
+    _id: string;
+    fillPrice: number;
+    side: 'buy' | 'sell';
+    positionEffect: 'open' | 'close';
+    dateCreated: string;
+    dateUpdated: string;
+}
+export interface BrokerOrderTrade extends ReadTrade {
+    _id: string;
+    source: 'alpaca';
+    action: 'STO' | 'BTC';
+    type: OptionType;
+    expiration: string;
+    optionSymbol: string;
+    side: 'buy' | 'sell';
+    positionEffect: 'open' | 'close';
+    dateCreated: string | null;
+    dateUpdated: string | null;
+    limitPrice: number | null;
+    filledContracts: number;
+    requestedContracts: number | null;
+    isPending: boolean;
+    alpacaFilledAt: string | null;
+}
+export interface BrokerAssignmentTrade extends ReadTrade {
+    _id: string;
+    source: 'alpaca-activity';
+    action: 'ASSIGN' | 'CALLED';
+    fillPrice: 0;
+}
+export type Trade = PersistedTrade | BrokerOrderTrade | BrokerAssignmentTrade;
+export interface BrokerPositionTrade extends ReadTrade {
+    source: 'alpaca-position';
+    action: 'STO' | 'BTC';
+    fillPrice: number;
+    type: OptionType;
+    expiration: string;
+    ticker: string;
+    premium: number;
+    leverage: number;
+}
+export type PairTrade = Trade | BrokerPositionTrade;
+export interface Pair extends WireObject {
+    ticker?: string | null;
+    duration: number | null;
+    totalPL: number | null;
+    returnPercent: number | null;
+    dailyReturn: number | null;
+    maxRisk: number;
+    annualizedReturn: number | null;
+    openTrade: PairTrade;
+    closeTrade: PairTrade | null;
+    stockPrice?: number | null;
+    btcAsk?: number | null;
+    btcBid?: number | null;
+    currentDTE?: number | null;
+}
+export interface PortfolioPair extends WireObject {
+    ticker: string;
+    duration: number;
+    totalPL: number;
+    returnPercent: number;
+    dailyReturn: number;
+    maxRisk: number;
+    annualizedReturn?: number;
+    startTrade?: Trade;
+    exitTrade?: Trade;
+}
+export interface StockPosition extends WireObject {
+    symbol: string;
+    qty?: string | number;
+    quantity?: number;
+    shares: number;
+    costBasis: number | null;
+    totalCost?: number | null;
+    currentPrice?: number | null;
+    marketValue?: number | null;
+    unrealizedPL?: number | null;
+    unrealizedPLPercent?: number | null;
+}
+export interface PortfolioPoint extends WireObject {
+    date: string;
+    pairNumber: number;
+    currentPair: PortfolioPair;
+    totalPairs: number;
+    cashBalance: number;
+    cumulativeProfit: number;
+    portfolioDailyProfit: number;
+    annualizedProfit: number;
+    annualizedReturn: number;
+    avgLeverage: number;
+}
+export interface DailyPL extends WireObject {
+    dailyData: Array<WireObject & {
+        date: string;
+        cumulativePL: number;
+        optionsRealizedPL: number;
+        stockRealizedPL: number;
+        stockHoldingsPL: number;
+        totalPL: number;
+    }>;
+    avgCapitalAtRisk: number;
+    stockHoldings: number;
+}
+export interface ContractQuery {
+    symbol: string;
+    expirationDateGte?: string;
+    expirationDateLte?: string;
+    strikeMin?: number;
+    strikeMax?: number;
+    type?: 'call' | 'put' | 'both';
+    includeQuotes?: boolean;
+    includeGreeks?: boolean;
+}
+export interface Contract extends WireObject {
+    symbol: string;
+    strike_price?: string;
+    expiration_date?: string;
+    type?: 'call' | 'put';
+    greeks?: Greeks | null;
+}
+export interface OptionQuote extends WireObject {
+    optionSymbol: string;
+    underlyingSymbol: string | null;
+    underlyingPrice: number | null;
+    timestamp: string | null;
+    last: number | null;
+    askSize: number | null;
+    bidSize: number | null;
+    greeksSource: string | null;
+    greeksAsOf: string | null;
+    greeksStale: boolean;
+    bid?: number | null;
+    ask?: number | null;
+    mid?: number | null;
+    greeks?: Greeks | null;
+    impliedVolatility?: number | null;
+}
+export interface Earnings extends WireObject {
+    symbol: string;
+    available?: boolean;
+    message?: string;
+    upcoming?: {
+        date: string;
+        daysUntil: number;
+        confirmed: boolean;
+        time: string | null;
+    } | null;
+    historical?: string[];
+}
+export interface EquityOrderInput {
+    symbol: string;
+    side: 'buy' | 'sell';
+    qty: number | string;
+}
+export interface OptionsOrderInput {
+    symbol: string;
+    limitPrice: number;
+    quantity?: number;
+    clientOrderId?: string;
+    action?: 'STO' | 'BTC';
+    underlyingPrice?: number;
+    greeks?: Greeks | null;
+    impliedVolatility?: number;
+}
+export interface RollOrderInput {
+    closeSymbol: string;
+    openSymbol: string;
+    limitPrice: number;
+    quantity?: number;
+    clientOrderId?: string;
+}
+export interface BrokerOrder extends WireObject {
+    id: string;
+    status: string;
+    symbol?: string;
+    qty?: string;
+    filled_qty?: string;
+    filled_avg_price?: string | null;
+    client_order_id?: string;
+}
+export interface OptionsOrderResult {
+    status: string;
+    orderId: string;
+    clientOrderId: string;
+    filledQuantity: number;
+    fillPrice: number | null;
+    limitPrice: number;
+    raw: BrokerOrder;
+    legs?: {
+        symbol: string;
+        side: string;
+        intent: string;
+    }[];
+}
+export interface AlpacaConfig {
+    configured: boolean;
+    endpoint: BrokerMode | null;
+    keyIdLast4: string | null;
+}
+export interface AlpacaCredentials {
+    endpoint: BrokerMode;
+    keyId: string;
+    secretKey: string;
+}
+export interface ShareMetadata {
+    id: string;
+    pageType: 'portfolio' | 'positions';
+    createdAt: string;
+    shareUrl: string;
+    imageUrl?: string;
+}
+export interface Snapshot extends WireObject {
+    pageType: 'portfolio' | 'positions';
+    data: WireObject;
+    createdAt: string;
+    redacted: true;
+}
+export interface KeyMetadata {
+    id: string;
+    prefix: string;
+    name: string;
+    scopes: Scope[];
+    brokerMode: BrokerMode;
+    createdAt: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
+}
+export interface KeyInput {
+    name: string;
+    scopes?: Scope[];
+    expiresInDays?: 30 | 90 | 365 | null;
+    brokerMode?: BrokerMode;
+}
+export interface Signal extends WireObject {
+    action: string;
+    urgency: 'high' | 'medium' | 'low' | 'none';
+    reason?: string;
+    recommendation?: string;
+    metrics?: WireObject & {
+        symbol?: string;
+        strike?: number;
+        btcAsk?: number | null;
+        totalPL?: number | null;
+        ivRank?: number | null;
+    };
+}
+export interface RollCandidate extends WireObject {
+    ticker: string;
+    strike: number;
+    expiration: string;
+    type: OptionType;
+    dte: number;
+    delta: number | null;
+    bid: number;
+    ask: number | null;
+    mid: number | null;
+    impliedVolatility: number | null;
+    netCredit: number;
+    costToClose: number;
+    newPremium: number;
+    annualizedReturn: number;
+}
+export interface AdvisorPosition extends WireObject {
+    position: Pair;
+    signal: Signal;
+}
+export interface IVR extends WireObject {
+    symbol: string;
+    source: string;
+    stats: {
+        minIV: number;
+        maxIV: number;
+        avgIV: number;
+        dataPoints?: number;
+        dataDate?: string;
+        currentIV: number | null;
+        ivRank: number | null;
+    };
+    history: {
+        date: string;
+        avgIV: number;
+        contracts?: number;
+        ivr?: number | null;
+    }[];
+    interpretation: {
+        level: 'high' | 'moderate' | 'low';
+        description: string;
+        recommendation: string;
+    } | null;
+}
+export interface BacktestQuery {
+    symbol: string;
+    start: string;
+    end: string;
+    strategy?: string;
+    deltaMin?: number | string;
+    deltaMax?: number | string;
+    dteMin?: number | string;
+    dteMax?: number | string;
+    profitTarget?: number | string;
+    minIvr?: number | string;
+    minVolume?: number | string;
+}
+export interface WheeliumClient {
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    me(options?: CallOptions): Promise<Me>;
+    trades: {
+        list(options?: CallOptions): Promise<Trade[]>;
+        get(id: string, options?: CallOptions): Promise<PersistedTrade>;
+        pairs(params?: {
+            includeGreeks?: boolean;
+            includeStockHoldings?: boolean;
+        }, options?: CallOptions): Promise<Pair[] | {
+            pairs: Pair[];
+            stockPositions: StockPosition[];
+        }>;
+        create(body: TradeInput, options?: CallOptions): Promise<PersistedTrade>;
+        update(id: string, body: Partial<TradeInput>, options?: CallOptions): Promise<PersistedTrade>;
+        delete(id: string, options?: CallOptions): Promise<void>;
+        cancelBrokerOrder(id: string, options?: CallOptions): Promise<{
+            success: boolean;
+            message: string;
+            raw?: unknown;
+        }>;
+    };
+    portfolio: {
+        get(params?: {
+            includeGreeks?: boolean;
+            comparison?: string;
+        }, options?: CallOptions): Promise<PortfolioPoint[]>;
+        dailyPL(params?: {
+            comparison?: string;
+        }, options?: CallOptions): Promise<DailyPL>;
+    };
+    market: {
+        contracts(params: ContractQuery, options?: CallOptions): Promise<{
+            symbol: string;
+            count: number;
+            contracts: Contract[];
+        }>;
+        quote(symbol: string, options?: CallOptions): Promise<{
+            symbol: string;
+            price: number;
+            date: string;
+        }>;
+        quotes(body: {
+            optionSymbols: string[];
+            includeGreeks?: boolean;
+        }, options?: CallOptions): Promise<{
+            quotes: OptionQuote[];
+        }>;
+        earnings(symbol: string, options?: CallOptions): Promise<Earnings>;
+        earningsBatch(body: {
+            symbols: string[];
+        }, options?: CallOptions): Promise<{
+            earnings: Record<string, Earnings | null>;
+        }>;
+        fomc(params?: {
+            daysAhead?: number;
+        }, options?: CallOptions): Promise<{
+            upcoming: {
+                date: string;
+                daysUntil: number;
+            }[];
+            next: {
+                date: string;
+                daysUntil: number;
+            } | null;
+            allDates: string[];
+        }>;
+        expirations(params: {
+            symbol: string;
+            type?: 'call' | 'put';
+            daysAhead?: number;
+        }, options?: CallOptions): Promise<{
+            symbol: string;
+            type: string;
+            expirations: {
+                date: string;
+                dte: number;
+            }[];
+        }>;
+        fundamentals(symbol: string, options?: CallOptions): Promise<WireObject & {
+            symbol: string;
+            available: boolean;
+            name?: string | null;
+            eps?: number | null;
+            peRatio?: number | null;
+            dividendYield?: number | null;
+            marketCap?: number | null;
+            high52w?: number | null;
+            low52w?: number | null;
+        }>;
+        priceProbability(params: {
+            symbol: string;
+            dteMin?: number;
+            dteMax?: number;
+        }, options?: CallOptions): Promise<{
+            symbol: string;
+            currentPrice: number;
+            historicalDataPoints: number;
+            distributions: {
+                dte: number;
+                date: string;
+                dataPoints: number;
+                historical: Record<'min' | 'p10' | 'p25' | 'median' | 'mean' | 'p75' | 'p90' | 'max' | 'stdDev', number>;
+            }[];
+        }>;
+        ivr(symbol: string, params?: {
+            currentIV?: number;
+            historyDays?: number;
+        }, options?: CallOptions): Promise<IVR>;
+        ivrSymbols(options?: CallOptions): Promise<{
+            symbols: string[];
+            count: number;
+            source: string;
+        }>;
+    };
+    advisor: {
+        notifications(params?: {
+            urgency?: string;
+            includeHold?: boolean;
+        }, options?: CallOptions): Promise<{
+            positions: AdvisorPosition[];
+            summary: WireObject & {
+                filtered: number;
+                total: number;
+                needsAction: number;
+            };
+        }>;
+        analyze(ticker: string, params?: {
+            includeRollCandidates?: boolean;
+        }, options?: CallOptions): Promise<{
+            position: Pair;
+            signal: Signal;
+            config: Record<string, number>;
+            rollCandidates?: RollCandidate[];
+            rollCandidatesError?: string;
+        }>;
+        rollCandidates(params: {
+            symbol: string;
+            type: OptionType;
+            currentStrike: number;
+            btcAsk?: number;
+            contracts?: number;
+        }, options?: CallOptions): Promise<{
+            symbol: string;
+            type: OptionType;
+            currentStrike: number;
+            costToClose: number;
+            candidates: RollCandidate[];
+            count: number;
+        }>;
+        config(options?: CallOptions): Promise<{
+            config: Record<string, number>;
+            description: Record<string, string>;
+        }>;
+    };
+    account: {
+        get(options?: CallOptions): Promise<{
+            buyingPower: string;
+            cash: string;
+        }>;
+    };
+    orders: {
+        list(options?: CallOptions): Promise<{
+            orders: BrokerOrder[];
+        }>;
+        placeEquity(body: EquityOrderInput, options?: CallOptions): Promise<BrokerOrder>;
+        cancel(id: string, options?: CallOptions): Promise<{
+            success: boolean;
+            message: string;
+        }>;
+        placeOptions(body: OptionsOrderInput, options?: CallOptions): Promise<OptionsOrderResult>;
+        roll(body: RollOrderInput, options?: CallOptions): Promise<OptionsOrderResult>;
+    };
+    shares: {
+        list(options?: CallOptions): Promise<ShareMetadata[]>;
+        create(body: FormData | {
+            page: 'portfolio' | 'positions';
+            data: WireObject;
+        }, options?: CallOptions): Promise<{
+            shareUrl: string;
+            id: string;
+        }>;
+        delete(id: string, options?: CallOptions): Promise<{
+            success: boolean;
+        }>;
+        publicSnapshot(url: string, options?: CallOptions): Promise<Snapshot>;
+    };
+    settingsAlpaca: {
+        get(options?: CallOptions): Promise<AlpacaConfig>;
+        save(body: AlpacaCredentials, options?: CallOptions): Promise<AlpacaConfig>;
+        test(body?: Partial<AlpacaCredentials>, options?: CallOptions): Promise<{
+            ok: boolean;
+            error?: string;
+            details?: string | {
+                accountId: string;
+                status: string;
+                currency: string;
+                tradingBlocked: boolean;
+                accountBlocked: boolean;
+            };
+        }>;
+        delete(options?: CallOptions): Promise<{
+            deleted: boolean;
+        }>;
+    };
+    invitations: {
+        status(options?: CallOptions): Promise<{
+            status: 'active' | 'pending';
+            email: string;
+        }>;
+        redeem(body: {
+            code: string;
+        }, options?: CallOptions): Promise<{
+            status: 'active' | 'pending';
+        }>;
+    };
+    keys: {
+        list(options?: CallOptions): Promise<KeyMetadata[]>;
+        create(body: KeyInput, options?: CallOptions): Promise<KeyMetadata & {
+            apiKey: string;
+        }>;
+        revoke(id: string, options?: CallOptions): Promise<{
+            success: boolean;
+        }>;
+    };
+    backtest: {
+        run(params: BacktestQuery, options?: CallOptions): Promise<{
+            summary: {
+                totalPL: number;
+                totalTrades: number;
+                winRate: number;
+                avgPLPerTrade: number;
+                totalReturn: number;
+                annualizedReturn: number;
+                avgCapitalAtRisk: number;
+                tradingDays: number;
+                daysElapsed: number;
+            };
+            trades: Array<WireObject & {
+                date: string;
+                action: string;
+                type: string;
+                strike: number | null;
+                expiration: string | null;
+                contracts: number;
+                fillPrice: number | null;
+                premium: number;
+                pl: number | null;
+                score: number | null;
+                signal: string | null;
+                dte: number | null;
+                volume: number;
+                stockPrice: number | null;
+                cumulative: number | null;
+            }>;
+            priceHistory: Array<{
+                date: string;
+                price: number;
+            }>;
+        }>;
+    };
+}

package/index.js

@@ -0,0 +1,214 @@
+/* global URL, URLSearchParams, FormData, Headers, AbortController, TextDecoder, Response, setTimeout, clearTimeout */
+/** @import { RequestOptions } from './types.js' */
+
+/** An HTTP or transport failure. Bodies, headers and credentials are never retained. */
+export class WheeliumError extends Error {
+  /** @param {string} message @param {{status?: number, code?: string, requestId?: string, requiredScopes?: string[]}} [details] */
+  constructor (message, details = {}) {
+    super(message)
+    this.name = 'WheeliumError'
+    this.status = details.status ?? 0
+    this.code = details.code ?? 'http_error'
+    this.requestId = details.requestId
+    this.requiredScopes = details.requiredScopes ?? []
+  }
+}
+
+function safeURL (value) {
+  let url
+  try { url = new URL(value) } catch { throw new WheeliumError('Invalid base or request URL', { code: 'unsafe_url' }) }
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) || url.username || url.password || url.hash) throw new WheeliumError('Unsafe URL: HTTPS without credentials or fragment required', { code: 'unsafe_url' })
+  return url
+}
+function redact (value, token, secrets = []) {
+  let text = String(value)
+  for (const secret of [token, ...secrets]) if (typeof secret === 'string' && secret) text = text.split(secret).join('[redacted]')
+  return text.replace(/Bearer\s+[^\s"']+/gi, 'Bearer [redacted]').replace(/whl_[A-Za-z0-9_-]+/g, '[redacted]').replace(/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[redacted]')
+}
+function query (path, params = {}) {
+  const qs = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) if (value !== undefined && value !== null) qs.set(key, String(value))
+  return path + (qs.size ? `?${qs}` : '')
+}
+const id = value => encodeURIComponent(value)
+const safeReads = new Set([
+  '/api/me', '/api/trades', '/api/options/contracts', '/api/options/quote', '/api/options/earnings',
+  '/api/options/fomc', '/api/options/expirations', '/api/options/fundamentals', '/api/options/price-probability',
+  '/api/wheel/notifications', '/api/wheel/roll-candidates', '/api/wheel/config', '/api/wheel/ivr',
+  '/api/settings/alpaca', '/api/settings/alpaca/account', '/api/orders/equity', '/api/share', '/api/invite/status', '/api/keys'
+])
+function isSafeRead (path, method, authenticated) {
+  if (!authenticated) return method === 'GET'
+  const pathname = path.split('?')[0]
+  if (method === 'POST') return ['/api/options/quotes', '/api/options/earnings/batch'].includes(pathname)
+  return method === 'GET' && (safeReads.has(pathname) || /^\/api\/trades\/[^/]+$/.test(pathname) || /^\/api\/wheel\/ivr\/[^/]+$/.test(pathname) || /^\/api\/wheel\/position\/[^/]+\/analysis$/.test(pathname))
+}
+function abortable (promise, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(new Error('aborted'))
+    const settle = (callback, value) => { signal.removeEventListener('abort', abort); callback(value) }
+    Promise.resolve(promise).then(value => settle(resolve, value), error => settle(reject, error))
+    if (signal.aborted) abort()
+    else signal.addEventListener('abort', abort, { once: true })
+  })
+}
+async function readBody (response, signal) {
+  if (!response.body?.getReader) return abortable(typeof response.text === 'function' ? response.text() : response.json().then(JSON.stringify), signal)
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let text = ''
+  try {
+    while (true) {
+      const { value, done } = await abortable(reader.read(), signal)
+      if (done) return text + decoder.decode()
+      text += decoder.decode(value, { stream: true })
+    }
+  } catch (error) {
+    // Cancel explicitly even when an injected fetch ignores AbortSignal.
+    void reader.cancel().catch(() => {})
+    throw error
+  } finally { reader.releaseLock() }
+}
+function bodySecrets (body) {
+  if (typeof body !== 'string') return []
+  try {
+    const data = JSON.parse(body)
+    return Object.entries(data).filter(([key]) => /^(apiKey|keyId|secretKey|password|token|authToken)$/i.test(key)).map(([, value]) => value).filter(value => typeof value === 'string')
+  } catch { return [] }
+}
+
+/**
+ * Exactly one credential source; token providers are evaluated for each attempt.
+ * Only domain methods explicitly marked safe may retry (never mutations/backtests).
+ * @param {ClientOptions} options
+ * @returns {WheeliumClient}
+ */
+export function createClient (options) {
+  if (!options || (options.apiKey !== undefined) === (options.getToken !== undefined) || (options.apiKey !== undefined && (typeof options.apiKey !== 'string' || !options.apiKey)) || (options.getToken !== undefined && typeof options.getToken !== 'function')) throw new TypeError('Exactly one credential source (apiKey or getToken) is required')
+  const base = safeURL(options.baseUrl ?? 'https://api.wheelium.app')
+  if (base.search) throw new WheeliumError('Invalid base URL query', { code: 'unsafe_url' })
+  const basePath = base.pathname.replace(/\/$/, '')
+  const timeoutMs = options.timeoutMs ?? 30000
+  const retries = options.maxRetries ?? 2
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isInteger(retries) || retries < 0 || retries > 3 || !Number.isFinite(options.retryDelayMs ?? 250) || (options.retryDelayMs ?? 250) < 0) throw new TypeError('Invalid timeout or retry limit')
+  /** @param {string} path @param {RequestOptions} [opts] */
+  async function request (path, opts = {}) {
+    const authenticated = opts.authenticated !== false
+    const method = (opts.method ?? 'GET').toUpperCase()
+    const retrySafe = opts.safeRetry === true && isSafeRead(path, method, authenticated)
+    let url
+    if (authenticated) {
+      // Relative paths must remain in the configured API base; no origin/path escape.
+      if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || /[\\\r\n]/.test(path) || /(?:^|\/)(?:\.|%2e){1,2}(?:\/|\?|$)/i.test(path)) throw new WheeliumError('Unsafe authenticated request URL', { code: 'unsafe_url' })
+      url = safeURL(`${base.origin}${basePath}${path}`)
+      if (url.origin !== base.origin || (basePath && !url.pathname.startsWith(`${basePath}/`))) throw new WheeliumError('Unsafe authenticated request URL', { code: 'unsafe_url' })
+    } else url = safeURL(path)
+    const controller = new AbortController()
+    let timedOut = false
+    const onAbort = () => controller.abort(opts.signal?.reason)
+    if (opts.signal?.aborted) onAbort()
+    else opts.signal?.addEventListener('abort', onAbort, { once: true })
+    const timer = setTimeout(() => { timedOut = true; controller.abort() }, timeoutMs)
+    const delay = ms => new Promise((resolve, reject) => {
+      if (controller.signal.aborted) return reject(new Error('aborted'))
+      const abort = () => { clearTimeout(handle); reject(new Error('aborted')) }
+      const handle = setTimeout(() => { controller.signal.removeEventListener('abort', abort); resolve() }, ms)
+      controller.signal.addEventListener('abort', abort, { once: true })
+    })
+    const retryDelay = (attempt, response) => {
+      const retryAfter = response?.headers?.get('Retry-After')
+      const retryMs = retryAfter == null ? null : (/^\d+(\.\d+)?$/.test(retryAfter) ? Number(retryAfter) * 1000 : Math.max(0, Date.parse(retryAfter) - Date.now()))
+      return delay(Number.isFinite(retryMs) && retryMs !== null ? retryMs + Math.random() * (options.retryDelayMs ?? 250) : (options.retryDelayMs ?? 250) * 2 ** attempt * (0.5 + Math.random()))
+    }
+    let token
+    try {
+      for (let attempt = 0; ; attempt++) {
+        if (controller.signal.aborted) throw new Error('aborted')
+        token = authenticated ? (options.getToken ? await abortable(Promise.resolve().then(options.getToken), controller.signal) : options.apiKey) : null
+        if (controller.signal.aborted) throw new Error('aborted')
+        const headers = new Headers(opts.headers)
+        headers.delete('Authorization')
+        headers.delete('Cookie')
+        const multipart = typeof FormData !== 'undefined' && opts.body instanceof FormData
+        if (multipart) headers.delete('Content-Type')
+        else if (opts.body !== undefined && !headers.has('Content-Type')) headers.set('Content-Type', 'application/json')
+        if (token) headers.set('Authorization', `Bearer ${token}`)
+        let response
+        let text
+        try {
+          response = await abortable((options.fetch ?? globalThis.fetch)(url.href, { method, body: opts.body, headers, signal: controller.signal, redirect: 'manual', credentials: 'omit', ...(authenticated ? { cache: 'no-store' } : {}) }), controller.signal)
+          if (response.type === 'opaqueredirect' || response.redirected || (response.status >= 300 && response.status < 400)) throw new WheeliumError('Redirect rejected; credentials were not forwarded', { code: 'unsafe_redirect', status: response.status })
+          text = response.status === 204 ? '' : await readBody(response, controller.signal)
+        } catch (err) {
+          if (controller.signal.aborted || err instanceof WheeliumError) throw err
+          // Body transport failures use the same attempt/time budget as fetch.
+          // Known HTTP denials must not become retriable network errors.
+          if (retrySafe && attempt < retries && (!response || response.ok || [408, 429, 500, 502, 503, 504].includes(response.status))) { await retryDelay(attempt, response); continue }
+          if (!response || response.ok) throw err
+          // An unreadable error body still retains status and correlation ID;
+          // never retain partial bodies or transport diagnostics/credentials.
+          text = ''
+        }
+        const secrets = bodySecrets(opts.body)
+        if (controller.signal.aborted) throw new Error('aborted')
+        if (!response.ok && retrySafe && attempt < retries && [408, 429, 500, 502, 503, 504].includes(response.status)) {
+          await retryDelay(attempt, response)
+          continue
+        }
+        let data
+        try { data = text.trim() ? JSON.parse(text) : undefined } catch {
+          if (response.ok && !opts.rawResponse) throw new WheeliumError('Response was not valid JSON', { code: 'invalid_response', status: response.status })
+        }
+        if (!response.ok) throw new WheeliumError(redact(data?.error ?? data?.message ?? `HTTP error! status: ${response.status}`, token, secrets), {
+          status: response.status,
+          code: redact(typeof data?.code === 'string' ? data.code : 'http_error', token, secrets),
+          requestId: typeof (data?.requestId ?? response.headers?.get('X-Request-Id')) === 'string' ? redact(data?.requestId ?? response.headers?.get('X-Request-Id'), token, secrets) : undefined,
+          requiredScopes: Array.isArray(data?.requiredScopes) ? data.requiredScopes.filter(v => typeof v === 'string').map(v => redact(v, token, secrets)) : []
+        })
+        // Buffered responses retain legacy apiCall behavior, with body covered by timeout.
+        return opts.rawResponse ? new Response(response.status === 204 ? null : text, { status: response.status, headers: response.headers }) : data
+      }
+    } catch (error) {
+      if (controller.signal.aborted) throw new WheeliumError(timedOut ? 'Request timed out' : 'Request aborted', { code: timedOut ? 'timeout' : 'aborted' })
+      if (error instanceof WheeliumError) throw error
+      throw new WheeliumError('Network request failed', { code: 'network_error' })
+    } finally {
+      clearTimeout(timer)
+      opts.signal?.removeEventListener('abort', onAbort)
+    }
+  }
+  const read = (path, params, opts) => request(query(path, params), { ...opts, safeRetry: true })
+  const write = (path, method, body, opts) => request(path, { ...opts, method, body: body === undefined ? undefined : (typeof FormData !== 'undefined' && body instanceof FormData ? body : JSON.stringify(body)) })
+  return {
+    request,
+    me: opts => read('/api/me', {}, opts),
+    trades: {
+      list: opts => read('/api/trades', {}, opts), get: (tradeId, opts) => read(`/api/trades/${id(tradeId)}`, {}, opts),
+      pairs: (params, opts) => read('/api/trades', { ...params, pairs: true }, opts),
+      create: (body, opts) => write('/api/trades', 'POST', body, opts), update: (tradeId, body, opts) => write(`/api/trades/${id(tradeId)}`, 'PUT', body, opts),
+      delete: (tradeId, opts) => write(`/api/trades/${id(tradeId)}`, 'DELETE', undefined, opts), cancelBrokerOrder: (orderId, opts) => write(`/api/trades/${id(orderId)}/cancel`, 'POST', undefined, opts)
+    },
+    portfolio: { get: (params, opts) => read('/api/trades', { ...params, portfolio: true }, opts), dailyPL: (params, opts) => read('/api/trades', { ...params, dailyPL: true }, opts) },
+    market: {
+      contracts: (params, opts) => read('/api/options/contracts', params, opts), quote: (symbol, opts) => read('/api/options/quote', { symbol }, opts),
+      quotes: (body, opts) => request('/api/options/quotes', { ...opts, method: 'POST', body: JSON.stringify(body), safeRetry: true }),
+      earnings: (symbol, opts) => read('/api/options/earnings', { symbol }, opts), earningsBatch: (body, opts) => request('/api/options/earnings/batch', { ...opts, method: 'POST', body: JSON.stringify(body), safeRetry: true }),
+      fomc: (params, opts) => read('/api/options/fomc', params, opts), expirations: (params, opts) => read('/api/options/expirations', params, opts), fundamentals: (symbol, opts) => read('/api/options/fundamentals', { symbol }, opts),
+      priceProbability: (params, opts) => read('/api/options/price-probability', params, opts), ivr: (symbol, params, opts) => read(`/api/wheel/ivr/${id(symbol)}`, params, opts), ivrSymbols: opts => read('/api/wheel/ivr', {}, opts)
+    },
+    advisor: { notifications: (params, opts) => read('/api/wheel/notifications', params, opts), analyze: (ticker, params, opts) => read(`/api/wheel/position/${id(ticker)}/analysis`, params, opts), rollCandidates: (params, opts) => read('/api/wheel/roll-candidates', params, opts), config: opts => read('/api/wheel/config', {}, opts) },
+    account: { get: opts => read('/api/settings/alpaca/account', {}, opts) },
+    orders: { list: opts => read('/api/orders/equity', {}, opts), placeEquity: (body, opts) => write('/api/orders/equity', 'POST', body, opts), cancel: (orderId, opts) => write(`/api/orders/equity/${id(orderId)}/cancel`, 'POST', undefined, opts), placeOptions: (body, opts) => write('/api/options/orders', 'POST', body, opts), roll: (body, opts) => write('/api/options/orders/roll', 'POST', body, opts) },
+    shares: { list: opts => read('/api/share', {}, opts), create: (body, opts) => write('/api/share', 'POST', body, opts), delete: (shareId, opts) => write(`/api/share/${id(shareId)}`, 'DELETE', undefined, opts), publicSnapshot: (url, opts) => request(url, { ...opts, authenticated: false, safeRetry: true }) },
+    settingsAlpaca: { get: opts => read('/api/settings/alpaca', {}, opts), save: (body, opts) => write('/api/settings/alpaca', 'POST', body, opts), test: (body, opts) => write('/api/settings/alpaca/test', 'POST', body, opts), delete: opts => write('/api/settings/alpaca', 'DELETE', undefined, opts) },
+    invitations: { status: opts => read('/api/invite/status', {}, opts), redeem: (body, opts) => write('/api/invite/redeem', 'POST', body, opts) },
+    keys: { list: opts => read('/api/keys', {}, opts), create: (body, opts) => write('/api/keys', 'POST', body, opts), revoke: (keyId, opts) => write(`/api/keys/${id(keyId)}`, 'DELETE', undefined, opts) },
+    backtest: { run: (params, opts) => request(query('/api/backtest', params), opts) }
+  }
+}
+
+/** @typedef {import('./types.js').ClientOptions} ClientOptions */
+/** @typedef {import('./types.js').WheeliumClient} WheeliumClient */
+/** @typedef {import('./types.js').Trade} Trade */
+/** @typedef {import('./types.js').Scope} Scope */
+/** @typedef {import('./types.js').CallOptions} CallOptions */

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@wheelium/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Wheelium browser and Node fetch client",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "index.js",
+    "dist/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidguttman/trade-tracker.git",
+    "directory": "packages/client"
+  }
+}