tickatlas 0.1.0

package/dist/index.mjs

@@ -0,0 +1,768 @@
+// src/errors.ts
+var TickAtlasError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "TickAtlasError";
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (options && "cause" in options) {
+      this.cause = options.cause;
+    }
+  }
+};
+var TickAtlasAPIError = class extends TickAtlasError {
+  constructor(opts) {
+    super(opts.message);
+    this.name = "TickAtlasAPIError";
+    this.statusCode = opts.statusCode;
+    this.code = opts.code;
+    this.details = opts.details;
+    this.requestId = opts.requestId ?? null;
+    this.raw = opts.raw ?? null;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends TickAtlasAPIError {
+  constructor(opts) {
+    super(opts);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PermissionDeniedError = class extends TickAtlasAPIError {
+  constructor(opts) {
+    super(opts);
+    this.name = "PermissionDeniedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotFoundError = class extends TickAtlasAPIError {
+  constructor(opts) {
+    super(opts);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ValidationError = class extends TickAtlasAPIError {
+  constructor(opts) {
+    super(opts);
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RateLimitError = class extends TickAtlasAPIError {
+  constructor(opts) {
+    super(opts);
+    this.name = "RateLimitError";
+    this.retryAfter = opts.retryAfter ?? null;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ServerError = class extends TickAtlasAPIError {
+  constructor(opts) {
+    super(opts);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TickAtlasNetworkError = class extends TickAtlasError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TickAtlasNetworkError";
+    this.isTimeout = options?.isTimeout ?? false;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TickAtlasConfigError = class extends TickAtlasError {
+  constructor(message) {
+    super(message);
+    this.name = "TickAtlasConfigError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function createApiError(statusCode, body, requestId, retryAfter) {
+  const code = body.code ?? `HTTP_${statusCode}`;
+  const message = body.message ?? `TickAtlas API error (HTTP ${statusCode}, code ${code})`;
+  const base = {
+    statusCode,
+    code,
+    message,
+    details: body.details,
+    requestId,
+    raw: body
+  };
+  if (code === "RATE_LIMIT_EXCEEDED" || code === "QUOTA_EXCEEDED" || code === "RATE_LIMITED") {
+    return new RateLimitError({ ...base, retryAfter });
+  }
+  switch (statusCode) {
+    case 401:
+      return new AuthenticationError(base);
+    case 403:
+      return new PermissionDeniedError(base);
+    case 404:
+      return new NotFoundError(base);
+    case 400:
+    case 422:
+      return new ValidationError(base);
+    case 429:
+      return new RateLimitError({ ...base, retryAfter });
+    default:
+      if (statusCode >= 500) return new ServerError(base);
+      if (statusCode >= 400) return new ValidationError(base);
+      return new TickAtlasAPIError(base);
+  }
+}
+
+// src/http.ts
+var SDK_VERSION = "0.1.0";
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var defaultJitter = () => Math.random();
+function buildQueryString(query) {
+  if (!query) return "";
+  const sp = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      sp.append(key, value.join(","));
+    } else {
+      sp.append(key, String(value));
+    }
+  }
+  const qs = sp.toString();
+  return qs ? `?${qs}` : "";
+}
+function parseIntHeader(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null) return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isNaN(n) ? null : n;
+}
+function retryAfterMs(headers, body) {
+  const ra = parseIntHeader(headers, "Retry-After");
+  if (ra !== null) return ra * 1e3;
+  const reset = parseIntHeader(headers, "X-RateLimit-Reset");
+  if (reset !== null) return reset * 1e3;
+  const bodyReset = body?.["reset_in_seconds"];
+  if (typeof bodyReset === "number") return bodyReset * 1e3;
+  return null;
+}
+function backoffMs(config, attempt) {
+  const exp = config.backoffBase * Math.pow(2, attempt);
+  const capped = Math.min(config.backoffCap, exp);
+  return capped * config.jitter();
+}
+async function request(config, opts) {
+  const base = opts.root ? new URL(config.baseURL).origin : config.baseURL.replace(/\/+$/, "");
+  const url = base + opts.path + buildQueryString(opts.query);
+  const maxAttempts = config.maxRetries + 1;
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const isLastAttempt = attempt === maxAttempts - 1;
+    const headers = {
+      "X-API-Key": config.apiKey,
+      Accept: "application/json"
+    };
+    if (config.sendUserAgent) {
+      headers["User-Agent"] = `tickatlas-js/${SDK_VERSION}`;
+    }
+    let bodyInit;
+    if (opts.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      bodyInit = JSON.stringify(opts.body);
+    }
+    const controller = new AbortController();
+    const timeoutMs = opts.timeout ?? config.timeout;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let timedOut = false;
+    const onTimeout = () => {
+      timedOut = true;
+    };
+    controller.signal.addEventListener("abort", onTimeout, { once: true });
+    let abortListener;
+    if (opts.signal) {
+      if (opts.signal.aborted) controller.abort();
+      else {
+        abortListener = () => controller.abort();
+        opts.signal.addEventListener("abort", abortListener, { once: true });
+      }
+    }
+    let response;
+    try {
+      response = await config.fetch(url, {
+        method: opts.method,
+        headers,
+        body: bodyInit,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (abortListener && opts.signal) {
+        opts.signal.removeEventListener("abort", abortListener);
+      }
+      if (opts.signal?.aborted && !timedOut) {
+        throw new TickAtlasNetworkError("Request aborted by caller", {
+          cause: err
+        });
+      }
+      const netErr = new TickAtlasNetworkError(
+        timedOut ? `Request timed out after ${timeoutMs}ms` : `Network request failed: ${err?.message ?? String(err)}`,
+        { cause: err, isTimeout: timedOut }
+      );
+      lastError = netErr;
+      if (isLastAttempt) throw netErr;
+      await config.sleep(backoffMs(config, attempt));
+      continue;
+    } finally {
+      clearTimeout(timer);
+      if (abortListener && opts.signal) {
+        opts.signal.removeEventListener("abort", abortListener);
+      }
+    }
+    const requestId = response.headers.get("X-Request-ID");
+    const text = await response.text();
+    let parsed = void 0;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = void 0;
+      }
+    }
+    if (response.ok) {
+      const env2 = parsed;
+      if (env2 && typeof env2 === "object" && "data" in env2) {
+        return env2.data;
+      }
+      return parsed;
+    }
+    const env = parsed;
+    const errorBody = env && typeof env === "object" && env.error && typeof env.error === "object" ? env.error : {
+      code: `HTTP_${response.status}`,
+      message: text.length > 0 ? text : `TickAtlas API returned HTTP ${response.status}`
+    };
+    const retryMs = response.status === 429 ? retryAfterMs(response.headers, errorBody) : null;
+    const apiError = createApiError(
+      response.status,
+      errorBody,
+      requestId,
+      retryMs !== null ? Math.round(retryMs / 1e3) : null
+    );
+    const retryable = RETRYABLE_STATUSES.has(response.status);
+    if (!retryable || isLastAttempt) {
+      throw apiError;
+    }
+    lastError = apiError;
+    const delay = response.status === 429 && retryMs !== null ? retryMs : backoffMs(config, attempt);
+    await config.sleep(delay);
+  }
+  throw lastError ?? new TickAtlasNetworkError("Request failed after all retries");
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://tickatlas.com/v1";
+function readEnv(name) {
+  if (typeof process !== "undefined" && process?.env) {
+    return process.env[name];
+  }
+  return void 0;
+}
+function isNodeLike() {
+  return typeof process !== "undefined" && !!process?.versions?.node;
+}
+function csv(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value.join(",") : value;
+}
+var TickAtlas = class {
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? readEnv("TICKATLAS_API_KEY");
+    if (!apiKey) {
+      throw new TickAtlasConfigError(
+        "No TickAtlas API key provided. Pass { apiKey } to the constructor or set the TICKATLAS_API_KEY environment variable."
+      );
+    }
+    const baseURL = options.baseURL ?? readEnv("TICKATLAS_BASE_URL") ?? DEFAULT_BASE_URL;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new TickAtlasConfigError(
+        "Global `fetch` is not available in this runtime. Use Node 18+ or a modern browser, or pass a `fetch` implementation in the options."
+      );
+    }
+    this.config = {
+      apiKey,
+      baseURL,
+      timeout: options.timeout ?? 3e4,
+      maxRetries: options.maxRetries ?? 3,
+      backoffBase: options.backoffBase ?? 500,
+      backoffCap: options.backoffCap ?? 3e4,
+      fetch: fetchImpl,
+      sleep: options.sleep ?? defaultSleep,
+      jitter: options.jitter ?? defaultJitter,
+      sendUserAgent: isNodeLike()
+    };
+  }
+  // =========================================================================
+  // Symbols
+  // =========================================================================
+  /** 7.1 `GET /symbols` — list symbols (paginated). */
+  getSymbols(opts = {}) {
+    const query = {
+      category: opts.category,
+      search: opts.search,
+      offset: opts.offset,
+      limit: opts.limit
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/symbols",
+      query
+    });
+  }
+  /** 7.2 `GET /symbols/{symbol}` — symbol contract spec. */
+  getSymbol(symbol) {
+    return request(this.config, {
+      method: "GET",
+      path: `/symbols/${encodeURIComponent(symbol)}`
+    });
+  }
+  // =========================================================================
+  // Quotes
+  // =========================================================================
+  /** 7.3 `GET /quote` — single real-time quote. */
+  getQuote(symbol, opts = {}) {
+    const query = {
+      symbol,
+      include_sources: opts.includeSources,
+      source: opts.source
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/quote",
+      query
+    });
+  }
+  /**
+   * 7.4 `POST /quotes` — batch quotes (1..100 symbols).
+   * `fields` ⊆ ["bid","ask","spread","spread_pips","timestamp"] (default all).
+   */
+  getQuotes(symbols, fields) {
+    const body = { symbols };
+    if (fields) body.fields = fields;
+    return request(this.config, {
+      method: "POST",
+      path: "/quotes",
+      body
+    });
+  }
+  // =========================================================================
+  // OHLC / Ticks
+  // =========================================================================
+  /** 7.5 `GET /ohlc` — OHLC candles. */
+  getOhlc(symbol, opts = {}) {
+    const query = {
+      symbol,
+      timeframe: opts.timeframe,
+      from: opts.from,
+      to: opts.to,
+      limit: opts.limit
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/ohlc",
+      query
+    });
+  }
+  /**
+   * 7.6 `GET /ticks` — tick data (plan: pro/enterprise).
+   * `from`/`to` are required ISO 8601; range must be ≤ 1 hour.
+   */
+  getTicks(symbol, from, to) {
+    return request(this.config, {
+      method: "GET",
+      path: "/ticks",
+      query: { symbol, from, to }
+    });
+  }
+  // =========================================================================
+  // Indicators
+  // =========================================================================
+  /** 7.7 `GET /indicator` — single indicator value. */
+  getIndicator(symbol, indicator, opts = {}) {
+    const query = {
+      symbol,
+      indicator,
+      timeframe: opts.timeframe,
+      source: opts.source
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/indicator",
+      query
+    });
+  }
+  /** 7.8 `GET /indicators` — all indicators for a symbol. */
+  getIndicators(symbol, opts = {}) {
+    const query = {
+      symbol,
+      timeframe: opts.timeframe,
+      category: opts.category
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/indicators",
+      query
+    });
+  }
+  /** 7.9 `GET /indicators/list` — indicator catalogue. */
+  listIndicators() {
+    return request(this.config, {
+      method: "GET",
+      path: "/indicators/list"
+    });
+  }
+  /**
+   * 7.10 `GET /indicator/history` — indicator series (plan: starter+).
+   */
+  getIndicatorHistory(symbol, indicator, opts = {}) {
+    const query = {
+      symbol,
+      indicator,
+      timeframe: opts.timeframe,
+      from: opts.from,
+      to: opts.to,
+      limit: opts.limit
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/indicator/history",
+      query
+    });
+  }
+  /**
+   * 7.11 `GET /multi` — batch indicators across symbols. Supplying `from`
+   * switches the server into historical mode (plan: starter+).
+   */
+  getMulti(symbols, indicators, opts = {}) {
+    const query = {
+      symbols: symbols.join(","),
+      indicators: indicators.join(","),
+      timeframe: opts.timeframe,
+      from: opts.from,
+      to: opts.to
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/multi",
+      query
+    });
+  }
+  // =========================================================================
+  // Screener
+  // =========================================================================
+  /**
+   * 7.12 `GET /screener` — scan symbols by indicator.
+   * Note: `minVal`/`maxVal` serialise to `min_val`/`max_val` (the docs' `min`/
+   * `max` are silently ignored by the API — see SPEC §12 F2).
+   */
+  screen(indicator, opts = {}) {
+    const query = {
+      indicator,
+      timeframe: opts.timeframe,
+      min_val: opts.minVal,
+      max_val: opts.maxVal,
+      sort: opts.sort,
+      offset: opts.offset,
+      limit: opts.limit
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/screener",
+      query
+    });
+  }
+  // =========================================================================
+  // Summary
+  // =========================================================================
+  /** 7.13 `GET /summary` — market-bias summary. */
+  getSummary(symbol, timeframe) {
+    return request(this.config, {
+      method: "GET",
+      path: "/summary",
+      query: { symbol, timeframe }
+    });
+  }
+  // =========================================================================
+  // Spread
+  // =========================================================================
+  /** 7.14 `GET /spread` — spread statistics. */
+  getSpread(symbol, period) {
+    return request(this.config, {
+      method: "GET",
+      path: "/spread",
+      query: { symbol, period }
+    });
+  }
+  /** 7.15 `GET /spread/compare` — compare spread across symbols (≤20). */
+  compareSpread(symbols, period) {
+    return request(this.config, {
+      method: "GET",
+      path: "/spread/compare",
+      query: { symbols: symbols.join(","), period }
+    });
+  }
+  // =========================================================================
+  // Sessions / Heatmap / Calendar
+  // =========================================================================
+  /** 7.16 `GET /sessions` — market session clock. */
+  getSessions() {
+    return request(this.config, { method: "GET", path: "/sessions" });
+  }
+  /** 7.17 `GET /heatmap` — currency strength / correlation. */
+  getHeatmap(opts = {}) {
+    const query = {
+      type: opts.type,
+      timeframe: opts.timeframe,
+      correlations: opts.correlations
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/heatmap",
+      query
+    });
+  }
+  /** 7.18 `GET /calendar` — economic calendar. */
+  getCalendar(opts = {}) {
+    const query = {
+      from: opts.from,
+      to: opts.to,
+      currencies: csv(opts.currencies),
+      country: csv(opts.country),
+      impact: opts.impact,
+      q: opts.q,
+      next_hours: opts.nextHours,
+      offset: opts.offset,
+      limit: opts.limit
+    };
+    return request(this.config, {
+      method: "GET",
+      path: "/calendar",
+      query
+    });
+  }
+  // =========================================================================
+  // Monitor (account / layout)
+  // =========================================================================
+  /** 7.19 `GET /monitor/account` — account identity & quota. */
+  getAccount() {
+    return request(this.config, {
+      method: "GET",
+      path: "/monitor/account"
+    });
+  }
+  /** 7.20 `GET /monitor/layout` — saved dashboard layout. */
+  getLayout() {
+    return request(this.config, {
+      method: "GET",
+      path: "/monitor/layout"
+    });
+  }
+  /**
+   * 7.21 `PUT /monitor/layout` — save dashboard layout (≤60 widgets).
+   *
+   * ADVANCED / WRITE: this is the only mutating endpoint in the SDK. It
+   * overwrites the user's saved dashboard layout for this API key. Use with care.
+   */
+  saveLayout(layout) {
+    return request(this.config, {
+      method: "PUT",
+      path: "/monitor/layout",
+      body: { layout }
+    });
+  }
+  // =========================================================================
+  // Infra probe
+  // =========================================================================
+  /** `GET /health` — service health probe (no API key required server-side). */
+  health() {
+    return request(this.config, {
+      method: "GET",
+      path: "/health",
+      root: true
+    });
+  }
+};
+/** SDK version (e.g. for diagnostics). */
+TickAtlas.version = SDK_VERSION;
+
+// src/constants.ts
+var Timeframes = {
+  M1: "M1",
+  M5: "M5",
+  M15: "M15",
+  M30: "M30",
+  H1: "H1",
+  H4: "H4",
+  D1: "D1"
+};
+var HeatmapTimeframes = {
+  H1: "H1",
+  H4: "H4",
+  D1: "D1",
+  W1: "W1"
+};
+var SymbolCategories = {
+  forex: "forex",
+  metals: "metals",
+  commodities: "commodities",
+  indices: "indices",
+  crypto: "crypto",
+  stocks: "stocks"
+};
+var SpreadPeriods = {
+  "1h": "1h",
+  "24h": "24h",
+  "7d": "7d",
+  "30d": "30d"
+};
+var CalendarImpacts = {
+  high: "high",
+  medium: "medium",
+  low: "low"
+};
+var Bias = {
+  bullish: "bullish",
+  bearish: "bearish",
+  neutral: "neutral"
+};
+var BiasStrengths = {
+  normal: "normal",
+  strong: "strong"
+};
+var HeatmapTypes = {
+  strength: "strength",
+  correlation: "correlation"
+};
+var IndicatorCategories = {
+  trend: "trend",
+  oscillator: "oscillator",
+  volatility: "volatility",
+  volume: "volume"
+};
+var Plans = {
+  free: "free",
+  trial: "trial",
+  starter: "starter",
+  pro: "pro",
+  enterprise: "enterprise",
+  payg: "payg"
+};
+var SortDirections = {
+  asc: "asc",
+  desc: "desc"
+};
+var Indicators = {
+  // --- Trend (23) ---
+  SMA_10: "SMA_10",
+  SMA_20: "SMA_20",
+  SMA_50: "SMA_50",
+  SMA_100: "SMA_100",
+  SMA_200: "SMA_200",
+  EMA_10: "EMA_10",
+  EMA_20: "EMA_20",
+  EMA_50: "EMA_50",
+  MACD_main: "MACD_main",
+  MACD_signal: "MACD_signal",
+  MACD_hist: "MACD_hist",
+  ADX: "ADX",
+  ADX_plusDI: "ADX_plusDI",
+  ADX_minusDI: "ADX_minusDI",
+  Ichimoku_tenkan: "Ichimoku_tenkan",
+  Ichimoku_kijun: "Ichimoku_kijun",
+  Ichimoku_senkou_a: "Ichimoku_senkou_a",
+  Alligator_jaw: "Alligator_jaw",
+  Alligator_teeth: "Alligator_teeth",
+  Alligator_lips: "Alligator_lips",
+  SAR: "SAR",
+  TEMA_20: "TEMA_20",
+  DEMA_20: "DEMA_20",
+  // --- Oscillator (8) ---
+  RSI_14: "RSI_14",
+  Stochastic_K: "Stochastic_K",
+  Stochastic_D: "Stochastic_D",
+  CCI_14: "CCI_14",
+  CCI_20: "CCI_20",
+  WilliamsR_14: "WilliamsR_14",
+  Momentum_14: "Momentum_14",
+  DeMarker_14: "DeMarker_14",
+  // --- Volatility (7) ---
+  BB_upper: "BB_upper",
+  BB_middle: "BB_middle",
+  BB_lower: "BB_lower",
+  BB_width: "BB_width",
+  ATR_14: "ATR_14",
+  ATR_7: "ATR_7",
+  StdDev_20: "StdDev_20",
+  // --- Volume (4) ---
+  OBV: "OBV",
+  MFI_14: "MFI_14",
+  AD: "AD",
+  Volumes: "Volumes"
+};
+var IndicatorsByCategory = {
+  trend: [
+    "SMA_10",
+    "SMA_20",
+    "SMA_50",
+    "SMA_100",
+    "SMA_200",
+    "EMA_10",
+    "EMA_20",
+    "EMA_50",
+    "MACD_main",
+    "MACD_signal",
+    "MACD_hist",
+    "ADX",
+    "ADX_plusDI",
+    "ADX_minusDI",
+    "Ichimoku_tenkan",
+    "Ichimoku_kijun",
+    "Ichimoku_senkou_a",
+    "Alligator_jaw",
+    "Alligator_teeth",
+    "Alligator_lips",
+    "SAR",
+    "TEMA_20",
+    "DEMA_20"
+  ],
+  oscillator: [
+    "RSI_14",
+    "Stochastic_K",
+    "Stochastic_D",
+    "CCI_14",
+    "CCI_20",
+    "WilliamsR_14",
+    "Momentum_14",
+    "DeMarker_14"
+  ],
+  volatility: [
+    "BB_upper",
+    "BB_middle",
+    "BB_lower",
+    "BB_width",
+    "ATR_14",
+    "ATR_7",
+    "StdDev_20"
+  ],
+  volume: ["OBV", "MFI_14", "AD", "Volumes"]
+};
+var ALL_INDICATORS = [
+  ...IndicatorsByCategory.trend,
+  ...IndicatorsByCategory.oscillator,
+  ...IndicatorsByCategory.volatility,
+  ...IndicatorsByCategory.volume
+];
+
+export { ALL_INDICATORS, AuthenticationError, Bias, BiasStrengths, CalendarImpacts, HeatmapTimeframes, HeatmapTypes, IndicatorCategories, Indicators, IndicatorsByCategory, NotFoundError, PermissionDeniedError, Plans, RateLimitError, SDK_VERSION, ServerError, SortDirections, SpreadPeriods, SymbolCategories, TickAtlas, TickAtlasAPIError, TickAtlasConfigError, TickAtlasError, TickAtlasNetworkError, Timeframes, ValidationError };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map