ndb2-api

name	ndb2-api
description	Describes how mission-control integrates with the Off-Nominal NDB2 HTTP API and webhooks: V2 (preferred) vs legacy V1 paths, shared client, error shapes, and webhook routes. Use when adding or changing NDB2 calls, webhooks, predictions, bets, votes, scores, or migrating from V1 to V2.

NDB2 API (mission-control)

NDB2 is the predictions backend. This repo calls it over HTTP and receives webhooks. Prefer V2 for new work; V1 remains for endpoints not yet moved.

Configuration

• mcconfig.ndb2.baseUrl — API origin (NDB2_API_BASEURL).
• mcconfig.ndb2.clientId — Bearer token for API and webhook auth (NDB2_CLIENT_ID).

All outbound calls use Authorization: Bearer <clientId>.

Types package

Shared contracts live in @offnominal/ndb2-api-types (see package.json version).

• V2: import from @offnominal/ndb2-api-types/v2 (e.g. Entities, Endpoints, Webhooks, Utils).
• V1: local types in src/providers/ndb2-client/types.ts under namespace NDB2API (and enums like PredictionLifeCycle).

HTTP client

src/providers/ndb2-client/index.ts — class Ndb2Client, default export ndb2Client (constructed with mcconfig.ndb2.clientId, initialize() loads seasons from V2).

Path convention: new URL(baseURL) then url.pathname = "api/v2/..." or "api/..." (V1).

V2 endpoints (use these when available)

Method	Path	Client method	Notes
GET	api/v2/seasons	getSeasons()	Cached on client after initialize()
GET	api/v2/predictions/:id	getPrediction(id)	Returns data only
POST	api/v2/predictions	addPrediction(body)	Body type: Endpoints.Predictions.POST_Predictions.Body
PATCH	api/v2/predictions/:id/retire	retirePrediction(id, discord_id)	V2 retire

Successful V2 JSON responses are unwrapped to res.data.data in the client. Errors use handleError: response shape { success, errors: [{ code, message }], data }; thrown value is a [userMessage, detailMessage] tuple (same pattern as other providers).

V1 endpoints (legacy; still in use)

Paths are under api/... (no v2). These methods use handleError_v1, which expects NDB2API.GeneralResponse: { success, errorCode, message, data }.

Still routed through Ndb2Client today:

• POST api/predictions/:id/bets — addBet
• POST api/predictions/:id/votes — addVote
• POST api/predictions/:id/snooze_checks/:snoozeCheckId — addSnoozeVote
• POST api/predictions/:id/trigger — triggerPrediction
• GET api/users/discord_id/:discord_id/scores — getScores
• GET api/predictions/search — searchPredictions (SearchOptions, SortByOption)
• GET api/scores (with view=points|predictions|bets, optional season) — leaderboard helpers
• PATCH api/predictions/:id/snooze — snoozePrediction

When migrating a call from V1 to V2, switch the path, response unwrapping (data vs full body), error handler (handleError vs handleError_v1), and types to the V2 package.

Example: creating a prediction (V2)

Service pattern: src/services/ndb2/add-prediction/index.ts builds NDB2API.Endpoints.Predictions.POST_Predictions.Body with discord_id, text, date (ISO string), driver ("date" | "event"), then ndb2Client.addPrediction(body).

Webhooks

Router: src/services/ndb2/webhooks/index.ts.

• Auth: validateWebhookAuthorization — Authorization: Bearer must match mcconfig.ndb2.clientId.
• V1 route: POST .../ndb2 — body must pass isNdb2WebhookEvent (src/services/ndb2/webhooks/v1/types.ts). Several event names are short-circuited as ignored before handleV1Webhook (see router): e.g. new_prediction, untriggered_prediction, unjudged_prediction, retired_prediction on this path.
• V2 route: POST .../ndb2/v2 — validate payload with API.Webhooks.isWebhookPayloadV2 from @offnominal/ndb2-api-types/v2. Handler: src/services/ndb2/webhooks/v2/index.ts (e.g. untriggered_prediction, unjudged_prediction, retired_prediction).

Middleware responds early with JSON "thank u"; do not assume the handler must send the HTTP response.

Where to look in the tree

• Client + V1/V2 split: src/providers/ndb2-client/
• Webhooks: src/services/ndb2/webhooks/ (v1/, v2/, middleware.ts)
• Feature services: src/services/ndb2/ (e.g. add-prediction, retire-prediction)

When the OpenAPI or ndb2-api-types package changes, update call sites and this skill if behavior or paths shift.