@forecite/sdk

Official TypeScript/JavaScript SDK for the Forecite API — the scored news feed (REST), the Verdict scoring engine, and the realtime WebSocket stream. Fully typed, ESM + CJS, zero runtime dependencies. Works in Node 18+ and the browser (streaming needs Node 22+ or a browser for the global WebSocket).

Install

npm install @forecite/sdk

Quick start

import { Forecite } from "@forecite/sdk";

const forecite = new Forecite("fc_live_your_key");
// or: new Forecite({ apiKey, baseUrl, wsUrl })

// REST — list scored feeds
const { data, next_cursor } = await forecite.feeds.list({ symbol: "TSLA", limit: 20 });

// Score an artifact (Pro+)
const verdict = await forecite.score({
  type: "news",
  title: "Acme beats earnings",
  body: "Acme reported Q2 revenue of …",
});

// Account + usage
const me = await forecite.me();
const usage = await forecite.usage({ days: 14 });

Realtime stream

const stream = forecite.stream(
  { filters: { symbols: ["TSLA", "AAPL"] }, snapshot: 10 },
  {
    onWelcome: (w) => console.log("connected:", w.tier),
    onFeed: (item, { snapshot }) =>
      console.log(snapshot ? "[snap]" : "[live]", item.title),
    onQuotaExceeded: (q) => console.warn(q.message),
    onError: (e) => console.error(e),
  },
);
// later: stream.close();

API surface

| Group | Methods | |---|---| | Feeds | feeds.list(query), feeds.get(id) | | Scoring | score(artifact, options?) / score(request) | | Account | me(), usage({ days }) | | Reference | providers.list/get, sources.list/get, symbols.list/get, tags.list/get | | Webhooks | webhooks.list/create/get/update/delete | | Realtime | stream(options, handlers) |

Config

new Forecite({
  apiKey: "fc_live_…",
  baseUrl: "http://localhost:3000/api", // local dev (default: https://api.forecite.dev)
  wsUrl: "ws://localhost:8080",          // local dev (default: wss://ws.forecite.dev)
});

Errors throw ForeciteError with .status and .code.

Build (for contributors)

npm install
npm run build     # tsup → dist/ (esm + cjs + d.ts)
npm run typecheck