@hello-bill/node 1.0.0 → 1.0.1

package/dist/webhooks-DPpqf7d2.d.cts

@@ -0,0 +1,751 @@
+/**
+ * Common HelloBill Partner API types.
+ * Source: HelloBill Partner API v15 (Revision 1.15, api_version "2026-05-10").
+ */
+type Environment = 'sandbox' | 'production';
+/**
+ * Determined by client_id prefix on the partner credential:
+ * `sb_*` → sandbox, `live_*` → live. Strict realm isolation; cross-realm IDs return 404.
+ */
+type ClientMode = 'sandbox' | 'live';
+type ApiVersion = '2026-05-10' | (string & {});
+type RequestId = string;
+/** UUID v4. Generated by SDK for idempotent POSTs; overridable per call. */
+type IdempotencyKey = string;
+/** ISO 8601 UTC timestamp, e.g. "2026-05-15T14:32:00Z". */
+type IsoDateTime = string;
+/** ISO 8601 date, e.g. "2026-06-01". */
+type IsoDate = string;
+/** UK postcode in canonical form, e.g. "SW1A 1AA". */
+type Postcode = string;
+type Email = string;
+/** E.164 phone number, e.g. "+447700900123". */
+type PhoneNumber = string;
+type Url = string;
+/**
+ * Cursor-paginated response envelope used by list endpoints (e.g. /products).
+ * `next_cursor` is `null` when no more pages.
+ */
+interface Paginated<T> {
+    data: T[];
+    next_cursor: string | null;
+    has_more: boolean;
+}
+/**
+ * The product category an item belongs to.
+ * Note: the embed renders AnyVan as an internal UI line item; it does NOT
+ * correspond to a Partner API category.
+ */
+type ProductCategory = 'energy' | 'water' | 'broadband' | 'council_tax' | 'mobile' | 'tv_licence' | 'home_insurance' | 'breakdown_cover';
+/**
+ * "current" = the property the customer is moving into.
+ * "previous" = the property they are moving out of (only present when move.out supplied).
+ */
+type PropertyLocation = 'current' | 'previous';
+/** Shared base address shape used anywhere an address appears. */
+interface AddressObject {
+    address_line_1: string;
+    address_line_2?: string;
+    address_line_3?: string;
+    city: string;
+    postcode: Postcode;
+    uprn?: string;
+    country?: 'GB';
+}
+/** @deprecated Use AddressObject. Kept for backwards-compatible imports. */
+type Address = AddressObject;
+type PropertyType = 'detached' | 'semi_detached' | 'terraced' | 'flat' | 'bungalow' | 'maisonette' | 'other';
+type HeatingType = 'gas_central' | 'electric' | 'oil' | 'heat_pump' | 'district' | 'solid_fuel' | 'other';
+type EpcRating = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G';
+/** A property where utilities are served. */
+interface PropertyObject extends AddressObject {
+    bedrooms?: number;
+    number_occupants?: number;
+    property_type?: PropertyType;
+    epc_rating?: EpcRating;
+    heating_type?: HeatingType;
+}
+type CustomerType = 'owner_occupier' | 'tenant' | 'licensee' | 'lodger' | 'management_company' | 'other';
+type OccupantType = 'owner' | 'tenant' | 'licensee' | 'lodger' | 'guarantor' | 'other';
+interface Customer {
+    type: CustomerType;
+    email: Email;
+    first_name?: string;
+    last_name?: string;
+    phone?: PhoneNumber;
+    /** YYYY-MM-DD. Required at POST /customers. Never log. */
+    date_of_birth?: IsoDate;
+    is_primary_occupant?: boolean;
+    on_psr?: boolean;
+    /** Optional B2B billing/contact address; server defaults to addresses.current. */
+    address?: AddressObject;
+}
+/** @deprecated Use Customer. */
+type Person = Customer;
+interface OccupantObject {
+    type: OccupantType;
+    first_name?: string;
+    last_name?: string;
+    email?: Email;
+    phone?: PhoneNumber;
+    is_primary_occupant?: boolean;
+}
+type BillType = 'single' | 'split';
+/** Customer-supplied move-in details for the new property. */
+interface MoveIn {
+    move_in_date: IsoDate;
+    bill_type?: BillType;
+    rent_pcm?: number;
+    tenancy_start_date?: IsoDate;
+    tenancy_end_date?: IsoDate;
+}
+type MoveOutReason = 'end_of_tenancy' | 'sale' | 'transfer' | 'bereavement' | 'other';
+interface MoveOutNotifyFlags {
+    energy?: boolean;
+    water?: boolean;
+    council_tax?: boolean;
+    tv_licence?: boolean;
+    broadband?: boolean;
+    mobile?: boolean;
+}
+type FuelType = 'electricity' | 'gas';
+interface FinalRead {
+    category: 'energy' | 'water';
+    fuel?: FuelType;
+    meter_serial_number?: string;
+    reading: number;
+    read_date: IsoDate;
+    photo_data_base64?: string;
+    estimated?: boolean;
+}
+/**
+ * Customer-supplied move-out details for the previous property.
+ * When this is absent, the simple move-in flow runs (no van service,
+ * no comparison screen, no /products?include_previous call).
+ */
+interface MoveOut {
+    move_out_date: IsoDate;
+    tenancy_end_date?: IsoDate;
+    reason?: MoveOutReason;
+    forwarding_address?: AddressObject;
+    notify?: MoveOutNotifyFlags;
+    final_reads?: FinalRead[];
+}
+interface Meters {
+    mpan?: string;
+    mprn?: string;
+    current_supplier_electricity?: string;
+    current_supplier_gas?: string;
+}
+interface Consent {
+    /** Must be `true` at POST /sessions. Spec-required. */
+    data_sharing_accepted: true;
+    data_sharing_accepted_at: IsoDateTime;
+    /** Customer-supplied. Drives marketing webhooks/email. */
+    marketing_accepted?: boolean;
+}
+type ContextEntry = {
+    name: string;
+    type: 'string';
+    value: string;
+} | {
+    name: string;
+    type: 'number';
+    value: number;
+} | {
+    name: string;
+    type: 'boolean';
+    value: boolean;
+};
+/**
+ * Per-field discovery / completeness signal returned alongside SessionResponse.
+ * Uses dot-notation: e.g. "addresses.current.postcode", "move.in.move_in_date".
+ */
+type ProvidedFieldPath = string;
+/** Async discovery state for a session. Embed polls /products until complete. */
+type DiscoveryStatus = 'running' | 'complete';
+/** Cache state on /products responses. */
+type CacheStatus = 'fresh' | 'cached' | 'throttled' | 'partial';
+
+declare const maskedSortCodeBrand: unique symbol;
+type MaskedSortCode = string & {
+    readonly [maskedSortCodeBrand]: 'NN-**-NN';
+};
+type BankDetailsStatus = 'collected' | 'pending' | 'failed';
+interface BankDetailsConsent {
+    direct_debit_authorised: true;
+    authorised_at: IsoDateTime;
+    consent_text_version: string;
+}
+interface BankDetailsRequest {
+    sort_code: string;
+    account_number: string;
+    account_holder_name: string;
+    consent: BankDetailsConsent;
+}
+interface StoredBankDetails {
+    id: string;
+    sort_code: string;
+    account_number: string;
+    account_holder_name: string;
+    consent: BankDetailsConsent;
+    modulus_check_passed: boolean;
+    status: BankDetailsStatus;
+    collected_at: IsoDateTime;
+}
+interface BankDetailsObject {
+    id: string;
+    account_number_ending: string;
+    sort_code_masked: MaskedSortCode;
+    bank_name?: string;
+    account_holder_name: string;
+    modulus_check_passed: boolean;
+    status: BankDetailsStatus;
+    collected_at: IsoDateTime;
+    consent: BankDetailsConsent;
+}
+interface BankDetailsResponse {
+    session_id: string;
+    bank_details: BankDetailsObject;
+    expires_at: IsoDateTime;
+}
+
+/**
+ * Session lifecycle types.
+ * POST /partner/sessions creates a session and returns a short-lived session_token
+ * that the embed presents to the frontend-facing endpoints.
+ */
+
+interface AddressesObject {
+    /** The property the customer is moving INTO. Where utilities are set up. */
+    current: PropertyObject;
+    /** The property the customer is moving OUT of, if applicable. */
+    previous?: PropertyObject;
+}
+interface MoveObject {
+    in: MoveIn;
+    out?: MoveOut;
+}
+/**
+ * Canonical snake_case shape the SDK sends to POST /partner/sessions.
+ * `buildSessionPayload(req)` on the server is responsible for assembling this
+ * from whatever shape the partner's host page provides.
+ */
+interface SessionPayload {
+    /** Partner-controlled correlation. Echoed back on webhooks as `data.referral_id`. */
+    referral_id?: string;
+    customer: Customer;
+    occupants?: OccupantObject[];
+    addresses: AddressesObject;
+    move: MoveObject;
+    meters?: Meters;
+    consent: Consent;
+    context?: ContextEntry[];
+}
+/** Response from POST /partner/sessions. */
+interface SessionResponse {
+    session_id: string;
+    /** Short-lived JWT (300s) the embed presents to the SDK-mounted endpoints. */
+    session_token: string;
+    embed_url: string;
+    /** Initial discovery status. Embed polls /products until complete. */
+    discovery_status: 'running' | 'complete';
+    estimated_ready_seconds?: number;
+    /** Dot-notation paths of fields HelloBill received. Drives adaptive UI. */
+    provided_fields: ProvidedFieldPath[];
+    /** ISO 8601. Session resource expires after 90 days. */
+    expires_at: IsoDateTime;
+}
+/**
+ * Response from GET /partner/sessions/:id.
+ *
+ * Per spec §3.7, the endpoint echoes back the full SessionPayload the partner
+ * originally sent to POST /partner/sessions, extended with server-assigned fields.
+ * This is distinct from SessionResponse (POST projection) which carries session_token
+ * and embed_url but not the original payload fields.
+ */
+interface SessionGetResponse extends SessionPayload {
+    /** Stable server-assigned session identifier. */
+    session_id: string;
+    /** ISO 8601 timestamp when the session was created. */
+    created_at: IsoDateTime;
+    /** ISO 8601 session expiry (90 days from creation). */
+    expires_at: IsoDateTime;
+    /** Lifecycle status of the session. */
+    status: 'created' | 'customer_created' | 'expired';
+}
+/**
+ * Idempotency window for POST /sessions: 24h on
+ * email + addresses.current.postcode + addresses.current.address_line_1.
+ * `move.out` is NOT part of the key — partners cannot retroactively change shape.
+ */
+declare const SESSION_IDEMPOTENCY_TTL_MS: number;
+
+/**
+ * Product catalog and property-detail types.
+ * Source: HelloBill Partner API v15 §§4, 5, 16.
+ */
+
+type ProductId = string;
+type LocationRole = PropertyLocation;
+type ProductConfidence = 'high' | 'medium' | 'low';
+interface ProductBase {
+    product_id: ProductId;
+    category: ProductCategory;
+    sub_categories: string[];
+    supplier_name: string;
+    supplier_logo_url?: string | null;
+    location: LocationRole;
+    /** True if this is the customer's existing supplier at the property. */
+    is_incumbent: boolean;
+    monthly_amount_pence?: number;
+    annual_amount_pence?: number;
+    confidence: ProductConfidence;
+    tariff_name?: string | null;
+    note?: string;
+    extracted_at: IsoDateTime;
+    /** Validity window for selecting this product (24h). */
+    expires_at: IsoDateTime;
+}
+interface EnergyProduct extends ProductBase {
+    category: 'energy';
+    details: {
+        unit_rate_pence_per_kwh: number;
+        unit_rate_pence_per_kwh_gas?: number;
+        standing_charge_pence_per_day: number;
+        standing_charge_pence_per_day_gas?: number;
+        estimated_annual_usage_kwh?: number;
+        estimated_annual_usage_kwh_gas?: number;
+        fuel_types: ('electricity' | 'gas')[];
+        contract_length_months?: number;
+        exit_fee_pence?: number;
+        green_percentage?: number;
+        tariff_type?: 'fixed' | 'variable' | 'tracker' | 'time_of_use' | 'prepayment' | 'ev';
+        smart_meter_required?: boolean;
+    };
+}
+interface WaterProduct extends ProductBase {
+    category: 'water';
+    details: {
+        metered: boolean;
+        estimated_litres_per_day?: number;
+        unit_rate_gbp_per_m3?: number;
+        standing_charge_gbp_per_year: number;
+        rateable_value_pence?: number;
+        sewerage_annual_pence?: number;
+        surface_water_drainage_pence?: number;
+        effective_tariff_year: string;
+        region: string;
+    };
+}
+interface BroadbandProduct extends ProductBase {
+    category: 'broadband';
+    details: {
+        download_speed_mbps: number;
+        upload_speed_mbps: number;
+        contract_length_months: number;
+        setup_fee_pence: number;
+        includes_line_rental: boolean;
+        technology: 'adsl' | 'fttc' | 'ftth' | 'full_fibre' | 'fixed_wireless' | 'mobile_5g_home' | 'satellite';
+        data_cap_gb?: number | null;
+        in_contract_discount_months?: number;
+        after_offer_monthly_pence?: number;
+    };
+}
+interface CouncilTaxProduct extends ProductBase {
+    category: 'council_tax';
+    details: {
+        local_authority: string;
+        region: 'england' | 'wales' | 'scotland';
+        band: 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I';
+        annual_charge_pence: number;
+        instalment_options?: (10 | 12)[];
+        single_occupant_discount_eligible?: boolean;
+        student_exemption_eligible?: boolean;
+    };
+}
+interface MobileProduct extends ProductBase {
+    category: 'mobile';
+    details: {
+        sub_type: 'sim_only' | 'pay_monthly_handset' | 'pay_as_you_go' | 'data_only';
+        data_allowance_gb: number | 'unlimited';
+        minutes: number | 'unlimited';
+        texts: number | 'unlimited';
+        network_name: string;
+        network_type: 'mno' | 'mvno';
+        contract_length_months: number;
+        handset_included?: boolean;
+        handset_model?: string | null;
+        five_g_included?: boolean;
+        eu_roaming_included?: boolean;
+    };
+}
+interface TvLicenceProduct extends ProductBase {
+    category: 'tv_licence';
+    details: {
+        licence_type: 'standard' | 'concessionary_blind' | 'over_75_pension_credit' | 'nursing_home';
+        annual_charge_pence: number;
+        payment_frequency_options: ('annual' | 'quarterly' | 'monthly')[];
+    };
+}
+interface HomeInsuranceProduct extends ProductBase {
+    category: 'home_insurance';
+    details: {
+        cover_type: 'buildings' | 'contents' | 'buildings_and_contents' | 'landlord';
+        contract_length_months: number;
+        voluntary_excess_pence?: number;
+        compulsory_excess_pence: number;
+        accidental_damage_included?: boolean;
+        legal_cover_included?: boolean;
+        home_emergency_included?: boolean;
+    };
+}
+interface BreakdownCoverProduct extends ProductBase {
+    category: 'breakdown_cover';
+    details: {
+        sub_type: 'boiler' | 'home_emergency' | 'vehicle';
+        contract_length_months: number;
+        callout_limit_per_year?: number | 'unlimited';
+        parts_included?: boolean;
+        labour_included?: boolean;
+    };
+}
+type Product = EnergyProduct | WaterProduct | BroadbandProduct | CouncilTaxProduct | MobileProduct | TvLicenceProduct | HomeInsuranceProduct | BreakdownCoverProduct;
+/**
+ * Response from GET /partner/sessions/:id/products.
+ * Partial results are valid: `products_complete: false` means discovery is still
+ * running and the embed should poll.
+ */
+interface ProductsResponse {
+    session_id: string;
+    products: Product[];
+    products_complete: boolean;
+    cache_status: CacheStatus;
+    total_suppliers_queried: number;
+    total_suppliers_responded: number;
+    next_cursor: string | null;
+}
+/** Query options for GET /products. */
+interface ProductsQuery {
+    cursor?: string;
+    limit?: number;
+    categories?: ProductCategory[];
+    include_previous?: boolean;
+    force_refresh?: boolean;
+}
+type DataCompleteness = 'complete' | 'partial' | 'empty';
+type PropertyTypeCode = 'house' | 'flat' | 'maisonette' | 'bungalow' | 'other';
+type PropertyTypeSubcode = 'detached' | 'semi_detached' | 'terraced' | 'end_terrace' | 'purpose_built_flat' | 'converted_flat' | 'studio' | 'penthouse' | 'other';
+type BuildingType = 'residential' | 'mixed_use' | 'commercial' | 'unknown';
+type BuildingStyle = 'victorian' | 'edwardian' | 'georgian' | 'interwar' | 'post_war' | 'modern' | 'new_build' | 'period' | 'unknown';
+interface NearbyPoi {
+    poi_id: string;
+    name: string;
+    sub: string;
+    distance_minutes: number;
+    mode: 'walk' | 'drive' | 'cycle' | 'tube';
+    icon_token: string;
+}
+type CollectionDay = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';
+type BinType = 'general_waste' | 'recycling' | 'food_waste' | 'garden_waste' | 'glass';
+type CollectionFrequency = 'weekly' | 'fortnightly' | 'monthly';
+interface BinCollectionPayload {
+    primary_collection_day: CollectionDay;
+    primary_collection_types: BinType[];
+    collection_frequency: CollectionFrequency;
+    /** ISO 'YYYY-MM-DD' or '' if not derivable from move_in_date */
+    next_collection_date: string;
+    days_after_move_in: number;
+    /** e.g. 'Tuesday evening' or '' */
+    reminder_eve_label: string;
+    secondary_collection_day?: CollectionDay;
+    secondary_collection_types?: BinType[];
+}
+interface PropertyDetailObject {
+    property_type_code?: PropertyTypeCode;
+    property_type_subcode?: PropertyTypeSubcode;
+    building_type?: BuildingType;
+    building_style?: BuildingStyle;
+    number_of_bedrooms?: number;
+    number_of_bathrooms?: number;
+    floor_number?: number;
+    energy_performance_rating?: 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G';
+    has_parking?: boolean;
+    property_has_off_road_parking?: boolean;
+    property_has_underground_parking?: boolean;
+    property_has_a_driveway?: boolean;
+    nearby?: NearbyPoi[];
+    bin_collection?: BinCollectionPayload;
+}
+interface PropertyDetailResponse {
+    session_id: string;
+    property: PropertyDetailObject;
+    data_completeness: DataCompleteness;
+    extracted_at: IsoDateTime;
+    expires_at: IsoDateTime;
+}
+
+/**
+ * Letter of Authority (LoA) types.
+ * GET /partner/sessions/:id/loa?product_ids=... returns one or more LoA templates
+ * covering the customer's product selection. URLs require Bearer auth and must
+ * be proxied server-side — never embedded in client HTML.
+ */
+
+type LoaId = string;
+interface LoaRecord {
+    loa_id: LoaId;
+    /**
+     * Bearer-gated URL to the PDF rendering of the LoA text.
+     * Never expose directly to the browser.
+     */
+    loa_text_url: Url;
+    /** Bearer-gated URL to an HTML rendering suitable for in-app display. */
+    loa_text_html_url: Url;
+    /** SHA-256 of the rendered LoA body — used to detect template changes mid-flow. */
+    checksum: string;
+    /** Product IDs whose switching this LoA authorises. */
+    covers_product_ids: ProductId[];
+    /** ISO 8601. Template expiry (~30 days). After this, fetch a fresh LoA. */
+    expires_at: IsoDateTime;
+    /** Template version, monotonically incremented on content change. */
+    version: 'loa-template-v4';
+}
+interface LoaListResponse {
+    session_id: string;
+    loas: LoaRecord[];
+}
+/**
+ * Signed LoA payload sent at POST /partner/sessions/:id/customers.
+ * `signed_checksum` MUST equal the LoA `checksum` at the time of signing —
+ * otherwise the server returns `loa.template_changed` and the embed must re-fetch + re-sign.
+ */
+interface LoASignature {
+    loa_id: LoaId;
+    signed_checksum: string;
+    /** ISO 8601 — client-reported sign time. Server stamps `signed_at_server`. */
+    signed_at_client: IsoDateTime;
+    /** Name as typed/signed by the customer. */
+    signed_by_full_name: string;
+    signature_image: SignatureImage;
+    /** Customer IP observed by the partner at signing time. */
+    ip_address?: string;
+    /** Customer user-agent observed by the partner at signing time. */
+    user_agent?: string;
+}
+/**
+ * PNG signature only (no JPEG). Re-encoded server-side via libpng; SVG is parsed
+ * and stripped. Decoded size ≤200KB, dimensions ≤2000×2000px. Recommended
+ * canvas: 800×240px.
+ */
+interface SignatureImage {
+    mime_type: 'image/png' | 'image/svg+xml';
+    /** Base64-encoded image bytes (no data: prefix). */
+    data_base64: string;
+    /** Optional capture width hint in pixels. */
+    width?: number;
+    /** Optional capture height hint in pixels. */
+    height?: number;
+}
+
+/**
+ * Customer creation and status types.
+ * POST /partner/sessions/:id/customers is idempotent — repeats return 200 with the
+ * existing customer_id, never 409.
+ */
+
+interface SavingsSummaryResponse {
+    customer_id: string;
+    time_saved_minutes: number;
+    annual_savings_pence: number;
+    services_set_up: number;
+    extracted_at: IsoDateTime;
+}
+
+type CustomerId = string;
+
+interface CreateCustomerInput {
+    selected_products: SelectedProduct[];
+    loa_signatures: LoASignature[];
+}
+interface SelectedProduct {
+    product_id: ProductId;
+    /** Shape varies by product category; current-address products only. */
+    onboarding_info?: OnboardingInfo;
+}
+interface OnboardingInfo {
+    meter_read_electricity?: number;
+    meter_read_gas?: number;
+    preferred_switch_date?: string;
+    preferred_install_date?: string;
+    existing_line_provider?: string;
+    keep_existing_number?: boolean;
+    moved_in_date?: string;
+    meter_read?: number;
+    notes?: string;
+}
+interface CustomerCreateResponse {
+    customer_id: CustomerId;
+    interstitial_url: string;
+    app_deeplinks: AppDeeplinks;
+    magic_link_sent: boolean;
+    product_setup: {
+        initiated: number;
+        products: ProductSetup[];
+    };
+}
+interface AppDeeplinks {
+    ios?: string;
+    android?: string;
+    universal: string;
+}
+/** Per-product setup state on creation. Status advances via setup_status webhooks. */
+interface ProductSetup {
+    product_id: ProductId;
+    setup_id: string;
+    category: ProductCategory;
+    sub_categories: string[];
+    supplier_name: string;
+    status: SetupStatus;
+    location: PropertyLocation;
+    status_updated_at: IsoDateTime;
+    max_retries_exceeded: boolean;
+    details?: {
+        account_number?: string;
+        switch_date?: IsoDate;
+        direct_debit_setup?: boolean;
+        notified_at?: IsoDateTime;
+        channel?: 'email' | 'api' | 'postal';
+        final_reads_submitted?: boolean;
+    };
+    expected_resolution_at?: IsoDateTime;
+}
+/**
+ * Status values on /partner/customers/:id/status.
+ * - `pending` / `in_progress` / `failed` are universal
+ * - `confirmed` only applies to current-address setups
+ * - `notified` / `acknowledged` only apply to previous-address (move-out) setups
+ */
+type SetupStatus = 'pending_setup' | 'in_progress' | 'awaiting_supplier' | 'confirmed' | 'notified' | 'acknowledged' | 'failed';
+type OverallStatus = 'pending' | 'in_progress' | 'confirmed' | 'partial' | 'failed';
+type MoveOutStatus = 'pending' | 'in_progress' | 'notified' | 'partial' | 'failed' | null;
+type SubscriptionStatus = 'not_subscribed' | 'trialing' | 'active' | 'past_due' | 'cancelled';
+/** GET /partner/customers/:id/status response. */
+interface CustomerStatusResponse {
+    customer_id: CustomerId;
+    overall_status: OverallStatus;
+    /** Null when no move.out was supplied — the two state machines run independently. */
+    move_out_status: MoveOutStatus;
+    subscription_status: SubscriptionStatus;
+    trial_ends_at: IsoDateTime | null;
+    products: Array<ProductSetup & {
+        last_updated_at: IsoDateTime;
+    }>;
+    last_updated_at: IsoDateTime;
+}
+
+/**
+ * Webhook event types.
+ * Delivery is at-least-once and out-of-order. Always dedupe on `event.id`.
+ * HMAC signature header: `X-HelloBill-Signature: t=<unix>,v1=<hex>` — verifyWebhook() parses + validates.
+ */
+
+type WebhookEventId = string;
+interface WebhookEventBase<TType extends string, TData> {
+    id: WebhookEventId;
+    type: TType;
+    event: TType;
+    created_at: IsoDateTime;
+    api_version: ApiVersion;
+    environment: Environment;
+    livemode: boolean;
+    data: TData & {
+        session_id: string;
+        /** Partner-controlled correlation, echoed from SessionPayload.referral_id. null when absent. */
+        referral_id: string | null;
+        /** Echo of SessionPayload.context (or [] when absent). */
+        context: ContextEntry[];
+    };
+}
+type SessionEmbedOpened = WebhookEventBase<'session.embed_opened', Record<string, never>>;
+type SessionDetailsConfirmed = WebhookEventBase<'session.details_confirmed', {
+    corrections: string[];
+}>;
+type SessionProductsSelected = WebhookEventBase<'session.products_selected', {
+    products: Array<{
+        product_id: ProductId;
+        category: ProductCategory;
+        sub_categories: string[];
+        location: PropertyLocation;
+    }>;
+}>;
+type SessionLoaSigned = WebhookEventBase<'session.loa_signed', {
+    loa_id: string;
+    /** Server-stamped at LoA signature time. Authoritative for LoA 12-month validity (see §17). Distinct from signed_at_client which is partner-supplied. */
+    signed_at_server: IsoDateTime;
+    signed_by_full_name: string;
+}>;
+type SessionAccountCreated = WebhookEventBase<'session.account_created', {
+    customer_id: CustomerId;
+}>;
+type SessionAppInstalled = WebhookEventBase<'session.app_installed', {
+    customer_id: CustomerId;
+    device_type: 'ios' | 'android';
+    installed_at: IsoDateTime;
+}>;
+type SessionAppDeferred = WebhookEventBase<'session.app_deferred', {
+    customer_id: CustomerId;
+    deferred_reason: string;
+}>;
+type SubscriptionChanged = WebhookEventBase<'subscription.changed', {
+    customer_id: CustomerId;
+    previous_status: SubscriptionStatus | null;
+    new_status: SubscriptionStatus;
+    trial_ends_at: IsoDateTime | null;
+}>;
+type SetupStatusChanged = WebhookEventBase<'setup_status.changed', {
+    customer_id: CustomerId;
+    product_id: ProductId;
+    setup_id: string;
+    category: ProductCategory;
+    sub_categories: string[];
+    supplier_name: string;
+    /** "current" = switching at new property; "previous" = closure flow at old property. */
+    location: PropertyLocation;
+    previous_status: SetupStatus;
+    new_status: SetupStatus;
+    max_retries_exceeded: boolean;
+    details?: ProductSetup['details'];
+}>;
+type MoveOutNotificationSent = WebhookEventBase<'move_out_notification.sent', {
+    customer_id: CustomerId;
+    setup_id: string;
+    product_id: ProductId;
+    category: ProductCategory;
+    supplier_name: string;
+    location: 'previous';
+    notified_at: IsoDateTime;
+    channel: 'email' | 'api' | 'postal';
+}>;
+type MoveOutNotificationFailed = WebhookEventBase<'move_out_notification.failed', {
+    customer_id: CustomerId;
+    setup_id: string;
+    product_id: ProductId;
+    category: ProductCategory;
+    supplier_name: string;
+    location: 'previous';
+    failed_at: IsoDateTime;
+    reason: string;
+    retry_scheduled_at?: IsoDateTime;
+}>;
+type BankDetailsCollected = WebhookEventBase<'bank_details.collected', {
+    bank_details_id: string;
+    account_number_ending: string;
+    sort_code_masked: MaskedSortCode;
+    modulus_check_passed: boolean;
+    collected_at: IsoDateTime;
+}>;
+type WebhookEvent = SessionEmbedOpened | SessionDetailsConfirmed | SessionProductsSelected | SessionLoaSigned | SessionAccountCreated | SessionAppInstalled | SessionAppDeferred | SubscriptionChanged | SetupStatusChanged | MoveOutNotificationSent | MoveOutNotificationFailed | BankDetailsCollected;
+type WebhookEventType = WebhookEvent['event'];
+
+export { type Meters as $, type Address as A, type BankDetailsRequest as B, type CreateCustomerInput as C, type Customer as D, type CustomerType as E, type DataCompleteness as F, type DiscoveryStatus as G, type Email as H, type EnergyProduct as I, type Environment as J, type EpcRating as K, type LoaListResponse as L, type FinalRead as M, type FuelType as N, type HeatingType as O, type ProductsQuery as P, type HomeInsuranceProduct as Q, type RequestId as R, type SessionPayload as S, type IdempotencyKey as T, type IsoDate as U, type IsoDateTime as V, type LoASignature as W, type LoaId as X, type LoaRecord as Y, type LocationRole as Z, type MaskedSortCode as _, type SessionResponse as a, type MobileProduct as a0, type MoveIn as a1, type MoveObject as a2, type MoveOut as a3, type MoveOutNotificationFailed as a4, type MoveOutNotificationSent as a5, type MoveOutNotifyFlags as a6, type MoveOutReason as a7, type MoveOutStatus as a8, type NearbyPoi as a9, type SessionAppInstalled as aA, type SessionDetailsConfirmed as aB, type SessionEmbedOpened as aC, type SessionLoaSigned as aD, type SessionProductsSelected as aE, type SetupStatus as aF, type SetupStatusChanged as aG, type SignatureImage as aH, type StoredBankDetails as aI, type SubscriptionChanged as aJ, type SubscriptionStatus as aK, type TvLicenceProduct as aL, type Url as aM, type WaterProduct as aN, type WebhookEvent as aO, type WebhookEventBase as aP, type WebhookEventId as aQ, type WebhookEventType as aR, type OccupantObject as aa, type OccupantType as ab, type OnboardingInfo as ac, type OverallStatus as ad, type Paginated as ae, type Person as af, type PhoneNumber as ag, type Postcode as ah, type Product as ai, type ProductBase as aj, type ProductCategory as ak, type ProductConfidence as al, type ProductId as am, type ProductSetup as an, type PropertyDetailObject as ao, type PropertyLocation as ap, type PropertyObject as aq, type PropertyType as ar, type PropertyTypeCode as as, type PropertyTypeSubcode as at, type ProvidedFieldPath as au, SESSION_IDEMPOTENCY_TTL_MS as av, type SavingsSummaryResponse as aw, type SelectedProduct as ax, type SessionAccountCreated as ay, type SessionAppDeferred as az, type SessionGetResponse as b, type ProductsResponse as c, type PropertyDetailResponse as d, type CustomerCreateResponse as e, type CustomerId as f, type CustomerStatusResponse as g, type BankDetailsResponse as h, type AddressObject as i, type AddressesObject as j, type ApiVersion as k, type AppDeeplinks as l, type BankDetailsCollected as m, type BankDetailsConsent as n, type BankDetailsObject as o, type BankDetailsStatus as p, type BillType as q, type BreakdownCoverProduct as r, type BroadbandProduct as s, type BuildingStyle as t, type BuildingType as u, type CacheStatus as v, type ClientMode as w, type Consent as x, type ContextEntry as y, type CouncilTaxProduct as z };