@usewind/node 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1035 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/errors.ts
+var WindError = class extends Error {
+  status;
+  code;
+  type;
+  connectionId;
+  requestId;
+  raw;
+  constructor(message, init = {}) {
+    super(message, init.cause !== void 0 ? { cause: init.cause } : void 0);
+    this.name = new.target.name;
+    this.status = init.status;
+    this.code = init.code;
+    this.type = init.type;
+    this.connectionId = init.connectionId ?? null;
+    this.requestId = init.requestId ?? null;
+    this.raw = init.raw;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /**
+   * Build the right subclass from an HTTP response. Matches on the envelope's
+   * `error.code` first, then falls back to `status`.
+   */
+  static fromResponse(status, body, extra = {}) {
+    const e = body?.error ?? {};
+    const message = e.message || `Wind API error (${status})`;
+    const init = {
+      status,
+      code: e.code,
+      type: e.type,
+      connectionId: e.connection_id ?? null,
+      requestId: extra.requestId ?? null,
+      raw: body
+    };
+    switch (e.code) {
+      case "allocation_exhausted":
+        return new AllocationExhaustedError(message, { ...init, increaseUrl: e.increase_url ?? null });
+      case "feature_cost_exceeded":
+        return new FeatureCostExceededError(message, init);
+      case "feature_model_not_configured":
+        return new FeatureModelNotConfiguredError(message, init);
+      case "connection_revoked":
+      case "invalid_grant":
+        return new ConnectionRevokedError(message, init);
+      case "connection_frozen":
+        return new ConnectionFrozenError(message, init);
+      case "model_not_allowed":
+        return new ModelNotAllowedError(message, init);
+      case "app_suspended":
+        return new AppSuspendedError(message, init);
+      case "rate_limited":
+      case "daily_limit_reached":
+      case "app_spend_limited":
+      case "sandbox_live_cost_limited":
+        return new RateLimitedError(message, { ...init, retryAfterMs: extra.retryAfterMs });
+      case "risk_throttled":
+        return new RiskThrottledError(message, { ...init, retryAfterMs: extra.retryAfterMs });
+      case "provider_error":
+        return new ProviderError(message, init);
+      case "token_expired":
+        return new TokenExpiredError(message, init);
+      case "idempotency_key_reused":
+        return new IdempotencyKeyReusedError(message, init);
+    }
+    switch (status) {
+      case 401:
+        return new TokenExpiredError(message, init);
+      case 402:
+        return new AllocationExhaustedError(message, init);
+      case 403:
+        return new ConnectionRevokedError(message, init);
+      case 409:
+        return new IdempotencyKeyReusedError(message, init);
+      case 429:
+        return new RateLimitedError(message, { ...init, retryAfterMs: extra.retryAfterMs });
+      case 502:
+        return new ProviderError(message, init);
+      default:
+        return new WindApiError(message, init);
+    }
+  }
+};
+var WindConfigError = class extends WindError {
+};
+var WindNotConnectedError = class extends WindError {
+};
+var WindSignatureError = class extends WindError {
+};
+var WindNotImplementedError = class extends WindError {
+  constructor(what) {
+    super(`${what} is not implemented yet (@usewind/node is a skeleton).`);
+  }
+};
+var WindApiError = class extends WindError {
+};
+var AllocationExhaustedError = class extends WindApiError {
+  increaseUrl;
+  constructor(message, init = {}) {
+    super(message, init);
+    this.increaseUrl = init.increaseUrl ?? null;
+  }
+};
+var FeatureCostExceededError = class extends WindApiError {
+};
+var FeatureModelNotConfiguredError = class extends WindApiError {
+};
+var ConnectionRevokedError = class extends WindApiError {
+};
+var ConnectionFrozenError = class extends WindApiError {
+};
+var AppSuspendedError = class extends WindApiError {
+};
+var ModelNotAllowedError = class extends WindApiError {
+};
+var RateLimitedError = class extends WindApiError {
+  retryAfterMs;
+  constructor(message, init = {}) {
+    super(message, init);
+    this.retryAfterMs = init.retryAfterMs ?? null;
+  }
+};
+var RiskThrottledError = class extends WindApiError {
+  retryAfterMs;
+  constructor(message, init = {}) {
+    super(message, init);
+    this.retryAfterMs = init.retryAfterMs ?? null;
+  }
+};
+var ProviderError = class extends WindApiError {
+};
+var TokenExpiredError = class extends WindApiError {
+};
+var IdempotencyKeyReusedError = class extends WindApiError {
+};
+
+// src/config.ts
+function memoryGrantStore() {
+  const grants = /* @__PURE__ */ new Map();
+  return {
+    get: (userId) => grants.get(userId) ?? null,
+    set: (userId, grant) => {
+      grants.set(userId, grant);
+    },
+    delete: (userId) => {
+      grants.delete(userId);
+    }
+  };
+}
+var DEFAULT_BASE_URL = "https://api.usewind.app";
+var DEFAULT_ACCOUNTS_URL = "https://accounts.usewind.app";
+function resolveConfig(partial = {}) {
+  const env = typeof process !== "undefined" ? process.env : {};
+  const clientId = partial.clientId ?? env.WIND_CLIENT_ID;
+  const clientSecret = partial.clientSecret ?? env.WIND_CLIENT_SECRET;
+  const redirectUri = partial.redirectUri ?? env.WIND_REDIRECT_URI;
+  const missing = [
+    !clientId && "clientId (WIND_CLIENT_ID)",
+    !clientSecret && "clientSecret (WIND_CLIENT_SECRET)",
+    !redirectUri && "redirectUri (WIND_REDIRECT_URI)"
+  ].filter(Boolean);
+  if (missing.length) {
+    throw new WindConfigError(
+      `@usewind/node is not configured. Missing: ${missing.join(", ")}. Call wind.configure({ \u2026 }) at boot or set the environment variables.`
+    );
+  }
+  const fetchImpl = partial.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new WindConfigError(
+      "No fetch implementation available. Use Node 18+ or pass config.fetch."
+    );
+  }
+  return {
+    clientId,
+    clientSecret,
+    redirectUri,
+    baseUrl: (partial.baseUrl ?? env.WIND_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    accountsUrl: (partial.accountsUrl ?? env.WIND_ACCOUNTS_URL ?? DEFAULT_ACCOUNTS_URL).replace(/\/$/, ""),
+    fetch: fetchImpl,
+    clock: partial.clock ?? Date.now,
+    webhookSecret: partial.webhookSecret ?? env.WIND_WEBHOOK_SECRET,
+    grantStore: partial.grantStore,
+    onConnected: partial.onConnected,
+    onGrantRotated: partial.onGrantRotated
+  };
+}
+function b64url(input) {
+  return Buffer.from(input).toString("base64url");
+}
+function pkce() {
+  const verifier = b64url(crypto.randomBytes(48));
+  const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
+  return { verifier, challenge, method: "S256" };
+}
+function stateToken() {
+  return b64url(crypto.randomBytes(24));
+}
+function basicAuth(clientId, clientSecret) {
+  return "Basic " + Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+}
+function retryAfterMs(header, now = Date.now()) {
+  if (!header) return void 0;
+  const secs = Number(header);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+  const date = Date.parse(header);
+  return Number.isFinite(date) ? Math.max(0, date - now) : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/http.ts
+var RawClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /** Low-level: perform one request, parse JSON, never throw on non-2xx (returns the response). */
+  async request(req) {
+    const url = `${this.config.baseUrl}${req.path}`;
+    const headers = { Accept: "application/json", ...req.headers };
+    if (req.bearer) headers.Authorization = `Bearer ${req.bearer}`;
+    else if (req.basic) headers.Authorization = basicAuth(this.config.clientId, this.config.clientSecret);
+    let body;
+    if (req.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(req.body);
+    }
+    const res = await this.config.fetch(url, {
+      method: req.method,
+      headers,
+      body,
+      signal: req.signal
+    });
+    const requestId = res.headers.get("x-request-id");
+    let parsed = void 0;
+    const text = await res.text();
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    return { status: res.status, headers: res.headers, body: parsed, requestId };
+  }
+  // ── OAuth ──────────────────────────────────────────────────────────────────
+  /** `POST /oauth/token` — `grant_type=authorization_code`. */
+  async exchangeCode(args) {
+    return this.postToken({
+      grant_type: "authorization_code",
+      code: args.code,
+      redirect_uri: args.redirectUri,
+      code_verifier: args.codeVerifier
+    });
+  }
+  /** `POST /oauth/token` — `grant_type=refresh_token`. */
+  async refresh(refreshToken) {
+    return this.postToken({ grant_type: "refresh_token", refresh_token: refreshToken });
+  }
+  async postToken(form) {
+    const url = `${this.config.baseUrl}/oauth/token`;
+    const res = await this.config.fetch(url, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: basicAuth(this.config.clientId, this.config.clientSecret)
+      },
+      body: new URLSearchParams(form).toString()
+    });
+    const text = await res.text();
+    const parsed = text ? JSON.parse(text) : void 0;
+    if (!res.ok) {
+      throw WindError.fromResponse(res.status, parsed, { requestId: res.headers.get("x-request-id") });
+    }
+    return parsed;
+  }
+  // ── Inference ──────────────────────────────────────────────────────────────
+  /** `POST /v1/ai/{model}`. Returns the raw response so callers can branch on status/headers. */
+  inference(args) {
+    const headers = { "Idempotency-Key": args.idempotencyKey };
+    if (args.feature) headers["X-Wind-Feature"] = args.feature;
+    return this.request({
+      method: "POST",
+      path: `/v1/ai/${encodeURIComponent(args.model)}`,
+      bearer: args.accessToken,
+      headers,
+      body: args.body,
+      signal: args.signal
+    });
+  }
+  /** `POST /v1/ai/features/{slug}`. */
+  inferenceFeature(args) {
+    return this.request({
+      method: "POST",
+      path: `/v1/ai/features/${encodeURIComponent(args.slug)}`,
+      bearer: args.accessToken,
+      headers: { "Idempotency-Key": args.idempotencyKey },
+      body: args.body,
+      signal: args.signal
+    });
+  }
+  // ── Management (client-credentials) ────────────────────────────────────────
+  async listConnections() {
+    const res = await this.request({ method: "GET", path: "/v1/connections", basic: true });
+    return this.unwrap(res);
+  }
+  async getConnection(id) {
+    const res = await this.request({ method: "GET", path: `/v1/connections/${encodeURIComponent(id)}`, basic: true });
+    return this.unwrap(res);
+  }
+  async revokeConnection(id) {
+    const res = await this.request({ method: "POST", path: `/v1/connections/${encodeURIComponent(id)}/revoke`, basic: true });
+    return this.unwrap(res);
+  }
+  async createAllocationRequest(id, body) {
+    const res = await this.request({
+      method: "POST",
+      path: `/v1/connections/${encodeURIComponent(id)}/allocation-requests`,
+      basic: true,
+      body
+    });
+    return this.unwrap(res);
+  }
+  async getAccount() {
+    const res = await this.request({ method: "GET", path: "/v1/account", basic: true });
+    return this.unwrap(res);
+  }
+  async listFeatures(appId) {
+    const res = await this.request({ method: "GET", path: `/v1/apps/${encodeURIComponent(appId)}/features`, basic: true });
+    return this.unwrap(res);
+  }
+  async registerFeature(appId, feature) {
+    const res = await this.request({
+      method: "POST",
+      path: `/v1/apps/${encodeURIComponent(appId)}/features`,
+      basic: true,
+      body: feature
+    });
+    return this.unwrap(res);
+  }
+  async updateFeature(appId, slug, patch) {
+    const res = await this.request({
+      method: "PATCH",
+      path: `/v1/apps/${encodeURIComponent(appId)}/features/${encodeURIComponent(slug)}`,
+      basic: true,
+      body: patch
+    });
+    return this.unwrap(res);
+  }
+  unwrap(res) {
+    if (res.status >= 200 && res.status < 300) return res.body;
+    throw WindError.fromResponse(res.status, res.body, { requestId: res.requestId });
+  }
+  // Convenience verbs for `wind.raw.get(...)` / `.post(...)`.
+  get(path, init) {
+    return this.request({ method: "GET", path, ...init });
+  }
+  post(path, init) {
+    return this.request({ method: "POST", path, ...init });
+  }
+};
+
+// src/tokens.ts
+var ACCESS_TOKEN_SKEW_MS = 6e4;
+var TokenManager = class {
+  constructor(config, raw) {
+    this.config = config;
+    this.raw = raw;
+  }
+  config;
+  raw;
+  /** True if the grant's cached access token is present and outside the skew window. */
+  isFresh(grant) {
+    if (!grant.accessToken || grant.accessTokenExpiresAt === void 0) return false;
+    return grant.accessTokenExpiresAt - ACCESS_TOKEN_SKEW_MS > this.config.clock();
+  }
+  /**
+   * Return a grant guaranteed to have a usable access token. If a refresh was
+   * needed, `grantStore.set(userId, next)` has already been awaited before this
+   * resolves (then `onGrantRotated` fired). Refresh failure (`invalid_grant`)
+   * throws `ConnectionRevokedError` — the caller then clears the store entry.
+   */
+  async ensureAccessToken(userId, grant) {
+    if (this.isFresh(grant)) return grant;
+    return this.forceRefresh(userId, grant);
+  }
+  /** Force a refresh regardless of cache state (used on a 401 retry). */
+  async forceRefresh(userId, grant) {
+    const grantStore = this.config.grantStore;
+    if (!grantStore) {
+      throw new WindConfigError("grantStore is required to refresh a connection but was not configured.");
+    }
+    let token;
+    try {
+      token = await this.raw.refresh(grant.refreshToken);
+    } catch (err) {
+      if (err instanceof ConnectionRevokedError) {
+        await grantStore.delete(userId);
+      }
+      throw err;
+    }
+    const next = grantFromToken(token, this.config.clock());
+    await grantStore.set(userId, next);
+    if (this.config.onGrantRotated) {
+      try {
+        await this.config.onGrantRotated(userId, next);
+      } catch {
+      }
+    }
+    return next;
+  }
+};
+function grantFromToken(token, now) {
+  return {
+    connectionId: token.connection_id,
+    refreshToken: token.refresh_token,
+    accessToken: token.access_token,
+    accessTokenExpiresAt: now + token.expires_in * 1e3
+  };
+}
+
+// src/oauth.ts
+var DEFAULT_START_PATH = "/wind/start";
+var DEFAULT_CALLBACK_PATH = "/wind/callback";
+var TRANSACTION_TTL_MS = 10 * 6e4;
+var TX_COOKIE_NAME = "__wind_tx";
+var TX_ID_COOKIE_NAME = "__wind_tx_id";
+function signTransactionCookie(tx, clientSecret) {
+  const payload = b64url(JSON.stringify(tx));
+  const sig = crypto.createHmac("sha256", clientSecret).update(payload).digest("hex");
+  return `${payload}.${sig}`;
+}
+function verifyTransactionCookie(value, clientSecret) {
+  if (!value) return null;
+  const dot = value.lastIndexOf(".");
+  if (dot < 0) return null;
+  const payload = value.slice(0, dot);
+  const providedHex = value.slice(dot + 1);
+  const expectedHex = crypto.createHmac("sha256", clientSecret).update(payload).digest("hex");
+  const provided = Buffer.from(providedHex, "hex");
+  const expected = Buffer.from(expectedHex, "hex");
+  if (provided.length !== expected.length || !crypto.timingSafeEqual(provided, expected)) return null;
+  try {
+    const json = Buffer.from(payload, "base64url").toString("utf8");
+    const tx = JSON.parse(json);
+    if (typeof tx?.verifier !== "string" || typeof tx?.state !== "string" || typeof tx?.createdAt !== "number") return null;
+    return tx;
+  } catch {
+    return null;
+  }
+}
+var OAuthFlow = class {
+  constructor(config, raw) {
+    this.config = config;
+    this.raw = raw;
+  }
+  config;
+  raw;
+  /**
+   * Build the `accounts.usewind.app/oauth/authorize` URL and the transaction to
+   * stash. The adapter persists `tx` and issues the redirect.
+   */
+  buildAuthorizeRedirect(opts) {
+    const { verifier, challenge, method } = pkce();
+    const state = stateToken();
+    const url = new URL("/oauth/authorize", this.config.accountsUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", this.config.clientId);
+    url.searchParams.set("redirect_uri", this.config.redirectUri);
+    url.searchParams.set("code_challenge", challenge);
+    url.searchParams.set("code_challenge_method", method);
+    url.searchParams.set("state", state);
+    if (opts.requestedAllocationMc !== void 0) {
+      url.searchParams.set("requested_allocation_mc", String(opts.requestedAllocationMc));
+    }
+    if (opts.features?.length) {
+      url.searchParams.set("features", opts.features.join(","));
+    }
+    return { url: url.toString(), tx: { verifier, state, createdAt: this.config.clock() } };
+  }
+  /**
+   * Given the callback query and the stashed transaction, verify `state`,
+   * exchange the `code`, and return the fresh `Grant`. Does not persist — the
+   * adapter writes it via `grantStore.set`, then fires the `onConnected` hook.
+   */
+  async completeCallback(args) {
+    const { query, tx } = args;
+    if (query.error) {
+      throw new WindConfigError(`Wind connect flow was not completed: ${query.error}`);
+    }
+    if (!tx) {
+      throw new WindConfigError("No pending Wind connect transaction found \u2014 it may have expired (10 min TTL) or the cookie was lost.");
+    }
+    if (this.config.clock() - tx.createdAt > TRANSACTION_TTL_MS) {
+      throw new WindConfigError("Wind connect transaction expired. Start the connection again.");
+    }
+    if (!query.state || query.state !== tx.state) {
+      throw new WindConfigError("state mismatch on Wind connect callback \u2014 possible CSRF, aborting.");
+    }
+    if (!query.code) {
+      throw new WindConfigError("Missing code on Wind connect callback.");
+    }
+    const token = await this.raw.exchangeCode({
+      code: query.code,
+      redirectUri: this.config.redirectUri,
+      codeVerifier: tx.verifier
+    });
+    return grantFromToken(token, this.config.clock());
+  }
+};
+var FEATURE_SLUG_RE = /^[a-z0-9-]{1,40}$/;
+var PROVIDER_ERROR_RETRIES = 2;
+var PROVIDER_ERROR_BACKOFF_MS = [250, 1e3];
+var ModelScope = class {
+  constructor(ctx, userId, model) {
+    this.ctx = ctx;
+    this.userId = userId;
+    this.model = model;
+  }
+  ctx;
+  userId;
+  model;
+  chat(params) {
+    return billedCall(
+      this.ctx,
+      this.userId,
+      params,
+      (accessToken, idempotencyKey, body, signal) => this.ctx.raw.inference({ model: this.model, accessToken, idempotencyKey, body, signal })
+    );
+  }
+  chatStream(params) {
+    return billedStream(
+      this.ctx,
+      this.userId,
+      params,
+      (accessToken, idempotencyKey, body, signal) => this.ctx.raw.inference({ model: this.model, accessToken, idempotencyKey, body, signal })
+    );
+  }
+};
+var FeatureScope = class {
+  constructor(ctx, userId, feature) {
+    this.ctx = ctx;
+    this.userId = userId;
+    this.feature = feature;
+    if (!FEATURE_SLUG_RE.test(feature)) {
+      throw new TypeError(`Invalid feature slug ${JSON.stringify(feature)} \u2014 must match ${FEATURE_SLUG_RE}`);
+    }
+  }
+  ctx;
+  userId;
+  feature;
+  chat(params) {
+    return billedCall(
+      this.ctx,
+      this.userId,
+      params,
+      (accessToken, idempotencyKey, body, signal) => this.ctx.raw.inferenceFeature({ slug: this.feature, accessToken, idempotencyKey, body, signal })
+    );
+  }
+  chatStream(params) {
+    return billedStream(
+      this.ctx,
+      this.userId,
+      params,
+      (accessToken, idempotencyKey, body, signal) => this.ctx.raw.inferenceFeature({ slug: this.feature, accessToken, idempotencyKey, body, signal })
+    );
+  }
+};
+var ConnectionScope = class {
+  constructor(ctx, userId) {
+    this.ctx = ctx;
+    this.userId = userId;
+  }
+  ctx;
+  userId;
+  /** `wind.connection(userId).model('gpt-5').chat(...)` — hits `POST /v1/ai/{model}`. */
+  model(id) {
+    return new ModelScope(this.ctx, this.userId, id);
+  }
+  /** `wind.connection(userId).feature('summarize').chat(...)` — hits `POST /v1/ai/features/{slug}`. */
+  feature(slug) {
+    return new FeatureScope(this.ctx, this.userId, slug);
+  }
+  /** `GET /v1/connections/{id}` for this user's connection. Named `.get()`, not `.connection()` — avoids `wind.connection(userId).connection()`. */
+  async get() {
+    const grant = await requireGrant(this.ctx, this.userId);
+    return this.ctx.raw.getConnection(grant.connectionId);
+  }
+  /** `POST /v1/connections/{id}/revoke`. */
+  async revoke() {
+    const grant = await requireGrant(this.ctx, this.userId);
+    const result = await this.ctx.raw.revokeConnection(grant.connectionId);
+    await this.ctx.config.grantStore?.delete(this.userId);
+    return result;
+  }
+  /** `POST /v1/connections/{id}/allocation-requests` — returns `{ approvalUrl }`. */
+  async requestIncrease(params) {
+    const grant = await requireGrant(this.ctx, this.userId);
+    return this.ctx.raw.createAllocationRequest(grant.connectionId, {
+      target_allocation_mc: params.targetAllocationMc,
+      reason: params.reason
+    });
+  }
+};
+async function requireGrant(ctx, userId) {
+  if (!ctx.config.grantStore) {
+    throw new WindNotConnectedError("grantStore is required for wind.connection(userId) but was not configured.");
+  }
+  const grant = await ctx.config.grantStore.get(userId);
+  if (!grant) {
+    throw new WindNotConnectedError(`No Wind connection found for user ${JSON.stringify(userId)}.`);
+  }
+  return grant;
+}
+function requestBody(params) {
+  return {
+    messages: params.messages,
+    ...params.max_tokens !== void 0 && { max_tokens: params.max_tokens },
+    ...params.temperature !== void 0 && { temperature: params.temperature },
+    ...params.stream !== void 0 && { stream: params.stream }
+  };
+}
+async function billedCall(ctx, userId, params, call) {
+  let grant = await requireGrant(ctx, userId);
+  grant = await ctx.tokens.ensureAccessToken(userId, grant);
+  const idempotencyKey = params.idempotencyKey ?? crypto.randomUUID();
+  const body = requestBody(params);
+  let res = await call(grant.accessToken, idempotencyKey, body, params.signal);
+  if (res.status === 401) {
+    grant = await ctx.tokens.forceRefresh(userId, grant);
+    res = await call(grant.accessToken, idempotencyKey, body, params.signal);
+    if (res.status === 401) {
+      await ctx.config.grantStore?.delete(userId);
+      throw WindError.fromResponse(res.status, res.body, { requestId: res.requestId });
+    }
+  }
+  for (let attempt = 0; res.status === 502 && attempt < PROVIDER_ERROR_RETRIES; attempt++) {
+    await sleep(PROVIDER_ERROR_BACKOFF_MS[attempt]);
+    res = await call(grant.accessToken, idempotencyKey, body, params.signal);
+  }
+  if (res.status < 200 || res.status >= 300) {
+    throw WindError.fromResponse(res.status, res.body, {
+      requestId: res.requestId,
+      retryAfterMs: retryAfterMs(res.headers.get("retry-after"))
+    });
+  }
+  return res.body;
+}
+async function* billedStream(ctx, userId, params, call) {
+  let grant = await requireGrant(ctx, userId);
+  grant = await ctx.tokens.ensureAccessToken(userId, grant);
+  const idempotencyKey = params.idempotencyKey ?? crypto.randomUUID();
+  const body = requestBody({ ...params, stream: true });
+  let res = await call(grant.accessToken, idempotencyKey, body, params.signal);
+  if (res.status === 401) {
+    grant = await ctx.tokens.forceRefresh(userId, grant);
+    res = await call(grant.accessToken, idempotencyKey, body, params.signal);
+    if (res.status === 401) {
+      await ctx.config.grantStore?.delete(userId);
+      throw WindError.fromResponse(res.status, res.body, { requestId: res.requestId });
+    }
+  }
+  if (res.status < 200 || res.status >= 300) {
+    throw WindError.fromResponse(res.status, res.body, { requestId: res.requestId });
+  }
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/event-stream")) {
+    const result = res.body;
+    yield { delta: result, wind: result.wind };
+    return;
+  }
+  yield { delta: res.body, wind: null };
+}
+var TOLERANCE_S = 300;
+var WebhookVerifier = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  /**
+   * Verify and parse. Throws `WindSignatureError` on any mismatch, malformed
+   * header, missing secret, or stale timestamp. Returns the typed event.
+   */
+  verify(input) {
+    if (!this.verifySignature(input)) {
+      throw new WindSignatureError("Wind webhook signature verification failed.");
+    }
+    const text = typeof input.payload === "string" ? input.payload : input.payload.toString("utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (cause) {
+      throw new WindSignatureError("Wind webhook payload is not valid JSON.", { cause });
+    }
+    const event = parsed;
+    if (!event || typeof event.id !== "string" || typeof event.type !== "string") {
+      throw new WindSignatureError("Wind webhook payload is missing required fields (id, type).");
+    }
+    return event;
+  }
+  /** Constant-time HMAC check only — no parsing. Implement this first. */
+  verifySignature(input, now = this.config.clock()) {
+    if (!this.config.webhookSecret) {
+      throw new WindSignatureError("webhookSecret is not configured \u2014 cannot verify Wind webhooks.");
+    }
+    const match = /^t=(\d+),v1=([0-9a-f]+)$/i.exec(input.signature?.trim() ?? "");
+    if (!match) return false;
+    const [, timestampStr, providedHex] = match;
+    const timestamp = Number(timestampStr);
+    if (!Number.isFinite(timestamp)) return false;
+    if (Math.abs(now / 1e3 - timestamp) > TOLERANCE_S) return false;
+    const payload = typeof input.payload === "string" ? Buffer.from(input.payload, "utf8") : input.payload;
+    const signedContent = Buffer.concat([Buffer.from(`${timestampStr}.`, "utf8"), payload]);
+    const expected = crypto.createHmac("sha256", this.config.webhookSecret).update(signedContent).digest();
+    let provided;
+    try {
+      provided = Buffer.from(providedHex, "hex");
+    } catch {
+      return false;
+    }
+    return provided.length === expected.length && crypto.timingSafeEqual(provided, expected);
+  }
+};
+
+// src/adapters/express.ts
+function parseCookies(header) {
+  const raw = Array.isArray(header) ? header.join("; ") : header;
+  const out = {};
+  if (!raw) return out;
+  for (const part of raw.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key) out[key] = decodeURIComponent(value);
+  }
+  return out;
+}
+function setCookie(res, name, value, opts = {}) {
+  const attrs = [`${name}=${opts.clear ? "" : encodeURIComponent(value)}`, "Path=/", "HttpOnly", "SameSite=Lax"];
+  if (process.env.NODE_ENV === "production") attrs.push("Secure");
+  attrs.push(opts.clear ? "Max-Age=0" : `Max-Age=${opts.maxAgeSeconds ?? Math.floor(TRANSACTION_TTL_MS / 1e3)}`);
+  res.setHeader("Set-Cookie", attrs.join("; "));
+}
+function getPath(req) {
+  if (req.path) return req.path;
+  const url = req.url ?? "/";
+  const q = url.indexOf("?");
+  return q >= 0 ? url.slice(0, q) : url;
+}
+function getQuery(req) {
+  if (req.query) {
+    const out = {};
+    for (const [k, v] of Object.entries(req.query)) out[k] = Array.isArray(v) ? String(v[0]) : String(v);
+    return out;
+  }
+  const url = req.url ?? "/";
+  const q = url.indexOf("?");
+  if (q < 0) return {};
+  return Object.fromEntries(new URLSearchParams(url.slice(q + 1)));
+}
+function createExpressRoutes(flow, opts) {
+  const startPath = opts.startPath ?? DEFAULT_START_PATH;
+  const callbackPath = opts.callbackPath ?? DEFAULT_CALLBACK_PATH;
+  const grantStore = opts.grantStore ?? flow.config.grantStore;
+  const onConnected = opts.onConnected ?? flow.config.onConnected;
+  const successRedirect = opts.successRedirect ?? "/?wind=connected";
+  function handleError(err, req, res) {
+    if (opts.onError) {
+      opts.onError(err, req, res);
+      return;
+    }
+    console.error("[@usewind/node] connect flow error:", err);
+    const message = err instanceof WindError ? err.message : "Wind connect flow failed.";
+    res.status(400).send(message);
+  }
+  return (req, res, next) => {
+    const path = getPath(req);
+    if (path !== startPath && path !== callbackPath) return next();
+    if ((req.method ?? "GET").toUpperCase() !== "GET") return next();
+    void (async () => {
+      try {
+        if (path === startPath) {
+          const { url, tx: tx2 } = flow.buildAuthorizeRedirect({
+            requestedAllocationMc: opts.requestedAllocationMc,
+            features: opts.features
+          });
+          if (opts.session && opts.session !== "cookie") {
+            const id = stateToken();
+            await opts.session.put(id, tx2);
+            setCookie(res, TX_ID_COOKIE_NAME, id);
+          } else {
+            setCookie(res, TX_COOKIE_NAME, signTransactionCookie(tx2, flow.config.clientSecret));
+          }
+          res.redirect(url);
+          return;
+        }
+        if (!grantStore) {
+          throw new WindConfigError("grantStore is required for wind.routes()/wind.handler() but was not configured.");
+        }
+        const userId = await opts.currentUser(req);
+        if (!userId) {
+          throw new WindConfigError("currentUser(req) returned no user \u2014 Wind is not your login; sign the user in first.");
+        }
+        const cookies = parseCookies(req.headers.cookie);
+        let tx = null;
+        if (opts.session && opts.session !== "cookie") {
+          const id = cookies[TX_ID_COOKIE_NAME];
+          tx = id ? await opts.session.take(id) : null;
+          setCookie(res, TX_ID_COOKIE_NAME, "", { clear: true });
+        } else {
+          tx = verifyTransactionCookie(cookies[TX_COOKIE_NAME], flow.config.clientSecret);
+          setCookie(res, TX_COOKIE_NAME, "", { clear: true });
+        }
+        const query = getQuery(req);
+        const grant = await flow.completeCallback({ query, tx });
+        await grantStore.set(userId, grant);
+        if (onConnected) {
+          try {
+            await onConnected(userId, grant);
+          } catch {
+          }
+        }
+        res.redirect(successRedirect);
+      } catch (err) {
+        handleError(err, req, res);
+      }
+    })();
+  };
+}
+
+// src/adapters/fetch.ts
+function parseCookies2(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key) out[key] = decodeURIComponent(value);
+  }
+  return out;
+}
+function cookieAttrs(opts = {}) {
+  const attrs = ["Path=/", "HttpOnly", "SameSite=Lax"];
+  if (process.env.NODE_ENV === "production") attrs.push("Secure");
+  attrs.push(opts.clear ? "Max-Age=0" : `Max-Age=${opts.maxAgeSeconds ?? Math.floor(TRANSACTION_TTL_MS / 1e3)}`);
+  return attrs.join("; ");
+}
+function createFetchHandler(flow, opts) {
+  const startPath = opts.startPath ?? DEFAULT_START_PATH;
+  const callbackPath = opts.callbackPath ?? DEFAULT_CALLBACK_PATH;
+  const grantStore = opts.grantStore ?? flow.config.grantStore;
+  const onConnected = opts.onConnected ?? flow.config.onConnected;
+  const successRedirect = opts.successRedirect ?? "/?wind=connected";
+  function errorResponse(err) {
+    const message = err instanceof WindError ? err.message : "Wind connect flow failed.";
+    console.error("[@usewind/node] connect flow error:", err);
+    return new Response(message, { status: 400 });
+  }
+  return async (req) => {
+    const url = new URL(req.url);
+    if (req.method !== "GET") return new Response("Not found", { status: 404 });
+    if (url.pathname !== startPath && url.pathname !== callbackPath) return new Response("Not found", { status: 404 });
+    try {
+      if (url.pathname === startPath) {
+        const { url: authorizeUrl, tx: tx2 } = flow.buildAuthorizeRedirect({
+          requestedAllocationMc: opts.requestedAllocationMc,
+          features: opts.features
+        });
+        const headers = new Headers({ Location: authorizeUrl });
+        if (opts.session && opts.session !== "cookie") {
+          const id = stateToken();
+          await opts.session.put(id, tx2);
+          headers.append("Set-Cookie", `${TX_ID_COOKIE_NAME}=${encodeURIComponent(id)}; ${cookieAttrs()}`);
+        } else {
+          const signed = signTransactionCookie(tx2, flow.config.clientSecret);
+          headers.append("Set-Cookie", `${TX_COOKIE_NAME}=${encodeURIComponent(signed)}; ${cookieAttrs()}`);
+        }
+        return new Response(null, { status: 302, headers });
+      }
+      if (!grantStore) {
+        throw new WindConfigError("grantStore is required for wind.routes()/wind.handler() but was not configured.");
+      }
+      const userId = await opts.currentUser(req);
+      if (!userId) {
+        throw new WindConfigError("currentUser(req) returned no user \u2014 Wind is not your login; sign the user in first.");
+      }
+      const cookies = parseCookies2(req.headers.get("cookie"));
+      const clearHeaders = new Headers();
+      let tx = null;
+      if (opts.session && opts.session !== "cookie") {
+        const id = cookies[TX_ID_COOKIE_NAME];
+        tx = id ? await opts.session.take(id) : null;
+        clearHeaders.append("Set-Cookie", `${TX_ID_COOKIE_NAME}=; ${cookieAttrs({ clear: true })}`);
+      } else {
+        tx = verifyTransactionCookie(cookies[TX_COOKIE_NAME], flow.config.clientSecret);
+        clearHeaders.append("Set-Cookie", `${TX_COOKIE_NAME}=; ${cookieAttrs({ clear: true })}`);
+      }
+      const query = {
+        code: url.searchParams.get("code") ?? void 0,
+        state: url.searchParams.get("state") ?? void 0,
+        error: url.searchParams.get("error") ?? void 0
+      };
+      const grant = await flow.completeCallback({ query, tx });
+      await grantStore.set(userId, grant);
+      if (onConnected) {
+        try {
+          await onConnected(userId, grant);
+        } catch {
+        }
+      }
+      clearHeaders.set("Location", successRedirect);
+      return new Response(null, { status: 302, headers: clearHeaders });
+    } catch (err) {
+      if (opts.onError) opts.onError(err, req, void 0);
+      return errorResponse(err);
+    }
+  };
+}
+
+// src/index.ts
+var Wind = class {
+  #partial;
+  #resolved = null;
+  #raw = null;
+  #flow = null;
+  #tokens = null;
+  #webhooks = null;
+  constructor(config = {}) {
+    this.#partial = config;
+  }
+  /** Set or override configuration. Call once at boot. Resets memoised internals. */
+  configure(config) {
+    this.#partial = { ...this.#partial, ...config };
+    this.#resolved = this.#raw = this.#flow = this.#tokens = this.#webhooks = null;
+    return this;
+  }
+  // ── lazily-built internals ────────────────────────────────────────────────
+  get #config() {
+    return this.#resolved ??= resolveConfig(this.#partial);
+  }
+  /** The low-level HTTP client — one method per openapi path. Escape hatch. */
+  get raw() {
+    return this.#raw ??= new RawClient(this.#config);
+  }
+  get #oauth() {
+    return this.#flow ??= new OAuthFlow(this.#config, this.raw);
+  }
+  get #tokenManager() {
+    return this.#tokens ??= new TokenManager(this.#config, this.raw);
+  }
+  get #verifier() {
+    return this.#webhooks ??= new WebhookVerifier(this.#config);
+  }
+  #scopeContext() {
+    return { config: this.#config, raw: this.raw, tokens: this.#tokenManager };
+  }
+  // ── connect flow ─────────────────────────────────────────────────────────
+  /** Express middleware owning `startPath` + `callbackPath`. */
+  routes(opts) {
+    return createExpressRoutes(this.#oauth, opts);
+  }
+  /** Web-standard `(Request) => Response` handler for the same two routes. */
+  handler(opts) {
+    return createFetchHandler(this.#oauth, opts);
+  }
+  // ── billed calls ─────────────────────────────────────────────────────────
+  /**
+   * Scope subsequent calls to one user of your app. Loads their grant via
+   * `grantStore.get`. Singular, one user's connection — distinct from the
+   * plural `wind.connections` below (client-credentials management across
+   * every connection).
+   */
+  connection(userId) {
+    return new ConnectionScope(this.#scopeContext(), userId);
+  }
+  // ── management (client-credentials) ──────────────────────────────────────
+  connections = {
+    list: () => this.raw.listConnections(),
+    get: (id) => this.raw.getConnection(id),
+    revoke: (id) => this.raw.revokeConnection(id),
+    requestIncrease: (id, p) => this.raw.createAllocationRequest(id, { target_allocation_mc: p.targetAllocationMc, reason: p.reason })
+  };
+  account() {
+    return this.raw.getAccount();
+  }
+  features = {
+    list: (appId) => this.raw.listFeatures(appId),
+    register: (appId, feature) => this.raw.registerFeature(appId, feature),
+    update: (appId, slug, patch) => this.raw.updateFeature(appId, slug, patch)
+  };
+  // ── webhooks ─────────────────────────────────────────────────────────────
+  /** Verify a webhook's `X-Wind-Signature` and return the typed event. Needs the raw body. */
+  verify(input) {
+    return this.#verifier.verify(input);
+  }
+};
+function createWind(config = {}) {
+  return new Wind(config);
+}
+var wind = new Wind();
+
+exports.AllocationExhaustedError = AllocationExhaustedError;
+exports.AppSuspendedError = AppSuspendedError;
+exports.ConnectionFrozenError = ConnectionFrozenError;
+exports.ConnectionRevokedError = ConnectionRevokedError;
+exports.ConnectionScope = ConnectionScope;
+exports.FeatureCostExceededError = FeatureCostExceededError;
+exports.FeatureModelNotConfiguredError = FeatureModelNotConfiguredError;
+exports.FeatureScope = FeatureScope;
+exports.IdempotencyKeyReusedError = IdempotencyKeyReusedError;
+exports.ModelNotAllowedError = ModelNotAllowedError;
+exports.ProviderError = ProviderError;
+exports.RateLimitedError = RateLimitedError;
+exports.RiskThrottledError = RiskThrottledError;
+exports.TokenExpiredError = TokenExpiredError;
+exports.Wind = Wind;
+exports.WindApiError = WindApiError;
+exports.WindConfigError = WindConfigError;
+exports.WindError = WindError;
+exports.WindNotConnectedError = WindNotConnectedError;
+exports.WindNotImplementedError = WindNotImplementedError;
+exports.WindSignatureError = WindSignatureError;
+exports.createWind = createWind;
+exports.memoryGrantStore = memoryGrantStore;
+exports.wind = wind;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map