outcometick 1.4.1 → 1.5.1

package/README.md

@@ -5,7 +5,7 @@
   scripts/publish-sdk-repos.mjs and overwritten wholesale on each publish.
   An edit made here survives until the next publish and then disappears.
 
-  Generated from monorepo revision 0ad1fd0cb6d49a6ceca5b70175f0ebeeaa207b6d.
+  Generated from monorepo revision 3652fc71edb3360170ce324e623b19d0ff994844.
 -->
 
 # outcometick
@@ -79,6 +79,37 @@ npm install && npm test
 Requires `python3` on PATH: one of the two static analysers is written in
 Python, and the CLI drives it the same way the API does.
 
+## Downloading data
+
+The other half of the package: a client for the data subscription, on a
+separate import because it has nothing to do with writing a strategy.
+
+```ts
+import { DataClient, NO_VALUE } from "outcometick/data";
+
+const ot = new DataClient();                    // key from OT_KEY
+
+const meta = await ot.meta();                   // what can this key see?
+
+const { files } = await ot.files({
+  from: "2026-08-01", to: "2026-08-12",         // or date: "2026-08-12"
+  asset: ["BTCUSD", "ETHUSD"],                  // an array means "any of these"
+  dataset: "prices",
+  interval: ["5m", NO_VALUE],                   // "5m" alone EXCLUDES the
+});                                             // period-less settlement streams
+
+await ot.download(files[0], { saveTo: files[0].name });   // checksum verified
+```
+
+`meta()` reports the dimensions this key can actually reach. Note that
+`intervals` holds real durations only — the `none` sentinel is reported
+separately under `filterTokens`, so a caller that builds an enum from it or
+parses the values as durations never meets a token.
+
+Downloads are checksum-verified: `/v1/dl` redirects to storage with the sha256
+in a header, and the client follows that redirect itself so the checksum is not
+thrown away.
+
 ---
 
 Writing your strategy in Python instead? The SDK for it is

package/api/lib/backtest-contract.mjs

@@ -15,7 +15,7 @@ import { FIRST_COMPLETE_DAY } from './coverage-window.mjs';
 export const SCHEMA_VERSION = 1;
 
 /** SDK version reported by the docs page and stamped into every report. */
-export const SDK_VERSION = '1.4.1';
+export const SDK_VERSION = '1.5.1';
 
 // ---------------------------------------------------------------------------
 // Languages

package/client/data.d.ts

@@ -0,0 +1,157 @@
+// Types for the data-subscription client, `outcometick/data`.
+//
+// Hand-written against api/subscription-api.mjs, like the strategy SDK's
+// declarations, and guarded the same way — see client/data-types.test.mjs.
+
+/** A filter value: one alternative, or several meaning "any of these". */
+export type Filter = string | readonly string[];
+
+/** The sentinel naming files that have no value for a dimension. */
+export declare const NO_VALUE: 'none';
+
+export declare const DEFAULT_BASE_URL: string;
+
+/** An error carrying the status and whatever the API said alongside it. */
+export declare class OutcometickError extends Error {
+  readonly status: number;
+  /** The API's `error` string. */
+  readonly detail: string;
+  /**
+   * The parsed response. A 403 on a date outside coverage also carries `floor`
+   * and `ceiling` — the difference between "no" and "no, but here is the range
+   * you do have".
+   */
+  readonly body: unknown;
+  readonly url: string;
+}
+
+/** One archive file, as returned by `files()`. */
+export interface FileRow {
+  date: string;
+  name: string;
+  venue: string;
+  dataset: string;
+  /** null for datasets that are not per-asset. */
+  asset: string | null;
+  /** null for streams with no period — the settlement feeds. */
+  interval: string | null;
+  bytes: number;
+  sha256: string;
+  /** Direct download; needs the key, as a header or `?api_key=`. */
+  url: string;
+}
+
+export interface FilesResult {
+  from: string;
+  to: string;
+  /** Days actually in scope within [from, to], not the span. */
+  days: number;
+  count: number;
+  /** Total size of the matched files. */
+  bytes: number;
+  files: FileRow[];
+}
+
+export interface FilesQuery {
+  /** One day. Cannot be combined with from/to. */
+  date?: string;
+  /** Inclusive start. Defaults to the newest day in scope. */
+  from?: string;
+  /** Inclusive end. Defaults to `from`. */
+  to?: string;
+  venue?: Filter;
+  dataset?: Filter;
+  asset?: Filter;
+  /** `"none"` selects the streams that have no period at all. */
+  interval?: Filter;
+}
+
+export interface MetaResult {
+  firstDay?: string;
+  lastDay?: string;
+  /** Number of days in scope, not a span. */
+  days: number;
+  venues: string[];
+  assets: string[];
+  /** Real durations only — the sentinel lives in `filterTokens`. */
+  intervals: string[];
+  /** dataset name -> human description. */
+  datasets: Record<string, string>;
+  filterTokens: {
+    noValue: 'none';
+    /** Which dimensions some file leaves empty. */
+    appliesTo: string[];
+  };
+  scope?: unknown;
+  sampledFrom?: string;
+}
+
+export interface DaysResult {
+  days: string[];
+  /** Earliest downloadable day, or null when unbounded. */
+  floor: string | null;
+  /** Latest downloadable day, or null when unbounded. */
+  ceiling: string | null;
+  scope?: unknown;
+}
+
+export interface SignedUrl {
+  url: string;
+  name: string;
+  bytes: number;
+  sha256: string;
+  expiresInSec: number;
+}
+
+export interface DownloadResult {
+  bytes: Uint8Array;
+  /** The checksum that was verified, when one was available. */
+  sha256: string | null;
+  name: string;
+  date: string;
+}
+
+export interface DownloadOptions {
+  /** Verify the sha256. Default true. */
+  verify?: boolean;
+  /** Also write the bytes to this path. */
+  saveTo?: string;
+}
+
+export interface DataClientOptions {
+  /** Defaults to process.env.OT_KEY. */
+  key?: string | null;
+  /** Defaults to https://outcometick.com. */
+  baseUrl?: string;
+  /** Injectable for tests. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export declare class DataClient {
+  constructor(options?: DataClientOptions);
+  readonly key: string | null;
+  readonly baseUrl: string;
+
+  /** The date window and every dimension value in it. */
+  meta(): Promise<MetaResult>;
+
+  /** The days this key may download, with the window bounds. */
+  days(): Promise<DaysResult>;
+
+  /** Search across a date range. Filters accept a string or an array. */
+  files(query?: FilesQuery): Promise<FilesResult>;
+
+  /** A presigned URL, without fetching the bytes. Short-lived. */
+  signUrl(date: string, name: string, options?: { expiresIn?: number }): Promise<SignedUrl>;
+
+  /** Download one file, verifying its checksum. */
+  download(file: FileRow, options?: DownloadOptions): Promise<DownloadResult>;
+  download(date: string, name: string, options?: DownloadOptions): Promise<DownloadResult>;
+
+  /** Public — no key required. */
+  coverage(): Promise<unknown>;
+  plans(): Promise<unknown>;
+  health(): Promise<unknown>;
+}
+
+export default DataClient;

package/client/data.mjs

@@ -0,0 +1,263 @@
+// The data-subscription client: `outcometick/data`.
+//
+//   import { DataClient } from "outcometick/data";
+//   const ot = new DataClient();                       // key from OT_KEY
+//   const { files } = await ot.files({ asset: ["btc", "eth"], dataset: "prices" });
+//   await ot.download(files[0], "./btc.csv.gz");       // verifies the checksum
+//
+// Deliberately a SUBPATH, not part of the package root. The root exports the
+// strategy SDK — `Strategy` and `Order` — which is what a backtest imports, and
+// that code runs in a container with no network at all. Putting an HTTP client
+// on the same import would invite a strategy to reach for it, type-check
+// locally, and then fail inside the sandbox. Here it cannot be reached by
+// accident, and the submission analyser rejects the import outright.
+//
+// Everything this file knows about the API's shape came from reading
+// api/subscription-api.mjs, not from the docs page. The two had drifted: the
+// published curl example shows only `asset` and `dataset`, while /v1/files also
+// takes a date RANGE and a venue and an interval, and every filter accepts
+// comma-separated alternatives plus a `none` sentinel.
+
+import { createHash } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+
+export const DEFAULT_BASE_URL = 'https://outcometick.com';
+
+/** The sentinel that names files with no value for a dimension. */
+export const NO_VALUE = 'none';
+
+/**
+ * An API error, carrying whatever the server said alongside the status.
+ *
+ * The subscription API answers 403 on a date outside coverage with the actual
+ * `floor` and `ceiling`, which is the difference between "you cannot have this"
+ * and "you cannot have this, here is what you can have". Flattening that into a
+ * message string would throw the useful half away.
+ */
+export class OutcometickError extends Error {
+  constructor(status, body, url) {
+    const detail = body?.error ?? (typeof body === 'string' ? body.slice(0, 200) : 'request failed');
+    super(`${status} ${detail}`);
+    this.name = 'OutcometickError';
+    this.status = status;
+    this.detail = detail;
+    this.body = body;
+    this.url = url;
+  }
+}
+
+/**
+ * Render one filter value.
+ *
+ * Arrays join with commas because that is exactly what the API means by
+ * `asset=btc,eth` — alternatives, not a nested structure. Passing an array is
+ * the friendlier spelling of the same request, so both work.
+ */
+function filterValue(v) {
+  if (v == null) return null;
+  const parts = (Array.isArray(v) ? v : [v])
+    .map((x) => String(x).trim())
+    .filter(Boolean);
+  return parts.length ? parts.join(',') : null;
+}
+
+export class DataClient {
+  /**
+   * @param opts.key      API key. Defaults to process.env.OT_KEY.
+   * @param opts.baseUrl  API origin. Defaults to https://outcometick.com.
+   * @param opts.fetch    Injectable for tests.
+   */
+  constructor({ key = null, baseUrl = DEFAULT_BASE_URL, fetch: fetchImpl = null } = {}) {
+    // Read at construction so the failure is "you have not set a key", raised
+    // once and early, rather than a 401 from whichever call happened to be
+    // first.
+    this.key = key ?? process.env.OT_KEY ?? null;
+    this.baseUrl = String(baseUrl).replace(/\/+$/, '');
+    this._fetch = fetchImpl ?? globalThis.fetch;
+  }
+
+  /** The key, or a readable explanation of its absence. */
+  _requireKey() {
+    if (!this.key) {
+      throw new Error('no API key.\n'
+        + '  Pass one as new DataClient({ key }), or set OT_KEY:\n'
+        + '    export OT_KEY="ck_…"');
+    }
+    return this.key;
+  }
+
+  async _get(path, { query = null, auth = true, redirect = 'follow' } = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(query ?? {})) {
+      const value = filterValue(v);
+      if (value !== null) url.searchParams.set(k, value);
+    }
+    const headers = auth ? { authorization: `Bearer ${this._requireKey()}` } : {};
+
+    let res;
+    try {
+      res = await this._fetch(url, { headers, redirect });
+    } catch (err) {
+      throw new Error(`could not reach ${this.baseUrl}: ${err.message}`);
+    }
+    return { res, url: url.toString() };
+  }
+
+  async _json(path, opts = {}) {
+    const { res, url } = await this._get(path, opts);
+    const text = await res.text();
+    let body;
+    try { body = JSON.parse(text); } catch { body = text; }
+    if (!res.ok) throw new OutcometickError(res.status, body, url);
+    return body;
+  }
+
+  // ---------- discovery -------------------------------------------------
+
+  /**
+   * What this key can see: the date window, and every dimension value in it.
+   *
+   * `assets` and `intervals` hold real symbols and real durations only. The
+   * `none` sentinel is reported separately under `filterTokens`, because a
+   * client that builds an enum from `intervals` or parses them as durations
+   * must not meet a token.
+   */
+  async meta() {
+    return this._json('/v1/meta');
+  }
+
+  /** The days this key may download, with the window's floor and ceiling. */
+  async days() {
+    return this._json('/v1/mirror/days');
+  }
+
+  /**
+   * Search for files across a date range.
+   *
+   * @param q.date      one day — sugar for from === to. Cannot be combined
+   *                    with from/to.
+   * @param q.from      inclusive start; defaults to the newest day in scope.
+   * @param q.to        inclusive end; defaults to `from`.
+   * @param q.venue     polymarket | predict-fun
+   * @param q.dataset   prices | twap60s | book | klines | …  (see meta())
+   * @param q.asset     BTCUSD, ETHUSD, …
+   * @param q.interval  5m, 1h, … or "none" for the streams that have no period
+   *
+   * Every filter accepts a string or an array; an array is joined with commas
+   * and means "any of these". `interval: ["5m", NO_VALUE]` is how you ask for
+   * 5-minute files AND the period-less settlement streams — asking for "5m"
+   * alone deliberately excludes them.
+   *
+   * The server caps the range (92 days by default) and answers 400 past it.
+   */
+  async files(q = {}) {
+    if (q.date && (q.from || q.to)) {
+      // The server rejects this too; catching it here saves a round trip and
+      // says the same thing, so the two cannot describe it differently.
+      throw new Error('use either date, or from/to — not both');
+    }
+    return this._json('/v1/files', {
+      query: {
+        date: q.date, from: q.from, to: q.to,
+        venue: q.venue, dataset: q.dataset, asset: q.asset, interval: q.interval,
+      },
+    });
+  }
+
+  // ---------- download --------------------------------------------------
+
+  /**
+   * A presigned URL for one file, without fetching it.
+   *
+   * Useful when something else does the fetching — a data frame library, a job
+   * runner, a browser. The URL is short-lived; hold the `{date, name}` pair and
+   * ask again rather than storing it.
+   */
+  async signUrl(date, name, { expiresIn = null } = {}) {
+    return this._json('/v1/mirror/download', {
+      query: { date, name, ...(expiresIn ? { expiresIn } : {}) },
+    });
+  }
+
+  /**
+   * Download one file.
+   *
+   * Accepts either a row from files() or an explicit (date, name).
+   *
+   * The checksum is verified by default. /v1/dl answers 302 with the sha256 in
+   * a header and the bytes come from R2 behind the redirect, so the redirect is
+   * followed MANUALLY: letting fetch follow it would discard the header and
+   * with it the only checksum available without a second API call. A row from
+   * files() carries its own sha256, which is used when present.
+   *
+   * @returns {Promise<{bytes: Uint8Array, sha256: string|null, name: string, date: string}>}
+   */
+  async download(fileOrDate, nameOrOpts = null, maybeOpts = null) {
+    const isRow = fileOrDate && typeof fileOrDate === 'object';
+    const date = isRow ? fileOrDate.date : fileOrDate;
+    const name = isRow ? fileOrDate.name : nameOrOpts;
+    const opts = (isRow ? nameOrOpts : maybeOpts) ?? {};
+    const { verify = true, saveTo = null } = opts;
+
+    if (!date || !name) throw new Error('download needs a file row, or a date and a name');
+
+    const { res, url } = await this._get(
+      `/v1/dl/${encodeURIComponent(date)}/${encodeURIComponent(name)}`,
+      { redirect: 'manual' },
+    );
+
+    let expected = isRow ? (fileOrDate.sha256 ?? null) : null;
+    let bytesRes = res;
+
+    if (res.status >= 300 && res.status < 400) {
+      expected = expected
+        ?? res.headers.get('x-outcometick-sha256')
+        ?? res.headers.get('x-amz-meta-sha256')
+        ?? null;
+      const location = res.headers.get('location');
+      if (!location) throw new OutcometickError(res.status, { error: 'redirect with no location' }, url);
+      // The signed URL carries its own auth; sending ours to R2 as well would
+      // leak the key to a host that has no use for it.
+      bytesRes = await this._fetch(location, { redirect: 'follow' });
+    }
+
+    if (!bytesRes.ok) {
+      const text = await bytesRes.text();
+      let body;
+      try { body = JSON.parse(text); } catch { body = text; }
+      throw new OutcometickError(bytesRes.status, body, url);
+    }
+
+    const bytes = new Uint8Array(await bytesRes.arrayBuffer());
+
+    if (verify && expected) {
+      const got = createHash('sha256').update(bytes).digest('hex');
+      if (got !== expected) {
+        throw new Error(`checksum mismatch for ${date}/${name}\n`
+          + `  expected ${expected}\n  got      ${got}`);
+      }
+    }
+
+    if (saveTo) await writeFile(saveTo, bytes);
+    return { bytes, sha256: expected, name, date };
+  }
+
+  // ---------- public, no key needed -------------------------------------
+
+  /** Coverage across all venues. Public — works without a key. */
+  async coverage() {
+    return this._json('/v1/public/coverage', { auth: false });
+  }
+
+  /** Plans and live prices. Public. */
+  async plans() {
+    return this._json('/v1/public/plans', { auth: false });
+  }
+
+  /** Liveness. Public. */
+  async health() {
+    return this._json('/v1/health', { auth: false });
+  }
+}
+
+export default DataClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outcometick",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Strategy SDK and CLI for outcometick prediction-market backtests",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,10 @@
     ".": {
       "types": "./index.d.ts",
       "default": "./index.mjs"
+    },
+    "./data": {
+      "types": "./client/data.d.ts",
+      "default": "./client/data.mjs"
     }
   },
   "engines": {
@@ -27,16 +31,17 @@
   },
   "files": [
     "api",
-    "runner",
-    "cli",
     "bin",
-    "index.mjs",
+    "cli",
+    "client",
     "index.d.ts",
+    "index.mjs",
+    "runner",
     "!**/*.test.mjs",
     "!**/*.test-d.ts"
   ],
   "scripts": {
-    "test": "node --test runner/analyze/*.test.mjs runner/engine/*.test.mjs runner/harness/node/*.test.mjs cli/*.test.mjs"
+    "test": "node --test runner/analyze/*.test.mjs runner/engine/*.test.mjs runner/harness/node/*.test.mjs cli/*.test.mjs client/*.test.mjs"
   },
   "dependencies": {
     "acorn": "^8.18.0"

package/runner/analyze/python_analyze.py

@@ -145,6 +145,26 @@ def check_import(module, name, line, deps, relative_ok):
             else "E_FORBIDDEN"
         )
         raise Reject(code, f"{name}:{line}: import {root} — {FORBIDDEN_IMPORTS[root]}", name, line)
+    # `outcometick` is allowed as the SDK module and nothing else. In the
+    # sandbox it is a single flat module -- Strategy and Order -- so
+    # `outcometick.data` resolves to nothing there, even though pip installs it
+    # as a real submodule. Allowing it because the ROOT matches would mean
+    # `ot check` passing a strategy that dies on import after being queued,
+    # which is the exact failure the "if it passes locally it will not be
+    # rejected on submit" promise exists to prevent.
+    #
+    # The JavaScript analyser has always compared the whole specifier, so
+    # `outcometick/data` was already refused there. This is the Python half of
+    # the same rule.
+    if root == "outcometick" and module != "outcometick":
+        raise Reject(
+            "E_IMPORT",
+            f"{name}:{line}: import of {module!r} — only 'outcometick' itself is "
+            "available to a strategy; the sandbox has no network and no submodules",
+            name,
+            line,
+            specifier=module,
+        )
     if root in ALWAYS_ALLOWED or root in deps:
         return
     raise Reject(