@hello-bill/node 1.0.0 → 1.0.1

package/dist/index.mjs

@@ -0,0 +1,1164 @@
+import { randomUUID, createHmac, timingSafeEqual } from 'crypto';
+
+// src/types/session.ts
+
+// src/types/errors.ts
+var RETRYABLE_HTTP_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+
+// src/core/retry.ts
+var NetworkError = class extends Error {
+  constructor(message, cause, kind = "network") {
+    super(message);
+    this.cause = cause;
+    this.kind = kind;
+    this.name = "NetworkError";
+  }
+};
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function parseRetryAfter(value) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  return null;
+}
+function backoff(attempt, base, cap, random) {
+  const exp = Math.min(cap, base * 2 ** attempt);
+  return Math.floor(random() * exp);
+}
+async function readErrorCode(res) {
+  try {
+    const clone = res.clone();
+    const body = await clone.json();
+    return body?.error?.code;
+  } catch {
+    return void 0;
+  }
+}
+async function retryFetch(input, init, opts = {}) {
+  const {
+    maxAttempts = 5,
+    baseDelayMs = 1e3,
+    maxDelayMs = 16e3,
+    fetch: fetchImpl = globalThis.fetch,
+    sleep = defaultSleep,
+    random = Math.random,
+    onTokenExpired,
+    timeoutMs = 3e4
+  } = opts;
+  let tokenRefreshed = false;
+  let lastResponse;
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    let res;
+    try {
+      res = await fetchWithTimeout(fetchImpl, input, init, timeoutMs);
+    } catch (err) {
+      lastError = err;
+      if (attempt === maxAttempts - 1) {
+        if (err instanceof NetworkError) throw err;
+        throw new NetworkError(
+          "upstream request failed",
+          err,
+          isAbortLike(err) ? "timeout" : "network"
+        );
+      }
+      const delay2 = backoff(attempt, baseDelayMs, maxDelayMs, random);
+      await sleep(delay2);
+      continue;
+    }
+    lastResponse = res;
+    if (res.ok) return res;
+    if (!tokenRefreshed && onTokenExpired && res.status === 401) {
+      const code = await readErrorCode(res);
+      if (code === "auth.token_expired") {
+        tokenRefreshed = true;
+        await onTokenExpired();
+        continue;
+      }
+    }
+    if (!RETRYABLE_HTTP_STATUSES.has(res.status)) return res;
+    if (attempt === maxAttempts - 1) return res;
+    const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
+    const delay = retryAfterMs ?? backoff(attempt, baseDelayMs, maxDelayMs, random);
+    await sleep(delay);
+  }
+  if (lastResponse) return lastResponse;
+  throw new NetworkError("upstream request failed", lastError);
+}
+function isAbortLike(err) {
+  if (!err || typeof err !== "object") return false;
+  const name = err.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
+async function fetchWithTimeout(fetchImpl, input, init, timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return fetchImpl(input, init);
+  }
+  const controller = new AbortController();
+  const userSignal = init.signal;
+  if (userSignal) {
+    if (userSignal.aborted) controller.abort(userSignal.reason);
+    else userSignal.addEventListener("abort", () => controller.abort(userSignal.reason), { once: true });
+  }
+  const timer = setTimeout(() => controller.abort(new Error("upstream timeout")), timeoutMs);
+  try {
+    return await fetchImpl(input, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (controller.signal.aborted && !userSignal?.aborted) {
+      throw new NetworkError(`upstream request timed out after ${timeoutMs}ms`, err, "timeout");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/core/client.ts
+function buildQueryString(query) {
+  if (!query) return "";
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v === void 0) continue;
+    if (Array.isArray(v)) {
+      for (const item of v) sp.append(k, item);
+    } else {
+      sp.append(k, v);
+    }
+  }
+  const qs = sp.toString();
+  return qs ? `?${qs}` : "";
+}
+async function callUpstream(apiBaseUrl, tokenManager, opts, fetchImpl) {
+  const base = apiBaseUrl.replace(/\/$/, "");
+  const url = `${base}${opts.path}${buildQueryString(opts.query)}`;
+  const token = await tokenManager.getAccessToken();
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/json"
+  };
+  if (opts.body !== void 0) headers["Content-Type"] = "application/json";
+  if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+  const init = {
+    method: opts.method,
+    headers
+  };
+  if (opts.body !== void 0) init.body = JSON.stringify(opts.body);
+  const res = await retryFetch(url, init, {
+    fetch: fetchImpl,
+    timeoutMs: opts.timeoutMs,
+    onTokenExpired: async () => {
+      await tokenManager.invalidate();
+      const fresh = await tokenManager.getAccessToken();
+      headers.Authorization = `Bearer ${fresh}`;
+    }
+  });
+  let body = null;
+  const text = await res.text();
+  if (text.length > 0) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  }
+  return {
+    status: res.status,
+    headers: res.headers,
+    body,
+    requestId: res.headers.get("x-hellobill-request-id") ?? void 0
+  };
+}
+function defaultIdempotencyKey() {
+  return randomUUID();
+}
+
+// src/core/errors.ts
+var HellobillApiError = class extends Error {
+  status;
+  envelope;
+  requestId;
+  headers;
+  constructor(status, envelope, requestId, headers) {
+    super(envelope?.error.message ?? `HelloBill API error (${status})`);
+    this.name = "HellobillApiError";
+    this.status = status;
+    this.envelope = envelope;
+    this.requestId = requestId;
+    this.headers = headers;
+  }
+  get code() {
+    return this.envelope?.error.code;
+  }
+};
+
+// src/core/token-manager.ts
+var InMemoryTokenStorage = class {
+  map = /* @__PURE__ */ new Map();
+  async get(clientId) {
+    return this.map.get(clientId) ?? null;
+  }
+  async set(clientId, value) {
+    this.map.set(clientId, value);
+  }
+};
+var TokenManager = class {
+  clientId;
+  clientSecret;
+  apiBaseUrl;
+  fetchImpl;
+  storage;
+  logger;
+  refreshLeewayMs;
+  now;
+  inflight = null;
+  constructor(opts) {
+    this.clientId = opts.clientId;
+    this.clientSecret = opts.clientSecret;
+    this.apiBaseUrl = opts.apiBaseUrl.replace(/\/$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.storage = opts.storage ?? new InMemoryTokenStorage();
+    this.logger = opts.logger;
+    this.refreshLeewayMs = opts.refreshLeewayMs ?? 3e4;
+    this.now = opts.now ?? Date.now;
+  }
+  /** Returns a valid bearer token, refreshing if necessary. Single-flight on refresh. */
+  async getAccessToken() {
+    if (this.inflight) return this.inflight;
+    const cached = await this.storage.get(this.clientId);
+    if (cached && cached.accessToken && cached.expiresAt - this.refreshLeewayMs > this.now()) {
+      return cached.accessToken;
+    }
+    if (this.inflight) return this.inflight;
+    this.inflight = this.fetchToken().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+  /** Forces invalidation of the cached token. Next `getAccessToken` will refresh. */
+  async invalidate() {
+    await this.storage.set(this.clientId, { accessToken: "", expiresAt: 0 });
+  }
+  async fetchToken() {
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: this.clientId,
+      client_secret: this.clientSecret
+    });
+    const res = await this.fetchImpl(`${this.apiBaseUrl}/auth/partner/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    if (!res.ok) {
+      let envelope = null;
+      try {
+        envelope = await res.json();
+      } catch {
+      }
+      const requestId = res.headers.get("x-hellobill-request-id") ?? void 0;
+      this.logger?.error("hellobill.token_refresh_failed", { status: res.status });
+      throw new HellobillApiError(res.status, envelope, requestId, res.headers);
+    }
+    const json = await res.json();
+    const expiresAt = this.now() + json.expires_in * 1e3;
+    await this.storage.set(this.clientId, {
+      accessToken: json.access_token,
+      expiresAt
+    });
+    this.logger?.debug("hellobill.token_refreshed", { expires_in: json.expires_in });
+    return json.access_token;
+  }
+};
+var WebhookVerificationError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "WebhookVerificationError";
+  }
+};
+function parseHeader(signatureHeader) {
+  if (!signatureHeader || typeof signatureHeader !== "string") {
+    throw new WebhookVerificationError(
+      "Missing signature header",
+      "signature.missing_header"
+    );
+  }
+  const parts = signatureHeader.split(",").map((p) => p.trim()).filter(Boolean);
+  let t;
+  const signatures = {};
+  for (const part of parts) {
+    const eq = part.indexOf("=");
+    if (eq === -1) {
+      throw new WebhookVerificationError(
+        "Malformed signature header element",
+        "signature.malformed"
+      );
+    }
+    const key = part.slice(0, eq);
+    const value = part.slice(eq + 1);
+    if (key === "t") {
+      t = Number(value);
+      if (!Number.isFinite(t)) {
+        throw new WebhookVerificationError(
+          "Malformed timestamp in signature header",
+          "signature.malformed"
+        );
+      }
+    } else if (key.length > 0 && value.length > 0) {
+      signatures[key] = value;
+    }
+  }
+  if (t === void 0) {
+    throw new WebhookVerificationError(
+      "Missing timestamp in signature header",
+      "signature.malformed"
+    );
+  }
+  if (Object.keys(signatures).length === 0) {
+    throw new WebhookVerificationError(
+      "No signature values in header",
+      "signature.malformed"
+    );
+  }
+  return { t, signatures };
+}
+function computeHmacHex(secret, payload) {
+  return createHmac("sha256", secret).update(payload).digest("hex");
+}
+function constantTimeHexEqual(a, b) {
+  if (a.length !== b.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+  } catch {
+    return false;
+  }
+}
+function verifyWebhook(rawBody, signatureHeader, secret, opts = {}) {
+  const tolerance = opts.tolerance ?? 300;
+  const supportedVersions = opts.supportedVersions ?? ["v1"];
+  const now = opts.now ?? Date.now;
+  const { t, signatures } = parseHeader(signatureHeader);
+  const nowSeconds = Math.floor(now() / 1e3);
+  const skew = Math.abs(nowSeconds - t);
+  if (skew > tolerance) {
+    throw new WebhookVerificationError(
+      `Signature timestamp outside tolerance (${skew}s > ${tolerance}s)`,
+      "signature.expired"
+    );
+  }
+  const hasAnyKnownVersion = supportedVersions.some((v) => v in signatures);
+  if (!hasAnyKnownVersion) {
+    throw new WebhookVerificationError(
+      "No supported signature version present in header",
+      "signature.unsupported_version"
+    );
+  }
+  const bodyStr = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+  const signingInput = `${t}.${bodyStr}`;
+  for (const version of supportedVersions) {
+    const provided = signatures[version];
+    if (!provided) continue;
+    const expected = computeHmacHex(secret, signingInput);
+    if (constantTimeHexEqual(expected, provided)) {
+      try {
+        return JSON.parse(bodyStr);
+      } catch {
+        throw new WebhookVerificationError(
+          "Verified payload is not valid JSON",
+          "signature.malformed"
+        );
+      }
+    }
+  }
+  throw new WebhookVerificationError(
+    "Signature does not match expected value",
+    "signature.invalid"
+  );
+}
+function verifyWebhookSignature(rawBody, signatureHeader, secret, opts = {}) {
+  const tolerance = opts.tolerance ?? 300;
+  const supportedVersions = opts.supportedVersions ?? ["v1"];
+  const now = opts.now ?? Date.now;
+  let parsed;
+  try {
+    parsed = parseHeader(signatureHeader);
+  } catch (err) {
+    if (err instanceof WebhookVerificationError) return false;
+    throw err;
+  }
+  const { t, signatures } = parsed;
+  const nowSeconds = Math.floor(now() / 1e3);
+  const skew = Math.abs(nowSeconds - t);
+  if (skew > tolerance) return false;
+  const hasAnyKnownVersion = supportedVersions.some((v) => v in signatures);
+  if (!hasAnyKnownVersion) return false;
+  const bodyStr = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+  const signingInput = `${t}.${bodyStr}`;
+  for (const version of supportedVersions) {
+    const provided = signatures[version];
+    if (!provided) continue;
+    const expected = computeHmacHex(secret, signingInput);
+    if (constantTimeHexEqual(expected, provided)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/webhook/dedupe-store.ts
+var InMemoryWebhookDedupeStore = class {
+  // Optional test injection. Defaults to Date.now.
+  constructor(now = () => Date.now()) {
+    this.now = now;
+  }
+  store = /* @__PURE__ */ new Map();
+  async has(id) {
+    const expiresAt = this.store.get(id);
+    if (expiresAt === void 0) return false;
+    if (expiresAt <= this.now()) {
+      this.store.delete(id);
+      return false;
+    }
+    return true;
+  }
+  async record(id, ttlSeconds) {
+    this.store.set(id, this.now() + ttlSeconds * 1e3);
+  }
+};
+
+// src/webhook/handler.ts
+function assertNever(x) {
+  throw new Error(`Unhandled webhook variant: ${JSON.stringify(x)}`);
+}
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+function withInfoFallback(logger) {
+  return {
+    debug: logger?.debug?.bind(logger) ?? (() => {
+    }),
+    info: logger?.info?.bind(logger) ?? (() => {
+    }),
+    warn: logger?.warn?.bind(logger) ?? (() => {
+    }),
+    error: logger?.error?.bind(logger) ?? (() => {
+    })
+  };
+}
+function headerValue(headers, name) {
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === lower) return Array.isArray(v) ? v[0] : v;
+  }
+  return void 0;
+}
+async function dispatch(event, ctx, handlers) {
+  const logUnhandled = (name) => {
+    ctx.logger.info("hellobill.webhook.unhandled_variant", {
+      event_id: event.id,
+      event_type: event.type,
+      handler: name
+    });
+  };
+  switch (event.type) {
+    case "session.embed_opened":
+      if (handlers.onSessionEmbedOpened) await handlers.onSessionEmbedOpened(event, ctx);
+      else logUnhandled("onSessionEmbedOpened");
+      return;
+    case "session.details_confirmed":
+      if (handlers.onSessionDetailsConfirmed) await handlers.onSessionDetailsConfirmed(event, ctx);
+      else logUnhandled("onSessionDetailsConfirmed");
+      return;
+    case "session.products_selected":
+      if (handlers.onSessionProductsSelected) await handlers.onSessionProductsSelected(event, ctx);
+      else logUnhandled("onSessionProductsSelected");
+      return;
+    case "session.loa_signed":
+      if (handlers.onSessionLoaSigned) await handlers.onSessionLoaSigned(event, ctx);
+      else logUnhandled("onSessionLoaSigned");
+      return;
+    case "session.account_created":
+      if (handlers.onSessionAccountCreated) await handlers.onSessionAccountCreated(event, ctx);
+      else logUnhandled("onSessionAccountCreated");
+      return;
+    case "session.app_installed":
+      if (handlers.onSessionAppInstalled) await handlers.onSessionAppInstalled(event, ctx);
+      else logUnhandled("onSessionAppInstalled");
+      return;
+    case "session.app_deferred":
+      if (handlers.onSessionAppDeferred) await handlers.onSessionAppDeferred(event, ctx);
+      else logUnhandled("onSessionAppDeferred");
+      return;
+    case "subscription.changed":
+      if (handlers.onSubscriptionChanged) await handlers.onSubscriptionChanged(event, ctx);
+      else logUnhandled("onSubscriptionChanged");
+      return;
+    case "setup_status.changed":
+      if (handlers.onSetupStatusChanged) await handlers.onSetupStatusChanged(event, ctx);
+      else logUnhandled("onSetupStatusChanged");
+      return;
+    case "move_out_notification.sent":
+      if (handlers.onMoveOutNotificationSent) await handlers.onMoveOutNotificationSent(event, ctx);
+      else logUnhandled("onMoveOutNotificationSent");
+      return;
+    case "move_out_notification.failed":
+      if (handlers.onMoveOutNotificationFailed) await handlers.onMoveOutNotificationFailed(event, ctx);
+      else logUnhandled("onMoveOutNotificationFailed");
+      return;
+    case "bank_details.collected":
+      if (handlers.onBankDetailsCollected) await handlers.onBankDetailsCollected(event, ctx);
+      else logUnhandled("onBankDetailsCollected");
+      return;
+    default:
+      return assertNever(event);
+  }
+}
+function createWebhookHandler(opts) {
+  if (opts.webhookSecret == null || opts.webhookSecret === "") {
+    throw new Error(
+      'HELLOBILL_WEBHOOK_SECRET must be set; see spec \xA713.2 and the @hello-bill/node README "Webhook receiver" section.'
+    );
+  }
+  const now = opts.now ?? (() => Date.now());
+  const dedupeStore = opts.dedupeStore ?? new InMemoryWebhookDedupeStore(now);
+  const dedupeTtlSeconds = opts.dedupeTtlSeconds ?? 86400;
+  const tolerance = opts.tolerance ?? 300;
+  const supportedVersions = opts.supportedVersions ?? ["v1"];
+  const handlers = opts.handlers ?? {};
+  const safeLogger = withInfoFallback(opts.logger ?? noopLogger);
+  return async (req, res) => {
+    const rawBody = req.rawBody;
+    if (!rawBody) {
+      safeLogger.error("hellobill.webhook.missing_raw_body", {});
+      res.status(500).json({
+        error: {
+          type: "api_error",
+          code: "server.internal",
+          message: "Webhook receiver requires raw body \u2014 adapter not wired correctly"
+        }
+      });
+      return;
+    }
+    const sigHeader = headerValue(req.headers, "x-hellobill-signature");
+    if (!sigHeader) {
+      res.status(401).json({ error: "invalid_signature" });
+      return;
+    }
+    const valid = verifyWebhookSignature(rawBody, sigHeader, opts.webhookSecret, {
+      tolerance,
+      supportedVersions,
+      now
+    });
+    if (!valid) {
+      res.status(401).json({ error: "invalid_signature" });
+      return;
+    }
+    let event;
+    try {
+      event = JSON.parse(rawBody.toString("utf8"));
+    } catch {
+      res.status(400).json({ error: "invalid_payload" });
+      return;
+    }
+    const seen = await dedupeStore.has(event.id);
+    if (seen) {
+      safeLogger.info("hellobill.webhook.dedup_hit", { event_id: event.id, event_type: event.type });
+      res.status(200).json({ received: true, deduped: true });
+      return;
+    }
+    await dedupeStore.record(event.id, dedupeTtlSeconds);
+    const deprecation = headerValue(req.headers, "x-hellobill-deprecation") ?? null;
+    if (deprecation) {
+      safeLogger.warn("hellobill.webhook.deprecation_notice", {
+        deprecation,
+        event_id: event.id,
+        event_type: event.type
+      });
+    }
+    res.status(200).json({ received: true });
+    const ctx = {
+      // safeLogger guarantees `info` is defined regardless of partner Logger shape.
+      logger: safeLogger,
+      headers: req.headers,
+      deprecation
+    };
+    void dispatch(event, ctx, handlers).catch((err) => {
+      safeLogger.error("hellobill.webhook.handler_error", {
+        event_id: event.id,
+        event_type: event.type,
+        message: err.message
+      });
+    });
+  };
+}
+
+// src/core/handler.ts
+function decodeSessionToken(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) {
+    throw new SessionTokenError("auth.token_malformed", "Session token is malformed");
+  }
+  let payload;
+  try {
+    const raw = Buffer.from(parts[1], "base64url").toString("utf8");
+    payload = JSON.parse(raw);
+  } catch {
+    throw new SessionTokenError("auth.token_malformed", "Session token payload unparseable");
+  }
+  const sessionId = typeof payload.session_id === "string" && payload.session_id.length > 0 ? payload.session_id : typeof payload.sub === "string" && payload.sub.length > 0 ? payload.sub : "";
+  if (sessionId === "") {
+    throw new SessionTokenError("auth.token_malformed", "Session token missing session_id (or sub)");
+  }
+  payload.session_id = sessionId;
+  return payload;
+}
+var SessionTokenError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+function getHeader(req, name) {
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (k.toLowerCase() === lower) {
+      return Array.isArray(v) ? v[0] : v;
+    }
+  }
+  return void 0;
+}
+function extractBearer(req) {
+  const auth = getHeader(req, "authorization");
+  if (!auth) return void 0;
+  const match = /^Bearer\s+(.+)$/i.exec(auth);
+  return match?.[1]?.trim();
+}
+function sendError(res, status, code, message, requestId) {
+  if (requestId) res.header("X-HelloBill-Request-Id", requestId);
+  const type = status === 401 || status === 403 ? "authentication_error" : status === 429 ? "rate_limit_error" : status >= 500 ? "api_error" : "validation_error";
+  res.status(status).json({
+    error: {
+      type,
+      code,
+      message,
+      request_id: requestId ?? ""
+    }
+  });
+}
+var PASSTHROUGH_HEADER_MAP = {
+  "retry-after": "Retry-After",
+  "x-ratelimit-limit": "X-RateLimit-Limit",
+  "x-ratelimit-remaining": "X-RateLimit-Remaining",
+  "x-ratelimit-reset": "X-RateLimit-Reset"
+};
+function passthroughUpstream(res, status, body, requestId, upstreamHeaders) {
+  if (requestId) res.header("X-HelloBill-Request-Id", requestId);
+  if (upstreamHeaders) {
+    for (const [lower, emit] of Object.entries(PASSTHROUGH_HEADER_MAP)) {
+      const v = upstreamHeaders.get(lower);
+      if (v !== null && v !== void 0 && v !== "") {
+        res.header(emit, v);
+      }
+    }
+  }
+  res.status(status).json(body);
+}
+function ensureSessionContext(req, res) {
+  const token = extractBearer(req);
+  if (!token) {
+    sendError(res, 401, "auth.token_malformed", "Missing Authorization bearer token");
+    return null;
+  }
+  try {
+    const claims = decodeSessionToken(token);
+    return { sessionId: claims.session_id };
+  } catch (err) {
+    const e = err;
+    sendError(res, 401, e.code ?? "auth.token_malformed", e.message ?? "Invalid session token");
+    return null;
+  }
+}
+function inboundIdempotencyKey(req) {
+  const v = getHeader(req, "idempotency-key");
+  return v && v.trim().length > 0 ? v.trim() : void 0;
+}
+function createHellobillHandler(opts) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const tokenStorage = opts.tokenStorage ?? new InMemoryTokenStorage();
+  const idempotencyKeyFactory = opts.idempotencyKeyFactory ?? defaultIdempotencyKey;
+  const logger = opts.logger;
+  const upstreamTimeoutMs = opts.upstreamTimeoutMs ?? 3e4;
+  const tokenManager = new TokenManager({
+    clientId: opts.clientId,
+    clientSecret: opts.clientSecret,
+    apiBaseUrl: opts.apiBaseUrl,
+    fetch: fetchImpl,
+    storage: tokenStorage,
+    logger
+  });
+  async function safeCallUpstream(res, upstreamOpts) {
+    try {
+      const result2 = await callUpstream(
+        opts.apiBaseUrl,
+        tokenManager,
+        { ...upstreamOpts, timeoutMs: upstreamOpts.timeoutMs ?? upstreamTimeoutMs },
+        fetchImpl
+      );
+      if (result2.status >= 200 && result2.status < 300 && result2.body !== null && typeof result2.body !== "object") {
+        logger?.warn("hellobill.upstream_invalid_response", {
+          status: result2.status,
+          path: upstreamOpts.path
+        });
+        sendError(
+          res,
+          502,
+          "internal.error",
+          "Upstream returned a malformed response",
+          result2.requestId
+        );
+        return null;
+      }
+      return result2;
+    } catch (err) {
+      if (err instanceof NetworkError) {
+        logger?.error("hellobill.upstream_unreachable", {
+          kind: err.kind,
+          path: upstreamOpts.path
+        });
+        if (err.kind === "timeout") {
+          sendError(res, 504, "internal.error", "Upstream request timed out");
+        } else {
+          sendError(res, 502, "internal.error", "Upstream request failed");
+        }
+        return null;
+      }
+      throw err;
+    }
+  }
+  const session = async (req, res) => {
+    let partnerSessionResult = null;
+    if (opts.partnerSession) {
+      try {
+        partnerSessionResult = await opts.partnerSession(req);
+      } catch (err) {
+        logger?.warn("hellobill.partner_session_resolver_failed", {
+          message: err.message
+        });
+        sendError(res, 500, "internal.error", "Partner session resolver failed");
+        return;
+      }
+      if (partnerSessionResult === null) {
+        sendError(res, 401, "auth.invalid_credentials", "Partner session is not established");
+        return;
+      }
+    }
+    let payload;
+    try {
+      payload = await opts.buildSessionPayload(req, partnerSessionResult);
+    } catch (err) {
+      logger?.warn("hellobill.build_session_payload_failed", {
+        message: err.message
+      });
+      sendError(res, 400, "validation.invalid_field_value", err.message);
+      return;
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "POST",
+      path: "/partner/sessions",
+      body: payload,
+      idempotencyKey: inboundIdempotencyKey(req) ?? idempotencyKeyFactory(),
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const loa = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const rawProductIds = req.query.product_ids;
+    const productIds = Array.isArray(rawProductIds) ? rawProductIds : typeof rawProductIds === "string" ? rawProductIds.split(",").map((s) => s.trim()).filter(Boolean) : [];
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/sessions/${encodeURIComponent(ctx.sessionId)}/loa`,
+      query: { product_ids: productIds.join(",") || void 0 },
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const customers = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const result2 = await safeCallUpstream(res, {
+      method: "POST",
+      path: `/partner/sessions/${encodeURIComponent(ctx.sessionId)}/customers`,
+      body: req.body,
+      idempotencyKey: inboundIdempotencyKey(req) ?? idempotencyKeyFactory(),
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const bankDetailsSubmit = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const result2 = await safeCallUpstream(res, {
+      method: "POST",
+      path: `/partner/sessions/${encodeURIComponent(ctx.sessionId)}/bank-details`,
+      body: req.body,
+      idempotencyKey: inboundIdempotencyKey(req) ?? idempotencyKeyFactory(),
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const bankDetailsGet = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/sessions/${encodeURIComponent(ctx.sessionId)}/bank-details`,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const status = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const rawCustomer = req.query.customer_id;
+    const customerId = Array.isArray(rawCustomer) ? rawCustomer[0] : rawCustomer;
+    if (!customerId) {
+      sendError(res, 400, "validation.missing_required_field", "customer_id query parameter required");
+      return;
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/customers/${encodeURIComponent(customerId)}/status`,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const products = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const query = {};
+    const keys = ["cursor", "limit", "categories", "include_previous", "force_refresh"];
+    for (const k of keys) {
+      const v = req.query[k];
+      if (Array.isArray(v)) query[k] = v[0];
+      else if (typeof v === "string") query[k] = v;
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/sessions/${encodeURIComponent(ctx.sessionId)}/products`,
+      query,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const property = async (req, res) => {
+    const ctx = ensureSessionContext(req, res);
+    if (!ctx) return;
+    const query = {};
+    const rawForce = req.query.force_refresh;
+    if (typeof rawForce === "string" && rawForce.length > 0) {
+      query.force_refresh = rawForce;
+    } else if (Array.isArray(rawForce) && typeof rawForce[0] === "string" && rawForce[0].length > 0) {
+      query.force_refresh = rawForce[0];
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/sessions/${encodeURIComponent(ctx.sessionId)}/property`,
+      query,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const sessionsList = async (req, res) => {
+    const query = {};
+    for (const [k, v] of Object.entries(req.query)) {
+      if (typeof v === "string" && v.length > 0) {
+        query[k] = v;
+      } else if (Array.isArray(v) && typeof v[0] === "string" && v[0].length > 0) {
+        query[k] = v[0];
+      }
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: "/partner/sessions",
+      query,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const sessionsGet = async (req, res) => {
+    const id = typeof req.params?.id === "string" ? req.params.id : void 0;
+    if (!id || id.length === 0) {
+      sendError(res, 400, "validation.missing_required_field", "sessions/:id requires a non-empty id path param");
+      return;
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/sessions/${encodeURIComponent(id)}`,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const savingsSummary = async (req, res) => {
+    const rawCustomer = req.query.customer_id ?? req.params?.id;
+    const customerId = Array.isArray(rawCustomer) ? rawCustomer[0] : rawCustomer;
+    if (!customerId) {
+      sendError(res, 400, "validation.missing_required_field", "customer_id query parameter required");
+      return;
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/customers/${encodeURIComponent(customerId)}/savings-summary`,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const anyvanSlots = async (req, res) => {
+    const rawSession = req.query.session_id ?? req.params?.id;
+    const sessionId = Array.isArray(rawSession) ? rawSession[0] : rawSession;
+    if (!sessionId) {
+      sendError(res, 400, "validation.missing_required_field", "session_id query parameter required");
+      return;
+    }
+    const result2 = await safeCallUpstream(res, {
+      method: "GET",
+      path: `/partner/sessions/${encodeURIComponent(sessionId)}/anyvan-slots`,
+      logger
+    });
+    if (!result2) return;
+    passthroughUpstream(res, result2.status, result2.body, result2.requestId, result2.headers);
+  };
+  const webhookHandler = opts.webhook ? createWebhookHandler({ ...opts.webhook, logger: opts.webhook.logger ?? opts.logger }) : void 0;
+  const result = {
+    session,
+    loa,
+    bankDetails: { submit: bankDetailsSubmit, get: bankDetailsGet },
+    customers,
+    status,
+    products,
+    property,
+    sessions: { list: sessionsList, get: sessionsGet },
+    savingsSummary,
+    anyvanSlots
+  };
+  if (webhookHandler !== void 0) {
+    result.webhook = webhookHandler;
+  }
+  return result;
+}
+
+// src/client/index.ts
+var DEFAULT_API_BASE_URL = "https://api.hellobill.app/api/v1";
+var HelloBillPartner = class {
+  tokenManager;
+  apiBaseUrl;
+  fetchImpl;
+  logger;
+  upstreamTimeoutMs;
+  idempotencyKeyFactory;
+  sessions;
+  customers;
+  bankDetails;
+  constructor(opts) {
+    this.apiBaseUrl = (opts.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+    this.logger = opts.logger;
+    this.upstreamTimeoutMs = opts.upstreamTimeoutMs ?? 3e4;
+    this.idempotencyKeyFactory = opts.idempotencyKeyFactory ?? defaultIdempotencyKey;
+    this.tokenManager = new TokenManager({
+      clientId: opts.clientId,
+      clientSecret: opts.clientSecret,
+      apiBaseUrl: this.apiBaseUrl,
+      fetch: this.fetchImpl,
+      storage: opts.tokenStorage ?? new InMemoryTokenStorage(),
+      logger: this.logger
+    });
+    this.sessions = {
+      create: (payload, callOpts) => this._call({
+        method: "POST",
+        path: "/partner/sessions",
+        body: payload,
+        idempotencyKey: callOpts?.idempotencyKey ?? this.idempotencyKeyFactory()
+      }),
+      list: (query) => this._call({
+        method: "GET",
+        path: "/partner/sessions",
+        query: this._sessionsListQuery(query)
+      }),
+      get: (sessionId) => this._call({
+        method: "GET",
+        path: `/partner/sessions/${encodeURIComponent(sessionId)}`
+      }),
+      products: (sessionId, query) => this._call({
+        method: "GET",
+        path: `/partner/sessions/${encodeURIComponent(sessionId)}/products`,
+        query: this._productsQuery(query)
+      }),
+      property: (sessionId, query) => this._call({
+        method: "GET",
+        path: `/partner/sessions/${encodeURIComponent(sessionId)}/property`,
+        query: this._propertyQuery(query)
+      }),
+      loa: (sessionId, query) => {
+        if (query.product_ids.length === 0) {
+          return Promise.reject(new TypeError("product_ids must contain at least one ID"));
+        }
+        return this._call({
+          method: "GET",
+          path: `/partner/sessions/${encodeURIComponent(sessionId)}/loa`,
+          query: { product_ids: query.product_ids.join(",") }
+        });
+      },
+      customers: (sessionId, payload, callOpts) => this._call({
+        method: "POST",
+        path: `/partner/sessions/${encodeURIComponent(sessionId)}/customers`,
+        body: payload,
+        idempotencyKey: callOpts?.idempotencyKey ?? this.idempotencyKeyFactory()
+      })
+    };
+    this.customers = {
+      status: (customerId) => this._call({
+        method: "GET",
+        path: `/partner/customers/${encodeURIComponent(customerId)}/status`
+      })
+    };
+    this.bankDetails = {
+      submit: (sessionId, payload, callOpts) => this._call({
+        method: "POST",
+        path: `/partner/sessions/${encodeURIComponent(sessionId)}/bank-details`,
+        body: payload,
+        idempotencyKey: callOpts?.idempotencyKey ?? this.idempotencyKeyFactory()
+      }),
+      get: (sessionId) => this._call({
+        method: "GET",
+        path: `/partner/sessions/${encodeURIComponent(sessionId)}/bank-details`
+      })
+    };
+  }
+  /**
+   * Shared transport envelope: acquires a token, builds the request,
+   * delegates to callUpstream (which handles retries and token refresh),
+   * then throws HellobillApiError for any non-2xx response.
+   */
+  async _call(opts) {
+    const result = await callUpstream(
+      this.apiBaseUrl,
+      this.tokenManager,
+      {
+        method: opts.method,
+        path: opts.path,
+        query: opts.query,
+        body: opts.body,
+        idempotencyKey: opts.idempotencyKey,
+        logger: this.logger,
+        timeoutMs: this.upstreamTimeoutMs
+      },
+      this.fetchImpl
+    );
+    if (result.status >= 200 && result.status < 300) {
+      return result.body;
+    }
+    throw new HellobillApiError(
+      result.status,
+      result.body,
+      result.requestId,
+      result.headers
+    );
+  }
+  /** Maps SessionsListQuery to a plain string record for URLSearchParams. */
+  _sessionsListQuery(q) {
+    if (!q) return void 0;
+    const out = {};
+    if (q.email !== void 0) out.email = q.email;
+    if (q.postcode !== void 0) out.postcode = q.postcode;
+    if (q.created_after !== void 0) out.created_after = q.created_after;
+    if (q.created_before !== void 0) out.created_before = q.created_before;
+    if (q.status !== void 0) out.status = q.status;
+    if (q.cursor !== void 0) out.cursor = q.cursor;
+    if (q.limit !== void 0) out.limit = String(q.limit);
+    return out;
+  }
+  /**
+   * Maps ProductsQuery to a wire-safe string record.
+   * - categories: joined as a single CSV value (one URL param, not repeated keys)
+   * - booleans: true → 'true'; false → omitted (no falsy leakage onto the wire)
+   * - numbers: coerced to string
+   */
+  _productsQuery(q) {
+    if (!q) return void 0;
+    const out = {};
+    if (q.categories !== void 0 && q.categories.length > 0) {
+      out.categories = q.categories.join(",");
+    }
+    if (q.cursor !== void 0) out.cursor = q.cursor;
+    if (q.limit !== void 0) out.limit = String(q.limit);
+    if (q.force_refresh === true) out.force_refresh = "true";
+    if (q.include_previous === true) out.include_previous = "true";
+    return out;
+  }
+  /** Maps PropertyQuery to a wire-safe string record. */
+  _propertyQuery(q) {
+    if (!q) return void 0;
+    const out = {};
+    if (q.force_refresh === true) out.force_refresh = "true";
+    return out;
+  }
+};
+
+// src/onboardingInfo.ts
+function buildOnboardingInfo(_productId, category, location, fields) {
+  if (location === "previous") {
+    return void 0;
+  }
+  if (category === "mobile" || category === "tv_licence" || category === "home_insurance" || category === "breakdown_cover") {
+    return void 0;
+  }
+  let result;
+  if (category === "energy") {
+    result = pickFields(fields, ["meter_read_electricity", "meter_read_gas", "preferred_switch_date"]);
+  } else if (category === "broadband") {
+    result = pickFields(fields, ["preferred_install_date", "existing_line_provider", "keep_existing_number"]);
+  } else if (category === "water") {
+    result = pickFields(fields, ["moved_in_date", "meter_read"]);
+  } else if (category === "council_tax") {
+    result = pickFields(fields, ["moved_in_date"]);
+  }
+  return result;
+}
+function pickFields(fields, keys) {
+  const picked = {};
+  let hasAny = false;
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(fields, key) && fields[key] !== void 0) {
+      picked[key] = fields[key];
+      hasAny = true;
+    }
+  }
+  return hasAny ? picked : void 0;
+}
+
+export { HelloBillPartner, HellobillApiError, InMemoryTokenStorage, InMemoryWebhookDedupeStore, TokenManager, WebhookVerificationError, buildOnboardingInfo, createHellobillHandler, createWebhookHandler, defaultIdempotencyKey, retryFetch, verifyWebhook, verifyWebhookSignature };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map