Off-Nominal/ndb2-api

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.