@goable-io/sdk 0.3.0 → 0.5.0

package/src/client.ts

@@ -5,22 +5,54 @@
 
 import { GoableNetworkError, toApiError } from "./errors.ts"
 import type {
+  AdaptationReportRequest,
+  AdaptationReportResponse,
+  AuditExportQuery,
+  AuditExportResponse,
+  BindPolicyRequest,
+  BindPolicyResponse,
   BriefingRequest,
   BriefingResponse,
+  CatalogStatsResponse,
   CounterfactualRequest,
   CounterfactualResponse,
+  CreateStationRequest,
+  CreateStationResponse,
   DecisionRequest,
   DecisionResponse,
   DeleteUserDataResult,
+  EdgeCaseRequest,
+  EdgeCaseResponse,
+  EvaluatePolicyResponse,
   ExplainRequest,
   ExplainResponse,
+  HealthReadyResponse,
   HealthResponse,
+  IdempotencyOptions,
+  LegalDocumentKind,
+  LegalDocumentResponse,
+  ListPoliciesQuery,
+  ListPoliciesResponse,
+  ListStationsResponse,
+  LlmKeyStatus,
+  PolicyResponse,
+  ProjectionsPortfolioRequest,
+  ProjectionsPortfolioResponse,
   ProjectionsRequest,
   ProjectionsResponse,
+  PublicSignupRequest,
+  PublicSignupResponse,
+  QuoteByIdResponse,
   QuoteRequest,
   QuoteResponse,
+  RecentObservationsQuery,
+  RecentObservationsResponse,
   RecommendSpotRequest,
   RecommendSpotResponse,
+  ReportOutcomeRequest,
+  ReportOutcomeResponse,
+  ScoreDifficultyRequest,
+  ScoreDifficultyResponse,
   ScoreHistoricalRequest,
   ScoreHistoricalResponse,
   ScoreMultiRequest,
@@ -31,6 +63,18 @@ import type {
   ScoreResponse,
   ScoreSeriesRequest,
   ScoreSeriesResponse,
+  SetLlmKeyRequest,
+  SettlePolicyRequest,
+  SettlePolicyResponse,
+  SubmitObservationsRequest,
+  SubmitObservationsResponse,
+  SubmitOutcomeRequest,
+  SubmitOutcomeResponse,
+  SustainabilityIndexQuery,
+  SustainabilityIndexResponse,
+  UpdateStationRequest,
+  UpdateStationResponse,
+  VerificationExportQuery,
 } from "./types.ts"
 
 export type FetchLike = (
@@ -85,6 +129,12 @@ export class GoableClient {
     return this.request<HealthResponse>("GET", "/v1/health")
   }
 
+  /** Readiness probe (DB + skill lookup + LLM config). Note: a degraded/critical
+   *  deployment answers `503`, which surfaces here as a {@link GoableApiError}. */
+  healthReady(): Promise<HealthReadyResponse> {
+    return this.request<HealthReadyResponse>("GET", "/v1/health/ready")
+  }
+
   score(input: ScoreRequest): Promise<ScoreResponse> {
     return this.request<ScoreResponse>("POST", "/v1/score", input)
   }
@@ -141,6 +191,212 @@ export class GoableClient {
     return this.request<RecommendSpotResponse>("POST", "/v1/recommend-spot", input)
   }
 
+  /** L15 — skill-conditioned difficulty grids per scoring dimension (Pro+). */
+  scoreDifficulty(input: ScoreDifficultyRequest): Promise<ScoreDifficultyResponse> {
+    return this.request<ScoreDifficultyResponse>("POST", "/v1/score/difficulty", input)
+  }
+
+  /** Close the calibration loop: report the observed outcome of a scored
+   *  session. Requires the `outcomes:write` scope. Pass `idempotencyKey` so a
+   *  retry after a network timeout can't record the same outcome twice. */
+  reportOutcome(
+    sessionId: string,
+    input: ReportOutcomeRequest,
+    options?: IdempotencyOptions,
+  ): Promise<ReportOutcomeResponse> {
+    return this.request<ReportOutcomeResponse>(
+      "POST",
+      `/v1/score/${encodeURIComponent(sessionId)}/outcome`,
+      input,
+      idempotencyHeader(options),
+    )
+  }
+
+  /** Report a standalone activity outcome not tied to a scored session — the
+   *  operator-reported behavioural signal behind the calibration + research
+   *  datasets. Responds 202. Requires the `outcomes:write` scope. For an
+   *  outcome linked to a specific score, use {@link reportOutcome} instead. */
+  submitOutcome(input: SubmitOutcomeRequest): Promise<SubmitOutcomeResponse> {
+    return this.request<SubmitOutcomeResponse>("POST", "/v1/outcomes", input)
+  }
+
+  /** LLM edge-case narrative for a marginal score. */
+  edgeCase(input: EdgeCaseRequest): Promise<EdgeCaseResponse> {
+    return this.request<EdgeCaseResponse>("POST", "/v1/intelligence/edge-case", input)
+  }
+
+  /** T3 — multi-spot climate-decadal projections (Scale). */
+  projectionsPortfolio(input: ProjectionsPortfolioRequest): Promise<ProjectionsPortfolioResponse> {
+    return this.request<ProjectionsPortfolioResponse>("POST", "/v1/projections/portfolio", input)
+  }
+
+  /** T3 — adaptation report across months × scenarios × decades (Scale). */
+  adaptationReport(input: AdaptationReportRequest): Promise<AdaptationReportResponse> {
+    return this.request<AdaptationReportResponse>("POST", "/v1/projections/adaptation-report", input)
+  }
+
+  // ── underwriting policy lifecycle (Scale) ─────────────────────────────────
+  /** Fetch a stored quote by id. */
+  getQuote(id: string): Promise<QuoteByIdResponse> {
+    return this.request<QuoteByIdResponse>("GET", `/v1/underwriting/quote/${encodeURIComponent(id)}`)
+  }
+
+  /**
+   * Bind a recent quote into a policy. Responds 201. A watch-level drift event
+   * on the resolved cell surfaces as `driftAdvisories` on success; a
+   * warning/critical event refuses the bind with `422 DRIFT_ACTIVE`, thrown as
+   * a {@link DriftActiveError}.
+   */
+  bindPolicy(input: BindPolicyRequest, options?: IdempotencyOptions): Promise<BindPolicyResponse> {
+    return this.request<BindPolicyResponse>(
+      "POST",
+      "/v1/underwriting/policy/bind",
+      input,
+      idempotencyHeader(options),
+    )
+  }
+
+  /** List the calling tenant's bound policies (paginated, boundAt DESC). */
+  listPolicies(query?: ListPoliciesQuery): Promise<ListPoliciesResponse> {
+    return this.request<ListPoliciesResponse>("GET", `/v1/underwriting/policy${toQuery(query)}`)
+  }
+
+  /** Fetch a single policy + its payout events. */
+  getPolicy(policyId: string): Promise<PolicyResponse> {
+    return this.request<PolicyResponse>("GET", `/v1/underwriting/policy/${encodeURIComponent(policyId)}`)
+  }
+
+  /** Re-evaluate a bound policy against the historical archive; inserts any
+   *  newly detected payout events. No request body. */
+  evaluatePolicy(policyId: string): Promise<EvaluatePolicyResponse> {
+    return this.request<EvaluatePolicyResponse>(
+      "POST",
+      `/v1/underwriting/policy/${encodeURIComponent(policyId)}/evaluate`,
+    )
+  }
+
+  /**
+   * Settle a bound policy. PLATFORM-OPS ONLY — requires the `platform_admin`
+   * scope (a cross-tenant underwriter operation, normally run by the daily
+   * settlement cron). Not a policyholder self-service action; tenant
+   * integrations should not call this.
+   */
+  settlePolicy(policyId: string, input: SettlePolicyRequest): Promise<SettlePolicyResponse> {
+    return this.request<SettlePolicyResponse>(
+      "POST",
+      `/v1/underwriting/policy/${encodeURIComponent(policyId)}/settle`,
+      input,
+    )
+  }
+
+  // ── observations / nowcasting (L5.3) ──────────────────────────────────────
+  /** Register a tenant observation station. Responds 201. */
+  createStation(input: CreateStationRequest): Promise<CreateStationResponse> {
+    return this.request<CreateStationResponse>("POST", "/v1/observations/stations", input)
+  }
+
+  /** List the calling tenant's observation stations. */
+  listStations(): Promise<ListStationsResponse> {
+    return this.request<ListStationsResponse>("GET", "/v1/observations/stations")
+  }
+
+  /** Patch a station (partial update). */
+  updateStation(stationId: string, input: UpdateStationRequest): Promise<UpdateStationResponse> {
+    return this.request<UpdateStationResponse>(
+      "PATCH",
+      `/v1/observations/stations/${encodeURIComponent(stationId)}`,
+      input,
+    )
+  }
+
+  /** Push station observations into the 0-6h assimilation window (Pro+).
+   *  Responds 202. */
+  submitObservations(input: SubmitObservationsRequest): Promise<SubmitObservationsResponse> {
+    return this.request<SubmitObservationsResponse>("POST", "/v1/observations", input)
+  }
+
+  /** Most-recent observations for one of the tenant's stations. */
+  recentObservations(
+    stationId: string,
+    query?: RecentObservationsQuery,
+  ): Promise<RecentObservationsResponse> {
+    return this.request<RecentObservationsResponse>(
+      "GET",
+      `/v1/observations/stations/${encodeURIComponent(stationId)}/recent${toQuery(query)}`,
+    )
+  }
+
+  // ── public / research (no-auth surfaces) ──────────────────────────────────
+  /** Public Goable Sustainability Index (JSON-LD, CC BY 4.0). */
+  sustainabilityIndex(query: SustainabilityIndexQuery): Promise<SustainabilityIndexResponse> {
+    return this.request<SustainabilityIndexResponse>(
+      "GET",
+      `/v1/public/sustainability-index${toQuery(query)}`,
+    )
+  }
+
+  /** Public Stream F forecast-verification export. Returns the raw NDJSON
+   *  stream as a string (one cell per line + a trailing meta line). */
+  verificationExport(query?: VerificationExportQuery): Promise<string> {
+    return this.requestText("GET", `/v1/research/verification/export${toQuery(query)}`)
+  }
+
+  /** Public L15 Difficulty Atlas export. Returns the raw NDJSON stream. */
+  difficultyAtlasExport(): Promise<string> {
+    return this.requestText("GET", "/v1/research/difficulty-atlas/export.jsonl")
+  }
+
+  /** Self-service tenant signup (no auth). Always 202 on success. */
+  publicSignup(input: PublicSignupRequest): Promise<PublicSignupResponse> {
+    return this.request<PublicSignupResponse>("POST", "/v1/public/signup", input)
+  }
+
+  /** Open catalogue coverage stats (no auth). */
+  catalogStats(): Promise<CatalogStatsResponse> {
+    return this.request<CatalogStatsResponse>("GET", "/v1/public/catalog-stats")
+  }
+
+  /** Fetch the current published legal document of a kind (no auth). */
+  legalDocument(kind: LegalDocumentKind): Promise<LegalDocumentResponse> {
+    return this.request<LegalDocumentResponse>(
+      "GET",
+      `/v1/legal/${encodeURIComponent(kind)}/current`,
+    )
+  }
+
+  // ── audit / compliance ────────────────────────────────────────────────────
+  /**
+   * Export the calling tenant's own score + outcome audit history for a date
+   * range. `format: "csv"` returns the raw CSV as a `string`; the default
+   * (`"json"`) returns the parsed {@link AuditExportResponse}. Offset-paginated
+   * via `limit` / `offset`.
+   */
+  auditExport(query: AuditExportQuery & { format: "csv" }): Promise<string>
+  auditExport(query: AuditExportQuery & { format?: "json" }): Promise<AuditExportResponse>
+  auditExport(query: AuditExportQuery): Promise<AuditExportResponse | string> {
+    const path = `/v1/audit/export${toQuery(query)}`
+    if (query.format === "csv") return this.requestText("GET", path)
+    return this.request<AuditExportResponse>("GET", path)
+  }
+
+  // ── LLM BYOK (bring-your-own Anthropic key) ───────────────────────────────
+  /** Set/rotate the tenant's Anthropic API key. The server validates it with
+   *  one cheap Anthropic call, encrypts it at rest, and never echoes it back.
+   *  Resolves `void` on the 204. */
+  async setLlmKey(input: SetLlmKeyRequest): Promise<void> {
+    await this.request<void>("PUT", "/v1/tenant/llm-key", input)
+  }
+
+  /** Get the tenant's Anthropic key status (masked — never the key itself). */
+  getLlmKey(): Promise<LlmKeyStatus> {
+    return this.request<LlmKeyStatus>("GET", "/v1/tenant/llm-key")
+  }
+
+  /** Remove the tenant's Anthropic key. Resolves `void` on the 204. */
+  async deleteLlmKey(): Promise<void> {
+    await this.request<void>("DELETE", "/v1/tenant/llm-key")
+  }
+
   /** GDPR Art. 17 erasure. Surfaces the receipt headers from a 204. */
   async deleteUserData(pseudonym: string): Promise<DeleteUserDataResult> {
     const res = await this.rawRequest("DELETE", `/v1/decision/user-data/${encodeURIComponent(pseudonym)}`)
@@ -162,14 +418,47 @@ export class GoableClient {
   }
 
   // ── transport ─────────────────────────────────────────────────────────────
-  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
-    const res = await this.rawRequest(method, path, body)
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    extraHeaders?: Record<string, string>,
+  ): Promise<T> {
+    const res = await this.rawRequest(method, path, body, extraHeaders)
     const parsed = await safeJson(res)
-    if (!res.ok) throw toApiError(res.status, parsed)
+    if (!res.ok) throw toApiError(res.status, parsed, res.headers)
     return parsed as T
   }
 
-  private async rawRequest(method: string, path: string, body?: unknown): ReturnType<FetchLike> {
+  /** Like {@link request} but returns the raw response body as text — used for
+   *  the NDJSON research streams and the `format=csv` audit export, which are
+   *  not a single JSON document. */
+  private async requestText(method: string, path: string): Promise<string> {
+    const res = await this.rawRequest(method, path)
+    let text: string
+    try {
+      text = await res.text()
+    } catch (err) {
+      throw new GoableNetworkError("Failed to read response body", "parse", err)
+    }
+    if (!res.ok) {
+      let parsed: unknown = text
+      try {
+        parsed = JSON.parse(text)
+      } catch {
+        // non-JSON error body — pass the raw text through to toApiError
+      }
+      throw toApiError(res.status, parsed, res.headers)
+    }
+    return text
+  }
+
+  private async rawRequest(
+    method: string,
+    path: string,
+    body?: unknown,
+    extraHeaders?: Record<string, string>,
+  ): ReturnType<FetchLike> {
     // `X-Goable-Key` rather than `Authorization: Bearer` — the API
     // sits behind CloudFront with OAC, which hijacks the standard
     // Authorization header for its own SigV4 signature. Custom header
@@ -181,6 +470,11 @@ export class GoableClient {
       Accept: "application/json",
     }
     if (body !== undefined) headers["Content-Type"] = "application/json"
+    if (extraHeaders) {
+      for (const [k, v] of Object.entries(extraHeaders)) {
+        if (v !== undefined) headers[k] = v
+      }
+    }
 
     const controller = this.timeoutMs > 0 ? new AbortController() : undefined
     const timer = controller && this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined
@@ -205,6 +499,23 @@ export class GoableClient {
   }
 }
 
+/** Serialise a query object into a leading-`?` string (or "" when empty).
+ *  Skips undefined/null; isomorphic (URLSearchParams is a Node 18+/browser global). */
+function toQuery(params?: Record<string, unknown>): string {
+  if (!params) return ""
+  const usp = new URLSearchParams()
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null) usp.append(k, String(v))
+  }
+  const s = usp.toString()
+  return s ? `?${s}` : ""
+}
+
+/** Build the optional `Idempotency-Key` header bag from per-call options. */
+function idempotencyHeader(options?: IdempotencyOptions): Record<string, string> | undefined {
+  return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : undefined
+}
+
 async function safeJson(res: { text(): Promise<string> }): Promise<unknown> {
   let text: string
   try {

package/src/errors.ts

@@ -14,8 +14,30 @@ export interface ZodIssueLike {
   [k: string]: unknown
 }
 
+/** Rate-limit snapshot parsed from `X-RateLimit-*` response headers. Present
+ *  when the server sent them (currently the `score` + `recommend-spot`
+ *  endpoints; omitted on unlimited Scale plans). */
+export interface RateLimit {
+  /** `X-RateLimit-Limit` — daily safety cap for this endpoint + plan. */
+  limit: number
+  /** `X-RateLimit-Remaining` — requests left in the current window. */
+  remaining: number
+  /** `X-RateLimit-Reset` — Unix timestamp (seconds) when the window resets. */
+  reset: number
+}
+
+/** Structured extras attached to a {@link GoableApiError}. */
+export interface ApiErrorExtra {
+  issues?: ZodIssueLike[]
+  detail?: Record<string, unknown>
+  retryAfterSeconds?: number | null
+  rateLimit?: RateLimit
+}
+
 export class GoableApiError extends Error {
-  override readonly name = "GoableApiError"
+  // Typed `string` (not the literal) so subclasses like DriftActiveError can
+  // override it with their own name.
+  override readonly name: string = "GoableApiError"
   /** HTTP status code. */
   readonly status: number
   /** Machine-readable code from the `error` field (e.g. "PAYMENT_REQUIRED"). */
@@ -24,23 +46,47 @@ export class GoableApiError extends Error {
   readonly issues?: ZodIssueLike[]
   /** Free-form extra context (e.g. plan info, quote id). */
   readonly detail?: Record<string, unknown>
+  /** Seconds to wait before retrying, from the `Retry-After` header. Set on a
+   *  `429`; `null` when the header is absent or unparseable. Lets a caller
+   *  implement a compliant back-off (`if (err.status === 429) sleep(err.retryAfterSeconds)`). */
+  readonly retryAfterSeconds: number | null
+  /** Rate-limit snapshot from `X-RateLimit-*` headers, when the response carried them. */
+  readonly rateLimit?: RateLimit
 
-  constructor(
-    status: number,
-    code: string,
-    message?: string,
-    extra?: { issues?: ZodIssueLike[]; detail?: Record<string, unknown> },
-  ) {
+  constructor(status: number, code: string, message?: string, extra?: ApiErrorExtra) {
     super(message ?? code)
     this.status = status
     this.code = code
     if (extra?.issues) this.issues = extra.issues
     if (extra?.detail) this.detail = extra.detail
+    this.retryAfterSeconds = extra?.retryAfterSeconds ?? null
+    if (extra?.rateLimit) this.rateLimit = extra.rateLimit
     // Restore prototype chain for `instanceof` across transpilation targets.
     Object.setPrototypeOf(this, GoableApiError.prototype)
   }
 }
 
+/**
+ * Raised on a `422 DRIFT_ACTIVE` from `POST /v1/underwriting/policy/bind`:
+ * the resolved cell has an open warning/critical L9 drift event, so the bind
+ * is refused (a watch-level event is a soft `driftAdvisories` on success, not
+ * an error). Subclasses `GoableApiError`, so existing `instanceof
+ * GoableApiError` / `.code === "DRIFT_ACTIVE"` checks keep working.
+ */
+export class DriftActiveError extends GoableApiError {
+  override readonly name = "DriftActiveError"
+  /** The blocking cells, from the server's `detail.openDriftEvents`. Shape is
+   *  per-cell and best-effort (documented, not part of the typed contract). */
+  readonly openDriftEvents: Array<Record<string, unknown>>
+
+  constructor(status: number, code: string, message?: string, extra?: ApiErrorExtra) {
+    super(status, code, message, extra)
+    const raw = extra?.detail?.openDriftEvents
+    this.openDriftEvents = Array.isArray(raw) ? (raw as Array<Record<string, unknown>>) : []
+    Object.setPrototypeOf(this, DriftActiveError.prototype)
+  }
+}
+
 export class GoableNetworkError extends Error {
   override readonly name = "GoableNetworkError"
   /** "timeout" when the request was aborted by the configured timeout. */
@@ -62,14 +108,39 @@ interface RawErrorBody {
   detail?: unknown
 }
 
+/** A minimal read-only header bag (the `headers` of a fetch Response). */
+export interface HeaderBag {
+  get(name: string): string | null
+}
+
+/** Parse an integer header, returning null when absent or non-numeric. */
+function intHeader(headers: HeaderBag | undefined, name: string): number | null {
+  const v = headers?.get(name)
+  if (v == null) return null
+  const n = Number(v)
+  return Number.isFinite(n) ? n : null
+}
+
 /** Map a parsed error body + status into a GoableApiError. Tolerant of a
- *  non-conforming body (falls back to the status code as the error code). */
-export function toApiError(status: number, body: unknown): GoableApiError {
+ *  non-conforming body (falls back to the status code as the error code).
+ *  When `headers` are supplied, surfaces `Retry-After` (as `retryAfterSeconds`)
+ *  and the `X-RateLimit-*` snapshot on the resulting error. */
+export function toApiError(status: number, body: unknown, headers?: HeaderBag): GoableApiError {
   const b = (body ?? {}) as RawErrorBody
   const code = typeof b.error === "string" ? b.error : `HTTP_${status}`
   const message = typeof b.message === "string" ? b.message : undefined
-  const extra: { issues?: ZodIssueLike[]; detail?: Record<string, unknown> } = {}
+  const extra: ApiErrorExtra = {}
   if (Array.isArray(b.issues)) extra.issues = b.issues as ZodIssueLike[]
   if (b.detail && typeof b.detail === "object") extra.detail = b.detail as Record<string, unknown>
+  extra.retryAfterSeconds = intHeader(headers, "Retry-After")
+  const limit = intHeader(headers, "X-RateLimit-Limit")
+  const remaining = intHeader(headers, "X-RateLimit-Remaining")
+  const reset = intHeader(headers, "X-RateLimit-Reset")
+  if (limit !== null && remaining !== null && reset !== null) {
+    extra.rateLimit = { limit, remaining, reset }
+  }
+  // Specialise the one error the SDK models with its own class. Stays a
+  // GoableApiError subclass, so generic catch sites are unaffected.
+  if (code === "DRIFT_ACTIVE") return new DriftActiveError(status, code, message, extra)
   return new GoableApiError(status, code, message, extra)
 }