polaris-data 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+/** Accepts ISO 8601 strings, `Date` instances, or Unix epoch microseconds. */
+type TimeInput = string | Date | number;
+/** Shape of the global `fetch` function so consumers can inject a custom one. */
+type FetchLike = typeof globalThis.fetch;
+type AuthMode = "none" | "if-available" | "required";
+interface PaginatedResponse<T = Record<string, unknown>> {
+    data: T[];
+    next_cursor: string | null;
+    has_more: boolean;
+}
+interface CatalogResponse {
+    sources: CatalogSource[];
+    updatedAt: string;
+}
+interface CatalogSource {
+    id: string;
+    markets: CatalogMarket[];
+}
+interface CatalogMarket {
+    id: string;
+    start?: string;
+    end?: string;
+    source?: string;
+    categories?: string[];
+    access?: {
+        status: string;
+        public_cutoff_date?: string;
+    };
+}
+interface StandardEvent {
+    timestamp: number;
+    venue: string;
+    symbol: string;
+    type: string;
+    data: Record<string, unknown>;
+}
+interface TradeData {
+    price: number;
+    quantity: number;
+    side: string;
+    [key: string]: unknown;
+}
+interface TradeEvent extends StandardEvent {
+    type: "trade";
+    data: TradeData;
+}
+type OhlcvInterval = "100ms" | "1s" | "10s" | "1m" | "5m" | "15m" | "1h";
+interface OhlcvBar {
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    trades: number;
+}
+interface TradingViewCandle {
+    t: number;
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+}
+interface TradingViewVolume {
+    t: number;
+    v: number;
+    trades?: number;
+}
+interface TradingViewOhlcvResponse {
+    candles: TradingViewCandle[];
+    volumes: TradingViewVolume[];
+}
+interface SnapshotEntry {
+    date: string;
+    key: string;
+    filename: string;
+}
+interface SnapshotsResponse {
+    source: string;
+    market: string;
+    access?: {
+        status: string;
+        public_cutoff_date?: string;
+    };
+    total: number;
+    total_bytes: number;
+    limit: number;
+    has_more: boolean;
+    next_cursor: string | null;
+    snapshots: SnapshotEntry[];
+}
+interface DownloadUrlResponse {
+    url: string;
+    filename?: string;
+    expires_in_seconds?: number;
+}
+interface PolarisClientOptions {
+    /** Polaris API key. Falls back to `POLARIS_API_KEY` env var. */
+    apiKey?: string;
+    /** API base URL. Defaults to `https://api.polaris.supply`. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to `30 000` (30 s). */
+    timeout?: number;
+    /** Custom fetch implementation (useful for testing or proxies). */
+    fetch?: FetchLike;
+    /**
+     * Override the local dataset root directory.
+     * Defaults to the platform-specific Polaris app-data directory,
+     * overridable globally via `POLARIS_ROOT` env var.
+     */
+    datasetRoot?: string;
+}
+interface CatalogOptions {
+    source?: string;
+    market?: string;
+}
+/** Options for snapshot-based historical data methods. `from` and `to` are required. */
+interface HistoricalQueryOptions {
+    source: string;
+    market: string;
+    from: TimeInput;
+    to: TimeInput;
+}
+interface ListSnapshotsOptions {
+    source: string;
+    market: string;
+    from?: TimeInput;
+    to?: TimeInput;
+    limit?: number;
+}
+/** Options for the /raw endpoint. `from`/`to` are optional (defaults to 24 h lookback). */
+interface RawQueryOptions {
+    source: string;
+    market: string;
+    from?: TimeInput;
+    to?: TimeInput;
+    limit?: number;
+    format?: string;
+}
+interface OhlcvOptions extends HistoricalQueryOptions {
+    interval: OhlcvInterval;
+}
+interface ReplayOptions {
+    source: string;
+    market: string;
+    from: TimeInput;
+    to: TimeInput;
+    /** `true` (default) streams standardised events from local snapshots. */
+    standard?: boolean;
+}
+interface DownloadSnapshotOptions {
+    key: string;
+    filename?: string;
+    mode?: "url" | "json";
+}
+
+type Json = Record<string, unknown>;
+declare class PolarisClient {
+    private readonly _apiKey;
+    private readonly _baseUrl;
+    private readonly _timeout;
+    private readonly _fetch;
+    private readonly _root;
+    private _layout;
+    constructor(options?: PolarisClientOptions);
+    /** Check API availability. */
+    health(): Promise<Json>;
+    /**
+     * Browse supported sources and markets.
+     *
+     * If neither `source` nor `market` is provided, returns the full catalog.
+     * `market` requires `source`.
+     */
+    catalog(options?: CatalogOptions): Promise<CatalogResponse>;
+    /**
+     * List available snapshot files for a source and market over a time range.
+     * Auto-paginates to return **all** matching entries.
+     */
+    listSnapshots(options: ListSnapshotsOptions): Promise<SnapshotEntry[]>;
+    /**
+     * Return all standardised historical events for a time range.
+     *
+     * Reads from locally-cached daily `.jsonl.zst` snapshot files.
+     * Missing daily artifacts are discovered via `GET /snapshots` and
+     * downloaded automatically.
+     */
+    events(options: HistoricalQueryOptions): Promise<Json[]>;
+    /**
+     * Return all standardised trade events for a time range.
+     *
+     * Reads from locally-cached daily snapshot files, filtering to
+     * `type === "trade"`.
+     */
+    trades(options: HistoricalQueryOptions): Promise<Json[]>;
+    /**
+     * Aggregate OHLCV bars from standardised trade data.
+     *
+     * Reads from locally-cached daily snapshot files and aggregates in memory
+     * using the same interval-bucketing strategy as the Python SDK.
+     */
+    ohlcv(options: OhlcvOptions): Promise<OhlcvBar[]>;
+    /**
+     * Return a TradingView-shaped OHLCV response.
+     *
+     * Aggregates bars from local snapshot data and reshapes to
+     * `{ candles, volumes }`.
+     */
+    ohlcvTradingView(options: OhlcvOptions): Promise<TradingViewOhlcvResponse>;
+    /**
+     * Stream historical events as an async iterable.
+     *
+     * Defaults to standardised events from local snapshots (`standard: true`).
+     * Pass `standard: false` to stream raw payloads via the `/raw` endpoint.
+     *
+     * @example
+     * ```ts
+     * for await (const row of client.replay({
+     *   source: "binance",
+     *   market: "BTC-USDT",
+     *   from: "2024-01-01T00:00:00Z",
+     *   to: "2024-01-01T01:00:00Z",
+     * })) {
+     *   console.log(row);
+     * }
+     * ```
+     */
+    replay(options: ReplayOptions): AsyncGenerator<Json>;
+    /**
+     * Return raw venue-native payloads for a time range.
+     * Requires an API key. Uses the `/raw` endpoint with pagination.
+     */
+    raw(options: RawQueryOptions): Promise<Json[]>;
+    /**
+     * Download a single snapshot file by key.
+     *
+     * Returns the native `Response` so you can consume the body as needed
+     * (`.arrayBuffer()`, `.blob()`, or pipe to a writable stream).
+     */
+    downloadSnapshot(options: DownloadSnapshotOptions): Promise<Response>;
+    /**
+     * Get a pre-signed download URL for a snapshot file
+     * without fetching the file itself.
+     */
+    getSnapshotDownloadUrl(options: DownloadSnapshotOptions): Promise<DownloadUrlResponse>;
+    /** Release resources. Currently a no-op (reserved for future use). */
+    close(): void;
+    /** Async disposable support (Node ≥ 18 / TypeScript ≥ 5.2). */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Core routine: ensure daily `.jsonl.zst` artifacts exist, decompress them,
+     * and yield matching events one at a time.
+     */
+    private _readDailyEvents;
+    /**
+     * Ensure every requested date has a materialised daily artifact.
+     * Downloads missing snapshots and materialises them into `daily/`.
+     */
+    private _ensureDailyArtifacts;
+    /**
+     * Download a snapshot to `data/` and create a hardlink (or copy) into
+     * `daily/`.
+     */
+    private _downloadAndMaterialise;
+    private _streamRaw;
+    private _getJson;
+    private _fetchRaw;
+    private _buildHeaders;
+    private _buildUrl;
+    private _paginateAll;
+    private _getLayout;
+}
+
+declare class PolarisError extends Error {
+    readonly name: string;
+    /** HTTP status code, if the error originated from an API response. */
+    readonly statusCode: number | undefined;
+    /** Raw response body string. */
+    readonly body: string | undefined;
+    constructor(message: string, statusCode?: number, body?: string);
+    toString(): string;
+}
+declare class UnauthorizedError extends PolarisError {
+    readonly name: string;
+}
+declare class NotFoundError extends PolarisError {
+    readonly name: string;
+}
+declare class RateLimitedError extends PolarisError {
+    readonly name: string;
+    /** ISO 8601 timestamp (or epoch) indicating when the rate limit resets. */
+    readonly resetAt: string | undefined;
+    constructor(message: string, statusCode?: number, body?: string, resetAt?: string);
+}
+declare class StreamDecodeError extends PolarisError {
+    readonly name: string;
+}
+declare class DownloadNotAllowedError extends PolarisError {
+    readonly name: string;
+}
+
+/**
+ * In-memory OHLCV bar aggregator that buckets trades by timestamp into
+ * fixed-width intervals.
+ *
+ * Volume is accumulated as `quantity × 1e12` (rounded to integer) to match the
+ * precision strategy used by the Python SDK's `_LocalOhlcvAggregator`.
+ */
+declare class OhlcvAggregator {
+    private readonly _intervalUs;
+    private readonly _bars;
+    constructor(interval: OhlcvInterval);
+    /** Ingest a single trade event. */
+    add(timestamp: number, price: number, quantity: number): void;
+    /**
+     * Finalise the aggregation and return sorted bars.
+     *
+     * The `open` of each subsequent bar is overwritten with the `close` of the
+     * previous bar, matching the convention used by the Python SDK.
+     */
+    finish(): OhlcvBar[];
+}
+
+export { type AuthMode, type CatalogMarket, type CatalogOptions, type CatalogResponse, type CatalogSource, DownloadNotAllowedError, type DownloadSnapshotOptions, type DownloadUrlResponse, type FetchLike, type HistoricalQueryOptions, type ListSnapshotsOptions, NotFoundError, OhlcvAggregator, type OhlcvBar, type OhlcvInterval, type OhlcvOptions, type PaginatedResponse, PolarisClient, type PolarisClientOptions, PolarisError, RateLimitedError, type RawQueryOptions, type ReplayOptions, type SnapshotEntry, type SnapshotsResponse, type StandardEvent, StreamDecodeError, type TimeInput, type TradeData, type TradeEvent, type TradingViewCandle, type TradingViewOhlcvResponse, type TradingViewVolume, UnauthorizedError };