@mywebapi.com/sdk 0.1.0

package/dist/mutator.context.d.ts

@@ -0,0 +1,13 @@
+import type { TokenProvider } from './auth';
+import type { RetryPolicy } from './retry';
+import type { ApiMeta } from './errors';
+export interface RequestContext {
+    apiBaseUrl: string;
+    tokenProvider: TokenProvider;
+    fetchImpl: typeof fetch;
+    retryPolicy: RetryPolicy;
+    lastMeta?: ApiMeta | null;
+}
+export declare function withContext<T>(ctx: RequestContext, fn: () => Promise<T>): Promise<T>;
+export declare function currentContext(): RequestContext;
+export declare function currentContextOrNull(): RequestContext | null;

package/dist/mutator.d.ts

@@ -0,0 +1,4 @@
+export type UnwrapEnvelope<T> = T extends {
+    data?: infer D;
+} ? NonNullable<D> : T;
+export declare function customFetch<T>(url: string, options: RequestInit): Promise<T>;

package/dist/pagination.d.ts

@@ -0,0 +1,27 @@
+import type { PagingMeta } from './errors';
+export interface PagedResult<T> {
+    items: T[];
+    paging?: PagingMeta | null;
+}
+/**
+ * Walk a cursor-paged endpoint as an async iterable, yielding one page of
+ * items at a time.
+ *
+ * @example
+ * ```ts
+ * for await (const page of paginate((cursor) => client.paged(() =>
+ *   client.mt4.getUserRecordsRequest('my-tp', { cursor })
+ * ))) {
+ *   process(page);
+ * }
+ * ```
+ */
+export declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<PagedResult<T>>): AsyncIterable<T[]>;
+/**
+ * Collect all pages into a single array by exhausting the async iterable.
+ *
+ * ! Memory-bounded only by total result size — prefer the async iterable
+ *   (`paginate`) for large collections to process pages one at a time without
+ *   accumulating the full dataset in memory.
+ */
+export declare function collectAll<T>(fetchPage: (cursor: string | undefined) => Promise<PagedResult<T>>): Promise<T[]>;

package/dist/retry.d.ts

@@ -0,0 +1,20 @@
+export interface RetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    factor: number;
+    jitterPercent: number;
+}
+export declare const defaultPolicy: RetryPolicy;
+export interface WithRetryOptions {
+    policy?: RetryPolicy;
+    isIdempotent: boolean;
+    signal?: AbortSignal;
+}
+export declare function withRetry<T>(op: () => Promise<{
+    response: Response;
+    result: T;
+}>, opts: WithRetryOptions): Promise<{
+    response: Response;
+    result: T;
+}>;

package/dist/signalr.d.ts

@@ -0,0 +1,179 @@
+import type { HubConnection } from '@microsoft/signalr';
+import { type TokenProvider } from './auth';
+import type { MT4V2ClientOptions } from './client';
+export interface ConnectionStatusPayload {
+    connected: boolean;
+}
+export interface TickPayload {
+    symbol: string;
+    bid: number;
+    ask: number;
+    /** ISO-8601 string when serialised over the wire; SignalR's JSON protocol
+     * does not auto-revive `Date`. Parse on the consumer side if needed. */
+    lastTime: string | null;
+}
+export interface MarginCallPayload {
+    login: number;
+    group: string | null;
+    leverage: number;
+    updated: number;
+    balance: number;
+    equity: number;
+    volumeLots: number;
+    margin: number;
+    free: number;
+    level: number;
+    controllingType: number;
+    levelType: number;
+}
+export type TradeUpdateKind = 'Added' | 'Updated' | 'Deleted';
+export interface TradeUpdatePayload {
+    kind: TradeUpdateKind;
+    order: number;
+    login: number;
+    symbol: string;
+    cmd: number;
+    volumeLots: number;
+    openPrice: number;
+    openTime: string;
+    sl: number;
+    tp: number;
+    closePrice: number;
+    closeTime: string;
+    commission: number;
+    storage: number;
+    profit: number;
+    taxes: number;
+    comment: string;
+}
+export type UserUpdateKind = 'Added' | 'Updated' | 'Deleted';
+export interface UserUpdatePayload {
+    kind: UserUpdateKind;
+    login: number;
+    group: string;
+    name: string;
+    country: string;
+    leverage: number;
+    balance: number;
+    credit: number;
+    enabled: boolean;
+    readOnly: boolean;
+    regDate: string;
+    lastDate: string;
+    email: string;
+    phone: string;
+    comment: string;
+}
+export type SymbolUpdateKind = 'Added' | 'Updated' | 'Deleted';
+export interface SymbolUpdatePayload {
+    kind: SymbolUpdateKind;
+    symbol: string;
+    description: string;
+    currency: string;
+    digits: number;
+    tradeMode: number;
+    spread: number;
+    stopsLevel: number;
+    freezeLevel: number;
+    contractSize: number;
+    tickValue: number;
+    tickSize: number;
+    marginInitial: number;
+    marginMaintenance: number;
+}
+/** SignalR-specific overrides layered on top of the REST-client options shape. */
+export interface SignalRClientExtras {
+    /** Defaults to `${baseUrl}/hubs/mt4/v2`. Override only for non-standard deployments. */
+    hubUrl?: string;
+    /** Optional logger sink — same shape `@microsoft/signalr` accepts.
+     * Pass `LogLevel.Information` from the package, or any object with a `log(level, message)` method. */
+    logger?: unknown;
+    /** Reconnect intervals in milliseconds. Pass `false` to disable auto-reconnect.
+     * Default: `[0, 2000, 10_000, 30_000]` then give up. */
+    reconnect?: number[] | false;
+}
+export type MT4V2SignalRClientOptions = ({
+    tokenProvider: TokenProvider;
+    baseUrl: string;
+    tradePlatform: string;
+} & SignalRClientExtras) | (MT4V2ClientOptions & SignalRClientExtras);
+export declare class MT4V2SignalRError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * SignalR wrapper around `/hubs/mt4/v2`. Holds a single `HubConnection` and exposes
+ * typed stream helpers.
+ *
+ * Lifecycle:
+ * 1. `new MT4V2SignalRClient(opts)` — synchronous; resolves the token provider and
+ *    pre-computes the hub URL but does NOT open a socket.
+ * 2. Register callbacks via `onConnectionStatus()` / `onTick()` — MAY be called
+ *    before `start()`. Registering before `start()` is recommended so no early
+ *    server push (e.g. the post-handshake `OnConnectionStatus`) is missed.
+ * 3. `await client.start()` — opens the connection. Auth token is fetched via the
+ *    provider's `getToken()`; `tradePlatform` is appended to the URL. All callbacks
+ *    queued before `start()` are attached to the `HubConnection` before the socket
+ *    opens, guaranteeing they are in place before any server push arrives.
+ * 4. Use `streamTicks()` / `streamMarginCallUpdates()` / etc. to consume server
+ *    streams. Each helper returns an `AsyncIterable<T>` for easy `for await` use.
+ *    Stream helpers require an open connection — call them after `start()`.
+ * 5. `await client.stop()` — closes the connection.
+ */
+export declare class MT4V2SignalRClient {
+    private readonly hubUrl;
+    private readonly tokenProvider;
+    private readonly reconnect;
+    private readonly logger?;
+    private connection;
+    private pendingHandlers;
+    constructor(opts: MT4V2SignalRClientOptions);
+    /** Register a handler on the connection.
+     *  - If the connection already exists (i.e. `start()` has been called), the
+     *    handler is applied immediately.
+     *  - Otherwise it is pushed onto `pendingHandlers` and applied in `start()`
+     *    BEFORE the socket opens, guaranteeing no server push is missed. */
+    private register;
+    /** The resolved hub URL including the `tradePlatform` query parameter.
+     *  Intended for tests and diagnostic tooling. */
+    get hubUrlForTest(): string;
+    /** Resolve a token via this client's token provider.
+     *  Intended for tests to verify that the shared provider is wired correctly. */
+    tokenForTest(): Promise<string>;
+    /** Lazy-load `@microsoft/signalr`. Throws a clear error if the peer dep is missing. */
+    private loadSignalRModule;
+    /** Open the SignalR connection. Idempotent — calling twice while already
+     *  connected resolves without action. */
+    start(): Promise<void>;
+    /** Close the SignalR connection. Safe to call on a connection that was never
+     *  started or has already been closed. */
+    stop(): Promise<void>;
+    /** Returns the underlying `HubConnection` for advanced use (manual `.on`/`.invoke`
+     *  calls not covered by the typed helpers below). Throws if not started yet. */
+    getConnection(): HubConnection;
+    /** Subscribe to `OnTick` callbacks. Pair with `subscribeToTicks(symbol)`.
+     *  May be called before or after `start()` — registering before is recommended
+     *  so no early server push is missed. */
+    onTick(handler: (payload: TickPayload) => void): void;
+    /** Subscribe to `OnConnectionStatus` callbacks. The server pushes one such
+     *  event right after the handshake completes.
+     *  May be called before or after `start()` — registering before `start()` is
+     *  strongly recommended to avoid missing the initial post-handshake push. */
+    onConnectionStatus(handler: (payload: ConnectionStatusPayload) => void): void;
+    /** Subscribe the connection to a per-symbol tick stream. Server will push
+     *  `OnTick` callbacks for every tick of that symbol until unsubscribed. */
+    subscribeToTicks(symbol: string): Promise<void>;
+    unsubscribeFromTicks(symbol: string): Promise<void>;
+    /** Returns an `AsyncIterable<TickPayload>`. When `symbol` is omitted, every
+     *  symbol's ticks flow through. */
+    streamTicks(symbol?: string): AsyncIterable<TickPayload>;
+    streamMarginCallUpdates(): AsyncIterable<MarginCallPayload>;
+    streamTrades(): AsyncIterable<TradeUpdatePayload>;
+    streamUserUpdates(): AsyncIterable<UserUpdatePayload>;
+    streamSymbolUpdates(): AsyncIterable<SymbolUpdatePayload>;
+    /** Bridge `IStreamResult<T>` (push-based) → `AsyncIterable<T>` (pull-based).
+     *  Backpressure: the SignalR client buffers in memory; if the consumer is
+     *  slower than the producer the buffer grows. Caller can `break` out of the
+     *  `for await` loop to cancel the underlying server-side stream. */
+    private toAsyncIterable;
+}

package/dist/signalr.mt5.d.ts

@@ -0,0 +1,78 @@
+import type { HubConnection } from '@microsoft/signalr';
+import { type TokenProvider } from './auth';
+import type { MT4V2ClientOptions } from './client';
+import { type SignalRClientExtras } from './signalr';
+export interface MT5ConnectionStatusPayload {
+    connected: boolean;
+}
+export interface MT5MarginCallPayload {
+    login: number;
+    type: string;
+    direction: string;
+}
+export type MT5V2SignalRClientOptions = ({
+    tokenProvider: TokenProvider;
+    baseUrl: string;
+    tradePlatform: string;
+} & SignalRClientExtras) | (MT4V2ClientOptions & SignalRClientExtras);
+/**
+ * SignalR wrapper around `/hubs/mt5/v2`. Holds a single `HubConnection` and
+ * exposes typed helpers for the MT5 reduced real-time scope.
+ *
+ * Lifecycle:
+ * 1. `new MT5V2SignalRClient(opts)` — synchronous; resolves the token provider
+ *    and pre-computes the hub URL but does NOT open a socket.
+ * 2. Register callbacks via `onConnectionStatus()` — MAY be called before
+ *    `start()`. Registering before `start()` is recommended so the initial
+ *    post-handshake `OnConnectionStatus` push is never missed.
+ * 3. `await client.start()` — opens the WebSocket connection. All callbacks
+ *    queued before `start()` are attached to the `HubConnection` before the
+ *    socket opens, guaranteeing they are in place before any server push arrives.
+ * 4. Use `streamMarginCallUpdates()` to consume streams (requires open connection).
+ * 5. `await client.stop()` — closes the connection.
+ */
+export declare class MT5V2SignalRClient {
+    private readonly hubUrl;
+    private readonly tokenProvider;
+    private readonly reconnect;
+    private readonly logger?;
+    private connection;
+    private pendingHandlers;
+    constructor(opts: MT5V2SignalRClientOptions);
+    /** Register a handler on the connection.
+     *  - If the connection already exists (i.e. `start()` has been called), the
+     *    handler is applied immediately.
+     *  - Otherwise it is pushed onto `pendingHandlers` and applied in `start()`
+     *    BEFORE the socket opens, guaranteeing no server push is missed. */
+    private register;
+    /** The resolved hub URL including the `tradePlatform` query parameter.
+     *  Intended for tests and diagnostic tooling. */
+    get hubUrlForTest(): string;
+    /** Resolve a token via this client's token provider.
+     *  Intended for tests to verify that the shared provider is wired correctly. */
+    tokenForTest(): Promise<string>;
+    /** Lazy-load `@microsoft/signalr`. Throws a clear error if the peer dep is missing. */
+    private loadSignalRModule;
+    /** Open the SignalR connection. Idempotent — calling twice while already
+     *  connected resolves without action. */
+    start(): Promise<void>;
+    /** Close the SignalR connection. Safe to call on a connection that was never
+     *  started or has already been closed. */
+    stop(): Promise<void>;
+    /** Returns the underlying `HubConnection` for advanced use (manual `.on`/`.invoke`
+     *  calls not covered by the typed helpers below). Throws if not started yet. */
+    getConnection(): HubConnection;
+    /** Subscribe to `OnConnectionStatus` callbacks. The server pushes one such
+     *  event right after the handshake completes.
+     *  May be called before or after `start()` — registering before `start()` is
+     *  strongly recommended to avoid missing the initial post-handshake push. */
+    onConnectionStatus(handler: (payload: MT5ConnectionStatusPayload) => void): void;
+    /** Returns an `AsyncIterable<MT5MarginCallPayload>` backed by the server-side
+     *  `StreamMarginCallUpdates` stream. Use in a `for await` loop. */
+    streamMarginCallUpdates(): AsyncIterable<MT5MarginCallPayload>;
+    /** Bridge `IStreamResult<T>` (push-based) → `AsyncIterable<T>` (pull-based).
+     *  Backpressure: SignalR buffers in memory; if the consumer is slower than the
+     *  producer the buffer grows. Caller can `break` out of the `for await` loop to
+     *  cancel the underlying server-side stream. */
+    private toAsyncIterable;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mywebapi.com/sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "TypeScript client for the SaaS WebAPI v2 (MT4/MT5 management). Auto-generated types + thin fetch wrapper.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CPlugin/mywebapi.com-sdk-js.git"
+  },
+  "homepage": "https://github.com/CPlugin/mywebapi.com-sdk-js#readme",
+  "bugs": {
+    "url": "https://github.com/CPlugin/mywebapi.com-sdk-js/issues"
+  },
+  "scripts": {
+    "generate": "orval --config orval.config.ts",
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target browser --format esm && tsc -p tsconfig.build.json --emitDeclarationOnly --declaration",
+    "test": "bun test",
+    "test:e2e": "WEBAPI_E2E=1 bun test e2e",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@microsoft/signalr": "^9.0.0 || ^10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@microsoft/signalr": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@microsoft/signalr": "^10.0.0",
+    "@types/bun": "latest",
+    "orval": "8.19.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}