@thg-agentic/hyper-personalisation-web 0.0.0-stage → 3.18.0

package/README.md

@@ -1,3 +1,861 @@
-# Temporary Holding Version
+# @thg-agentic/hyper-personalisation-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser SDK for THG Hyper-Personalisation, a customer data platform. It implements the event
+specification (spec 1.10, stamped on every event as `context.spec.version`) for any storefront: it
+sends events in the Segment wire format, applies consent strictly whichever CMP the site uses, reads
+the GA4 `dataLayer` the site already pushes to, and has no runtime dependencies.
+
+The core knows standards only: GA4 and Segment. A **preset** teaches it one commerce platform's
+conventions; none ships with the SDK, and you can write your own in about 20 lines.
+
+```sh
+npm i @thg-agentic/hyper-personalisation-web
+```
+
+Or, without a bundler, the [CDN script](#cdn-script).
+
+## Integrating in one call
+
+```js
+import { bootstrap } from '@thg-agentic/hyper-personalisation-web/bootstrap';
+
+const hp = await bootstrap(
+  { writeKey: 'hp_pk_live_…' },
+  {
+    consent: { provider: 'onetrust' },
+    identityCookies: { sessionId: 'session_id' },
+    getCurrency: () => getCookie('currency'),
+    pageType: 'product',
+    identity: { userId: customer?.id, emailSha256: customer?.emailSha256 },
+    dataLayer: {},
+  },
+);
+```
+
+**The site configures one value: the key.** `writeKey` is the source's publishable key
+(`hp_pk_live_…` in production, `hp_pk_test_…` elsewhere), safe in page source. It names the
+organisation, the property and test or live, so there is no host, property or switch to set per
+environment, as with Stripe's or LaunchDarkly's keys. `apiHost` is optional, only for a first-party
+proxy (a bare host or an `https://` origin); without it the SDK uses the HP API
+(`DEFAULT_API_HOST`, `https://hp.thgingenuity.com` since 3.18, for test and live keys alike; see
+[Default host](#default-host-by-release)). Everything tenant-level comes from
+`GET {apiHost}/v1/projects/{writeKey}/settings`, so switching a site on or off, or changing what it
+collects, is a settings change and never a deploy:
+
+| From the settings (`hp`) | |
+|---|---|
+| `enabled` | Anything but `true` leaves the SDK off: no events, no cookie, nothing stored. |
+| `propertyId` | `context.source.property_id`. Null for a key scoped to several properties; the page then passes `propertyId`. |
+| `environment` | `context.source.environment`. |
+| `consent.purposes` | The purposes the property asks for. Only those are reported; the rest read as unanswered. Strict is the only mode. |
+| `queryParamAllowlist` | Query parameters kept on page URLs (plus campaign parameters). |
+| `anonymousId` | Where device ids come from, chosen per source in the console (since 3.6): `{ source: 'site_cookie', cookie }` or `{ source: 'hp_cookie' }`. See [Device ids](#device-ids). |
+| `apiHost` | Where events go, when not the host the settings came from. |
+| `plan.track` | Segment's tracking plan: an event with `enabled: false` is dropped at the source. The console's blocked events arrive here. |
+| `sampleRate` | The share of visitors events are sent for, by a hash of the anonymous id (since 3.18). Absent: 1. |
+| `debug` | `{ enabled, tokenSha256 }`: console logging for everyone, or for a session opened with `?hp_debug=<token>` whose SHA-256 is `tokenSha256` (since 3.18). `?hp_debug=` ends it. |
+
+**The page configures only what the page knows** (the second argument):
+
+| Option | |
+|---|---|
+| `consent` | **Required.** The page's CMP: `{ provider: 'didomi' \| 'onetrust' \| 'cookie' \| 'forwarded' \| 'static', ...adapterOptions }`, or a consent adapter of your own. A preset may supply defaults for a provider. |
+| `identityCookies` | `{ anonymousId, sessionId }`: the names of your own first-party device and session cookies. `sessionId` is always read from here; without it the SDK keeps its own session (see [Session ids](#session-ids)). `anonymousId` is read only when the settings name no device cookie: see [Device ids](#device-ids). |
+| `autocapture` | `false`, or per tracker `{ promotions, productLists, recommendations, exposures }`, each `false` or its options. All on by default: they report only what the page tags. |
+| `identity` | The signed-in visitor, `{ userId, emailSha256 }`. `userId` goes on every event; the `identify` is sent once per session and user. |
+| `getCurrency`, `getShipToCountry`, `getLocale` | Read per event; see below. |
+| `preset` | A platform preset, passed in by the host. |
+| `pageType` | `context.page.type` of this page's page view. |
+| `dataLayer` | `{ name?, ignore? }`: connect `window[name ?? 'dataLayer']` through the preset's mapping. Absent: no bridge. |
+| `propertyId` | Only for a key scoped to several properties, whose settings name none. |
+| `consentCookieDomain` | `Domain` for the consent cookie, e.g. `.acme.com` to share it with checkout. |
+| `storageNames` | Rename what the SDK stores; see [Storage](#storage). |
+| `debug` | Log every event and delivery problem. Also on when the settings' `debug` says so. |
+| `settings` | Development and tests only: use this settings response, never fetch or cache one. |
+| `extend` | `createAnalytics` options that are functions, such as `getRecommendations` or `getExtensions`. |
+
+What `bootstrap` does:
+
+- **Resolves to the client**, or `null` when the key is not enabled, the settings cannot be fetched
+  on a first visit, or the options are invalid. Invalid options log one console warning listing
+  every problem. It never rejects, and a second call on the same page returns the first client.
+- **Settings.** The last good answer is cached in `localStorage`, only once analytics is granted,
+  and forgotten on a refusal. A page with a cache starts from it at once and asks the API again for
+  the next page; a first visit waits for the API (which answers `Cache-Control: max-age=10`
+  and an `ETag`, so the browser revalidates for a `304`). A key the API switches off clears the cache, so the next page is
+  off too.
+- **Consent**, identity, one page view, the dataLayer bridge and a once-per-session `identify`, as
+  configured.
+- **Never waited for.** Call `hp` (`@thg-agentic/hyper-personalisation-web/hp`) from anywhere, at
+  any time, and never await or flush it: calls made before the client starts wait, each with the
+  messageId and time it was made at, and are sent in order once it has. The page view is stamped
+  when the page was navigated to, so none of them precedes it (3.18). A page that navigates
+  first (a sign-in that redirects at once) carries them in sessionStorage, and the next page's
+  `bootstrap` sends them once, before its own page view (since 3.9). So does a page whose settings
+  request never answered: the API down, or the request cancelled by the navigation (3.9.1). The carry is a device write,
+  so it is made only once this device has granted analytics, or unanswered with `holdAcrossPages`;
+  the next page's consent decides whether they are sent, and a refusal drops them. Once started,
+  the SDK hands its queue to `sendBeacon` at `pagehide` itself.
+
+## Multi-currency and multi-destination tenants
+
+One property can trade in several currencies and ship to many countries: a visitor on one site can
+pick EUR and a German delivery address halfway through a visit. So `context.currency`,
+`context.ship_to_country` and `context.locale` are read **per event**, never fixed per tenant.
+
+- **Getters.** Pass `getCurrency`, `getShipToCountry` and `getLocale` (to `bootstrap`,
+  `createAnalytics` or `cdpPlugins`). They are called for every event. `createAnalytics` and
+  `cdpPlugins` also take static `currency` / `shipToCountry` / `locale`, which a getter wins over
+  whenever it returns a value.
+- **Validation.** Values are uppercased and validated on read: currency `^[A-Z]{3}$`, ship-to
+  country `^[A-Z]{2}$`, locale a BCP-47 tag such as `en-GB` (a platform's `en_GB` is normalised to
+  `en-GB`). An invalid value is dropped (sent as null), never emitted, so it cannot quarantine the
+  event.
+- **Prices keep their own currency.** A GA4 push carries the currency its prices are in.
+  - Cart Viewed and Checkout Started take it as `properties.currency`.
+  - Every event mapped from that push also gets it as its `context.currency`, so a price pushed
+    in EUR is never stamped with the site's current GBP.
+  - A push with no currency falls back to the site's current one.
+- **Country is not here.** `context.country` (where the visitor is) is derived at the edge, so
+  there is deliberately no `getCountry`.
+
+## The lower-level API
+
+```js
+import { createAnalytics, getCookie, hashEmail } from '@thg-agentic/hyper-personalisation-web';
+import { didomiConsent } from '@thg-agentic/hyper-personalisation-web/consent';
+import { connectDataLayer } from '@thg-agentic/hyper-personalisation-web/datalayer';
+
+const analytics = createAnalytics({
+  writeKey: 'hp_pk_live_…',
+  propertyId: 'acme-gb',      // stable id of this site
+  currency: 'GBP',
+  locale: 'en-GB',            // the site's locale, not the browser's
+  consent: didomiConsent(),   // strict: nothing is sent until analytics is granted
+  consentCookieDomain: '.acme.com',
+  queryParamAllowlist: ['colour', 'size', 'sort'],
+  getAnonymousId: () => getCookie('device_id'),
+  getSessionId: () => getCookie('session_id'),
+});
+
+analytics.page({ type: 'product' });
+connectDataLayer(analytics);   // every GA4 ecommerce push becomes a spec event
+analytics.identify({ userId: customer.id, email_sha256: await hashEmail(customer.email) });
+```
+
+`createAnalytics` takes everything as options and fetches nothing: it is what `bootstrap` calls once
+the settings have answered. Add the named methods (`analytics.productViewed(...)` and so on)
+wherever a page has something the dataLayer does not.
+
+Since 3.1 (spec 1.2) there is a named method for every Segment Ecommerce V2 event, including the
+five spec 1.2 restored:
+
+| Method | Event | Notes |
+|---|---|---|
+| `wishlistProductAddedToCart` | Wishlist Product Added to Cart | A wishlist conversion. Call `productAdded` (with `surface: 'wishlist'`) for the cart add as well: every cart-add metric reads Product Added |
+| `productShared` / `cartShared` | Product Shared / Cart Shared | `share_message` and `recipient` are personal data; the ingest splits them off before anything is stored |
+| `couponEntered` | Coupon Entered | The attempt, before the outcome. The code goes in `coupon_name` (Segment's `coupon_id` is accepted too) |
+| `couponApplied` / `couponDenied` / `couponRemoved` | Coupon Applied / Denied / Removed | Sendable from the browser since spec 1.2. Report them from ONE producer per property, the storefront or the service that handles the code, or every code is counted twice |
+
+Since 3.5 (spec 1.4):
+
+| Method | Event | Notes |
+|---|---|---|
+| `cartUpdated` | Cart Updated | Pass the basket your cart API returned after the change: every line with its TOTAL quantity, `value` excluding tax, the codes, a `reason` and an `initiator`. Send it alongside `productAdded` / `productRemoved`, never instead. `item_count` is summed from the lines when omitted; `value` is never derived, because line prices include tax where the market shows them so |
+| `productVariantSelected` | Product Variant Selected | On the shopper's pick of a size, colour or flavour, not on page load. `product_id` the master, `sku` the variant now selected, `changed_attributes` what changed |
+| `backInStockSubscribed` | Back In Stock Subscribed | `kind` back_in_stock, price_drop or launch, for one product (the out-of-stock `sku`). Hash any email or phone with `hashEmail()` / `hashPhone()` |
+| `newsletterUnsubscribed` | Newsletter Unsubscribed | An opt-out made on the site. The ESP reports its own opt-outs as Email Unsubscribed |
+| `checkoutFailed` | Checkout Failed | `stage` and `reason_kind` are required. `payment_method` is the kind of instrument, never card data |
+
+`identityLinked` and `slotEngaged` complete the set: every spec event a browser may send has a
+named method, and `hp.track('<Spec Event>', …)` is typed by the event's schema as the client's
+`track` is.
+
+New optional fields on existing methods: `search_request_id` on `productsSearched`, `productClicked`
+and `productAdded` (your search engine's id for the result set, such as Algolia's `queryID`);
+`initiator` (`shopper` or `system`) on `productAdded` and `productRemoved`;
+`products[].subscription` on basket and order lines; `channel` and `phone_sha256` on
+`newsletterSubscribed`. A search page sends `productsSearched` with its results and never a
+`productListViewed` for the same grid.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `apiHost` | the HP API | Only for a first-party proxy. Events are POSTed to `${apiHost}/v1/batch`. |
+| `writeKey` | `'web'` | The source's publishable key, `hp_pk_…`. Sent in the batch body. |
+| `propertyId` | required | `context.source.property_id`. |
+| `channel`, `market`, `environment` | `null` | The rest of `context.source`. |
+| `currency`, `getCurrency` | `null` | ISO-4217 currency of this request; the getter is read per event and wins. A per-call override wins over both. |
+| `shipToCountry`, `getShipToCountry` | `null` | ISO-3166 alpha-2 destination, per event. |
+| `locale`, `getLocale` | `null` | The storefront locale served (BCP-47), per event. |
+| `country` | `null` | Visitor country; the ingest derives it at the edge and overwrites this. |
+| `consent` | none | A consent adapter (see below). Makes the SDK strict. |
+| `consentTimeoutMs` | `5000` | How long events wait for the CMP before they are dropped. |
+| `consentCookieDomain` | host only | `Domain` for the consent cookie. |
+| `onConsentStatus` | none | Called with the gate's status: `granted`, `denied` or `unknown` (timed out). |
+| `storageNames` | `thg_hp_*` | Rename what the SDK stores; see [Storage](#storage). |
+| `plan` | none | A Segment tracking plan, `{ track: { [event]: { enabled } } }`; `__default` covers unlisted events. |
+| `sampleRate` | `1` | The share of visitors to send for, by a hash of the anonymous id salted `hp_sample`; a visitor with no anonymous id is sent for. A consent withdrawal is always sent. Since 3.18. |
+| `queryParamAllowlist` | none | Keep only these query params (plus campaign params) in `context.page`. Patterns are anchored and case-insensitive. |
+| `queryParamBlocklist` | `[]` | Strip these params. Ignored when an allowlist is given. |
+| `sensitiveParamAllowlist` | `[]` | Whatever else is configured, a param is always dropped from every reported URL when its name contains `email`, `token`, `password`, `secret`, `auth`, `session`, `phone`, `address`, `card`, `customerid` and the like (see `SENSITIVE_PARAM_FRAGMENTS` in `src/context.js`), or when its value is an email address or a card-length number — campaign params and the referrer included. This exempts names from the first rule, for a false positive such as an `author` filter; nothing exempts a value. |
+| `getAnonymousId`, `getUserId`, `getSessionId`, `getRenderId` | none | Identity accessors. Without `getSessionId` the SDK keeps its own session (see [Session ids](#session-ids)); a missing or empty device id gives way to the SDK's own (see [Device ids](#device-ids)). |
+| `getExperiments`, `getAudiences`, `getDecisions`, `getRecommendations`, `getExtensions` | none | Read per event into the matching `context` field. Without `getDecisions`, `context.decisions` is what `recordExposure` last recorded per slot. |
+| `pageType` | `null` | `context.page.type` before the first `page()` call. |
+| `onEvent` | none | Observer for every event that will be sent. |
+| `debug` | `false` | Logs every event and delivery problem to the console. |
+| `validate`, `throwOnInvalid` | none | Inject `validateEvent` from `@thg-agentic/hyper-personalisation-spec` in development. |
+| `transport` | built in | Replace delivery, for example in tests. |
+
+The client has one method per browser event in the spec, plus `track`, `page`, `identify`,
+`reset`, `signedOut`, `flush`, `servingHeaders`, and the read-only `consent` and
+`lastPageMessageId`. Every method takes an optional last argument of context overrides, either as
+the overrides or as `{ context }`. An event method returns the event, or null when the tracking
+plan disables it. Declarations are in `types/`, and event properties are typed from the registry.
+
+## Calling the serving API
+
+Recommendations, decisions and audience membership personalise only for a visitor who granted
+personalisation. Every request to them carries the visitor's consent in the `hp-consent` header,
+in the consent cookie's serialisation (`a=1&p=0`):
+
+```js
+const res = await fetch(`https://api.example.com/v1/recommendations?placement=pdp`, {
+  headers: { authorization: `Bearer ${writeKey}`, ...hp.servingHeaders() },
+});
+```
+
+Without `p=1` the API answers with the non-personalised response. `servingHeaders(state)` from
+`./consent` builds the header from any consent state.
+
+### The visit, for a rail that reacts to it
+
+Since 3.11, `hp.recommendationContext()` returns what this visitor did earlier in the visit, as the
+recommendations API's session parameters: `viewed` (products viewed, clicked or added), `basket`,
+`q` (searches) and `impressed` (products shown and not engaged with, as `id:count`), newest first
+and within the API's limits. Append it to the rail request, or send it to the server that makes it:
+
+```js
+const visit = new URLSearchParams(hp.recommendationContext());
+const res = await fetch(`https://api.example.com/v1/recommendations?recipe=similar_items&sku=${sku}&${visit}`, {
+  headers: { authorization: `Bearer ${writeKey}`, ...hp.servingHeaders() },
+});
+```
+
+The SDK keeps the visit from the events it sends (Product Viewed, Clicked, Added, Removed, Added to
+Wishlist, Products Searched, and the products of a list viewed or filtered), in this browser's storage for the
+session, only while the visitor allows personalisation; withdrawing it forgets the visit. The call
+is synchronous and never throws. Before the client has started on a page it answers with the visit
+an earlier page kept (for 30 minutes from its last event), so a rail requested at page load, before
+the SDK has downloaded, still carries it. It returns `{}` without personalisation consent, and for a
+client whose host decided consent itself (no consent adapter), which the API would not personalise. `createAnalytics` clients have it as
+`client.recommendationContext()`; `recommendationContextFrom(signals)` from `./session` builds the
+same from session signals you keep yourself.
+
+### Holdout and exposure
+
+Since 3.2 (spec 1.3). A property can hold a share of its shoppers out of personalisation, so its
+uplift can be measured. The settings carry each property's holdout, and the edge, the public API
+and the SDK all hold out the same shoppers (by a hash of the anonymous id;
+`spec/assignment/holdout.json` has the vectors). A held-out shopper gets the default everywhere.
+Since spec 1.6 a property may also set a ramp, the share of all shoppers personalised; shoppers
+above holdout + ramp are `excluded` and get the default too, with no exposure. Personalise in the page
+only for the `personalised` group:
+
+```js
+if (hp.personalisationGroup() === 'personalised') applySessionAudiences();
+```
+
+`inHoldout()` means "show the default": true for held-out and excluded shoppers alike, and before
+the client has loaded, so the older `if (!hp.inHoldout())` gate stays safe under a ramp.
+`personalisationGroup()` gives the exact group.
+
+A membership, decisions or recommendations response that personalised the page, or would have for
+a held-out shopper, carries an `exposure` block. Record it after rendering, so both sides of the
+holdout are counted on the same trigger. The SDK sends one Personalisation Exposed per token:
+
+```js
+const body = await res.json();
+render(body);
+hp.recordExposure(body);
+```
+
+Since 3.7, recording a decisions response also puts its decisions in force. Every later event in
+the browser session carries them as `context.decisions`, latest per slot, so a basket is credited
+to the slot shown before it. Send the session id your events carry as `session_id` on
+`/v1/decisions` too: the reward joins a basket to a decision within one session. Pass
+`getDecisions` to supply `context.decisions` yourself instead.
+
+### Server-side assignments
+
+A page your server rendered from `POST /v1/assignments` and cached per arm has no `decision_id` in
+it. Since 3.10, `hp.assignmentDecisionId({ slot, arm })` derives the one HP logged, synchronously,
+for that page's `Slot Engaged`:
+
+```js
+const decisionId = hp.assignmentDecisionId({ slot, arm });
+if (decisionId) hp.slotEngaged({ slot, arm, engagement: 'view', decision_id: decisionId });
+```
+
+It reads the session cookie named in `identityCookies.sessionId`, else the visitor cookie
+(`identityCookies.anonymousId`), as your renderer forwards them to HP, so it answers once
+`bootstrap` has been called, before the client has started. It returns `null` before that, or
+with neither cookie. The id is `UUIDv5(ASSIGNMENT_DECISION_NAMESPACE, "<session>:<slot>:<arm>")`;
+`assignmentDecisionId({ sessionId, slot, arm })` from the main entry computes it from values you
+pass, and the spec's `assignment/decision-id.json` has the vectors.
+
+Such a page also reports the property holdout's exposure itself, when the slot is on screen, for
+both groups. The answer's `hash` is `holdout` for a held-out visitor (cache that page apart from
+the `""` one); on any other page with a hash the visitor was treated. The exposure token is the
+assignment's derived id for the arm shown, control included. Since 3.13 the shares come from the
+property's settings when the exposure has none:
+
+```js
+const token = hp.assignmentDecisionId({ slot, arm });
+hp.recordExposure({
+  exposure: { token, surface: 'decisions', holdout },
+  decisions: [holdout ? { slot, holdout: true } : { slot, arm, decision_id: token }],
+});
+```
+
+A surface your server fetched from HP for the page, so the page never sees HP's answer, reports
+its exposure with `surfaceViewed` when it comes into view: a product rail your server asked HP for,
+which HP answers with its rail for a treated visitor and the site's own rail for a held-out one.
+Since 3.14 the SDK groups the visitor itself, with the holdout settings, salt and visitor id serving
+used (`spec/assignment/holdout.json`), so it is the group serving answered with. It records one
+exposure per session per surface, and nothing for a visitor outside the experiment: no holdout in
+the settings, outside the ramp, no visitor or session id, or a rail or audience without
+personalisation consent, which serving needs to personalise them:
+
+```js
+hp.surfaceViewed({ surface: 'recommendations' });
+```
+
+Since 3.15 markup does the same without a call: `bootstrap`'s autocapture calls `surfaceViewed`
+for an element tagged `data-hp-exposure="<surface>"` (`recommendations`, `decisions` or
+`audiences`) once it is viewable, half on screen for a continuous second (MRC), including one
+rendered after the SDK started. Tag what renders for both groups. `trackExposures(client)` from
+`./auto` is the same for `createAnalytics` clients; `autocapture: { exposures: false }` turns it
+off.
+
+```html
+<section data-hp-exposure="recommendations">…</section>
+```
+
+### Bandit against the default
+
+Since 3.16. A readout slot (the placement's **Peak readout** setting in the console) splits the
+shoppers it personalises 50/50, by a hash of the device id salted with the slot
+(`banditSplit(slot, anonymousId)`, vectors in the spec's `assignment/bandit-split.json`): half get
+the bandit's arm, half the slot's default. The settings list each property's readout slots
+(`holdouts.<property>.readoutSlots`), so `recordExposure` adds the shopper's side to the slot's
+entry as `variant: 'bandit' | 'default'`, for a cached server-rendered page as for a serving
+response (whose own `variant` wins). The default side is no decision: its `decision_id` is dropped
+and it is not put in force. Nothing changes in your calls.
+
+### Preview
+
+Since 3.15. A trader's preview link from the console opens the site with `?hp_preview=<token>`.
+The SDK keeps the token in the `thg_hp_preview` session cookie for the rest of the browser
+session, for your server to forward to `/v1/assignments` as `preview` (the query parameter on the
+first request, the cookie after), which then answers that link's arm and logs nothing. While a
+preview is on, `recordExposure`, `surfaceViewed`, `data-hp-exposure` and `slotEngaged` send nothing
+and put nothing in force: the trader is not a shopper, so must neither train a slot nor count in its
+readout. Every other event is sent as usual. `?hp_preview=` with no value ends the preview. The
+SDK never checks the token: serving does, and ignores one that has expired.
+
+### Visit traits
+
+A session audience's rules name fields the SDK keeps for the visit, from the events it sends:
+`productViews`, `listViews`, `cartAdds`, `searches`, `browseViews.<path>`, `browseShare.<path>`,
+`categoryViews.<path>`, `categoryShare.<path>` and, since 3.18, `basketValue`. A field this build
+does not know fails its rule closed.
+
+`basketValue` is the `value` of the last `cartUpdated` (Cart Updated), in that event's currency:
+the basket as your platform priced it. It is never summed from `productAdded` lines, whose prices
+can include tax where `value` does not. It is `null`, so every rule on it fails, until the visit
+sends a Cart Updated, and again after one without a `value`. Send `cartUpdated` after every confirmed basket change, as the spec asks, or
+a basket audience goes stale.
+
+### Audiences only some integrations may target
+
+Since 3.8, only audiences marked Targetable in the console are membership. Pass the membership
+response's `audiences` and `qualified_for`, and the datafile's `session_audiences`, to
+`resolveAudienceMemberships` exactly as before:
+
+```js
+const memberships = resolveAudienceMemberships(body.audiences, datafile.session_audiences, undefined, body.qualified_for);
+```
+
+A targetable visit audience may require an audience nobody may target. The server sends that base
+in `qualified_for` (never in `audiences`), and the datafile ships it with `targetable: false` if the
+browser evaluates it. From 3.8 the resolver uses both to meet the `requires`, and never returns
+them, so `context.audiences` and exposures carry targetable audiences only. Before 3.8 such an
+audience matches nobody, and a shipped untargetable visit audience the visitor meets may be reported
+as membership. Every other audience resolves as it did.
+
+Social proof has a client of its own, which batches and caches, and never throws once created
+(creating it without a `writeKey` or with an invalid `apiHost` throws):
+
+```js
+const proof = createSocialProof({ writeKey, getConsent: () => hp.consent });
+const badges = await proof.forProducts(['123', '456']); // GET /v1/social-proof, Bearer writeKey
+```
+
+It sends the key and `hp-consent` itself; `propertyId` is needed only for a key scoped to several
+properties.
+
+## Consent
+
+With a `consent` adapter the SDK is strict:
+
+- **Before the CMP answers**, events are held in memory: not sent, not stored. They wait up to
+  `consentTimeoutMs`.
+- **Analytics granted:** held events are sent, each carrying the answer in `context.consent`.
+- **Analytics refused:** held events are dropped, and so is everything after. Nothing goes into
+  local or session storage.
+- **No answer by the timeout:** held and later events are dropped until an answer arrives. Strict
+  is the only mode: an unanswered CMP is never a grant, however long it takes.
+- **Page closed before an answer:** nothing is sent. Switching to another tab is not closing the
+  page: held events wait for the visitor to come back.
+- **A navigation before an answer** (a sign-in that redirects) loses what the page held, unless
+  you opt in with `holdAcrossPages: true` (since 3.5). Then held events are also kept in
+  sessionStorage under `thg_hp_held:<property>` and sent when the next page's answer is a grant,
+  stamped with it. A refusal deletes them, and so does a tab left unanswered for 30 minutes. This
+  writes event data to the device before the visitor answers, which strict mode otherwise never
+  does, so turn it on only where your consent policy allows that.
+- **The retry buffer:** a batch is kept in localStorage only while analytics is granted, and one
+  kept on an earlier page is replayed only once this page's answer is a grant. A refusal clears it.
+- **Consent changes:** each change is recorded as a `Consent Updated` event. A decision that
+  matches the last one this device reported (read from `thg_hp_consent`) is not a change. A
+  withdrawal of analytics is also sent, once, stamped with the withdrawn state: the raw event
+  table is where a refusal is shown to have been received, and the warehouse's consent filter
+  keeps that event out of every model. After that, nothing more is sent.
+- **Changes nothing announces:** after the first answer, an adapter whose `subscribe` cannot see
+  every change (a cookie adapter on a browser without the Cookie Store API, or your own adapter
+  without `observesChanges: true`) is re-read every 2 seconds while the page is visible.
+
+- **Purposes the property does not ask for:** with the settings' `consent.purposes`, only the
+  purposes listed as `true` are reported (analytics always is). The others read as unanswered in
+  `context.consent`, the cookie and `hp-consent`, so nothing claims a grant the property never
+  sought.
+
+`bootstrap` requires a consent adapter. `createAnalytics` without one sends straight away with
+`context.consent: { basis: 'host' }`: that is for a host that has settled the lawful basis itself,
+and `staticConsent` says so more explicitly. Leaving the adapter out is that statement.
+
+- **Who decided (3.7.0, spec 1.5):** every event's `context.consent.basis` says whose decision it
+  carries. `visitor` is the visitor's own answer, from any adapter but `staticConsent`. `host` is
+  the site's decision: no adapter, or `staticConsent`. Under `visitor` a null purpose is unanswered,
+  so the warehouse keeps a browser event only with `analytics: true`. Under `host` a null purpose is
+  no statement, so the event is kept unless `analytics` is `false`. An adapter that reports the
+  site's decision rather than asking the visitor can say so with `basis: 'host'`.
+
+### Adapters
+
+All adapters are imported from `@thg-agentic/hyper-personalisation-web/consent`.
+
+| Adapter | Reads | Not answered while |
+|---|---|---|
+| `didomiConsent({ purposes })` | `Didomi.getCurrentUserStatus().purposes`, subscribed via `didomiEventListeners` / `consent.changed` | Didomi is not loaded, `shouldUserStatusBeCollected()` is true, or `isUserStatusPartial()` is true |
+| `oneTrustConsent({ groups, impliedConsent })` | `OnetrustActiveGroups`, else the `OptanonConsent` cookie's `groups=`; subscribed via `OneTrustGroupsUpdated`, `OptanonWrapper` and `OneTrust.OnConsentChanged` | The banner was never closed (`OptanonAlertBoxClosed`) and never interacted with (`interactionCount`) |
+| `cookieConsent({ name, categories, parse, refusedValue, source, changeEvent })` | A first-party cookie your banner writes; subscribed via a `thg_hp_consent_change` window event (`changeEvent`) and Cookie Store `change` | The cookie is absent, or its value cannot be parsed |
+| `staticConsent(state)` | The state you pass, for sites with no CMP | Never |
+
+- **Didomi purposes.** The defaults are:
+  - analytics: `analytics`, `measure_content_performance`, `audience_measurement`
+  - marketing: `marketing`, `targeting`, `advertising`, `select_personalized_ads`,
+    `create_ads_profile`
+  - personalisation: `personalisation`, `personalization`, `select_personalized_content`,
+    `create_content_profile`
+
+  An id also matches Didomi's suffixed custom ids (`analytics-BNjaanaW`). A spec purpose is
+  granted if any of its mapped Didomi purposes is enabled. If the notice defines none of them,
+  it is `null`.
+- **OneTrust groups.** Defaults: analytics `C0002`, personalisation `C0003`, marketing `C0004`.
+  - `impliedConsent: true` accepts OneTrust's groups as soon as it loads. Only use it where the
+    geolocation rule is notice-only or opt-out, never for an opt-in (GDPR) audience.
+  - Global Privacy Control (`navigator.globalPrivacyControl`, or `isGpcEnabled=1` in the cookie)
+    turns marketing and both ad signals off. It does not change analytics.
+- **Ad signals.** In every adapter, `ad_user_data` and `ad_personalization` follow marketing
+  unless you map them separately.
+- **Your own banner (`cookieConsent`).** `name` and `categories.analytics` are required.
+  - By default the (URL-decoded) cookie value is a comma-separated list of accepted category ids;
+    an empty value is unknown, never a refusal.
+  - `refusedValue` is a literal value meaning "rejected everything".
+  - `parse(raw)` handles any other format: return the accepted ids as a `Set`, or null when
+    unreadable.
+  - After writing its cookie, the banner should call
+    `window.dispatchEvent(new Event('thg_hp_consent_change'))`.
+
+Any object with `{ name, read(), subscribe(onChange) }` is an adapter. `read()` returns null until
+the CMP has answered, and the five purposes otherwise.
+
+**`forwardedConsent()`** (bootstrap provider `"forwarded"`) is for pages that run without the CMP:
+a separate checkout app, a subdomain or a microsite on the same registrable domain as a page that
+has it. The SDK on the CMP page records the decision in `thg_hp_consent`; set `consentCookieDomain`
+there so the cookie reaches the other pages, and use `"forwarded"` on them. A site that renames the
+cookie with `storageNames.consent` gets the same name read back by `"forwarded"` when both pages
+pass the same `storageNames`, or passes `forwardedConsent({ name })` directly. No cookie, or no analytics answer in it,
+means not answered, and strict mode then drops the events.
+
+A checkout on **another registrable domain** never receives that cookie. Carry it in the checkout
+handoff your servers already make:
+
+1. The storefront's server reads `thg_hp_consent` from the shopper's request and puts it on the
+   checkout session it creates.
+2. On every page it renders, checkout's server sets `thg_hp_consent_handoff` on its own host
+   from the session. The value is `formatConsentCookie(parseConsentCookie(value))` (from
+   `@thg-agentic/hyper-personalisation-web/consent`), so an unreadable value is unknown, never a
+   grant. The cookie is not `HttpOnly`. With no value it deletes the cookie.
+3. The checkout page boots with `storageNames: { consent: 'thg_hp_consent_handoff' }` and
+   `"forwarded"`. Use a name of its own: a checkout host that also serves a storefront on its
+   own domain sees that storefront's `thg_hp_consent` first, and a delete cannot remove it.
+
+Hand the device cookie over the same way if checkout's events should land on the storefront's
+visitor. Never put the value on the checkout URL: it would end up in access logs and referrers.
+
+## GA4 dataLayer
+
+```js
+const disconnect = connectDataLayer(analytics, {
+  dataLayer: window.dataLayer,     // default; created if absent
+  ignore: ['view_promotion'],      // e.g. when trackPromotions() measures impressions instead
+  steps: { shipping: 2, payment: 3 },
+  map: {
+    size_guide_opened: (entry, { products }) => ({ event: 'Product Clicked', properties: { products: products.slice(0, 1) } }),
+  },
+});
+```
+
+What it reads and how it hooks in:
+
+- **Existing entries.** Entries already on the array are read when you connect.
+- **New pushes.** It wraps `push` and calls the previous `push` first. GTM does the same, so
+  both keep working whichever loads first. It never replaces the array and never throws into the
+  page.
+- **Push shapes.** The GA4 standard only:
+  - `{ event: 'view_item', ecommerce: { items, currency, value } }`, as GTM documents it;
+  - non-ecommerce parameters at the top level (`{ event: 'login', method }`);
+  - `gtag('event', name, params)`.
+- **Currency** is `ecommerce.currency`, set as `context.currency`.
+- **Items.** GA4 items map to spec products:
+  - `productId(item)` (default `item_group_id ?? item_id`) becomes `product_id`, and `item_id`
+    becomes `sku`.
+  - `item_category` to `item_category5` are joined with `/`.
+  - `item_variant`, `discount`, `index` (as a 1-based position), `coupon` and `image_link` are
+    carried over.
+- **Duplicates.** Identical pushes (same event, same item ids, same value) within 1 second
+  (`dedupeMs`) are sent once.
+- **Unusable pushes.** A push that cannot make a valid event, such as one with no product ids
+  where products are required, is skipped.
+- **Custom mappings.** `map` adds or overrides a mapping, keyed by GA4 event name. It receives the
+  push and helpers (`products`, `items`, `currency`, `value`, `promotions`, `toProducts`).
+- **Any client.** It works with this package's client and with an analytics-next instance: it
+  only calls `track(event, properties, { context })`, plus `signedOut()` when the client has one.
+
+| GA4 event | Spec event | Notes |
+|---|---|---|
+| `view_item` | Product Viewed | First item only (the event holds exactly one product); `value`, `currency` |
+| `view_item_list` | Product List Viewed | `list_id` from `item_list_id`, else `item_list_name` |
+| `view_search_results` | Products Searched, or Product List Viewed | Products Searched if `search_term` is present |
+| `search` | Products Searched | `query` = `search_term` |
+| `select_item` | Product Clicked | |
+| `add_to_cart` / `remove_from_cart` | Product Added / Product Removed | `cart_id` when present |
+| `view_cart` | Cart Viewed | `value`, `currency`, `coupon`, products |
+| `begin_checkout` | Checkout Started | `value`, `currency`, `coupon`, products |
+| `add_shipping_info` | Checkout Step Completed | `step` 2, `step_name` `'shipping'`, `shipping_method` = `shipping_tier` |
+| `add_payment_info` | Payment Info Entered | `step` 3, `step_name` `'payment'`, `payment_method` = `payment_type` |
+| `view_promotion` / `select_promotion` | Promotion Viewed / Promotion Clicked | Fields from `ecommerce` or its items; one event per `promotion_id`. `creative_slot` is sent as Segment's `position` |
+| `add_to_wishlist` | Product Added to Wishlist | |
+| `share` | Product Shared | Only when `item_id` is present and `content_type` is absent or a product (`product`, `item`); `share_via` = `method`, `product_id` = `item_id` |
+| `login` / `sign_up` | Signed In / Signed Up | `method` mapped to the spec enum (`email` becomes `password`, anything unknown becomes `other`) |
+| `purchase`, `refund` | not mapped | Orders are reported by the service that took them, which sees every order exactly once, including app and redirect orders. The ingest refuses them from browser keys. |
+
+GA4 has no event for removing from a wishlist, moving a wishlist item to the basket, sharing a
+basket, signing out or filtering a list, and no coupon events at all (`coupon` is a parameter on
+its commerce events, carried through above). Add them with `map` or a preset if your site pushes
+them, or call the client's named methods directly.
+
+## Presets
+
+The core knows GA4 and Segment. A preset teaches it one platform's conventions. It is plain
+configuration, spread into the options, and each part can be overridden:
+
+- `eventName(entry)`: the GA4 name of a push (default `entry.event`);
+- `transform(entry)`: rewrites a push into the GA4 shape before anything reads it, or returns null
+  to skip it;
+- `productId(item)`: the parent product id of an item;
+- `map` and `ignore`: as above;
+- `consent`: optional adapter factories by provider name, used by `bootstrap`.
+
+`firstId(...candidates)`, exported from `./datalayer`, is the id helper the core uses: the first
+non-blank candidate as a string, or null.
+
+A preset for a hypothetical platform whose pushes look like
+`{ acmeEvent: 'basket_add', money: 'EUR', lines: [{ sku, style }] }`:
+
+```js
+export const acme = {
+  eventName: (entry) => ({ basket_add: 'add_to_cart', pdp_view: 'view_item' })[entry.acmeEvent] ?? null,
+  transform: (entry) =>
+    entry.acmeEvent
+      ? {
+          ...entry,
+          ecommerce: {
+            currency: entry.money,
+            items: (entry.lines ?? []).map((line) => ({ item_id: line.sku, item_group_id: line.style, ...line })),
+          },
+        }
+      : entry,
+  productId: (item) => item.item_group_id ?? item.item_id,
+  map: { wishlist_remove: (entry, { products }) => ({ event: 'Product Removed from Wishlist', properties: { products } }) },
+  ignore: [],
+};
+
+connectDataLayer(analytics, { ...acme, ignore: [...acme.ignore, 'begin_checkout'] });
+```
+
+## Identity and hashing
+
+`emailSha256(email)` returns the SHA-256 of the trimmed, lowercased email as lowercase hex,
+synchronously (since 3.9), so a page hashes an address in the same call that reports it and never
+awaits the SDK. This is the rule `identify.email_sha256` expects. It returns null for anything that
+is not an email address. `hashEmail(email)` is the same as a promise, and `sha256(value)` the
+underlying helper.
+
+`hashPhone(phone)` returns the SHA-256 of the E.164 number (`+447700900123`), after removing spaces,
+dots, dashes and brackets. This is the rule `identify.phone_sha256` expects. It returns null for a
+national number such as `07700 900123`: convert to E.164 first, since the country cannot be guessed
+and a number hashed as typed never matches the same number sent in E.164.
+
+Already have the digest? Platforms encode SHA-256 as hex or as base64 (some platforms return
+base64). `bootstrap`'s `identity.emailSha256` and `identify`'s `email_sha256` (since 3.9) accept
+either, and `normaliseSha256(value)` converts either to the lowercase hex the spec wants. It re-encodes the same digest and never
+re-hashes, so pass the hash, never the email.
+
+## Handing off to server producers
+
+Server-side producers (for example an order service using the Java SDK) read two first-party cookies:
+
+- **`thg_hp_consent`** carries the visitor's consent decision.
+  - It is written whenever the decision is known or changes, with `Path=/`, `SameSite=Lax`, a
+    `Max-Age` of 180 days, `Secure` on https, and `Domain` from `consentCookieDomain`.
+  - Its value is `a=1&m=0&p=1&aud=0&adp=0`: analytics, marketing, personalisation,
+    ad_user_data and ad_personalization.
+  - `1` means granted, `0` refused, and a missing key means unknown.
+  - The format is byte-identical to `ConsentCookie` in analytics-java, and a test checks this
+    against the Java parser.
+- **The device and session cookies.** The device cookie is the one the source's settings choose:
+  your own, or `thg_hp_anonymous_id` under `hp_cookie`. Your server must read that one, and the
+  session cookie you name in `identityCookies` (or return from `getSessionId`), so both sides agree
+  on who the visitor is. `client.anonymousId` is the id events carry.
+
+## Choosing a delivery path
+
+There are two ways to deliver events. Both use the same consent adapters, the same consent
+logic, the same context shaping and URL scrubbing, the same settings and the same cookie. Only the
+delivery differs.
+
+**Built-in client** (`bootstrap` / `createAnalytics`)
+- Dependency-free.
+- Batched, with a retry buffer in localStorage: each batch is stored before it is sent and
+  removed when the ingest accepts it (or rejects it for good), so an outage costs a delay, not the
+  events. The buffer is per tenant and capped at 20 batches and 1 MB, oldest dropped first.
+- On page unload, sends by `sendBeacon` in chunks that fit.
+- Never throws into the page. An event JSON cannot serialise (a BigInt, a circular object, a
+  throwing `toJSON`) is dropped on its own, logged under `debug`, and the queue behind it carries
+  on. A `Date` in properties is sent as its ISO string.
+- Size: the CDN script is `bootstrap` with every consent adapter and the dataLayer bridge. A test
+  fails it past 90 KB gzip, and the inline snippet past 1 KB; the budget catches a runaway bundle.
+
+**analytics-next plugins** (`cdpPlugins` from `./segment`)
+- For sites already using `@segment/analytics-next`: keep it, and add the spec on top of it.
+- Size: about 50 KB gzip as a single bundle; with code splitting, about 39 KB loads up front.
+
+Use the built-in client on performance-critical storefronts. Use the plugins if you are already
+on Segment: the wire format and the spec are identical.
+
+```js
+import { AnalyticsBrowser } from '@segment/analytics-next';
+import {
+  cdpPlugins,
+  DEFAULT_API_HOST,
+  hpLoadOptions,
+} from '@thg-agentic/hyper-personalisation-web/segment';
+import { didomiConsent } from '@thg-agentic/hyper-personalisation-web/consent';
+
+const hp = { writeKey: 'hp_pk_live_…' };
+const analytics = AnalyticsBrowser.load(
+  {
+    writeKey: hp.writeKey,
+    cdnURL: DEFAULT_API_HOST, // or your proxy, passed as hp.apiHost too
+    plugins: cdpPlugins({ consent: didomiConsent(), getCurrency: () => getCookie('currency') }),
+  },
+  hpLoadOptions(hp),
+);
+```
+
+Things to get right when configuring analytics-next:
+
+- **`cdnURL` is the HP API** (`DEFAULT_API_HOST`), or your proxy. analytics-next fetches its settings from
+  `{cdnURL}/v1/projects/{writeKey}/settings`, the same Segment-compatible document `bootstrap`
+  reads. The plugins take the property, environment, reported purposes, allowlist and tracking plan
+  from its `hp` block.
+- **`hpLoadOptions` is required with it.** The settings carry no `Segment.io` destination, and
+  without one analytics-next sends to api.segment.io with no key. `hpLoadOptions` points delivery
+  at the settings' apiHost with the write key, turns analytics-next's own telemetry off (it would
+  otherwise POST to `<apiHost>/m` every 30 seconds), and makes a disabled key a no-op.
+- **`plugins` go in the first argument** of `AnalyticsBrowser.load`. In the second, they are
+  ignored.
+- **Endpoints.** analytics-next POSTs one event per request to `<apiHost>/v1/t`, `/v1/p` and
+  `/v1/i`, or a `{ batch }` body to `/v1/b` with the batching strategy. The write key is in the
+  body and in an `Authorization: Basic` header.
+- **Keep strict consent strict.** `hpLoadOptions` sets `disableClientPersistence`, which stops
+  analytics-next writing its queue and ids to storage before consent. Keep it if you build the
+  options yourself.
+- **Device id.** Pass `getAnonymousId` to `cdpPlugins` to use the site's device id instead of
+  analytics-next's.
+
+`@segment/analytics-consent-tools` is not used, for two reasons. It writes
+`context.consent.categoryPreferences`, which is not the spec's consent block. And it keeps sending
+to Segment.io after a withdrawal.
+
+## CDN script
+
+For a site without a bundler, `dist/hp.min.js` is `bootstrap` as one script, and
+`dist/snippet.min.js` is the loader to paste inline in `<head>`, Segment-style: it puts a stub on
+`window.hp` that queues every call, loads the script asynchronously, and the script drains the
+queue into the client once the settings have answered.
+
+```html
+<script>
+  /* dist/snippet.min.js, with your write key and options in its hp.load(…) call */
+</script>
+<script>
+  hp.productViewed({ products: [{ product_id: '10530943' }] }); // queued until the script loads
+</script>
+```
+
+The snippet's `hp.load(config, options, src)` takes the same `{ writeKey }` (and optional `apiHost`) and options as
+`bootstrap`, and the script URL: `https://cdn.jsdelivr.net/npm/@thg-agentic/hyper-personalisation-web@3/dist/hp.min.js`
+once published, or wherever you host `dist/hp.min.js`. Once loaded, `window.hp` stays the same
+object, forwards every call to the client, and holds it as `hp.client`. A key the settings do not
+enable leaves every method a no-op. Without the snippet, call `hp.load(config, options)` after the
+script has loaded.
+
+The ESM build is the primary distribution; the script is for pages that cannot use it. It targets
+evergreen browsers.
+
+## Storage
+
+Everything the SDK stores carries the `thg_hp_` prefix, and every name can be changed with
+`storageNames` (on `bootstrap`, `createAnalytics` or `cdpPlugins`). The names are page-wide: one
+SDK per page.
+
+| Kind | Default name | Where | Scope |
+|---|---|---|---|
+| `consent` | `thg_hp_consent` | cookie | the consent decision, for your servers and `forwarded` pages |
+| `retry` | `thg_hp_retry:<property>` | localStorage | batches waiting for the ingest; only under a grant |
+| `sessionSignals` | `thg_hp_session_signals:<property>:<session>` | localStorage (sessionStorage until a session is bound) | in-session audience counters |
+| `identified` | `thg_hp_identified:<property>` | sessionStorage | the identify already sent this session |
+| `previousPage` | `thg_hp_prev_page:<property>` | sessionStorage | the previous page view's messageId; only under a grant |
+| `decisions` | `thg_hp_decisions:<property>` | sessionStorage | the decisions in force, latest per slot; only under a grant |
+| `settings` | `thg_hp_settings:<writeKey>` | localStorage | the last good settings; only under a grant |
+| `held` | `thg_hp_held:<property>` | sessionStorage | events held for an unanswered CMP; only with `holdAcrossPages` |
+| `carried` | `thg_hp_carried:<writeKey>` | sessionStorage | `hp` calls made before the SDK started, on a page that navigated first (3.9); only under a grant, or with `holdAcrossPages` |
+| `recommendationContext` | `thg_hp_recommendation_context` | localStorage | The visit's wire form, for `hp.recommendationContext()` on the next page before the SDK starts there; 30 minutes from the last event, only while personalisation is granted (3.11) |
+| `anonymousId` | `thg_hp_anonymous_id` | cookie, one per browser | Hyper-Personalisation's device id, for a source set to `hp_cookie`; only under a grant (see [Device ids](#device-ids)) |
+| `session` | `thg_hp_session` | cookie, one per browser | the session id the SDK keeps when you name none, 30 minutes from the last event; only under a grant (3.15, see [Session ids](#session-ids)) |
+| `preview` | `thg_hp_preview` | session cookie | a trader's preview token from `?hp_preview=` (3.15, see [Preview](#preview)) |
+| `debug` | `thg_hp_debug` | sessionStorage | a developer's debug token from `?hp_debug=` (3.18), checked against the settings on every page |
+| — | `thg_hp_conformance_page_type` | sessionStorage | the previous page's type, only while the development-only conformance checker runs |
+
+Keys are scoped by property because one origin can serve several tenants. The names the SDK used
+before 3.0 (`cdp.retry`, `cdp_session_signals`, `cdp_identified`, `cdp_prev_page_message_id`) are
+moved to the new names once, on the first page that loads 3.x, and deleted. A banner using
+`cookieConsent` announces a change with the `thg_hp_consent_change` window event.
+
+### Device ids
+
+Each web source takes its device ids (`anonymousId`) from one place, chosen in the console and
+served in the settings as `hp.anonymousId`. Since 3.18 an event never leaves without one: when the
+site's id is missing, empty or a placeholder, the SDK's own cookie stands in, as analytics.js does.
+
+| `hp.anonymousId` | The device id | |
+|---|---|---|
+| `{ source: 'site_cookie', cookie: 'site_visitor_id' }` | your own first-party cookie, by the name the console gives | read only; a visitor without it gets the SDK's `thg_hp_anonymous_id` (3.18; before, no `anonymousId`) |
+| `{ source: 'site_cookie', cookie: null }` | the cookie you name in `identityCookies.anonymousId` (or return from `getAnonymousId`) | as above. Every web source that existed before the setting is set to this |
+| `{ source: 'hp_cookie' }` | Hyper-Personalisation's first-party cookie, `thg_hp_anonymous_id` | minted by the SDK; your own device cookie is ignored. The default for a new source |
+| absent (settings from before 3.6) | as `site_cookie` with `cookie: null` | |
+
+The `hp_cookie` cookie is one per browser, not per property. It is written with `Path=/`,
+`SameSite=Lax`, `Secure` on https, and the `Domain` of `consentCookieDomain` when you set one. Its
+`Max-Age` is 400 days, and it is written again on every page under a grant, so it lasts 400 days
+from the last visit. With a consent adapter it is never written before analytics is granted: until
+then the id lives in memory, and in the held store with `holdAcrossPages`, so a redirect keeps it.
+A refusal or withdrawal deletes it, and the id with it: a later grant, on the same page or another,
+starts a new device, as `analytics.reset()` does in analytics.js (3.18). Without a consent adapter
+you have decided the lawful basis yourself, so it is written at once.
+
+Changing a source's choice gives every returning visitor a new device id. A device id 3.5 minted
+into localStorage (`thg_hp_anonymous_id:<property>`) becomes the cookie's value under a grant, and
+the localStorage key is removed. `mintAnonymousId` is deprecated since 3.6 and ignored; with
+`debug` the SDK says so once. `client.anonymousId` reads the id events carry, so a server can be
+handed the same one.
+
+### Session ids
+
+Every event carries `context.session_id`. Name your own session cookie in
+`identityCookies.sessionId`, or pass `getSessionId`, and the SDK reads it. Without either (since
+3.15), or while it is missing or empty (since 3.18), the SDK keeps its own, as Amplitude and GA4 do: a random UUID in the `thg_hp_session` cookie, ended by 30 minutes
+without an event. Its `Max-Age` is 30 minutes and every event writes it again, so it is shared by
+the site's tabs and ends on its own. It is written with the attributes of the device cookie. With a
+consent adapter it is never written before analytics is granted (until then the session lives in
+memory), and a refusal deletes it. Before 3.15 such a site sent `session_id: null`.
+
+## CSP and proxying
+
+The SDK makes requests only to `apiHost` (the settings, and the events unless the settings name
+another host), so allow it in `connect-src`: `resolveApiHost(apiHost)` is that origin, the HP API
+(`DEFAULT_API_HOST`) when you set none. Since 3.18 that is `https://hp.thgingenuity.com`
+(`connect-src https://hp.thgingenuity.com`); 3.17 used HP's nonprod host and 3.16 and earlier a
+staging host that is being retired. Allow the CDN host in `script-src` too if you use the script. Call the API host directly rather than through a CDN proxy route: behind a proxy the ingest
+would see the CDN's IP and country instead of the shopper's.
+
+### Default host by release
+
+| Release | `DEFAULT_API_HOST` | For |
+|---|---|---|
+| 3.12 to 3.16 | A staging host | Being retired. Upgrade. |
+| 3.17 | `https://hp.uat.thgingenuity.com` | Interim: HP's nonprod stack. Test keys only. |
+| 3.18 | `https://hp.thgingenuity.com` | Production, for test and live keys alike. Go live on this. |
+
+The key, not the host, keeps test traffic out of live results, so UAT and preview builds use the
+same host with a `hp_pk_test_…` key. Upgrade from 3.17 before shipping a live key.
+
+The SDK loads no scripts and sets no cookie except `thg_hp_consent`, once the CMP has answered,
+and `thg_hp_anonymous_id` for a source set to `hp_cookie`, once analytics is granted.
+
+## Debugging
+
+- **`debug: true`** logs every event as it is built, plus any delivery problems.
+- **`validate: validateEvent`** checks every event against the spec as it is built and logs
+  anything the ingest would quarantine. Import `validateEvent` from `spec/lib/index.mjs`, or from
+  `@thg-agentic/hyper-personalisation-spec` where it is published, and use it in development only, since it pulls in
+  ajv. Add `throwOnInvalid: true` to fail fast in tests.
+- **`createConformanceChecker`**, from `./conformance`, reports what a page is missing against
+  the registry's expectations (`page_expectations`). Since spec 1.2 a `list` page owes Product List
+  Viewed, and `checkout` owes Checkout Step Viewed on every page and Checkout Started on entry:
+  the first page of a run of checkout pages, known from the previous page's type in
+  `sessionStorage` (`thg_hp_conformance_page_type`), so a checkout on its own origin counts its first
+  page as the entry. It also looks inside `products[]`, against the product version each event
+  holds. An item the ingest would reject is an error. Two things the ingest accepts but the
+  warehouse cannot use are warnings: priced products with no currency, on the event or in
+  `context.currency` (the amounts drop out of revenue), and a category separated by `>` or `|`
+  rather than `/` (it counts as one level).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).