@firstforecast/sdk

Official TypeScript SDK for the First Forecast B2B2C API.

npm install @firstforecast/sdk
# or: pnpm add @firstforecast/sdk

Quick start

import { FirstForecast } from '@firstforecast/sdk';

const ff = new FirstForecast({
  apiKey: process.env.FF_API_KEY!, // ff_live_<...> or ff_test_<...>
});

const result = await ff.forecast('AAPL', { persona: 'balanced' });
console.log(result.compliance.jurisdiction); // 'US'
console.log(result.forecast.horizons[0].most_probable);

Sandbox testing:

const ff = new FirstForecast({
  apiKey: process.env.FF_SANDBOX_KEY!, // ff_test_<...>
  baseUrl: 'https://api-sandbox.first-forecast.app',
});

Methods

| Method | Endpoint | |--------------------------------|---------------------------------------| | ff.forecast(ticker, opts?) | GET /v1/forecast/{ticker} | | ff.multi(tickers, opts?) | GET /v1/multi | | ff.tickers(opts?) | GET /v1/tickers | | ff.usage(opts?) | GET /v1/usage |

The SSE stream endpoint (/v1/forecast/{ticker}/stream) is intentionally not bundled — use Node's eventsource or browser-native EventSource directly.

Options

new FirstForecast({
  apiKey: 'ff_live_...',
  baseUrl: 'https://api.first-forecast.app',     // optional, defaults to prod
  jurisdiction: 'EU',                           // optional default for X-User-Jurisdiction
  timeoutMs: 15000,                             // per-request, default 15s
  fetch: customFetch,                           // optional fetch override
});

Per-call options override the constructor defaults:

await ff.forecast('AAPL', {
  persona: 'risk_on',                           // 'conservative' | 'balanced' | 'risk_on'
  jurisdiction: 'EU',                           // applies EU compliance rules to this call
  signal: abortController.signal,               // composes with the SDK's internal timeout
});

Errors

Every method throws FirstForecastError (extends Error) on failure:

import { FirstForecast, FirstForecastError } from '@firstforecast/sdk';

try {
  await ff.forecast('NOTAREAL');
} catch (e) {
  if (e instanceof FirstForecastError) {
    switch (e.kind) {
      case 'auth':         // 401 / 403
      case 'not_found':    // 404
      case 'bad_request':  // 400
      case 'rate_limited': // 429 — e.retryAfter has the seconds
      case 'server_error': // 5xx
      case 'network':      // fetch threw, or timeout fired
      case 'parse':        // server returned non-JSON
    }
    console.log(e.status, e.body);
  }
}

Versioning

This SDK tracks packages/schemas/openapi.yml in the first-forecast monorepo. The OpenAPI snapshot is regenerated from the live FastAPI service whenever the public surface changes. Major-version bumps on this SDK indicate a breaking change to that contract.

License

MIT.