@kkkermit/trading212.js 0.1.0 → 0.1.1

package/dist/testing.d.cts

@@ -0,0 +1,159 @@
+import { FetchLike, TradableInstrument, HistoryDividendItem, HistoryTransactionItem, Exchange, Order, Environment, HistoricalOrder, ReportResponse, PieRequest, EndpointId, Position, Trading212Options, Trading212 } from './index.cjs';
+
+/** A request seen by `scriptedFetch` or the fake server. The Authorization header is never recorded. */
+interface RecordedRequest {
+    readonly method: string;
+    readonly url: string;
+    readonly path: string;
+    readonly query: Readonly<Record<string, string>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** True when an Authorization header was sent. Its value is never kept. */
+    readonly authorized: boolean;
+    /** The body, parsed when it was JSON. */
+    readonly body: unknown;
+}
+interface ScriptedResponse {
+    /** Default 200. */
+    status?: number;
+    /** An object or array is sent as JSON; a string as it is; `undefined` as an empty body. */
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** A response, an error to throw as the network failure, or a function that decides from the request. */
+type ScriptStep = ScriptedResponse | Error | ((request: RecordedRequest) => ScriptedResponse | Error | Promise<ScriptedResponse | Error>);
+interface ScriptedFetch {
+    readonly fetch: FetchLike;
+    /** Every request made so far. */
+    readonly requests: readonly RecordedRequest[];
+    /** How many scripted steps have not been used. */
+    readonly pending: () => number;
+}
+/**
+ * A `fetch` that answers from a script, in order, and records what it was asked. Use it to test code at the HTTP
+ * level; for whole flows, `createFakeTrading212()` is usually easier.
+ *
+ * @example
+ * const { fetch, requests } = scriptedFetch([{ body: { id: 1, currency: "GBP" } }]);
+ * const t212 = new Trading212({ environment: "demo", apiKey: "k", apiSecret: "s", fetch, rateLimit: "off" });
+ */
+declare function scriptedFetch(steps: readonly ScriptStep[]): ScriptedFetch;
+/** A network failure shaped like Node's, with the `code` this library reads to tell "never sent" from "lost". */
+declare function networkError(code?: string): TypeError;
+
+declare const FAKE_API_KEY = "fake-trading212-key";
+declare const FAKE_API_SECRET = "fake-trading212-secret";
+interface FakeHolding {
+    ticker: string;
+    quantity: number;
+    /** Average price paid per share. Defaults to the current price. */
+    averagePrice?: number;
+    /** Shares held in pies, which cannot be sold directly. */
+    inPies?: number;
+}
+/** The account the fake starts with. Everything is optional. */
+interface FakeAccountState {
+    accountId?: number;
+    /** Default `GBP`. Prices are treated as already in this currency; the fake does no FX. */
+    currency?: string;
+    /** Free cash. Default 10,000. */
+    cash?: number;
+    /** Default: Apple, Microsoft and Tesla on US markets, and Vanguard's S&P 500 ETF in London. */
+    instruments?: TradableInstrument[];
+    /** Price per ticker. Unlisted tickers default to 100. */
+    prices?: Record<string, number>;
+    positions?: FakeHolding[];
+    dividends?: HistoryDividendItem[];
+    transactions?: HistoryTransactionItem[];
+    exchanges?: Exchange[];
+}
+/** A failure to inject: an HTTP response, or a network failure with Node's error code. */
+type FakeFailure = ScriptedResponse | {
+    network: string;
+};
+declare const DEFAULT_INSTRUMENTS: readonly TradableInstrument[];
+/** A week of weekday sessions from the start of `from`'s day, in UTC. */
+declare function weekOfSessions(from: Date, openUtc: string, closeUtc: string): {
+    date: string;
+    type: string;
+}[];
+/** A holding as the fake keeps it. */
+interface FakeHoldingState {
+    ticker: string;
+    quantity: number;
+    averagePrice: number;
+    inPies: number;
+    createdAt: string;
+}
+/** A pending order and what it has reserved. */
+interface FakePendingOrder {
+    order: Order;
+    reservedCash: number;
+    reservedShares: number;
+}
+/**
+ * An in-memory Trading 212 that the real client talks to through `fetch`, so your code runs exactly as it would
+ * against the API: validation, errors, pagination and all. Market orders fill at once at the current price; limit
+ * and stop orders wait until you call `fill()`.
+ */
+declare class FakeTrading212Server {
+    #private;
+    readonly environment: Environment;
+    /** Every request the client made, without credentials. */
+    readonly requests: RecordedRequest[];
+    /** When false, every order is refused with `market-closed`. */
+    marketOpen: boolean;
+    /** Trading 212 refuses CSV exports on demo; set this to let the fake offer them anyway. */
+    exportsOnDemo: boolean;
+    cash: number;
+    readonly currency: string;
+    readonly accountId: number;
+    readonly instruments: TradableInstrument[];
+    readonly prices: Map<string, number>;
+    readonly holdings: Map<string, FakeHoldingState>;
+    readonly pending: Map<number, FakePendingOrder>;
+    readonly orderHistory: HistoricalOrder[];
+    readonly dividends: HistoryDividendItem[];
+    readonly transactions: HistoryTransactionItem[];
+    readonly exchanges: Exchange[];
+    readonly reports: ReportResponse[];
+    readonly pies: Map<number, {
+        settings: PieRequest;
+        cash: number;
+    }>;
+    realisedProfitLoss: number;
+    constructor(state?: FakeAccountState, environment?: Environment);
+    /** Pass this as the client's `fetch`. */
+    readonly fetch: FetchLike;
+    /** Makes the next call to an endpoint fail. Queue several to fail several calls. */
+    failNext(endpoint: EndpointId, failure: FakeFailure): this;
+    setPrice(ticker: string, price: number): this;
+    priceOf(ticker: string): number;
+    /** Fills a pending limit or stop order, at its limit price, or `price` if given. */
+    fill(orderId: number, price?: number): Order;
+    position(ticker: string): Position | undefined;
+}
+
+interface CreateFakeOptions {
+    /** The account the fake starts with. */
+    state?: FakeAccountState;
+    /** Default `demo`. On `live`, trading is enabled for you unless `client.trading` says otherwise. */
+    environment?: Environment;
+    /** Any other client option, such as a logger. */
+    client?: Partial<Omit<Trading212Options, "environment" | "apiKey" | "apiSecret" | "fetch">>;
+}
+/**
+ * A real `Trading212` client wired to an in-memory Trading 212, for testing your own code with no network and no
+ * key. Rate limiting is off so tests run instantly.
+ *
+ * @example
+ * const { client, server } = createFakeTrading212({ state: { cash: 1000 } });
+ * await client.orders.buy({ ticker: "AAPL_US_EQ", quantity: 2 });
+ * expect(server.position("AAPL_US_EQ")?.quantity).toBe(2);
+ */
+declare function createFakeTrading212(options?: CreateFakeOptions): {
+    client: Trading212;
+    server: FakeTrading212Server;
+};
+
+export { DEFAULT_INSTRUMENTS, FAKE_API_KEY, FAKE_API_SECRET, FakeTrading212Server, createFakeTrading212, networkError, scriptedFetch, weekOfSessions };
+export type { CreateFakeOptions, FakeAccountState, FakeFailure, FakeHolding, FakeHoldingState, FakePendingOrder, RecordedRequest, ScriptStep, ScriptedFetch, ScriptedResponse };

package/dist/testing.d.ts

@@ -0,0 +1,159 @@
+import { FetchLike, TradableInstrument, HistoryDividendItem, HistoryTransactionItem, Exchange, Order, Environment, HistoricalOrder, ReportResponse, PieRequest, EndpointId, Position, Trading212Options, Trading212 } from './index.js';
+
+/** A request seen by `scriptedFetch` or the fake server. The Authorization header is never recorded. */
+interface RecordedRequest {
+    readonly method: string;
+    readonly url: string;
+    readonly path: string;
+    readonly query: Readonly<Record<string, string>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** True when an Authorization header was sent. Its value is never kept. */
+    readonly authorized: boolean;
+    /** The body, parsed when it was JSON. */
+    readonly body: unknown;
+}
+interface ScriptedResponse {
+    /** Default 200. */
+    status?: number;
+    /** An object or array is sent as JSON; a string as it is; `undefined` as an empty body. */
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** A response, an error to throw as the network failure, or a function that decides from the request. */
+type ScriptStep = ScriptedResponse | Error | ((request: RecordedRequest) => ScriptedResponse | Error | Promise<ScriptedResponse | Error>);
+interface ScriptedFetch {
+    readonly fetch: FetchLike;
+    /** Every request made so far. */
+    readonly requests: readonly RecordedRequest[];
+    /** How many scripted steps have not been used. */
+    readonly pending: () => number;
+}
+/**
+ * A `fetch` that answers from a script, in order, and records what it was asked. Use it to test code at the HTTP
+ * level; for whole flows, `createFakeTrading212()` is usually easier.
+ *
+ * @example
+ * const { fetch, requests } = scriptedFetch([{ body: { id: 1, currency: "GBP" } }]);
+ * const t212 = new Trading212({ environment: "demo", apiKey: "k", apiSecret: "s", fetch, rateLimit: "off" });
+ */
+declare function scriptedFetch(steps: readonly ScriptStep[]): ScriptedFetch;
+/** A network failure shaped like Node's, with the `code` this library reads to tell "never sent" from "lost". */
+declare function networkError(code?: string): TypeError;
+
+declare const FAKE_API_KEY = "fake-trading212-key";
+declare const FAKE_API_SECRET = "fake-trading212-secret";
+interface FakeHolding {
+    ticker: string;
+    quantity: number;
+    /** Average price paid per share. Defaults to the current price. */
+    averagePrice?: number;
+    /** Shares held in pies, which cannot be sold directly. */
+    inPies?: number;
+}
+/** The account the fake starts with. Everything is optional. */
+interface FakeAccountState {
+    accountId?: number;
+    /** Default `GBP`. Prices are treated as already in this currency; the fake does no FX. */
+    currency?: string;
+    /** Free cash. Default 10,000. */
+    cash?: number;
+    /** Default: Apple, Microsoft and Tesla on US markets, and Vanguard's S&P 500 ETF in London. */
+    instruments?: TradableInstrument[];
+    /** Price per ticker. Unlisted tickers default to 100. */
+    prices?: Record<string, number>;
+    positions?: FakeHolding[];
+    dividends?: HistoryDividendItem[];
+    transactions?: HistoryTransactionItem[];
+    exchanges?: Exchange[];
+}
+/** A failure to inject: an HTTP response, or a network failure with Node's error code. */
+type FakeFailure = ScriptedResponse | {
+    network: string;
+};
+declare const DEFAULT_INSTRUMENTS: readonly TradableInstrument[];
+/** A week of weekday sessions from the start of `from`'s day, in UTC. */
+declare function weekOfSessions(from: Date, openUtc: string, closeUtc: string): {
+    date: string;
+    type: string;
+}[];
+/** A holding as the fake keeps it. */
+interface FakeHoldingState {
+    ticker: string;
+    quantity: number;
+    averagePrice: number;
+    inPies: number;
+    createdAt: string;
+}
+/** A pending order and what it has reserved. */
+interface FakePendingOrder {
+    order: Order;
+    reservedCash: number;
+    reservedShares: number;
+}
+/**
+ * An in-memory Trading 212 that the real client talks to through `fetch`, so your code runs exactly as it would
+ * against the API: validation, errors, pagination and all. Market orders fill at once at the current price; limit
+ * and stop orders wait until you call `fill()`.
+ */
+declare class FakeTrading212Server {
+    #private;
+    readonly environment: Environment;
+    /** Every request the client made, without credentials. */
+    readonly requests: RecordedRequest[];
+    /** When false, every order is refused with `market-closed`. */
+    marketOpen: boolean;
+    /** Trading 212 refuses CSV exports on demo; set this to let the fake offer them anyway. */
+    exportsOnDemo: boolean;
+    cash: number;
+    readonly currency: string;
+    readonly accountId: number;
+    readonly instruments: TradableInstrument[];
+    readonly prices: Map<string, number>;
+    readonly holdings: Map<string, FakeHoldingState>;
+    readonly pending: Map<number, FakePendingOrder>;
+    readonly orderHistory: HistoricalOrder[];
+    readonly dividends: HistoryDividendItem[];
+    readonly transactions: HistoryTransactionItem[];
+    readonly exchanges: Exchange[];
+    readonly reports: ReportResponse[];
+    readonly pies: Map<number, {
+        settings: PieRequest;
+        cash: number;
+    }>;
+    realisedProfitLoss: number;
+    constructor(state?: FakeAccountState, environment?: Environment);
+    /** Pass this as the client's `fetch`. */
+    readonly fetch: FetchLike;
+    /** Makes the next call to an endpoint fail. Queue several to fail several calls. */
+    failNext(endpoint: EndpointId, failure: FakeFailure): this;
+    setPrice(ticker: string, price: number): this;
+    priceOf(ticker: string): number;
+    /** Fills a pending limit or stop order, at its limit price, or `price` if given. */
+    fill(orderId: number, price?: number): Order;
+    position(ticker: string): Position | undefined;
+}
+
+interface CreateFakeOptions {
+    /** The account the fake starts with. */
+    state?: FakeAccountState;
+    /** Default `demo`. On `live`, trading is enabled for you unless `client.trading` says otherwise. */
+    environment?: Environment;
+    /** Any other client option, such as a logger. */
+    client?: Partial<Omit<Trading212Options, "environment" | "apiKey" | "apiSecret" | "fetch">>;
+}
+/**
+ * A real `Trading212` client wired to an in-memory Trading 212, for testing your own code with no network and no
+ * key. Rate limiting is off so tests run instantly.
+ *
+ * @example
+ * const { client, server } = createFakeTrading212({ state: { cash: 1000 } });
+ * await client.orders.buy({ ticker: "AAPL_US_EQ", quantity: 2 });
+ * expect(server.position("AAPL_US_EQ")?.quantity).toBe(2);
+ */
+declare function createFakeTrading212(options?: CreateFakeOptions): {
+    client: Trading212;
+    server: FakeTrading212Server;
+};
+
+export { DEFAULT_INSTRUMENTS, FAKE_API_KEY, FAKE_API_SECRET, FakeTrading212Server, createFakeTrading212, networkError, scriptedFetch, weekOfSessions };
+export type { CreateFakeOptions, FakeAccountState, FakeFailure, FakeHolding, FakeHoldingState, FakePendingOrder, RecordedRequest, ScriptStep, ScriptedFetch, ScriptedResponse };