@usewind/node 0.1.0

package/DESIGN.md

@@ -0,0 +1,404 @@
+# `@usewind/node` — design
+
+Server SDK for **Connect with Wind**. Wraps the OAuth (auth code + PKCE) connect
+flow and the billed inference endpoint so an integration is *one middleware mount
+plus one call*, instead of the ~120 lines in
+`apps/docs/public/skills/wind-connect/SKILL.md`.
+
+- **Contract:** `apps/docs/public/openapi.yaml` is the source of truth. Types in
+  this package are generated-by-hand from it and must track it.
+- **Trust boundary:** this package holds the `client_secret` and the rotating
+  `refresh_token`. It is server-only and has no browser build. The button ships
+  separately as `@usewind/browser`.
+- **Status:** implemented, tracking `apps/docs/public/openapi.yaml` (0.1.0).
+  Streaming (`chatStream`) is wired to the documented `Chattable` contract but
+  the gateway itself doesn't emit SSE yet (`apps/api` accepts `stream: true`
+  and returns one buffered JSON response) — `chatStream()` degrades to a
+  single terminal chunk until the server ships real streaming.
+
+---
+
+## Principles
+
+1. **Wrap, don't hide.** Every HTTP call the SDK makes is documented in
+   `rest-api.mdx`. `wind.raw` exposes the low-level client for anything the
+   ergonomic surface doesn't cover.
+2. **No datastore assumption, one persistence contract.** The app supplies a
+   `grantStore` — `{ get, set, delete }` keyed by the app's user id. That is the
+   *only* interface the SDK needs for correctness; it never writes to a DB
+   itself. `onConnected` / `onGrantRotated` are optional notifications layered on
+   top, not where persistence happens.
+3. **Rotation safety is the SDK's job.** `grantStore` is the only place refresh
+   tokens move. After a refresh the SDK calls `grantStore.set(userId, next)` and
+   **awaits it before** using the new access token — a throw aborts the call
+   rather than stranding a rotated token. From the caller's side it's one
+   `await`, new grant persisted before the billed call resumes.
+4. **Framework-agnostic core, thin adapters.** All logic works on a plain
+   `{ method, url, headers, body }` → `{ status, headers, body }` shape. Express
+   is the first adapter; Next.js route handlers and Fastify are adapters over
+   the same core.
+5. **Zero runtime dependencies.** Node 18+ `fetch`, `node:crypto`,
+   `URLSearchParams`. Nothing else.
+
+---
+
+## Package layout
+
+```
+packages/node/
+  DESIGN.md            this file
+  package.json         @usewind/node — dual ESM/CJS, tsup
+  tsconfig.json        extends ../../tsconfig.base.json
+  tsup.config.ts       esm + cjs + .d.ts from src/index.ts
+  src/
+    index.ts           public surface: `wind`, `createWind`, error classes, types
+    config.ts          resolve + validate config (explicit args → env vars); memoryGrantStore()
+    errors.ts          WindError hierarchy + fromResponse() factory
+    types.ts           TokenResponse, WindBlock, Connection, Feature, ChatParams…
+    internal.ts        b64url(), pkce(), basicAuth(), retryAfterMs(), sleep()
+    http.ts            RawClient — one method per openapi path; retry/backoff
+    oauth.ts           PKCE start + callback token exchange; framework core
+    tokens.ts          access-token cache + atomic refresh-token rotation
+    client.ts          wind.connection(userId).model(id)/.feature(slug).chat(…)  billed calls
+    webhooks.ts        wind.verify(req) — HMAC-SHA256 signature check
+    adapters/
+      express.ts       wind.routes(...) → (req, res, next)
+      fetch.ts         wind.handler(...) → (Request) => Response  (Next.js, Hono)
+  test/
+    *.test.ts          vitest — nock-free, fetch mocked
+```
+
+---
+
+## Public surface
+
+### Construction
+
+```ts
+import { wind, createWind } from '@usewind/node'
+```
+
+- **`wind`** — a lazily-configured default instance. On first use it reads
+  `WIND_CLIENT_ID`, `WIND_CLIENT_SECRET`, `WIND_REDIRECT_URI` from `process.env`.
+  Call `wind.configure({...})` once at boot to set them explicitly (wins over
+  env). One app, one instance — the common case.
+- **`createWind(config)`** — an explicit, independent instance. For tests,
+  multi-tenant servers, or anything managing more than one Wind app.
+
+```ts
+interface WindConfig {
+  clientId: string
+  clientSecret: string
+  redirectUri: string             // must exactly match a registered URI + the callback route
+  baseUrl?: string                // default 'https://api.usewind.app'
+  accountsUrl?: string            // default 'https://accounts.usewind.app'
+  webhookSecret?: string          // enables wind.verify()
+  fetch?: typeof fetch            // injectable for tests
+  clock?: () => number            // Date.now, injectable
+
+  // The one persistence contract. Required for wind.routes() / wind.handler() /
+  // wind.connection() — they throw WindConfigError without it. Not needed for
+  // client-credentials-only use (connections / account / raw).
+  grantStore?: GrantStore
+
+  // Optional notifications. NOT where persistence happens — they run after
+  // grantStore has committed, and a throw from either is caught and ignored.
+  onConnected?: (userId: string, grant: Grant) => Promise<void> | void      // first connect only
+  onGrantRotated?: (userId: string, grant: Grant) => Promise<void> | void   // every refresh
+}
+
+interface GrantStore {
+  get(userId: string): Promise<Grant | null> | Grant | null
+  set(userId: string, grant: Grant): Promise<void> | void   // first connect AND every rotation; awaited before new tokens are used
+  delete(userId: string): Promise<void> | void              // on revoke (terminal)
+}
+
+interface Grant {
+  connectionId: string            // conn_…
+  refreshToken: string            // rotates every refresh
+  accessToken?: string            // cache; optional
+  accessTokenExpiresAt?: number   // epoch ms
+}
+```
+
+Minimal in-memory `grantStore` (dev / tests) — a `Map` already satisfies the
+shape:
+
+```ts
+const grants = new Map<string, Grant>()
+wind.configure({
+  grantStore: {
+    get: (id) => grants.get(id) ?? null,
+    set: (id, g) => { grants.set(id, g) },
+    delete: (id) => { grants.delete(id) },
+  },
+})
+```
+
+### The connect routes
+
+```ts
+// Express
+app.use(wind.routes({
+  startPath:    '/wind/start',      // GET — build PKCE, redirect to accounts.usewind.app/oauth/authorize
+  callbackPath: '/wind/callback',   // GET — verify state, POST /oauth/token, grantStore.set, onConnected
+  currentUser:  (req) => req.session.userId,          // required — Wind is not your login
+  // grantStore comes from config; pass grantStore here only to override it for these routes
+  session: 'cookie',               // 'cookie' (signed, default) | custom { get, set }
+  onError:  (err, req, res) => { … },   // default: 400 + short text, log
+  successRedirect: '/settings?wind=connected',
+}))
+```
+
+- **PKCE + `state`** are generated in `startPath` and stashed. Default storage is
+  a short-lived signed cookie (`__wind_tx`, 10 min, `HttpOnly`, `SameSite=Lax`);
+  pass `session` to use a server store instead.
+- `startPath` forwards `requested_allocation_mc` and `features` if given as
+  options or query params.
+- `callbackPath` verifies `state`, exchanges the `code` (HTTP Basic), builds the
+  `Grant`, `await`s `grantStore.set(userId, grant)`, then fires the optional
+  `onConnected` hook and redirects to `successRedirect`.
+
+Framework-neutral form:
+
+```ts
+const handler = wind.handler({ …same options… })   // (Request) => Promise<Response>
+export const GET = handler                          // Next.js app/wind/[...wind]/route.ts
+```
+
+### Billed calls
+
+`.model(id)` and `.feature(slug)` are **deliberately mutually exclusive, no
+chaining** — each hits a different route with a different model-resolution
+rule, and picking one is an explicit, unambiguous choice at the call site
+rather than something that falls out of which optional field you happened to
+pass.
+
+```ts
+// model call — you pick the model. POST /v1/ai/{model}
+const res = await wind.connection(userId).model('gpt-4o').chat({ messages, max_tokens: 500 })
+
+// feature call — no model in the request. POST /v1/ai/features/{slug},
+// resolved server-side from the feature's default_model (must be registered
+// with one set, else 400 feature_model_not_configured)
+const res = await wind.connection(userId).feature('voice_coach').chat({ messages })
+```
+
+The one thing this can't express — a specific model *and* a feature tag on
+the same call (`X-Wind-Feature` on `POST /v1/ai/{model}`, still a real,
+supported combination on the wire) — drops to the escape hatch:
+`wind.raw.inference({ model, feature, ... })`. Enforcing a simpler mental
+model at the ergonomic layer doesn't cost anything at the raw layer.
+
+`wind.connection(userId)` → `ConnectionScope`
+
+| method | notes |
+|---|---|
+| `.model(id)` | returns a `ModelScope` — `.chat`/`.chatStream` hit `POST /v1/ai/{id}` |
+| `.feature(slug)` | returns a `FeatureScope` — `.chat`/`.chatStream` hit `POST /v1/ai/features/{slug}`; slug validated against `^[a-z0-9-]{1,40}$` |
+| `.get()` | `GET /v1/connections/{id}` for this user (named `.get()`, not `.connection()` — avoids `wind.connection(userId).connection()`) |
+| `.revoke()` | `POST /v1/connections/{id}/revoke` |
+| `.requestIncrease({ targetAllocationMc, reason })` | `POST …/allocation-requests` → `{ approvalUrl }` |
+
+`ModelScope` and `FeatureScope` both implement the same `Chattable` interface
+(`.chat` / `.chatStream`), and neither takes `model` in its params — it's
+bound once by whichever scope you're in:
+
+```ts
+interface ChatParams {
+  messages: ChatMessage[]
+  max_tokens?: number              // optional — resolves request→feature→app→model ceiling
+  temperature?: number
+  stream?: boolean                 // prefer .chatStream()
+  idempotencyKey?: string          // default: crypto.randomUUID(); reused on internal retry
+  signal?: AbortSignal
+}
+
+interface ChatResult {
+  id: string
+  choices: unknown[]
+  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }
+  wind: WindBlock                  // hold_amount_mc, provider_cost_mc, wind_fee_mc, dev_margin_mc, user_charge_mc, allocation_remaining_mc, feature
+}
+```
+
+**What `.chat()` does internally** (identical for `ModelScope` and `FeatureScope`, only the route differs)
+
+1. `grantStore.get(userId)` → grant. No grant → `WindNotConnectedError`.
+2. Ensure a fresh access token: if `accessToken` missing or within 60 s of
+   expiry, `POST /oauth/token grant_type=refresh_token`. On success, build the
+   rotated grant, `await grantStore.set(userId, next)` **before proceeding**
+   (a throw here aborts the call), then fire `onGrantRotated` (errors ignored).
+   Refresh `400 invalid_grant` → `await grantStore.delete(userId)` and throw
+   `ConnectionRevokedError` (terminal).
+3. `POST /v1/ai/{model}` (from `ModelScope`) or `POST /v1/ai/features/{slug}`
+   (from `FeatureScope`) with `Authorization: Bearer`, `Idempotency-Key`.
+4. `401 token_expired` → refresh once (step 2), retry once with the **same**
+   idempotency key. Second 401 → `grantStore.delete(userId)` + `ConnectionRevokedError`.
+5. `502 provider_error` → retry up to 2× with the same idempotency key and
+   exponential backoff (250 ms, 1 s). Then throw `ProviderError`.
+6. `429` → throw `RateLimitedError` with `retryAfterMs` from `Retry-After`. The
+   SDK does **not** auto-sleep; the caller decides.
+7. `400 feature_model_not_configured` (`FeatureScope` only) → throw
+   `FeatureModelNotConfiguredError` — a config bug, not runtime-retryable.
+8. `403 connection_frozen` (Wind's platform risk layer, not user revocation) →
+   throw `ConnectionFrozenError`; unlike a revoke, the grant is NOT deleted —
+   the same connection reactivates once the user reconnects.
+9. Map any other non-2xx via `WindError.fromResponse`.
+
+No fallback models, no non-cost-plus pricing (e.g. per-minute) — both deferred,
+not part of this surface.
+
+### Management (client-credentials, no user context)
+
+```ts
+wind.connections.list()                     // GET /v1/connections
+wind.connections.get(connectionId)
+wind.connections.revoke(connectionId)
+wind.connections.requestIncrease(connectionId, { targetAllocationMc, reason })
+wind.account()                              // GET /v1/account
+wind.features.list(appId)
+wind.features.register(appId, feature)
+wind.features.update(appId, slug, patch)
+```
+
+### Webhooks
+
+```ts
+const event = wind.verify(req)   // throws WindSignatureError on mismatch
+// event: { id: 'evt_…', type: 'connection.revoked' | 'allocation_request.approved' | …, data: {…} }
+```
+
+- HMAC-SHA256 over the raw body with `webhookSecret`, constant-time compare,
+  `X-Wind-Signature: t=<unix>,v1=<hex>` header, 5-minute timestamp tolerance
+  (replay guard). Requires the raw (unparsed) body — documented loudly.
+
+### Escape hatch
+
+```ts
+wind.raw.post('/v1/ai/gpt-4o', { headers, body })   // RawClient — typed per openapi path, no ergonomics
+```
+
+---
+
+## Error model  (`src/errors.ts` — implemented now)
+
+```
+WindError                       base; .status, .code, .type, .connectionId, .requestId, .raw
+├─ WindConfigError              missing/invalid config; thrown at configure/first-use
+├─ WindNotConnectedError        grantStore.get returned null for this user
+├─ WindApiError                 catch-all non-2xx not otherwise classified
+│  ├─ AllocationExhaustedError  402 allocation_exhausted     .increaseUrl
+│  ├─ FeatureCostExceededError  402 feature_cost_exceeded     (not billed)
+│  ├─ FeatureModelNotConfiguredError  400 feature_model_not_configured  (FeatureScope only, integration bug)
+│  ├─ ConnectionRevokedError    403 connection_revoked / invalid_grant  (terminal — clear the grant)
+│  ├─ ConnectionFrozenError     403 connection_frozen         (Wind's risk layer, NOT terminal — keep the grant, reactivates on reconnect)
+│  ├─ AppSuspendedError         403 app_suspended             (whole app off — stop calling, keep grants)
+│  ├─ ModelNotAllowedError      403 model_not_allowed         (integration bug)
+│  ├─ RateLimitedError          429 rate_limited / daily_limit_reached / app_spend_limited / sandbox_live_cost_limited  .retryAfterMs  (.code says which)
+│  ├─ RiskThrottledError        429 risk_throttled             .retryAfterMs  (Wind's risk layer, distinct from RateLimitedError)
+│  ├─ ProviderError             502 provider_error            (retried internally, not billed)
+│  ├─ TokenExpiredError         401 token_expired             (internal; surfaces only if refresh also fails)
+│  └─ IdempotencyKeyReusedError 409 idempotency_key_reused    (same key, different body — integration bug)
+├─ WindSignatureError           webhook HMAC mismatch / stale timestamp
+└─ WindNotImplementedError      skeleton stub marker
+```
+
+`WindError.fromResponse(status, bodyJson, { requestId })` reads the openapi
+`Error` envelope (`error.code`, `error.type`, `error.connection_id`,
+`error.increase_url`) and returns the right subclass. Codes are matched on
+`error.code` first, then `status`.
+
+---
+
+## Decisions
+
+- **Named `@usewind/node`, not `wind` or `wind-ai`.** Scope makes the
+  server/browser split legible; `wind-ai` was the retired product.
+- **Two initialization styles, not one.** `import { wind } from '@usewind/node'`
+  is a lazily-configured singleton reading `WIND_CLIENT_*` from env — the
+  common case, one app, one instance, zero config drama. `new Wind(config)` (or
+  the equivalent `createWind(config)` factory) is an explicit, independent
+  instance for tests or multi-tenant servers. Both are cheap to keep; dropping
+  either loses either the "one script tag" pitch or testability.
+- **`.connection(userId)`, not `.for(userId)`.** Renamed for domain alignment —
+  `Connection` is already the exact term used throughout the wire types
+  (`Connection`, `connection_id`, `ConnectionScope`); `.for()` was terser but
+  required knowing the convention rather than just reading the method name.
+- **`.model(id)` / `.feature(slug)` are mutually exclusive, no chaining.**
+  Each hits a different route with a different model-resolution rule
+  (`POST /v1/ai/{model}` vs `POST /v1/ai/features/{slug}`), so picking one is
+  an explicit, unambiguous choice at the call site — not something that falls
+  out of whether an optional `model` field happened to be set (the earlier
+  design's `FeatureScope.chat({ model? })` silently switched routes on
+  presence/absence of that field, a real footgun). The one thing this can't
+  express — a specific model *and* a feature tag on one call — is still a
+  supported wire combination (`X-Wind-Feature` on `POST /v1/ai/{model}`); it's
+  reachable via `wind.raw.inference({ model, feature, ... })` instead. Keeping
+  the ergonomic surface unambiguous doesn't have to cost the escape hatch
+  anything.
+- **Grant, not "tokens".** One object carries `connectionId` + `refreshToken`
+  (+ optional cached access token). The app persists and returns it whole; the
+  SDK never asks for fields piecemeal, which is how rotation bugs happen.
+- **One `grantStore`, not three callbacks.** Persistence is correctness-critical
+  precisely *because* refresh tokens rotate, so it gets a single named contract
+  (`{ get, set, delete }`) with an explicit rotation rule — `set` is awaited
+  before the new tokens are used. The earlier `loadGrant` / `onConnected` /
+  `onGrantRotated` trio blurred "retrieve", "persist", and "notify" into
+  same-shaped functions; a missed `onGrantRotated` silently broke rotation.
+- **`onConnected` / `onGrantRotated` are optional notifications**, layered over
+  `grantStore` — first-connect vs. every-refresh hooks for audit logs, emails,
+  analytics. They run *after* `grantStore` commits and their errors are caught
+  and ignored, so a broken hook can't strand a token.
+- **No auto-sleep on 429.** A server SDK sleeping inside a request handler is a
+  footgun; hand back `retryAfterMs` and let the caller / queue decide.
+- **Idempotency key is per logical `.chat()` call**, generated once, reused for
+  every internal retry of that call. Callers can pass their own for
+  cross-process dedupe.
+- **Streaming is a separate method** (`.chatStream`), not a `stream: true` branch
+  that changes the return type.
+- **Express adapter first**, `fetch`-handler second (covers Next.js / Hono /
+  Bun). Fastify plugin later if asked.
+- **`peerDependencies`: none.** Express is detected structurally, not imported.
+
+## Open questions
+
+- **Session storage default: RESOLVED — signed cookie.** PKCE transaction
+  state is write-once, ~10-minute, single-use — the risk profile is about
+  lifetime and mutability, not whether the blob happens to carry an
+  identifier (it may). Cookie (`__wind_tx`) must be `HttpOnly`, `Secure` in
+  production, `SameSite=Lax`, signed/authenticated, short-lived, and
+  size-bounded. `session: {get, set}` remains the override for apps with an
+  existing server-side session store.
+- **Grant memoization: RESOLVED — no scope-level cache.** `wind.connection(userId)`
+  is a cheap, stateless factory; every `.chat()` does its own fresh
+  `grantStore.get()` at step 1. Caching on `ConnectionScope` was tempting
+  (avoid two reads for `.get()` then `.chat()`) but unsound: a scope isn't
+  guaranteed short-lived just because it isn't global — a caller can hold
+  `conn` across multiple `await`ed calls, and a concurrent refresh (another
+  request, or another `.chat()` on the same scope) can rotate the grant
+  underneath a stale cached copy, producing a silent stale-token retry
+  instead of a loud extra read. `grantStore.get()` is typically a cheap
+  local/Redis read anyway, dwarfed by the actual `POST /v1/ai/*` call — not
+  worth the correctness risk. If a real caller later shows `grantStore.get()`
+  is expensive, cache it *inside* a single `.chat()` invocation (fetched once
+  at entry, reused through its own internal retries), never on the scope
+  object.
+- **`MapGrantStore` / `memoryGrantStore()` helper: RESOLVED — ship it.** Named
+  export, clearly labeled dev-only (name says "memory", JSDoc warns it
+  doesn't survive restarts / isn't safe for multi-instance prod) — people
+  will copy an unlabeled snippet to prod otherwise, so an officially-named,
+  documented-as-dev-only export is safer than not shipping one.
+- **`grantStore.delete` on `403 connection_revoked`: RESOLVED — SDK deletes.**
+  A revoked grant is genuinely dead and can never be refreshed; leaving it
+  invites a retry loop that always 403s. Consistent with how refresh
+  `invalid_grant` is already handled (step 2 of `.chat()`).
+- **`allocation_mc` on `Grant`: RESOLVED — keep credential-only.** `Grant`
+  staying single-purpose (credential + rotation) is why it's one object
+  instead of three callbacks; folding in dynamic state like allocation
+  reopens the same "piecemeal fields go stale" problem. Read allocation via
+  `.connection()` / `.get()` instead.
+- **Retry budget / circuit-breaker config: RESOLVED — stay hard-coded.** No
+  config surface until a real caller needs one; matches the "wrap, don't
+  hide" posture and the already-deferred fallback-model / non-cost-plus
+  pricing scope.

package/README.md

@@ -0,0 +1,65 @@
+# @usewind/node — the server SDK
+
+Publishes as **`@usewind/node`**. Server-only — it handles the `client_secret`
+and the rotating `refresh_token`, which must never reach a browser. The connect
+button ships separately as `@usewind/browser`.
+
+Status: **implemented**, tracking `apps/docs/public/openapi.yaml`. See
+**[DESIGN.md](./DESIGN.md)** for the full API surface, module map, error
+mapping, and design decisions.
+
+Not a port. The retired `ai-wallet/packages/sdk-node` (`wind-ai`) targeted the
+previous product (`sk_live_` keys, `windUserId` in the body, `/v1/ai/:featureId`).
+
+## Shape
+
+```js
+import { wind } from '@usewind/node'
+
+// 0. one persistence contract — { get, set, delete } keyed by your user id.
+//    `set` is called on first connect AND every refresh-token rotation, and is
+//    awaited before the new tokens are used. Back it with your database.
+wind.configure({
+  grantStore: {
+    get:    (userId) => db.users.getWindGrant(userId),
+    set:    (userId, grant) => db.users.setWindGrant(userId, grant),
+    delete: (userId) => db.users.clearWindGrant(userId),
+  },
+})
+
+// 1. the connect routes (Express; wind.handler(...) for Next.js / fetch)
+app.use(wind.routes({
+  currentUser: (req) => req.session.userId,
+  onConnected: (userId) => analytics.track(userId, 'wind_connected'), // optional hook, not persistence
+}))
+
+// 2. a billed call — refresh-and-retry, idempotency key, feature header handled inside
+const res = await wind.connection(userId).model('gpt-4o').chat({
+  messages,
+  max_tokens: 500,
+})
+// res.wind.{ user_charge_mc, allocation_remaining_mc, ... }
+
+// or, to bill against a registered feature's server-resolved default_model:
+const res2 = await wind.connection(userId).feature('chat').chat({ messages })
+
+// 3. webhooks
+const event = wind.verify({ payload: rawBody, signature: req.headers['x-wind-signature'] })
+```
+
+Credentials come from `wind.configure({ … })` or the env vars `WIND_CLIENT_ID`,
+`WIND_CLIENT_SECRET`, `WIND_REDIRECT_URI`. `grantStore` is required for
+`wind.routes()` / `wind.connection()`; without it those throw `WindConfigError`.
+Use `createWind({ … })` for an explicit instance (tests, multi-tenant), or
+`memoryGrantStore()` from this package for a dev-only in-memory `grantStore`.
+
+## Build
+
+```
+pnpm --filter @usewind/node build      # tsup → dist/ (esm + cjs + .d.ts)
+pnpm --filter @usewind/node typecheck
+pnpm --filter @usewind/node test
+```
+
+Contract source of truth: `apps/docs/public/openapi.yaml`. The raw HTTP flow the
+SDK wraps: `apps/docs/public/skills/wind-connect/SKILL.md`.