TypeScript SDK · @goable-io/sdk
A thin, fully-typed transport over the public API: one request method powers every call, and the types are generated from the versioned OpenAPI contract. It covers the public API surface, from scoring and recommend-spot to decision, counterfactual explain, intelligence, underwriting, observations and outcomes.
Install
npm install @goable-io/sdk
# pnpm add @goable-io/sdk · yarn add @goable-io/sdkv0.5.0, MIT licensed, published to npm with provenance (verifiable build attestation via npm audit signatures). Isomorphic: the same package runs in Node, browsers, and edge runtimes off the global fetch; inject your own fetch implementation for older Node or test environments. Zero runtime dependencies. Source + the full method list: github.com/goable-io/sdk.
Quickstart
import { GoableClient } from "@goable-io/sdk" const goable = new GoableClient({ apiKey: process.env.GOABLE_API_KEY! }) const { score, verdict, breakdown } = await goable.score({ location: { lat: 36.013, lng: -5.604 }, activity: "kitesurfing", window: { from: "2026-05-23T09:00Z", to: "2026-05-23T18:00Z" }, })
Authentication
The constructor takes your key plus optional transport overrides. See Authentication for how keys work.
new GoableClient({ apiKey: string, // required baseUrl?: string, // default https://api.goable.io fetch?: FetchLike, // inject for tests timeoutMs?: number, // default 30000; 0 disables })
Methods
| Method | Endpoint | Returns |
|---|---|---|
| score(req) | POST /v1/score | Single 0–100 verdict for an activity, location and window. |
| scoreSeries(req) | POST /v1/score/series | Hourly series across the forecast horizon. |
| scoreMulti(req) | POST /v1/score/multi | Several activities at one location in one call. |
| scorePortfolio(req) | POST /v1/score/portfolio | Joint score across many spots with correlation. |
| scoreHistorical(req) | POST /v1/score/historical | Percentiles + exceedance over the ERA5 archive. |
| projections(req) | POST /v1/projections | CMIP6 / CORDEX climate-decadal projections (Scale). |
| decision(req) | POST /v1/decision | Personalised go / no-go decision (any plan; reasoning narrative needs your own Anthropic key). |
| recommendSpot(req) | POST /v1/recommend-spot | Top-K ranked sub-spots in a region. |
| explainCounterfactual(req) | POST /v1/score/explain-counterfactual | Binding constraint, sensitivities, best window, best nearby spot. |
| explain(req) | POST /v1/intelligence/explain | Natural-language explanation of a score (any plan; needs your own Anthropic key). |
| briefing(req) | POST /v1/intelligence/briefing | Multi-slot narrative briefing (any plan; needs your own Anthropic key). |
| quote(req) | POST /v1/underwriting/quote | Parametric premium quote (Scale). |
| bindPolicy(req) | POST /v1/underwriting/policy/bind | Convert a quote into a bound policy (Scale). |
| submitOutcome(sessionId, req) | POST /v1/score/:id/outcome | Report what actually happened for a scored session. |
| health() | GET /v1/health | Liveness / readiness probe. |
Try it
Pick an activity, a spot and the flags. Runs against the live engine (public demo tenant, 60 calls / hour / IP); falls back to a deterministic sample.
Display-only — the real /v1/score request has no option to omit fields; this just trims what's shown here.
Errors
Non-2xx throws GoableApiError (with status, code, issues); transport failures throw GoableNetworkError. A few high-signal 422 codes are surfaced as dedicated subclasses, currently DriftActiveError for a refused underwriting bind. See Errors & rate limits.
import { GoableApiError } from "@goable-io/sdk" try { await goable.score(req) } catch (err) { if (err instanceof GoableApiError) console.error(err.status, err.code) }
Types
ScoreRequest, ScoreResponse and the rest are generated from the versioned OpenAPI 3.1 contract, so they track the contract they were built against rather than being hand-maintained. The SDK is released alongside the API versions it supports, and compatibility is covered by contract tests. Full endpoint reference: POST /v1/score.