Embed SDK Integration Guide

npm install @hello-bill/node @hello-bill/sdk

import express from 'express';
import { createHellobillRouter } from '@hello-bill/node/express';

const app = express();
app.use(express.json());

app.use('/api/hellobill', createHellobillRouter({
  clientId:     process.env.HELLOBILL_CLIENT_ID,    // sb_… or live_…
  clientSecret: process.env.HELLOBILL_CLIENT_SECRET,

  buildSessionPayload: async (req) => ({
    customer:  { type: 'tenant', email: req.body.email },
    addresses: {
      current: {
        address_line_1: req.body.addressLine1,
        city:           req.body.city,
        postcode:       req.body.postcode,
      },
      // Optional: only when the customer is moving OUT of a previous property
      previous: req.body.previousAddress ?? undefined,
    },
    move: {
      in:  { move_in_date: req.body.moveInDate },
      // Optional: when partner wants HelloBill to notify incumbents at the previous address
      out: req.body.moveOut ?? undefined,
    },
    consent: { data_sharing_accepted: true, data_sharing_accepted_at: new Date().toISOString() },
  }),
}));

<script src="https://embed-sandbox.hellobill.app/v1/sdk.js"></script>
<div id="hellobill-mount"></div>
<script>
  HelloBill.init({
    baseEndpoint: '/api/hellobill',
    mountTo: '#hellobill-mount',
    sessionData: {
      email: currentCustomer.email,
      addressLine1: property.addressLine1,
      addressLine3: property.addressLine3,        // NEW v11 — optional 3rd line
      city:         property.city,
      postcode:     property.postcode,
      moveInDate:   occupancy.moveInDate,
      // Optional B2B: customer's billing address differs from property
      customerAddress: currentCustomer.address,
      // Optional move-out journey
      previousAddress: previousProperty,           // PropertyObject; null when no move-out
      moveOut: undefined,                          // MoveOutObject; omit for move-in only
    },
    onComplete(result) {
      window.location.href = '/move/complete?account=' + result.customer_id;
    },
  });
</script>

POST /api/v1/auth/partner/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=sb_goodlord_abc&client_secret=***

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}

{
  "referral_id": "REF-2026-05-10-abc123",

  "customer": {
    "type": "tenant",
    "first_name": "Anya",
    "last_name": "Haq",
    "email": "anya@example.com",
    "phone": "+447700900000",
    "date_of_birth": "1995-03-15",
    "is_primary_occupant": true,
    "on_psr": false,
    "address": {
      "address_line_1": "Goodlord Lettings",
      "address_line_2": "Unit 4, Lensbury Way",
      "address_line_3": "Thamesmead",
      "city": "London",
      "postcode": "SE2 9TG"
    }
  },

  "occupants": [
    {
      "type": "tenant",
      "first_name": "James",
      "last_name": "Haq",
      "email": "james@example.com",
      "phone": "+447700900001",
      "is_primary_occupant": false
    }
  ],

  "addresses": {
    "current": {
      "address_line_1": "14 Clapham Road",
      "address_line_2": "Flat 3",
      "address_line_3": null,
      "city": "London",
      "postcode": "SW8 2JB",
      "uprn": "100023456789",
      "bedrooms": 2,
      "number_occupants": 2,
      "property_type": "flat",
      "epc_rating": "C",
      "heating_type": "gas_central"
    },
    "previous": {
      "address_line_1": "Holly Cottage",
      "address_line_2": "Mill Lane",
      "address_line_3": "Saxton-cum-Scarthingwell",
      "city": "Tadcaster",
      "postcode": "LS24 9PX",
      "uprn": "100022345678",
      "property_type": "house"
    }
  },

  "move": {
    "in": {
      "move_in_date": "2026-06-01",
      "bill_type": "single",
      "rent_pcm": 1450,
      "tenancy_start_date": "2026-06-01",
      "tenancy_end_date": "2027-05-31"
    },
    "out": {
      "move_out_date": "2026-05-30",
      "tenancy_end_date": "2026-05-31",
      "reason": "end_of_tenancy",
      "forwarding_address": {
        "address_line_1": "14 Clapham Road",
        "address_line_2": "Flat 3",
        "city": "London",
        "postcode": "SW8 2JB"
      },
      "notify": {
        "energy":      true,
        "water":       true,
        "council_tax": true,
        "tv_licence":  false,
        "broadband":   true,
        "mobile":      false
      },
      "final_reads": [
        {
          "category": "energy",
          "fuel": "electricity",
          "meter_serial_number": "S95L00012345",
          "reading": 42180,
          "read_date": "2026-05-30"
        },
        {
          "category": "energy",
          "fuel": "gas",
          "meter_serial_number": "G4A00098765",
          "reading": 9817,
          "read_date": "2026-05-30"
        }
      ]
    }
  },

  "meters": {
    "mpan": "1900000123456",
    "mprn": "7612345678",
    "current_supplier_electricity": "British Gas",
    "current_supplier_gas": "British Gas"
  },

  "consent": {
    "data_sharing_accepted": true,
    "marketing_accepted": false,
    "data_sharing_accepted_at": "2026-05-10T14:30:00Z"
  },

  "context": [
    { "name": "device_type",    "type": "string",  "value": "iPhone 16 Pro" },
    { "name": "utm_source",     "type": "string",  "value": "email" },
    { "name": "utm_campaign",   "type": "string",  "value": "move_in_2026_q2" },
    { "name": "gl_tenancy_id",  "type": "string",  "value": "TEN-89234" },
    { "name": "session_seconds","type": "number",  "value": 42 }
  ]
}

"context": [
  { "name": "device_type",   "type": "string",  "value": "iPhone 16 Pro" },
  { "name": "utm_source",    "type": "string",  "value": "email" },
  { "name": "gl_tenancy_id", "type": "string",  "value": "TEN-89234" },
  { "name": "session_seconds","type": "number", "value": 42 },
  { "name": "marketing_opt_in","type": "boolean","value": false }
]

| { name: string; type: 'string';  value: string  }
| { name: string; type: 'number';  value: number  }
| { name: string; type: 'boolean'; value: boolean }

{
  "session_id": "ses_01HX7G2K...",
  "session_token": "eyJhbGciOiJIUzI1NiIs...",
  "embed_base_url": "https://embed-sandbox.hellobill.app",
  "discovery_status": "running",
  "estimated_ready_seconds": 8,
  "provided_fields": [
    "customer.first_name", "customer.last_name", "customer.email",
    "addresses.current.postcode", "addresses.current.address_line_1",
    "addresses.current.bedrooms", "move.in.move_in_date",
    "addresses.previous.postcode", "addresses.previous.address_line_1",
    "move.out.move_out_date", "move.out.forwarding_address.postcode",
    "move.out.notify.energy", "move.out.notify.water"
  ],
  "expires_at": "2026-05-11T14:30:00Z",
  "gmaps_key": "AIza..."
}

{
  "sessions": [
    {
      "session_id": "ses_01HX7G2K...",
      "referral_id": "REF-2026-05-10-abc123",
      "email": "anya@example.com",
      "postcode": "SW8 2JB",
      "address_line_1": "14 Clapham Road",
      "status": "customer_created",
      "customer_id": "CU-7310-5480-8",
      "created_at": "2026-05-10T14:30:00Z",
      "expires_at": "2026-05-11T14:30:00Z"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}

GET /api/v1/partner/sessions/ses_01HX7G2K...
Authorization: Bearer {access_token}

{
  "sort_code": "089999",
  "account_number": "66374958",
  "account_holder_name": "John Smith",
  "consent": {
    "direct_debit_authorised": true,
    "authorised_at": "2026-05-19T10:00:00Z",
    "consent_text_version": "ddg-v1"
  }
}

{
  "session_id": "ses_abc123",
  "bank_details": {
    "id": "bnk_xyz789",
    "account_number_ending": "4958",
    "sort_code_masked": "08-**-99",
    "account_holder_name": "John Smith",
    "bank_name": "Barclays",
    "modulus_check_passed": true,
    "status": "collected",
    "collected_at": "2026-05-19T10:00:01Z",
    "consent": {
      "direct_debit_authorised": true,
      "authorised_at": "2026-05-19T10:00:00Z",
      "consent_text_version": "ddg-v1"
    }
  },
  "expires_at": "2026-05-20T10:00:00Z"
}

GET /api/v1/partner/sessions/ses_abc123/bank-details
Authorization: Bearer {access_token}

// app/api/hellobill/[...slug]/route.ts
import { createHellobillHandler } from '@hello-bill/node/next';

export const POST = createHellobillHandler({
  clientId:     process.env.HELLOBILL_CLIENT_ID!,
  clientSecret: process.env.HELLOBILL_CLIENT_SECRET!,
  buildSessionPayload: async (req) => {
    const body = await req.json();
    return {
      referral_id: body.referralId,
      customer: { type: 'tenant', email: body.email, first_name: body.firstName, last_name: body.lastName },
      addresses: {
        current: { address_line_1: body.addressLine1, city: body.city, postcode: body.postcode, bedrooms: body.bedrooms },
        previous: body.previousAddress ?? undefined,
      },
      move: {
        in:  { move_in_date: body.moveInDate, bill_type: body.billType ?? 'single' },
        out: body.moveOut ?? undefined,
      },
      consent: { data_sharing_accepted: true, data_sharing_accepted_at: new Date().toISOString() },
      context: [{ name: 'gl_tenancy_id', type: 'string', value: body.tenancyId }],
    };
  },
});

export const GET = POST;  // Same handler serves all sub-paths

HelloBillEmbed.init({
  // ...
  onEvent: (event) => {
    // Stable, low-cardinality — feed your funnel.
    analytics.track('hellobill.lifecycle', event);
  },
  onUserAction: (action) => {
    // Information-dense, evolving — feed your product analytics.
    if (action.type === 'product.chosen') {
      productAnalytics.track('product_selected', action.data);
    }
  },
});

GET /api/v1/partner/sessions/ses_01HX.../property
Authorization: Bearer {access_token}

{
  "session_id": "ses_01HX...",
  "property": {
    "property_type_code": "house",
    "property_type_subcode": "terraced",
    "building_type": "residential",
    "building_style": "victorian",
    "number_of_bedrooms": 3,
    "number_of_bathrooms": 1.5,
    "floor_number": 0,
    "energy_performance_rating": "D",
    "has_parking": true,
    "property_has_off_road_parking": true,
    "property_has_underground_parking": false,
    "property_has_a_driveway": true,
    "bin_collection": {
      "primary_collection_day": "wednesday",
      "primary_collection_types": ["general_waste", "recycling"],
      "collection_frequency": "fortnightly",
      "next_collection_date": "2026-06-03",
      "days_after_move_in": 2,
      "reminder_eve_label": "Tuesday evening",
      "secondary_collection_day": "wednesday",
      "secondary_collection_types": ["food_waste"]
    }
  },
  "data_completeness": "partial",
  "extracted_at": "2026-05-13T14:50:00Z",
  "expires_at": "2026-05-14T14:50:00Z",
  "broadband": {
    "max_down_speed_mbps": 1000,
    "max_up_speed_mbps": 220
  }
}

HelloBill.init({
  baseEndpoint: '/api/hellobill',
  mountTo: '#hellobill-mount',
  sessionData: { /* … */ },

  appearance: {
    theme: 'hellobill',                 // 'hellobill' | 'light' | 'dark' | 'system'
    disableAnimations: false,           // honours OS prefers-reduced-motion regardless
    variables: {
      colorPrimary:         '#1a73e8',
      colorOnPrimary:       '#ffffff',
      colorBackground:      '#ffffff',
      colorSurface:         '#f7f9fc',
      colorBorder:          '#e4e8ee',
      colorText:            '#0f172a',
      colorTextSecondary:   '#475569',
      colorTextPlaceholder: '#94a3b8',
      colorTextDisabled:    '#cbd5e1',
      colorDanger:          '#c43c3c',
      colorSuccess:         '#16a34a',
      colorWarning:         '#b97900',
      fontFamily:           'Inter, -apple-system, sans-serif',
      fontSizeBase:         '16px',
      fontLineHeight:       '1.55',
      fontWeightNormal:     '400',
      fontWeightMedium:     '500',
      fontWeightBold:       '700',
      spacingUnit:          '4px',
      gridRowSpacing:       '16px',
      gridColumnSpacing:    '16px',
      borderRadius:         '8px',
      buttonBorderRadius:   '8px',
      focusBoxShadow:       '0 0 0 3px rgba(26,115,232,0.25)',
      focusOutline:         '2px solid #1a73e8',
      iconColor:            '#475569',
      iconHoverColor:       '#0f172a',
      iconCheckmarkColor:   '#ffffff',
    },
    rules: {
      '.HBButton':                 { fontWeight: '600' },
      '.HBButton:hover':           { boxShadow: '0 2px 8px rgba(0,0,0,0.08)' },
      '.HBInput':                  { borderColor: '#dbe2ea' },
      '.HBInput:focus':            { borderColor: '#1a73e8' },
      '.HBInput--invalid':         { borderColor: '#c43c3c' },
      '.HBCard':                   { boxShadow: '0 1px 3px rgba(0,0,0,0.04)' },
      '.HBCard--selected':         { borderColor: '#1a73e8' },
    },
  },

  locale: 'en-GB',                      // 'auto' | 'en' | 'en-GB' | 'cy-GB'
});

embed.updateAppearance({ theme: 'dark' });   // merges; partial updates supported
embed.updateAppearance({ variables: { colorPrimary: '#ff8800' } });
embed.setLocale('cy-GB');                    // also re-renders strings
embed.destroy();                             // unmounts and tears down listeners

HelloBill.init({
  baseEndpoint: '/api/hellobill',
  mountTo: '#hellobill-mount',
  sessionData: { /* ... */ },
  integrations: {
    gmapsKey: process.env.NEXT_PUBLIC_GMAPS_KEY,
  },
});

X-HelloBill-Signature: t=1715349660,v1=8a3f9c2b7e4d...

import crypto from 'node:crypto';
import express from 'express';

const TOLERANCE_SECONDS = 300;

function verifyWebhook(rawBody: Buffer, header: string, secret: string): boolean {
  // Parse header: "t=1715349660,v1=8a3f..."
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('=', 2) as [string, string])
  );
  const t = parseInt(parts.t, 10);
  if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;

  // Iterate over all v* schemes present; accept if any verifies
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.`).update(rawBody)   // raw bytes — do NOT parse JSON first
    .digest('hex');

  for (const [k, v] of Object.entries(parts)) {
    if (k.startsWith('v') && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected))) {
      return true;
    }
  }
  return false;
}

app.post('/webhooks/hellobill',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-hellobill-signature'] as string;
    if (!verifyWebhook(req.body, sig, process.env.HELLOBILL_WEBHOOK_SECRET!)) {
      return res.status(401).json({ error: 'invalid_signature' });
    }
    const event = JSON.parse(req.body.toString());
    // deduplicate on event.id, then process
    res.json({ received: true });
  }
);

{
  "type": "bank_details.collected",
  "event": "bank_details.collected",
  "id": "evt_01HX...",
  "created_at": "2026-05-19T10:00:01Z",
  "api_version": "2026-05-10",
  "livemode": false,
  "environment": "sandbox",
  "data": {
    "session_id": "ses_abc123",
    "referral_id": "REF-2026-05-10-abc123",
    "context": [],
    "bank_details_id": "bnk_xyz789",
    "account_number_ending": "4958",
    "sort_code_masked": "08-**-99",
    "modulus_check_passed": true,
    "collected_at": "2026-05-19T10:00:01Z"
  }
}

{
  "error": {
    "type":       "invalid_request",
    "code":       "validation.failed",
    "message":    "addresses.current.postcode: String must contain at least 3 character(s)",
    "request_id": "req_01HX7G2K..."
  }
}

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 43
X-RateLimit-Reset: 1715349660
X-HelloBill-Request-Id: req_01HX7G2K...

T+0s   pending_setup    → in_progress
T+5s   in_progress      → awaiting_supplier
T+30s  awaiting_supplier→ confirmed (80%) or failed (20%)
T+40s  failed           → in_progress (auto-retry)
T+60s  in_progress      → confirmed (always succeeds on retry in sandbox)

T+0s    pending_setup → in_progress
T+10s   in_progress   → notified  (90% — supplier accepts notification)
T+10s   in_progress   → failed    (10% — supplier rejects, e.g. account not found)
T+20s   failed        → in_progress (auto-retry)
T+30s   in_progress   → notified  (always succeeds on retry in sandbox)

interface SessionPayload {
  referral_id?: string;
  customer:    CustomerObject;       // required
  occupants?:  OccupantObject[];
  addresses:   AddressesObject;      // required — grouped current + optional previous
  move:        MoveObject;           // required — grouped in (required) + out (optional)
  meters?:     MetersObject;         // optional — current-address meter identifiers
  consent:     ConsentObject;        // required
  context?:    ContextEntry[];       // optional — max 50 entries
}

interface SessionResponse {
  session_id:               string;
  session_token:            string;          // HS256 JWT, 300 s
  embed_base_url:           string;          // embed ORIGIN only; SDK composes {embed_base_url}/{version}/onboard?token=...
  discovery_status:         'running' | 'complete';
  estimated_ready_seconds?: number;          // omitted when discovery_status is 'complete'
  provided_fields:          string[];        // dot-notation paths
  expires_at:               string;          // ISO 8601, 24 h from creation
  gmaps_key?:               string;          // Google Maps Embed API key; SDK forwards to iframe
}

interface AddressObject {
  address_line_1: string;            // required
  address_line_2?: string;
  address_line_3?: string;           // optional — rural / multi-building / industrial estate
  city:            string;           // required
  postcode:        string;           // required, UK format
  uprn?:           string;           // canonical when supplied
  country?:        'GB';             // reserved for future expansion
}

interface PropertyObject extends AddressObject {
  bedrooms?:        number;
  number_occupants?: number;
  property_type?:   PropertyType;
  epc_rating?:      'A'|'B'|'C'|'D'|'E'|'F'|'G';
  heating_type?:    HeatingType;
}
type PropertyType = 'detached'|'semi_detached'|'terraced'|'flat'|'bungalow'|'maisonette'|'other';
type HeatingType  = 'gas_central'|'electric'|'oil'|'heat_pump'|'district'|'solid_fuel'|'other';

interface AddressesObject {
  current:   PropertyObject;
  previous?: PropertyObject;
}

// Returned by GET /partner/sessions/:id/property
type CollectionDay = 'monday'|'tuesday'|'wednesday'|'thursday'|'friday'|'saturday'|'sunday';
type BinType = 'general_waste'|'recycling'|'food_waste'|'garden_waste'|'glass';
interface BinCollectionPayload {
  primary_collection_day:      CollectionDay;
  primary_collection_types:    BinType[];
  collection_frequency:        'weekly'|'fortnightly'|'monthly';
  next_collection_date:        string;     // ISO date
  days_after_move_in:          number;     // int >= 0
  reminder_eve_label:          string;
  secondary_collection_day?:   CollectionDay;
  secondary_collection_types?: BinType[];
}
interface BroadbandAvailability {
  max_down_speed_mbps?: number;   // >= 0
  max_up_speed_mbps?:   number;   // >= 0
}
interface PropertyDetailResponse {
  session_id:        string;
  property:          PropertyDetailObject;   // may be {} when data_completeness === 'empty'
  data_completeness: 'complete' | 'partial' | 'empty';
  extracted_at:      string;
  expires_at:        string;
  broadband?:        BroadbandAvailability;  // added 1.16
}

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;
  bin_collection?:                   BinCollectionPayload;  // added 1.16
}
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';
type LocationRole        = 'current' | 'previous';

interface CustomerObject {
  type:                CustomerType;
  email:               string;
  first_name?:         string;
  last_name?:          string;
  phone?:              string;
  date_of_birth?:      string;        // YYYY-MM-DD
  is_primary_occupant?: boolean;       // default: true
  on_psr?:             boolean;
  address?:            AddressObject;  // optional — defaults to addresses.current
}
type CustomerType = 'owner_occupier'|'tenant'|'licensee'|'lodger'|'management_company'|'other';

interface OccupantObject {
  type:                OccupantType;
  first_name?:         string;
  last_name?:          string;
  email?:              string;
  phone?:              string;
  is_primary_occupant?: boolean;
}
type OccupantType = 'owner'|'tenant'|'licensee'|'lodger'|'guarantor'|'other';

interface MoveObject {
  in:   MoveInObject;
  out?: MoveOutObject;
}

interface MoveInObject {
  move_in_date:         string;          // required, YYYY-MM-DD
  bill_type?:           'single'|'split'; // default: 'single'
  rent_pcm?:            number;           // integer GBP/month
  tenancy_start_date?:  string;
  tenancy_end_date?:    string;
}

interface MoveOutObject {
  move_out_date:        string;          // required, YYYY-MM-DD
  tenancy_end_date?:    string;
  reason?:              MoveOutReason;
  forwarding_address?:  AddressObject;
  notify?: {
    energy?:        boolean;
    water?:         boolean;
    council_tax?:   boolean;
    tv_licence?:    boolean;
    broadband?:     boolean;
    mobile?:        boolean;
  };
  final_reads?:         FinalReadObject[];
}
type MoveOutReason = 'end_of_tenancy'|'sale'|'transfer'|'bereavement'|'other';

interface FinalReadObject {
  category:              'energy'|'water';
  fuel?:                 'electricity'|'gas';     // only for energy
  meter_serial_number?:  string;
  reading:               number;
  read_date:             string;                   // YYYY-MM-DD
  photo_data_base64?:    string;                   // PNG, max 500 KB decoded
  estimated?:            boolean;
}

interface MetersObject {
  mpan?: string;
  mprn?: string;
  current_supplier_electricity?: string;
  current_supplier_gas?: string;
}

interface ConsentObject {
  data_sharing_accepted:    true;
  data_sharing_accepted_at: string;
  marketing_accepted?:      boolean;
}

type ContextEntry =
  | { name: string; type: 'string';  value: string  }
  | { name: string; type: 'number';  value: number  }
  | { name: string; type: 'boolean'; value: boolean };

type Category =
  | 'energy' | 'water' | 'broadband' | 'council_tax' | 'mobile' | 'tv_licence'
  | 'home_insurance' | 'breakdown_cover';

interface ProductBase {
  product_id:          string;          // PR-NNNN-NNNN-C
  category:            Category;
  sub_categories:      string[];
  supplier_name:       string;
  supplier_logo_url?:  string | null;
  location:            LocationRole;    // 'current' | 'previous' — server-derived
  is_incumbent:        boolean;
  monthly_amount_pence?: number;
  annual_amount_pence?:  number;
  confidence:          'high'|'medium'|'low';
  tariff_name?:        string | null;
  note?:               string;
  extracted_at:        string;
  expires_at:          string;
}

type CacheStatus = 'fresh' | 'partial' | 'throttled';   // 'cached' is not emitted

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;
}

interface ProductSetup {
  product_id:           string;
  setup_id:             string;
  category:             string;
  sub_categories:       string[];
  supplier_name:        string;
  location:             LocationRole;
  status:               SetupStatus;
  status_updated_at:    string;
  max_retries_exceeded: boolean;
  details?: {
    account_number?:     string;
    switch_date?:        string;
    direct_debit_setup?: boolean;
    notified_at?:        string;
    channel?:            'email'|'api'|'postal';
    final_reads_submitted?: boolean;
  };
  expected_resolution_at?: string;
}

type SetupStatus =
  | 'pending_setup' | 'in_progress' | 'awaiting_supplier'
  | 'confirmed'     // location: 'current' only
  | 'notified'      // location: 'previous' only
  | 'acknowledged'  // location: 'previous' only
  | 'failed';

interface LoaRecord {
  loa_id:              string;
  loa_text_url:        string;         // Bearer-gated PDF URL — proxy server-side only
  loa_text_html_url:   string;         // (1.17) session-token-gated document URL → GET /api/v1/partner/loa/:id/document → { body_html, checksum }
  covers_product_ids:  string[];
  checksum:            string;         // SHA-256 of LoA body — submit as signed_checksum
  expires_at:          string;
  version:             string;         // e.g. 'loa-template-v4'
}

interface LoaListResponse {
  session_id: string;
  loas:       LoaRecord[];
}

interface SignatureImage {
  mime_type:   'image/png' | 'image/jpeg';  // SVG is not accepted
  data_base64: string;                       // base64 payload only (strip data: URI prefix)
  width?:      number;                       // 1 <= w <= 2000
  height?:     number;                       // 1 <= h <= 1000
}

interface LoaSignature {   // used in POST /loa body and in loa_signatures[] on /customers
  loa_id:              string;
  signed_checksum:     string;
  signed_at_client:    string;   // ISO 8601 datetime — advisory audit metadata only
  signed_by_full_name: string;   // max 200 chars
  signature_image:     SignatureImage;
  ip_address?:         string;
  user_agent?:         string;   // max 500 chars
}

interface SubmitLoaResponse {
  loa_id:              string;
  signed_at_server:    string;   // authoritative UTC timestamp — determines 12-month validity
  signed_by_full_name: string;
}

interface BankDetailsRequest {
  sort_code: string;           // 6 digits, may include hyphens/spaces
  account_number: string;      // 6-10 digits
  account_holder_name: string;
  consent: BankDetailsConsent;
}

interface BankDetailsConsent {
  direct_debit_authorised: true;
  authorised_at: string;       // ISO-8601
  consent_text_version: string;
}

interface BankDetailsObject {
  id: string;
  account_number_ending: string; // last 4 digits
  sort_code_masked: string;      // format "NN-**-NN"
  account_holder_name: string;
  bank_name?: string;            // best-effort lookup; may be null
  modulus_check_passed: boolean;
  status: 'collected' | 'pending' | 'failed';
  collected_at: string;          // ISO-8601
  consent: BankDetailsConsent;
}

interface BankDetailsResponse {
  session_id: string;
  bank_details: BankDetailsObject;
  expires_at: string;            // ISO-8601
}

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';

type IsoDateTime = string;
type CustomerId  = string;

interface SavingsSummaryResponse {  // (1.17) — also available via GET /partner/customers/:id/savings-summary
  customer_id:          string;
  annual_savings_pence: number;   // realized savings; 0 until setups confirm
  time_saved_minutes:   number;
  services_set_up:      number;   // count of confirmed setups at snapshot time
  extracted_at:         IsoDateTime;
}

interface CustomerStatusResponse {
  customer_id:         string;
  overall_status:      OverallStatus;
  move_out_status:     MoveOutStatus;    // null when no move.out
  subscription_status: SubscriptionStatus;
  trial_ends_at:       IsoDateTime | null;
  products: Array<ProductSetup & {
    last_updated_at: IsoDateTime;
  }>;
  last_updated_at:     IsoDateTime;
  savings_summary:     SavingsSummaryResponse | null;  // (1.17) null pre-terminal; populated once overall_status === 'confirmed'
}

interface CustomerCreateResponse {
  customer_id:       CustomerId;
  interstitial_url?: string;          // optional — handoff page to install the app
  app_deeplinks?: {
    ios?:      string;
    android?:  string;
    universal: string;
  };
  magic_link_sent:   boolean;
  loa_required:      boolean;         // added 1.16: true when an LoA signature is still outstanding
  product_setup: {
    initiated: number;
    products:  ProductSetup[];
  };
}

interface WebhookEnvelope {
  id:           string;
  type:         string;          // primary event-type field
  event:        string;          // alias for `type` — same value, for v1.10 back-compat
  created_at:   string;
  api_version:  string;
  livemode:     boolean;         // true when environment === 'production'
  environment:  'production' | 'sandbox';
  data: {
    session_id:  string;
    referral_id: string | null;
    context:     ContextEntry[];
    [key: string]: unknown;
  };
}

type WebhookEvent = WebhookEnvelope & (
  | { type: 'session.embed_opened';
      data: WebhookEnvelope['data'] }
  | { type: 'session.details_confirmed';
      data: WebhookEnvelope['data'] & { corrections: string[] } }
  | { type: 'session.products_selected';
      data: WebhookEnvelope['data'] & {
              products: Array<{ product_id: string; category: Category;
                                sub_categories: string[]; location: LocationRole }> } }
  | { type: 'session.loa_signed';
      data: WebhookEnvelope['data'] & {
              loa_id: string; signed_at_server: IsoDateTime; signed_by_full_name: string } }
  | { type: 'session.account_created';
      data: WebhookEnvelope['data'] & { customer_id: CustomerId } }
  | { type: 'session.app_installed';
      data: WebhookEnvelope['data'] & {
              customer_id: CustomerId; device_type: 'ios'|'android';
              installed_at: IsoDateTime } }
  | { type: 'session.app_deferred';
      data: WebhookEnvelope['data'] & {
              customer_id: CustomerId; deferred_reason: string } }
  | { type: 'subscription.changed';
      data: WebhookEnvelope['data'] & {
              customer_id: CustomerId; previous_status: SubscriptionStatus | null;
              new_status: SubscriptionStatus; trial_ends_at: IsoDateTime | null } }
  | { type: 'setup_status.changed';
      data: WebhookEnvelope['data'] & {
              customer_id: CustomerId; product_id: string; setup_id: string;
              category: Category; sub_categories: string[]; supplier_name: string;
              location: LocationRole; previous_status: SetupStatus; new_status: SetupStatus;
              max_retries_exceeded: boolean; details?: ProductSetup['details'] } }
  | { type: 'move_out_notification.sent';
      data: WebhookEnvelope['data'] & {
              customer_id: CustomerId; setup_id: string; product_id: string;
              category: Category; supplier_name: string; location: 'previous';
              notified_at: IsoDateTime; channel: 'email'|'api'|'postal' } }
  | { type: 'move_out_notification.failed';
      data: WebhookEnvelope['data'] & {
              customer_id: CustomerId; setup_id: string; product_id: string;
              category: Category; supplier_name: string; location: 'previous';
              failed_at: IsoDateTime; reason: string; retry_scheduled_at?: IsoDateTime } }
  | { type: 'bank_details.collected';
      data: WebhookEnvelope['data'] & {
              bank_details_id: string; account_number_ending: string;
              sort_code_masked: string; modulus_check_passed: boolean;
              collected_at: IsoDateTime } }
);

type ErrorType =
  | 'invalid_request' | 'invalid_credentials' | 'not_found'
  | 'rate_limited' | 'idempotency_conflict' | 'mode_not_implemented' | 'internal';

type ErrorCode =
  | 'validation.failed'
  | 'loa.products_required'
  | 'signature_image.invalid'
  | 'customer.products_required'
  | 'customer.product_not_in_catalog'
  | 'auth.invalid_credentials'
  | 'session.not_found'
  | 'customer.not_found'
  | 'loa.not_found'
  | 'bank_details.not_found'
  | 'idempotency.fingerprint_mismatch'
  | 'loa.already_signed'
  | 'loa.selection_changed'
  | 'bank_details.session_locked'
  | 'customer.session_already_has_customer'
  | 'loa.template_changed'
  | 'bank_details.invalid_modulus'
  | 'property.discovery_in_progress'
  | 'rate.limited'
  | 'internal.error'
  | 'mode.live_not_implemented';

interface ErrorEnvelope {
  error: {
    type:            ErrorType;
    code:            ErrorCode;
    message:         string;
    request_id:      string;
    param?:          string;
    missing_fields?: string[];
    details?:        Record<string, unknown>;
  };
}

type ThemePreset = 'hellobill' | 'light' | 'dark' | 'system';
type Locale      = 'auto' | 'en' | 'en-GB' | 'cy-GB';

interface AppearanceObject {
  theme?:             ThemePreset;
  disableAnimations?: boolean;
  variables?:         AppearanceVariables;
  rules?:             AppearanceRules;
}

interface AppearanceVariables {
  colorPrimary?: string;        colorOnPrimary?: string;
  colorBackground?: string;     colorSurface?: string;
  colorBorder?: string;         colorText?: string;
  colorTextSecondary?: string;  colorTextPlaceholder?: string;
  colorTextDisabled?: string;   colorDanger?: string;
  colorSuccess?: string;        colorWarning?: string;
  iconColor?: string;           iconHoverColor?: string;
  iconCheckmarkColor?: string;  fontFamily?: string;
  fontSizeBase?: string;        fontLineHeight?: string;
  fontWeightNormal?: string;    fontWeightMedium?: string;
  fontWeightBold?: string;      spacingUnit?: string;
  gridRowSpacing?: string;      gridColumnSpacing?: string;
  borderRadius?: string;        buttonBorderRadius?: string;
  focusBoxShadow?: string;      focusOutline?: string;
}

type AppearanceSelector =
  | '.HBLabel'
  | '.HBInput' | '.HBInput:focus' | '.HBInput:hover'
  | '.HBInput--invalid' | '.HBInput::placeholder'
  | '.HBButton' | '.HBButton:hover' | '.HBButton:focus' | '.HBButton:disabled'
  | '.HBCard' | '.HBCard--selected' | '.HBCard:hover'
  | '.HBCheckbox' | '.HBCheckboxLabel' | '.HBCheckboxInput'
  | '.HBRadioIcon' | '.HBRadioIconOuter' | '.HBRadioIconInner'
  | '.HBTab' | '.HBTab:hover' | '.HBTab--selected'
  | '.HBAccordionItem' | '.HBError' | '.HBMenu' | '.HBMenuAction';

type AppearanceRules = Partial<Record<AppearanceSelector, Record<string, string>>>;

type LifecycleEventType =
  | 'ready' | 'session.created' | 'consent.granted' | 'screen.shown'
  | 'loa.signed' | 'account.creating' | 'account.created'
  | 'error' | 'complete' | 'close';

interface CompletionResult {
  customer_id:          string;
  selected_products:    { product_id: string; location: 'current' | 'previous' }[];
  loa_signed_at?:       string;
  setup_status?:        OverallStatus;
  move_out_status?:     MoveOutStatus | null;
}

interface InitOptions {
  baseEndpoint:     string;
  mountTo:          string | HTMLElement;
  sessionData:      SessionData;
  embedOrigin?:     string;          // default 'https://embed-sandbox.hellobill.app'; dev/UAT override only — ignored when NODE_ENV==='production'
  locale?:          Locale;
  appearance?:      AppearanceObject;
  integrations?:    { gmapsKey?: string };
  onComplete?:      (result: CompletionResult) => void;
  onClose?:         (reason: 'user_dismissed' | 'timeout' | 'error') => void;
  onEvent?:         (event: { type: LifecycleEventType; data: Record<string, unknown> }) => void;
  onUserAction?:    (action: { type: string; data: Record<string, unknown> }) => void;
}

interface EmbedHandle {
  updateAppearance(patch: Partial<AppearanceObject>): void;
  setLocale(locale: Locale): void;
  destroy(): void;
}