@tickerall/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Santos
+
+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

@@ -0,0 +1,275 @@
+# @tickerall/sdk
+
+Official TypeScript client for the [TickerAll](https://tickerall.com) REST + WebSocket API.
+
+Place trades, stream live market data, and manage broker sessions programmatically — without an MT4/MT5 terminal in the path.
+
+## Install
+
+```bash
+npm install @tickerall/sdk
+```
+
+Requires Node.js 18 or later (native `fetch`). Bun and Deno are also supported.
+
+## Quickstart
+
+```ts
+import { Tickerall } from '@tickerall/sdk'
+
+const ticker = new Tickerall({ apiKey: process.env.TICKERALL_API_KEY! })
+
+const { accountId } = await ticker.sessions.start({
+  broker: 'mt4',
+  server: 'Exness-Trial8',
+  account: 69542056,
+  password: process.env.MT4_PASSWORD!,
+})
+
+const order = await ticker.orders.place(accountId, {
+  type: 'market',
+  symbol: 'EURUSDm',
+  side: 'BUY',
+  volume: 0.1,
+  stopLoss: 1.0800,
+  takeProfit: 1.1000,
+})
+
+await ticker.sessions.end(accountId)
+```
+
+## Configuration
+
+```ts
+new Tickerall({
+  apiKey: 'cf_live_...',                       // required
+  baseUrl: 'https://api.tickerall.com',        // optional; override for staging
+  streamUrl: 'wss://api.tickerall.com/v1/stream',
+  timeout: 30_000,                             // ms; per-request default
+  fetch: globalThis.fetch,                     // injection point for tests
+  userAgent: 'my-algo/1.0',                    // tacked onto outgoing UA
+})
+```
+
+Multiple `Tickerall` instances are independent — useful for multi-tenant code.
+
+## Sessions
+
+```ts
+const session = await ticker.sessions.start({
+  broker: 'mt4',
+  server: 'Exness-Trial8',
+  account: 69542056,
+  password: '...',
+})
+// { accountId, isDemo, status: 'connected', expiresAt }
+
+await ticker.sessions.end(session.accountId)
+```
+
+Credentials are sent on each `sessions.start`. TickerAll never persists broker passwords; a session lives only as long as the underlying broker connection.
+
+## Accounts
+
+```ts
+const accounts = await ticker.accounts.list()
+const account  = await ticker.accounts.get(accountId)
+const symbols  = await ticker.accounts.symbols(accountId)
+```
+
+If `account.status === 'offline'`, call `sessions.start` again with credentials to reconnect.
+
+## Candles (historical OHLC)
+
+```ts
+const bars = await ticker.candles.get({ symbol: 'BTCUSDm', hours: 8760, timeframe: 'D1' })
+// [{ timestamp, open, high, low, close, bid }, ...]
+// timestamp is the bar OPEN time (Unix seconds, UTC); bid mirrors close.
+```
+
+Public endpoint — available on every plan (the API key is sent but isn't required). Timeframes: `M1 M5 M15 M30 H1 H4 D1 W1 MN1` (defaults to `M5`). Coarser timeframes reach further back; one request returns as much history as fits in a few seconds, so pass a large `hours` and take what comes back.
+
+## Orders + positions
+
+```ts
+const order = await ticker.orders.place(accountId, {
+  type: 'market',
+  symbol: 'EURUSDm',
+  side: 'BUY',
+  volume: 0.1,
+})
+// { ticket, symbol, side, type, volume, status, timestamp, ... }
+
+const limit = await ticker.orders.place(accountId, {
+  type: 'limit',
+  symbol: 'EURUSDm',
+  side: 'BUY',
+  volume: 0.1,
+  price: 1.0800,
+})
+
+await ticker.positions.modify(accountId, order.ticket, { stopLoss: 1.0850 })
+await ticker.positions.close(accountId, order.ticket)
+await ticker.positions.close(accountId, order.ticket, { volume: 0.05 }) // partial close
+```
+
+## Idempotency
+
+State-changing endpoints (`sessions.start`, `orders.place`, `positions.close`, `positions.modify`) auto-generate an `Idempotency-Key` (UUID v4) per call. Pass your own to deduplicate retries on your side:
+
+```ts
+await ticker.orders.place(
+  accountId,
+  { type: 'market', symbol: 'EURUSDm', side: 'BUY', volume: 0.1 },
+  { idempotencyKey: 'my-strategy-tick-12345' },
+)
+```
+
+## Resilience
+
+TickerAll keeps a fast, always-on connection to your broker, and the SDK is built so a momentary backend blip — a deploy, a restart, a network hiccup — **doesn't break an idle app**. The stream reconnects silently and re-sends your subscriptions; nothing is thrown unless you actively try to do something during the window.
+
+**Trades fail fast by default.** If you place an order while TickerAll is momentarily unreachable, you get a `TickerallServiceUnavailableError` (`err.transient === true`) right away — so you can re-decide with fresh prices rather than fire a stale order late:
+
+```ts
+try {
+  await ticker.orders.place(accountId, params)
+} catch (err) {
+  if (err instanceof TickerallServiceUnavailableError) {
+    // momentarily unreachable — retry, or skip this tick
+  }
+}
+```
+
+**Queue-and-replay (opt-in).** For calls that aren't price-sensitive (a pending order, an SL/TP edit), pass `queueIfReconnecting` to have the SDK hold the call and replay it — with its stable idempotency key, so it can't double-execute — until connectivity returns or `queueMaxMs` (default 60s) elapses:
+
+```ts
+await ticker.positions.modify(
+  accountId, ticket, { stopLoss: 1.0850 },
+  { queueIfReconnecting: true, queueMaxMs: 30_000 },
+)
+```
+
+Queued calls replay in submission order. Avoid this for market orders — a delayed fill at a moved price is usually worse than a fast failure.
+
+### Keep a session alive (auto re-arm)
+
+For an account you want to stay connected with no manual reconnect, start it with `keepAlive` instead of `start`. The SDK caches the broker credentials **in your process's memory** (never persisted) and transparently re-supplies them — re-arming the session — if the account ever goes cold (e.g. TickerAll restarted and dropped its server-side credentials):
+
+```ts
+const { accountId } = await ticker.sessions.keepAlive({
+  broker: 'mt5', server: 'Exness-...', account: 123, password: process.env.MT5_PASSWORD!,
+})
+
+// A later call that hits a cold account auto-re-arms and retries — once:
+await ticker.orders.place(accountId, { type: 'market', symbol: 'ETHUSDm', side: 'BUY', volume: 0.1 })
+
+ticker.sessions.stopKeepAlive(accountId) // forget the cached credentials
+```
+
+- The live **stream** re-arms kept sessions automatically when it reconnects, so subscriptions resume against a hot account.
+- Observe re-arms with the `onRearm` hook: `new Tickerall({ apiKey, onRearm: id => log('re-armed', id) })`.
+- Proactively recover after a known outage: `await ticker.sessions.rearmPending()` re-arms every kept account that TickerAll reports cold (or inspect `await ticker.sessions.pendingRearm()` yourself).
+- Credentials live in RAM only and are dropped on `stopKeepAlive` or `sessions.end`. **TickerAll never persists broker passwords** — which is also why, after a TickerAll restart, a kept session is recovered by *your* SDK re-supplying them (automatically), not by us having stored them.
+
+## Live stream
+
+```ts
+const stream = await ticker.stream.connect()
+
+await stream.subscribeTicks(accountId, ['EURUSDm', 'XAUUSDm'])
+await stream.subscribePositions(accountId)
+await stream.subscribeAccount(accountId)
+
+stream.on('tick',     e => console.log(e.symbol, e.bid, e.ask))
+stream.on('position', e => console.log(e.event, e.position))
+stream.on('account',  e => console.log(e.snapshot.balance))
+stream.on('error',    e => console.error(e.message))
+stream.on('reconnect', e => console.log('reconnecting, attempt', e.attempt))
+stream.on('close',    e => console.log('closed:', e.code, e.reason))
+
+await stream.close()
+```
+
+Connection state is queryable any time — never pushed at you, so an idle app stays quiet:
+
+```ts
+stream.getState()             // 'connecting' | 'open' | 'reconnecting' | 'closed'
+stream.isConnected()          // true only when live
+await stream.waitUntilConnected(10_000)  // resolve when open, reject on timeout
+```
+
+The stream:
+
+- Reconnects on disconnect with exponential backoff (1s, 2s, 4s, 8s, 16s, max 30s, with jitter) — silently, so an idle app never breaks on a backend blip.
+- Re-sends all known subscriptions on reconnect.
+- Sends a heartbeat every 25 seconds; force-reconnects on missed pong.
+- A missing `error` listener never crashes your process; subscribe to `'reconnect'`/`'close'` only if you want to observe it.
+- Does not buffer missed ticks (mirrors the server contract — resubscribe and discard stale state if you reconnect).
+
+## Errors
+
+All API errors extend `TickerallApiError`. Check `err.status` and `err.code`:
+
+```ts
+import {
+  TickerallApiError,
+  TickerallAuthError,
+  TickerallForbiddenError,
+  TickerallValidationError,
+  TickerallNotFoundError,
+  TickerallBrokerError,
+  TickerallServiceUnavailableError,
+} from '@tickerall/sdk'
+
+try {
+  await ticker.orders.place(accountId, params)
+} catch (err) {
+  if (err instanceof TickerallServiceUnavailableError) {
+    // TickerAll was momentarily unreachable (network blip, deploy, restart).
+    // The request never reached a verdict — safe to retry. See "Resilience".
+  } else if (err instanceof TickerallBrokerError) {
+    // broker rejected the order, broker is offline, etc.
+  } else if (err instanceof TickerallForbiddenError && err.code === 'FREE_TIER_LIVE_REJECTED') {
+    // user is on the free tier — upgrade to use live accounts
+  } else if (err instanceof TickerallValidationError) {
+    console.error('bad input:', err.details)
+  } else if (err instanceof TickerallApiError) {
+    console.error(err.status, err.code, err.message, err.requestId)
+  }
+}
+```
+
+Every error carries a boolean `err.transient` — `true` only for `TickerallServiceUnavailableError` (a connectivity blip you can safely retry), `false` for everything else (auth, validation, broker rejection — these won't change on retry).
+
+| Error class                       | Status / code                       | Notes                                                       |
+| ---------------------------------- | ----------------------------------- | ----------------------------------------------------------- |
+| `TickerallAuthError`               | 401                                 | invalid or missing API key                                  |
+| `TickerallForbiddenError`          | 403                                 | includes `FREE_TIER_LIVE_REJECTED`                          |
+| `TickerallValidationError`         | 400 / 422                           | bad request body or params                                  |
+| `TickerallNotFoundError`           | 404                                 | unknown account, ticket, etc.                               |
+| `TickerallBrokerError`             | broker-coded (e.g. `BROKER_*`)      | broker rejection or broker connection issues                |
+| `TickerallServiceUnavailableError` | network / timeout / bare 502·503    | **transient** — TickerAll momentarily unreachable; retry    |
+| `TickerallApiError`                | any                                 | base class; check `.code` and `.transient` for specifics    |
+
+## Timeouts and cancellation
+
+```ts
+await ticker.accounts.list({ timeout: 5_000 })
+
+const controller = new AbortController()
+setTimeout(() => controller.abort(), 1_000)
+await ticker.accounts.list({ signal: controller.signal })
+```
+
+## TypeScript
+
+The SDK ships hand-written `.d.ts` files. All public types are exported from the root:
+
+```ts
+import type { PlaceOrderParams, Position, TickEvent } from '@tickerall/sdk'
+```
+
+## License
+
+MIT