@hello-bill/node 1.0.0 → 1.0.1

package/dist/index-EXetQn1f.d.ts

@@ -0,0 +1,341 @@
+import { aO as WebhookEvent, aC as SessionEmbedOpened, aB as SessionDetailsConfirmed, aE as SessionProductsSelected, aD as SessionLoaSigned, ay as SessionAccountCreated, aA as SessionAppInstalled, az as SessionAppDeferred, aJ as SubscriptionChanged, aG as SetupStatusChanged, a5 as MoveOutNotificationSent, a4 as MoveOutNotificationFailed, m as BankDetailsCollected, S as SessionPayload } from './webhooks-DPpqf7d2.js';
+
+interface TokenStorage {
+    get(clientId: string): Promise<{
+        accessToken: string;
+        expiresAt: number;
+    } | null>;
+    set(clientId: string, value: {
+        accessToken: string;
+        expiresAt: number;
+    }): Promise<void>;
+}
+interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    /**
+     * Optional — added for unhandled-variant and dedup-hit logs in the webhook
+     * receiver. Existing `Logger` literals (without `info`) continue to satisfy
+     * the interface because `info` is optional.
+     */
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+interface TokenManagerOptions {
+    clientId: string;
+    clientSecret: string;
+    apiBaseUrl: string;
+    fetch?: typeof globalThis.fetch;
+    storage?: TokenStorage;
+    logger?: Logger;
+    /** Renew tokens this many ms before expiry. Default 30_000. */
+    refreshLeewayMs?: number;
+    /** Override `Date.now()` for tests. */
+    now?: () => number;
+}
+/** Default in-memory single-instance storage. */
+declare class InMemoryTokenStorage implements TokenStorage {
+    private readonly map;
+    get(clientId: string): Promise<{
+        accessToken: string;
+        expiresAt: number;
+    } | null>;
+    set(clientId: string, value: {
+        accessToken: string;
+        expiresAt: number;
+    }): Promise<void>;
+}
+/**
+ * Manages partner client_credentials tokens with caching, leeway-based renewal,
+ * and single-flight refresh. Pluggable storage for multi-instance deployments.
+ */
+declare class TokenManager {
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    private readonly storage;
+    private readonly logger;
+    private readonly refreshLeewayMs;
+    private readonly now;
+    private inflight;
+    constructor(opts: TokenManagerOptions);
+    /** Returns a valid bearer token, refreshing if necessary. Single-flight on refresh. */
+    getAccessToken(): Promise<string>;
+    /** Forces invalidation of the cached token. Next `getAccessToken` will refresh. */
+    invalidate(): Promise<void>;
+    private fetchToken;
+}
+
+interface VerifyWebhookOptions {
+    /** Replay window in seconds. Default 300. */
+    tolerance?: number;
+    /** Signature versions to accept. Default ['v1']. Use ['v1', 'v2'] during key rotation. */
+    supportedVersions?: ('v1' | 'v2')[];
+    /** Override `Date.now()` for tests. */
+    now?: () => number;
+}
+declare class WebhookVerificationError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Verifies a HelloBill webhook delivery.
+ * Header format: `t=<unix>,v1=<hex>,v2=<hex>`.
+ * HMAC computed over `${t}.${rawBody}` (raw bytes — do not re-serialise).
+ */
+declare function verifyWebhook(rawBody: Buffer | string, signatureHeader: string, secret: string, opts?: VerifyWebhookOptions): WebhookEvent;
+/**
+ * Verifies a HelloBill webhook delivery without parsing the payload.
+ * Returns `true` only if the timestamp is within tolerance AND at least one
+ * supported scheme verifies. Returns `false` for every other case (missing/
+ * malformed header, expired timestamp, no supported version, signature
+ * mismatch). Never throws on verification failure — callers route on the
+ * boolean. Re-throws non-verification errors (e.g. unexpected crypto failures).
+ *
+ * Unlike the throwing `verifyWebhook`, this function does NOT attempt to parse
+ * the body as JSON — signature verification is purely over the raw bytes.
+ * Callers that need the parsed event should call `verifyWebhook` directly or
+ * parse separately after calling this function.
+ *
+ * @param rawBody  Raw request body bytes (NOT re-serialised JSON).
+ * @param signatureHeader  Value of `X-HelloBill-Signature`.
+ * @param secret  Partner-issued webhook secret (env `HELLOBILL_WEBHOOK_SECRET`).
+ * @param opts  Optional `tolerance` (default 300s), `supportedVersions`
+ *              (default `['v1']`), `now` (test injection).
+ */
+declare function verifyWebhookSignature(rawBody: Buffer | string, signatureHeader: string, secret: string, opts?: VerifyWebhookOptions): boolean;
+
+/**
+ * Webhook idempotency dedupe store. Keyed on `WebhookEnvelope.id`.
+ *
+ * Default `InMemoryWebhookDedupeStore` is fine for single-process deployments
+ * (and unit tests). Multi-replica deployments MUST inject a shared backend
+ * (e.g. Redis SETEX, RDS `INSERT ... ON CONFLICT DO NOTHING`). Per spec §11.1
+ * line 2270: "Use the `id` field to deduplicate."
+ */
+interface WebhookDedupeStore {
+    /** Returns true if `id` has been recorded within its TTL. Never throws on miss. */
+    has(id: string): Promise<boolean> | boolean;
+    /** Records `id` with the given TTL in seconds. Idempotent on repeat calls. */
+    record(id: string, ttlSeconds: number): Promise<void> | void;
+}
+/** In-memory implementation. NOT durable across process restarts. Tests + single-proc deploys. */
+declare class InMemoryWebhookDedupeStore implements WebhookDedupeStore {
+    private readonly now;
+    private readonly store;
+    constructor(now?: () => number);
+    has(id: string): Promise<boolean>;
+    record(id: string, ttlSeconds: number): Promise<void>;
+}
+
+/** Per-event runtime context passed to every typed handler. */
+interface WebhookHandlerContext {
+    /**
+     * Logger guaranteed to have `info` defined — sourced from `withInfoFallback`
+     * at handler construction. Partner handlers may call `ctx.logger.info(...)`
+     * without a null-check regardless of what Logger literal was supplied.
+     */
+    logger: Logger & {
+        info: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    headers: Record<string, string | string[] | undefined>;
+    deprecation: string | null;
+}
+/**
+ * Typed handlers — one per `WebhookEvent` variant. All optional; an
+ * unprovided variant logs at info (`unhandled_variant`) and the dispatcher
+ * still responds 2xx so HelloBill stops retrying.
+ *
+ * Handlers run async AFTER the route has already responded; throwing
+ * from a handler does NOT cause HelloBill to retry (a 2xx was already
+ * written). Errors are logged via `opts.logger?.error`.
+ */
+interface WebhookHandlers {
+    onSessionEmbedOpened?(event: SessionEmbedOpened, ctx: WebhookHandlerContext): Promise<void>;
+    onSessionDetailsConfirmed?(event: SessionDetailsConfirmed, ctx: WebhookHandlerContext): Promise<void>;
+    onSessionProductsSelected?(event: SessionProductsSelected, ctx: WebhookHandlerContext): Promise<void>;
+    onSessionLoaSigned?(event: SessionLoaSigned, ctx: WebhookHandlerContext): Promise<void>;
+    onSessionAccountCreated?(event: SessionAccountCreated, ctx: WebhookHandlerContext): Promise<void>;
+    onSessionAppInstalled?(event: SessionAppInstalled, ctx: WebhookHandlerContext): Promise<void>;
+    onSessionAppDeferred?(event: SessionAppDeferred, ctx: WebhookHandlerContext): Promise<void>;
+    onSubscriptionChanged?(event: SubscriptionChanged, ctx: WebhookHandlerContext): Promise<void>;
+    onSetupStatusChanged?(event: SetupStatusChanged, ctx: WebhookHandlerContext): Promise<void>;
+    onMoveOutNotificationSent?(event: MoveOutNotificationSent, ctx: WebhookHandlerContext): Promise<void>;
+    onMoveOutNotificationFailed?(event: MoveOutNotificationFailed, ctx: WebhookHandlerContext): Promise<void>;
+    onBankDetailsCollected?(event: BankDetailsCollected, ctx: WebhookHandlerContext): Promise<void>;
+}
+/** Options for the webhook route. Lives alongside `CreateHellobillHandlerOptions`. */
+interface WebhookHandlerOptions {
+    /**
+     * Partner webhook secret. From `process.env.HELLOBILL_WEBHOOK_SECRET`.
+     * MUST be a non-empty string at `createWebhookHandler` call time — the
+     * factory throws synchronously on `null`/`undefined`/`''` so that an
+     * unset env var is caught immediately rather than silently 401ing every
+     * incoming webhook.
+     */
+    webhookSecret: string;
+    /**
+     * Optional dedupe-store. Default: in-memory (single-process). Multi-replica
+     * deployments MUST supply a shared backend (Redis, RDS, etc.) — see README.
+     */
+    dedupeStore?: WebhookDedupeStore;
+    /**
+     * Idempotency window in seconds. Default 86_400 (24h). Per spec §11.1 line 2270.
+     */
+    dedupeTtlSeconds?: number;
+    /** Signature versions accepted. Default `['v1']`. Set to `['v1','v2']` during rotation. */
+    supportedVersions?: VerifyWebhookOptions['supportedVersions'];
+    /** Timestamp tolerance in seconds. Default 300. */
+    tolerance?: number;
+    /** Optional logger. Defaults to no-op. */
+    logger?: Logger;
+    /** Typed handlers — provide as many as you care about; missing ones log "unhandled". */
+    handlers?: WebhookHandlers;
+    /**
+     * Test injection for `Date.now()`. Applied to the signature timestamp AND,
+     * only when using the default `InMemoryWebhookDedupeStore`, the dedupe TTL
+     * clock. Partner-supplied `dedupeStore` instances MUST own their own clock
+     * injection — `opts.now` is NOT forwarded to a partner-supplied store.
+     */
+    now?: () => number;
+}
+/**
+ * Creates the framework-agnostic webhook receive handler. Returns a function
+ * matching the same `HellobillRequest`/`HellobillResponse` shape used by the
+ * other routes on `HellobillHandlerSet` (see `core/handler.ts`).
+ *
+ * Throws synchronously if `opts.webhookSecret` is falsy — a missing or
+ * empty secret is caught early so that every incoming webhook does not
+ * silently 401 with no visible cause.
+ *
+ * The Express adapter wires this in alongside `session`/`loa`/etc.
+ */
+declare function createWebhookHandler(opts: WebhookHandlerOptions): (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+
+interface HellobillRequest {
+    method: string;
+    url: string;
+    query: Record<string, string | string[] | undefined>;
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * Path parameters extracted by the adapter's router and populated on the
+     * way in. Example: Express maps `:id` on `router.get('/sessions/:id', ...)`
+     * into `req.params.id`; the SDK Express adapter forwards that verbatim via
+     * `params: req.params`. Adapters that do not expose path parameters leave
+     * this field `undefined` for the 8 contractual routes and synthesise
+     * `params: { id }` only for the `/sessions/:id` branch.
+     *
+     * Optional. Backwards-compatible — adapters that pre-date this field
+     * type-check unchanged.
+     */
+    params?: Record<string, string | undefined>;
+    /** Optional raw request body for webhook verification — populated by adapter. */
+    rawBody?: Buffer;
+}
+interface HellobillResponse {
+    status(code: number): HellobillResponse;
+    header(name: string, value: string): HellobillResponse;
+    json(body: unknown): void;
+}
+interface CreateHellobillHandlerOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Partner API base URL, e.g. https://api.hellobill.app/api/v1 or http://localhost:4100. */
+    apiBaseUrl: string;
+    /**
+     * Called on POST /session to assemble the canonical SessionPayload from whatever
+     * the partner's host page sent. Receives the request unchanged and the resolved
+     * partner session (if configured, or null if `partnerSession` is absent).
+     *
+     * When `partnerSession` is configured, this function MUST source
+     * `customer.email` from the second argument — never from `req.body` —
+     * to prevent the browser from spoofing the email address.
+     */
+    buildSessionPayload: (req: HellobillRequest, partnerSession: unknown | null) => Promise<SessionPayload> | SessionPayload;
+    /**
+     * Optional. Resolves the partner's authenticated server-side session from the
+     * incoming request. Result (if non-null) is passed to `buildSessionPayload`
+     * as the second argument.
+     *
+     * Returning `null` causes the middleware to return `401 auth.invalid_credentials`
+     * before invoking `buildSessionPayload` or calling the upstream API.
+     * Throwing causes a `500 internal.error` response and a warn-level log.
+     * When absent, `buildSessionPayload` is called with `null` as the second arg;
+     * the partner's `buildSessionPayload` is then solely responsible for any
+     * CSRF / origin / session checks.
+     */
+    partnerSession?: (req: HellobillRequest) => Promise<unknown | null> | unknown | null;
+    /** Optional override for idempotency key generation. Defaults to crypto.randomUUID(). */
+    idempotencyKeyFactory?: () => string;
+    /** Optional token storage adapter for multi-instance deployments. Default: in-memory. */
+    tokenStorage?: TokenStorage;
+    /** Custom fetch implementation (for tests). Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional logger. Defaults to no-op. Receives safe (no-secret) log lines. */
+    logger?: Logger;
+    /**
+     * Per-attempt upstream request timeout in ms. Default 30_000 (30s). Each retry
+     * starts a fresh timeout. Network failures and timeouts are surfaced as a
+     * clean `internal.error` envelope.
+     */
+    upstreamTimeoutMs?: number;
+    /**
+     * Optional webhook receiver configuration. When provided, exposes a
+     * `webhook` handler on `HellobillHandlerSet` that the Express adapter
+     * mounts at POST /webhooks. Omit to skip the route entirely.
+     */
+    webhook?: WebhookHandlerOptions;
+}
+interface HellobillHandlerSet {
+    session: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    loa: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    bankDetails: {
+        submit: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+        get: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    };
+    customers: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    status: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    products: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    property: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    /**
+     * Partner-side session recovery: list or fetch a single session by id.
+     * Both proxy the bearer-gated upstream endpoints without requiring a
+     * session_token — they are scoped to the partner's access_token.
+     *
+     * Query params on `list` pass through verbatim (including non-spec keys;
+     * upstream owns 400-on-unknown-filter semantics). The `get` handler reads
+     * the session id from `req.params.id`.
+     *
+     * Additive: not part of the v1.15 contract (spec §9.2.1). The reference SDK
+     * always includes them; partners may opt out by substituting a handler that
+     * returns 404.
+     */
+    sessions: {
+        list: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+        get: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    };
+    /**
+     * Proxies GET /partner/customers/:id/savings-summary.
+     * Reads customer_id from req.query.customer_id or req.params.id.
+     * Scoped to the partner's access_token — no session_token required.
+     */
+    savingsSummary: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    /**
+     * Proxies GET /partner/sessions/:id/anyvan-slots.
+     * Reads session_id from req.query.session_id or req.params.id.
+     * Scoped to the partner's access_token — no session_token required.
+     */
+    anyvanSlots: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+    /**
+     * Optional webhook receiver. Present only when `opts.webhook` is supplied to
+     * `createHellobillHandler`. The Express adapter mounts POST /webhooks when
+     * this slot is defined, and omits the route when it is `undefined`.
+     */
+    webhook?: (req: HellobillRequest, res: HellobillResponse) => Promise<void>;
+}
+
+declare function createHellobillHandler(opts: CreateHellobillHandlerOptions): HellobillHandlerSet;
+
+export { type CreateHellobillHandlerOptions as C, type HellobillHandlerSet as H, InMemoryTokenStorage as I, type Logger as L, type TokenStorage as T, type VerifyWebhookOptions as V, type WebhookDedupeStore as W, type HellobillRequest as a, type HellobillResponse as b, InMemoryWebhookDedupeStore as c, TokenManager as d, type TokenManagerOptions as e, type WebhookHandlerContext as f, type WebhookHandlerOptions as g, type WebhookHandlers as h, WebhookVerificationError as i, createHellobillHandler as j, createWebhookHandler as k, verifyWebhookSignature as l, verifyWebhook as v };

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+import { T as TokenStorage, L as Logger } from './index-BrfG82zs.cjs';
+export { C as CreateHellobillHandlerOptions, H as HellobillHandlerSet, a as HellobillRequest, b as HellobillResponse, I as InMemoryTokenStorage, c as InMemoryWebhookDedupeStore, d as TokenManager, e as TokenManagerOptions, V as VerifyWebhookOptions, W as WebhookDedupeStore, f as WebhookHandlerContext, g as WebhookHandlerOptions, h as WebhookHandlers, i as WebhookVerificationError, j as createHellobillHandler, k as createWebhookHandler, v as verifyWebhook, l as verifyWebhookSignature } from './index-BrfG82zs.cjs';
+import { R as RequestId, S as SessionPayload, a as SessionResponse, b as SessionGetResponse, P as ProductsQuery, c as ProductsResponse, d as PropertyDetailResponse, L as LoaListResponse, C as CreateCustomerInput, e as CustomerCreateResponse, f as CustomerId, g as CustomerStatusResponse, B as BankDetailsRequest, h as BankDetailsResponse } from './webhooks-DPpqf7d2.cjs';
+export { A as Address, i as AddressObject, j as AddressesObject, k as ApiVersion, l as AppDeeplinks, m as BankDetailsCollected, n as BankDetailsConsent, o as BankDetailsObject, p as BankDetailsStatus, q as BillType, r as BreakdownCoverProduct, s as BroadbandProduct, t as BuildingStyle, u as BuildingType, v as CacheStatus, w as ClientMode, x as Consent, y as ContextEntry, z as CouncilTaxProduct, D as Customer, E as CustomerType, F as DataCompleteness, G as DiscoveryStatus, H as Email, I as EnergyProduct, J as Environment, K as EpcRating, M as FinalRead, N as FuelType, O as HeatingType, Q as HomeInsuranceProduct, T as IdempotencyKey, U as IsoDate, V as IsoDateTime, W as LoASignature, X as LoaId, Y as LoaRecord, Z as LocationRole, _ as MaskedSortCode, $ as Meters, a0 as MobileProduct, a1 as MoveIn, a2 as MoveObject, a3 as MoveOut, a4 as MoveOutNotificationFailed, a5 as MoveOutNotificationSent, a6 as MoveOutNotifyFlags, a7 as MoveOutReason, a8 as MoveOutStatus, a9 as NearbyPoi, aa as OccupantObject, ab as OccupantType, ac as OnboardingInfo, ad as OverallStatus, ae as Paginated, af as Person, ag as PhoneNumber, ah as Postcode, ai as Product, aj as ProductBase, ak as ProductCategory, al as ProductConfidence, am as ProductId, an as ProductSetup, ao as PropertyDetailObject, ap as PropertyLocation, aq as PropertyObject, ar as PropertyType, as as PropertyTypeCode, at as PropertyTypeSubcode, au as ProvidedFieldPath, av as SESSION_IDEMPOTENCY_TTL_MS, aw as SavingsSummaryResponse, ax as SelectedProduct, ay as SessionAccountCreated, az as SessionAppDeferred, aA as SessionAppInstalled, aB as SessionDetailsConfirmed, aC as SessionEmbedOpened, aD as SessionLoaSigned, aE as SessionProductsSelected, aF as SetupStatus, aG as SetupStatusChanged, aH as SignatureImage, aI as StoredBankDetails, aJ as SubscriptionChanged, aK as SubscriptionStatus, aL as TvLicenceProduct, aM as Url, aN as WaterProduct, aO as WebhookEvent, aP as WebhookEventBase, aQ as WebhookEventId, aR as WebhookEventType } from './webhooks-DPpqf7d2.cjs';
+import { ErrorEnvelope } from './types/index.cjs';
+export { AnyvanSlot, AnyvanSlotsResponse, ErrorCode, ErrorType, RETRYABLE_HTTP_STATUSES } from './types/index.cjs';
+
+interface RetryOptions {
+    /** Max attempts including the first. Default 5. */
+    maxAttempts?: number;
+    /** Base delay in ms for exponential backoff. Default 1000. */
+    baseDelayMs?: number;
+    /** Cap on delay (ms). Default 16000. */
+    maxDelayMs?: number;
+    /** Override fetch (for tests). Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Override sleep (for tests). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Random source for jitter (0..1). */
+    random?: () => number;
+    /**
+     * Optional pre-attempt hook. Resolves with `true` to swap in a refreshed token.
+     * Called once per attempt when the previous response indicated `auth.token_expired`.
+     */
+    onTokenExpired?: () => Promise<void>;
+    /**
+     * Per-attempt request timeout in ms. If the fetch does not resolve within this
+     * window, it is aborted and treated as a retryable network error. Default 30_000.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Fetch with retry. Retries on retryable HTTP statuses honoring `Retry-After`,
+ * and invokes `onTokenExpired` once when the upstream returns `auth.token_expired`.
+ */
+declare function retryFetch(input: string | URL, init: RequestInit, opts?: RetryOptions): Promise<Response>;
+
+/** Default idempotency key generator — UUID v4 via Node crypto. */
+declare function defaultIdempotencyKey(): string;
+
+/**
+ * Thrown when an upstream call returns a non-2xx response.
+ * Handlers catch and pass through the envelope verbatim to the caller.
+ *
+ * `headers` carries the upstream response headers so callers can read
+ * rate-limit budget (X-RateLimit-Remaining) and back-off hints (Retry-After)
+ * after retries are exhausted.
+ */
+declare class HellobillApiError extends Error {
+    readonly status: number;
+    readonly envelope: ErrorEnvelope | null;
+    readonly requestId: RequestId | undefined;
+    readonly headers: Headers | undefined;
+    constructor(status: number, envelope: ErrorEnvelope | null, requestId?: RequestId, headers?: Headers);
+    get code(): string | undefined;
+}
+
+interface HelloBillPartnerOptions {
+    clientId: string;
+    clientSecret: string;
+    /**
+     * Partner API base URL. Defaults to the production endpoint.
+     * Override for sandbox proxies or local mock-api testing.
+     */
+    apiBaseUrl?: string;
+    /** Optional token storage adapter for multi-instance deployments. Default: in-memory. */
+    tokenStorage?: TokenStorage;
+    /** Custom fetch implementation (for tests). Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional logger. Defaults to no-op. */
+    logger?: Logger;
+    /** Per-attempt upstream request timeout in ms. Default 30_000 (30s). */
+    upstreamTimeoutMs?: number;
+    /** Optional override for idempotency key generation. Defaults to crypto.randomUUID(). */
+    idempotencyKeyFactory?: () => string;
+}
+interface IdempotencyOptions {
+    idempotencyKey?: string;
+}
+interface SessionsListQuery {
+    email?: string;
+    postcode?: string;
+    created_after?: string;
+    created_before?: string;
+    status?: 'created' | 'customer_created' | 'expired';
+    cursor?: string;
+    limit?: number;
+}
+interface SessionsListResponse {
+    sessions: Array<{
+        session_id: string;
+        referral_id: string | null;
+        email: string;
+        postcode: string;
+        address_line_1: string;
+        status: string;
+        customer_id?: string;
+        created_at: string;
+        expires_at: string;
+    }>;
+    next_cursor: string | null;
+}
+interface LoaQuery {
+    product_ids: string[];
+}
+interface PropertyQuery {
+    force_refresh?: boolean;
+}
+declare class HelloBillPartner {
+    private readonly tokenManager;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    private readonly logger;
+    private readonly upstreamTimeoutMs;
+    private readonly idempotencyKeyFactory;
+    readonly sessions: {
+        create: (payload: SessionPayload, opts?: IdempotencyOptions) => Promise<SessionResponse>;
+        list: (query?: SessionsListQuery) => Promise<SessionsListResponse>;
+        get: (sessionId: string) => Promise<SessionGetResponse>;
+        products: (sessionId: string, query?: ProductsQuery) => Promise<ProductsResponse>;
+        property: (sessionId: string, query?: PropertyQuery) => Promise<PropertyDetailResponse>;
+        loa: (sessionId: string, query: LoaQuery) => Promise<LoaListResponse>;
+        customers: (sessionId: string, payload: CreateCustomerInput, opts?: IdempotencyOptions) => Promise<CustomerCreateResponse>;
+    };
+    readonly customers: {
+        status: (customerId: CustomerId) => Promise<CustomerStatusResponse>;
+    };
+    readonly bankDetails: {
+        submit: (sessionId: string, payload: BankDetailsRequest, opts?: IdempotencyOptions) => Promise<BankDetailsResponse>;
+        get: (sessionId: string) => Promise<BankDetailsResponse>;
+    };
+    constructor(opts: HelloBillPartnerOptions);
+    /**
+     * 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.
+     */
+    private _call;
+    /** Maps SessionsListQuery to a plain string record for URLSearchParams. */
+    private _sessionsListQuery;
+    /**
+     * 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
+     */
+    private _productsQuery;
+    /** Maps PropertyQuery to a wire-safe string record. */
+    private _propertyQuery;
+}
+
+/**
+ * Builds the onboarding_info object for a product entry in the createCustomer request.
+ *
+ * Returns undefined when:
+ * - location is 'previous' (previous-address products have no standard onboarding fields)
+ * - category has no standard onboarding fields (mobile, tv_licence, home_insurance, breakdown_cover)
+ * - none of the canonical fields for the category are present in the supplied fields object
+ *
+ * Callers must omit the onboarding_info key entirely when this returns undefined.
+ */
+declare function buildOnboardingInfo(_productId: string, category: string, location: string, fields: Record<string, unknown>): Record<string, unknown> | undefined;
+
+export { BankDetailsRequest, BankDetailsResponse, CreateCustomerInput, CustomerCreateResponse, CustomerId, CustomerStatusResponse, ErrorEnvelope, HelloBillPartner, type HelloBillPartnerOptions, HellobillApiError, type IdempotencyOptions, LoaListResponse, type LoaQuery, Logger, ProductsQuery, ProductsResponse, PropertyDetailResponse, type PropertyQuery, RequestId, type RetryOptions, SessionGetResponse, SessionPayload, SessionResponse, type SessionsListQuery, type SessionsListResponse, TokenStorage, buildOnboardingInfo, defaultIdempotencyKey, retryFetch };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+import { T as TokenStorage, L as Logger } from './index-EXetQn1f.js';
+export { C as CreateHellobillHandlerOptions, H as HellobillHandlerSet, a as HellobillRequest, b as HellobillResponse, I as InMemoryTokenStorage, c as InMemoryWebhookDedupeStore, d as TokenManager, e as TokenManagerOptions, V as VerifyWebhookOptions, W as WebhookDedupeStore, f as WebhookHandlerContext, g as WebhookHandlerOptions, h as WebhookHandlers, i as WebhookVerificationError, j as createHellobillHandler, k as createWebhookHandler, v as verifyWebhook, l as verifyWebhookSignature } from './index-EXetQn1f.js';
+import { R as RequestId, S as SessionPayload, a as SessionResponse, b as SessionGetResponse, P as ProductsQuery, c as ProductsResponse, d as PropertyDetailResponse, L as LoaListResponse, C as CreateCustomerInput, e as CustomerCreateResponse, f as CustomerId, g as CustomerStatusResponse, B as BankDetailsRequest, h as BankDetailsResponse } from './webhooks-DPpqf7d2.js';
+export { A as Address, i as AddressObject, j as AddressesObject, k as ApiVersion, l as AppDeeplinks, m as BankDetailsCollected, n as BankDetailsConsent, o as BankDetailsObject, p as BankDetailsStatus, q as BillType, r as BreakdownCoverProduct, s as BroadbandProduct, t as BuildingStyle, u as BuildingType, v as CacheStatus, w as ClientMode, x as Consent, y as ContextEntry, z as CouncilTaxProduct, D as Customer, E as CustomerType, F as DataCompleteness, G as DiscoveryStatus, H as Email, I as EnergyProduct, J as Environment, K as EpcRating, M as FinalRead, N as FuelType, O as HeatingType, Q as HomeInsuranceProduct, T as IdempotencyKey, U as IsoDate, V as IsoDateTime, W as LoASignature, X as LoaId, Y as LoaRecord, Z as LocationRole, _ as MaskedSortCode, $ as Meters, a0 as MobileProduct, a1 as MoveIn, a2 as MoveObject, a3 as MoveOut, a4 as MoveOutNotificationFailed, a5 as MoveOutNotificationSent, a6 as MoveOutNotifyFlags, a7 as MoveOutReason, a8 as MoveOutStatus, a9 as NearbyPoi, aa as OccupantObject, ab as OccupantType, ac as OnboardingInfo, ad as OverallStatus, ae as Paginated, af as Person, ag as PhoneNumber, ah as Postcode, ai as Product, aj as ProductBase, ak as ProductCategory, al as ProductConfidence, am as ProductId, an as ProductSetup, ao as PropertyDetailObject, ap as PropertyLocation, aq as PropertyObject, ar as PropertyType, as as PropertyTypeCode, at as PropertyTypeSubcode, au as ProvidedFieldPath, av as SESSION_IDEMPOTENCY_TTL_MS, aw as SavingsSummaryResponse, ax as SelectedProduct, ay as SessionAccountCreated, az as SessionAppDeferred, aA as SessionAppInstalled, aB as SessionDetailsConfirmed, aC as SessionEmbedOpened, aD as SessionLoaSigned, aE as SessionProductsSelected, aF as SetupStatus, aG as SetupStatusChanged, aH as SignatureImage, aI as StoredBankDetails, aJ as SubscriptionChanged, aK as SubscriptionStatus, aL as TvLicenceProduct, aM as Url, aN as WaterProduct, aO as WebhookEvent, aP as WebhookEventBase, aQ as WebhookEventId, aR as WebhookEventType } from './webhooks-DPpqf7d2.js';
+import { ErrorEnvelope } from './types/index.js';
+export { AnyvanSlot, AnyvanSlotsResponse, ErrorCode, ErrorType, RETRYABLE_HTTP_STATUSES } from './types/index.js';
+
+interface RetryOptions {
+    /** Max attempts including the first. Default 5. */
+    maxAttempts?: number;
+    /** Base delay in ms for exponential backoff. Default 1000. */
+    baseDelayMs?: number;
+    /** Cap on delay (ms). Default 16000. */
+    maxDelayMs?: number;
+    /** Override fetch (for tests). Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Override sleep (for tests). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Random source for jitter (0..1). */
+    random?: () => number;
+    /**
+     * Optional pre-attempt hook. Resolves with `true` to swap in a refreshed token.
+     * Called once per attempt when the previous response indicated `auth.token_expired`.
+     */
+    onTokenExpired?: () => Promise<void>;
+    /**
+     * Per-attempt request timeout in ms. If the fetch does not resolve within this
+     * window, it is aborted and treated as a retryable network error. Default 30_000.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Fetch with retry. Retries on retryable HTTP statuses honoring `Retry-After`,
+ * and invokes `onTokenExpired` once when the upstream returns `auth.token_expired`.
+ */
+declare function retryFetch(input: string | URL, init: RequestInit, opts?: RetryOptions): Promise<Response>;
+
+/** Default idempotency key generator — UUID v4 via Node crypto. */
+declare function defaultIdempotencyKey(): string;
+
+/**
+ * Thrown when an upstream call returns a non-2xx response.
+ * Handlers catch and pass through the envelope verbatim to the caller.
+ *
+ * `headers` carries the upstream response headers so callers can read
+ * rate-limit budget (X-RateLimit-Remaining) and back-off hints (Retry-After)
+ * after retries are exhausted.
+ */
+declare class HellobillApiError extends Error {
+    readonly status: number;
+    readonly envelope: ErrorEnvelope | null;
+    readonly requestId: RequestId | undefined;
+    readonly headers: Headers | undefined;
+    constructor(status: number, envelope: ErrorEnvelope | null, requestId?: RequestId, headers?: Headers);
+    get code(): string | undefined;
+}
+
+interface HelloBillPartnerOptions {
+    clientId: string;
+    clientSecret: string;
+    /**
+     * Partner API base URL. Defaults to the production endpoint.
+     * Override for sandbox proxies or local mock-api testing.
+     */
+    apiBaseUrl?: string;
+    /** Optional token storage adapter for multi-instance deployments. Default: in-memory. */
+    tokenStorage?: TokenStorage;
+    /** Custom fetch implementation (for tests). Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Optional logger. Defaults to no-op. */
+    logger?: Logger;
+    /** Per-attempt upstream request timeout in ms. Default 30_000 (30s). */
+    upstreamTimeoutMs?: number;
+    /** Optional override for idempotency key generation. Defaults to crypto.randomUUID(). */
+    idempotencyKeyFactory?: () => string;
+}
+interface IdempotencyOptions {
+    idempotencyKey?: string;
+}
+interface SessionsListQuery {
+    email?: string;
+    postcode?: string;
+    created_after?: string;
+    created_before?: string;
+    status?: 'created' | 'customer_created' | 'expired';
+    cursor?: string;
+    limit?: number;
+}
+interface SessionsListResponse {
+    sessions: Array<{
+        session_id: string;
+        referral_id: string | null;
+        email: string;
+        postcode: string;
+        address_line_1: string;
+        status: string;
+        customer_id?: string;
+        created_at: string;
+        expires_at: string;
+    }>;
+    next_cursor: string | null;
+}
+interface LoaQuery {
+    product_ids: string[];
+}
+interface PropertyQuery {
+    force_refresh?: boolean;
+}
+declare class HelloBillPartner {
+    private readonly tokenManager;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    private readonly logger;
+    private readonly upstreamTimeoutMs;
+    private readonly idempotencyKeyFactory;
+    readonly sessions: {
+        create: (payload: SessionPayload, opts?: IdempotencyOptions) => Promise<SessionResponse>;
+        list: (query?: SessionsListQuery) => Promise<SessionsListResponse>;
+        get: (sessionId: string) => Promise<SessionGetResponse>;
+        products: (sessionId: string, query?: ProductsQuery) => Promise<ProductsResponse>;
+        property: (sessionId: string, query?: PropertyQuery) => Promise<PropertyDetailResponse>;
+        loa: (sessionId: string, query: LoaQuery) => Promise<LoaListResponse>;
+        customers: (sessionId: string, payload: CreateCustomerInput, opts?: IdempotencyOptions) => Promise<CustomerCreateResponse>;
+    };
+    readonly customers: {
+        status: (customerId: CustomerId) => Promise<CustomerStatusResponse>;
+    };
+    readonly bankDetails: {
+        submit: (sessionId: string, payload: BankDetailsRequest, opts?: IdempotencyOptions) => Promise<BankDetailsResponse>;
+        get: (sessionId: string) => Promise<BankDetailsResponse>;
+    };
+    constructor(opts: HelloBillPartnerOptions);
+    /**
+     * 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.
+     */
+    private _call;
+    /** Maps SessionsListQuery to a plain string record for URLSearchParams. */
+    private _sessionsListQuery;
+    /**
+     * 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
+     */
+    private _productsQuery;
+    /** Maps PropertyQuery to a wire-safe string record. */
+    private _propertyQuery;
+}
+
+/**
+ * Builds the onboarding_info object for a product entry in the createCustomer request.
+ *
+ * Returns undefined when:
+ * - location is 'previous' (previous-address products have no standard onboarding fields)
+ * - category has no standard onboarding fields (mobile, tv_licence, home_insurance, breakdown_cover)
+ * - none of the canonical fields for the category are present in the supplied fields object
+ *
+ * Callers must omit the onboarding_info key entirely when this returns undefined.
+ */
+declare function buildOnboardingInfo(_productId: string, category: string, location: string, fields: Record<string, unknown>): Record<string, unknown> | undefined;
+
+export { BankDetailsRequest, BankDetailsResponse, CreateCustomerInput, CustomerCreateResponse, CustomerId, CustomerStatusResponse, ErrorEnvelope, HelloBillPartner, type HelloBillPartnerOptions, HellobillApiError, type IdempotencyOptions, LoaListResponse, type LoaQuery, Logger, ProductsQuery, ProductsResponse, PropertyDetailResponse, type PropertyQuery, RequestId, type RetryOptions, SessionGetResponse, SessionPayload, SessionResponse, type SessionsListQuery, type SessionsListResponse, TokenStorage, buildOnboardingInfo, defaultIdempotencyKey, retryFetch };