@teemtape/api-client 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared data contracts for the teemtape API.
+ *
+ * These types are the single source of truth used by every client (CLI, web,
+ * and later React Native) and will be implemented by the Cloudflare Worker in
+ * milestone M0. See docs/architecture.md and docs/roadmap.md.
+ */
+/** Where a note came from. Drives the "agent" badge in the web UI. */
+type NoteSource = "web" | "cli";
+/** A delayed stock quote (delayed ~1 minute on purpose — not a trading tool). */
+interface Quote {
+    symbol: string;
+    name: string;
+    /** Last (delayed) price. */
+    price: number;
+    /** Absolute change vs previous close. */
+    change: number;
+    /** Percentage change vs previous close. */
+    pct: number;
+    /** ISO timestamp of the (delayed) quote. */
+    asOf: string;
+}
+interface QuotesResponse {
+    quotes: Quote[];
+    /** How many seconds the data is intentionally delayed by. */
+    delayedSeconds: number;
+    /** Upstream data source, e.g. "polygon" | "massive" | "mock". */
+    source: string;
+}
+/** An anonymous note attached to a (watchlist, symbol). */
+interface Note {
+    id: string;
+    symbol: string;
+    /** Short anonymous handle, e.g. "anon-6f1ed0" or "agent-cli". */
+    author: string;
+    source: NoteSource;
+    body: string;
+    /** ISO timestamp. */
+    createdAt: string;
+}
+interface NotesResponse {
+    symbol: string;
+    notes: Note[];
+}
+/** A watchlist identified by an anonymous MD5 token (lives in the share URL). */
+interface Watchlist {
+    token: string;
+    symbols: string[];
+    createdAt: string;
+}
+interface CreateNoteInput {
+    symbol: string;
+    body: string;
+    source: NoteSource;
+}
+/** A row in the SEC symbols reference catalog. */
+interface SymbolEntry {
+    ticker: string;
+    cikStr: number;
+    title: string;
+}
+interface SymbolsListResponse {
+    symbols: SymbolEntry[];
+    /** Zero-based row offset (e.g. 0, 100, 200). */
+    offset: number;
+    /** Page size (max 100). */
+    limit: number;
+    /** Total rows matching the current filters. */
+    total: number;
+    /** Sort order applied: ticker or title. */
+    sort: "ticker" | "title";
+}
+
+interface ApiClientOptions {
+    /** Base URL of the Worker API, e.g. http://localhost:8787 */
+    baseUrl: string;
+    /** Optional default watchlist token used by watchlist/note calls. */
+    token?: string;
+    /** Injectable fetch (defaults to global fetch); handy for tests. */
+    fetch?: typeof fetch;
+}
+/** Thrown for any non-2xx API response. */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+/**
+ * Minimal typed client for the teemtape Worker API. The same contract is reused
+ * by the CLI now and the web/native apps later (see docs/cli-options.md).
+ */
+declare class TeemtapeClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly fetchImpl;
+    constructor(options: ApiClientOptions);
+    /** Delayed quotes for the given symbols. */
+    getQuotes(symbols: string[]): Promise<QuotesResponse>;
+    /** Paginated SEC symbol catalog with optional search and sort. */
+    listSymbols(params?: {
+        offset?: number;
+        limit?: number;
+        sort?: "ticker" | "title";
+        q?: string;
+        symbol?: string;
+        name?: string;
+    }): Promise<SymbolsListResponse>;
+    /** Create a new anonymous watchlist and return its MD5 token. */
+    createWatchlist(): Promise<Watchlist>;
+    /** Fetch a watchlist (symbols + metadata) by token. */
+    getWatchlist(token?: string): Promise<Watchlist>;
+    /** Add a symbol to a watchlist. */
+    addSymbol(symbol: string, token?: string): Promise<Watchlist>;
+    /** Notes for a symbol on a watchlist. */
+    getNotes(symbol: string, token?: string): Promise<NotesResponse>;
+    /** Post an anonymous note to a symbol. */
+    addNote(input: CreateNoteInput, token?: string): Promise<Note>;
+    private requireToken;
+    private request;
+}
+
+export { type ApiClientOptions, ApiError, type CreateNoteInput, type Note, type NoteSource, type NotesResponse, type Quote, type QuotesResponse, type SymbolEntry, type SymbolsListResponse, TeemtapeClient, type Watchlist };

package/dist/index.js

@@ -0,0 +1,104 @@
+// src/client.ts
+var ApiError = class extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var TeemtapeClient = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.token = options.token;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("No fetch implementation available (need Node 18+ or pass options.fetch).");
+    }
+  }
+  /** Delayed quotes for the given symbols. */
+  async getQuotes(symbols) {
+    const query = encodeURIComponent(symbols.join(","));
+    return this.request(`/api/quotes?symbols=${query}`);
+  }
+  /** Paginated SEC symbol catalog with optional search and sort. */
+  async listSymbols(params = {}) {
+    const search = new URLSearchParams();
+    if (params.offset !== void 0) search.set("offset", String(params.offset));
+    if (params.limit !== void 0) search.set("limit", String(params.limit));
+    if (params.sort) search.set("sort", params.sort);
+    if (params.q) search.set("q", params.q);
+    if (params.symbol) search.set("symbol", params.symbol);
+    if (params.name) search.set("name", params.name);
+    const qs = search.toString();
+    return this.request(`/api/symbols${qs ? `?${qs}` : ""}`);
+  }
+  /** Create a new anonymous watchlist and return its MD5 token. */
+  async createWatchlist() {
+    return this.request(`/api/watchlists`, { method: "POST" });
+  }
+  /** Fetch a watchlist (symbols + metadata) by token. */
+  async getWatchlist(token = this.requireToken()) {
+    return this.request(`/api/w/${token}`);
+  }
+  /** Add a symbol to a watchlist. */
+  async addSymbol(symbol, token = this.requireToken()) {
+    return this.request(`/api/w/${token}/symbols`, {
+      method: "POST",
+      body: JSON.stringify({ symbol: symbol.toUpperCase() })
+    });
+  }
+  /** Notes for a symbol on a watchlist. */
+  async getNotes(symbol, token = this.requireToken()) {
+    const query = encodeURIComponent(symbol.toUpperCase());
+    return this.request(`/api/w/${token}/notes?symbol=${query}`);
+  }
+  /** Post an anonymous note to a symbol. */
+  async addNote(input, token = this.requireToken()) {
+    return this.request(`/api/w/${token}/notes`, {
+      method: "POST",
+      body: JSON.stringify({ ...input, symbol: input.symbol.toUpperCase() })
+    });
+  }
+  requireToken() {
+    if (!this.token) {
+      throw new Error("A watchlist token is required. Pass --token or set TEEMTAPE_TOKEN.");
+    }
+    return this.token;
+  }
+  async request(path, init = {}) {
+    const headers = new Headers(init.headers);
+    if (init.body && !headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    headers.set("accept", "application/json");
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, { ...init, headers });
+    const text = await res.text();
+    const data = text ? safeJsonParse(text) : void 0;
+    if (!res.ok) {
+      const message = isRecord(data) && typeof data.error === "string" && data.error || `Request to ${path} failed with ${res.status}`;
+      throw new ApiError(res.status, message, data);
+    }
+    return data;
+  }
+};
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  ApiError,
+  TeemtapeClient
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type {\n  CreateNoteInput,\n  Note,\n  NotesResponse,\n  QuotesResponse,\n  SymbolsListResponse,\n  Watchlist,\n} from \"./types.js\";\n\nexport interface ApiClientOptions {\n  /** Base URL of the Worker API, e.g. http://localhost:8787 */\n  baseUrl: string;\n  /** Optional default watchlist token used by watchlist/note calls. */\n  token?: string;\n  /** Injectable fetch (defaults to global fetch); handy for tests. */\n  fetch?: typeof fetch;\n}\n\n/** Thrown for any non-2xx API response. */\nexport class ApiError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(status: number, message: string, body: unknown) {\n    super(message);\n    this.name = \"ApiError\";\n    this.status = status;\n    this.body = body;\n  }\n}\n\n/**\n * Minimal typed client for the teemtape Worker API. The same contract is reused\n * by the CLI now and the web/native apps later (see docs/cli-options.md).\n */\nexport class TeemtapeClient {\n  private readonly baseUrl: string;\n  private readonly token?: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(options: ApiClientOptions) {\n    this.baseUrl = options.baseUrl.replace(/\\/$/, \"\");\n    this.token = options.token;\n    this.fetchImpl = options.fetch ?? globalThis.fetch;\n    if (typeof this.fetchImpl !== \"function\") {\n      throw new Error(\"No fetch implementation available (need Node 18+ or pass options.fetch).\");\n    }\n  }\n\n  /** Delayed quotes for the given symbols. */\n  async getQuotes(symbols: string[]): Promise<QuotesResponse> {\n    const query = encodeURIComponent(symbols.join(\",\"));\n    return this.request<QuotesResponse>(`/api/quotes?symbols=${query}`);\n  }\n\n  /** Paginated SEC symbol catalog with optional search and sort. */\n  async listSymbols(params: {\n    offset?: number;\n    limit?: number;\n    sort?: \"ticker\" | \"title\";\n    q?: string;\n    symbol?: string;\n    name?: string;\n  } = {}): Promise<SymbolsListResponse> {\n    const search = new URLSearchParams();\n    if (params.offset !== undefined) search.set(\"offset\", String(params.offset));\n    if (params.limit !== undefined) search.set(\"limit\", String(params.limit));\n    if (params.sort) search.set(\"sort\", params.sort);\n    if (params.q) search.set(\"q\", params.q);\n    if (params.symbol) search.set(\"symbol\", params.symbol);\n    if (params.name) search.set(\"name\", params.name);\n    const qs = search.toString();\n    return this.request<SymbolsListResponse>(`/api/symbols${qs ? `?${qs}` : \"\"}`);\n  }\n\n  /** Create a new anonymous watchlist and return its MD5 token. */\n  async createWatchlist(): Promise<Watchlist> {\n    return this.request<Watchlist>(`/api/watchlists`, { method: \"POST\" });\n  }\n\n  /** Fetch a watchlist (symbols + metadata) by token. */\n  async getWatchlist(token = this.requireToken()): Promise<Watchlist> {\n    return this.request<Watchlist>(`/api/w/${token}`);\n  }\n\n  /** Add a symbol to a watchlist. */\n  async addSymbol(symbol: string, token = this.requireToken()): Promise<Watchlist> {\n    return this.request<Watchlist>(`/api/w/${token}/symbols`, {\n      method: \"POST\",\n      body: JSON.stringify({ symbol: symbol.toUpperCase() }),\n    });\n  }\n\n  /** Notes for a symbol on a watchlist. */\n  async getNotes(symbol: string, token = this.requireToken()): Promise<NotesResponse> {\n    const query = encodeURIComponent(symbol.toUpperCase());\n    return this.request<NotesResponse>(`/api/w/${token}/notes?symbol=${query}`);\n  }\n\n  /** Post an anonymous note to a symbol. */\n  async addNote(input: CreateNoteInput, token = this.requireToken()): Promise<Note> {\n    return this.request<Note>(`/api/w/${token}/notes`, {\n      method: \"POST\",\n      body: JSON.stringify({ ...input, symbol: input.symbol.toUpperCase() }),\n    });\n  }\n\n  private requireToken(): string {\n    if (!this.token) {\n      throw new Error(\"A watchlist token is required. Pass --token or set TEEMTAPE_TOKEN.\");\n    }\n    return this.token;\n  }\n\n  private async request<T>(path: string, init: RequestInit = {}): Promise<T> {\n    const headers = new Headers(init.headers);\n    if (init.body && !headers.has(\"content-type\")) {\n      headers.set(\"content-type\", \"application/json\");\n    }\n    headers.set(\"accept\", \"application/json\");\n\n    const res = await this.fetchImpl(`${this.baseUrl}${path}`, { ...init, headers });\n    const text = await res.text();\n    const data = text ? safeJsonParse(text) : undefined;\n\n    if (!res.ok) {\n      const message =\n        (isRecord(data) && typeof data.error === \"string\" && data.error) ||\n        `Request to ${path} failed with ${res.status}`;\n      throw new ApiError(res.status, message, data);\n    }\n    return data as T;\n  }\n}\n\nfunction safeJsonParse(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n"],"mappings":";AAmBO,IAAM,WAAN,cAAuB,MAAM;AAAA,EACzB;AAAA,EACA;AAAA,EAET,YAAY,QAAgB,SAAiB,MAAe;AAC1D,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,OAAO;AAAA,EACd;AACF;AAMO,IAAM,iBAAN,MAAqB;AAAA,EACT;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,SAA2B;AACrC,SAAK,UAAU,QAAQ,QAAQ,QAAQ,OAAO,EAAE;AAChD,SAAK,QAAQ,QAAQ;AACrB,SAAK,YAAY,QAAQ,SAAS,WAAW;AAC7C,QAAI,OAAO,KAAK,cAAc,YAAY;AACxC,YAAM,IAAI,MAAM,0EAA0E;AAAA,IAC5F;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,UAAU,SAA4C;AAC1D,UAAM,QAAQ,mBAAmB,QAAQ,KAAK,GAAG,CAAC;AAClD,WAAO,KAAK,QAAwB,uBAAuB,KAAK,EAAE;AAAA,EACpE;AAAA;AAAA,EAGA,MAAM,YAAY,SAOd,CAAC,GAAiC;AACpC,UAAM,SAAS,IAAI,gBAAgB;AACnC,QAAI,OAAO,WAAW,OAAW,QAAO,IAAI,UAAU,OAAO,OAAO,MAAM,CAAC;AAC3E,QAAI,OAAO,UAAU,OAAW,QAAO,IAAI,SAAS,OAAO,OAAO,KAAK,CAAC;AACxE,QAAI,OAAO,KAAM,QAAO,IAAI,QAAQ,OAAO,IAAI;AAC/C,QAAI,OAAO,EAAG,QAAO,IAAI,KAAK,OAAO,CAAC;AACtC,QAAI,OAAO,OAAQ,QAAO,IAAI,UAAU,OAAO,MAAM;AACrD,QAAI,OAAO,KAAM,QAAO,IAAI,QAAQ,OAAO,IAAI;AAC/C,UAAM,KAAK,OAAO,SAAS;AAC3B,WAAO,KAAK,QAA6B,eAAe,KAAK,IAAI,EAAE,KAAK,EAAE,EAAE;AAAA,EAC9E;AAAA;AAAA,EAGA,MAAM,kBAAsC;AAC1C,WAAO,KAAK,QAAmB,mBAAmB,EAAE,QAAQ,OAAO,CAAC;AAAA,EACtE;AAAA;AAAA,EAGA,MAAM,aAAa,QAAQ,KAAK,aAAa,GAAuB;AAClE,WAAO,KAAK,QAAmB,UAAU,KAAK,EAAE;AAAA,EAClD;AAAA;AAAA,EAGA,MAAM,UAAU,QAAgB,QAAQ,KAAK,aAAa,GAAuB;AAC/E,WAAO,KAAK,QAAmB,UAAU,KAAK,YAAY;AAAA,MACxD,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU,EAAE,QAAQ,OAAO,YAAY,EAAE,CAAC;AAAA,IACvD,CAAC;AAAA,EACH;AAAA;AAAA,EAGA,MAAM,SAAS,QAAgB,QAAQ,KAAK,aAAa,GAA2B;AAClF,UAAM,QAAQ,mBAAmB,OAAO,YAAY,CAAC;AACrD,WAAO,KAAK,QAAuB,UAAU,KAAK,iBAAiB,KAAK,EAAE;AAAA,EAC5E;AAAA;AAAA,EAGA,MAAM,QAAQ,OAAwB,QAAQ,KAAK,aAAa,GAAkB;AAChF,WAAO,KAAK,QAAc,UAAU,KAAK,UAAU;AAAA,MACjD,QAAQ;AAAA,MACR,MAAM,KAAK,UAAU,EAAE,GAAG,OAAO,QAAQ,MAAM,OAAO,YAAY,EAAE,CAAC;AAAA,IACvE,CAAC;AAAA,EACH;AAAA,EAEQ,eAAuB;AAC7B,QAAI,CAAC,KAAK,OAAO;AACf,YAAM,IAAI,MAAM,oEAAoE;AAAA,IACtF;AACA,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAc,QAAW,MAAc,OAAoB,CAAC,GAAe;AACzE,UAAM,UAAU,IAAI,QAAQ,KAAK,OAAO;AACxC,QAAI,KAAK,QAAQ,CAAC,QAAQ,IAAI,cAAc,GAAG;AAC7C,cAAQ,IAAI,gBAAgB,kBAAkB;AAAA,IAChD;AACA,YAAQ,IAAI,UAAU,kBAAkB;AAExC,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,OAAO,GAAG,IAAI,IAAI,EAAE,GAAG,MAAM,QAAQ,CAAC;AAC/E,UAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,UAAM,OAAO,OAAO,cAAc,IAAI,IAAI;AAE1C,QAAI,CAAC,IAAI,IAAI;AACX,YAAM,UACH,SAAS,IAAI,KAAK,OAAO,KAAK,UAAU,YAAY,KAAK,SAC1D,cAAc,IAAI,gBAAgB,IAAI,MAAM;AAC9C,YAAM,IAAI,SAAS,IAAI,QAAQ,SAAS,IAAI;AAAA,IAC9C;AACA,WAAO;AAAA,EACT;AACF;AAEA,SAAS,cAAc,MAAuB;AAC5C,MAAI;AACF,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;","names":[]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@teemtape/api-client",
+  "version": "0.0.1",
+  "description": "Shared typed client + types for the teemtape Worker API.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}