@intenque/network-sdk 0.0.0-stage → 2.2.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+`@intenque/network-sdk`. The SDK major is the manifest schema major (spec §6.1). Design decisions are in the hub
+repository: `docs/Network_CrossPromo_Plan.md` and `docs/spec-addendum-phase0-auth.md` ("# Phase 3: conversions").
+
+## 2.2.0-beta.2
+
+Security fix round (hub Phase 3 WP19). No API change; one new drop reason.
+
+### Server entry (`@intenque/network-sdk/server`)
+
+- **Misrouted answers are retried, not dropped.** `403`, `404` and any 3xx the classifier sees (`300`, `304`, or a
+  `fetch` that hands redirects back) were terminal after one attempt, so a missing route prefix, a WAF or a
+  maintenance page in front of the hub lost every report in that window. They are now `misrouted`
+  (`classifyResponse` returns the new kind): retried in process after 2, 8 and 30 s, then every 10 min from the
+  outbox, and dropped only 24 h after the first 401 / missing-config / misrouted answer with reason `misrouted_24h`
+  (the clock is the existing `unauthorizedSince` field, shared with the 401 rule; no outbox migration). A real
+  redirect (`301`/`302`/`303`/`307`/`308`, with or without `Location`) is still a transport error under
+  `redirect: 'error'` (status 0, retryable), as before. `400`, other `409`s, `402`, `413`, `422` and the rest of 4xx
+  stay terminal.
+- **The responder's error code is bounded.** A code is kept (logged in `inr_outbox_dropped_total` /
+  `INR_UNAUTHORIZED`, stored in `lastError.code`) only when it matches `^[A-Z][A-Z0-9_]{0,63}$`; anything else
+  (a captive portal, a misrouted proxy, a 5000-character string) is `null`.
+- **`referralMiddleware()` strips `inrRef` from any object body** (arrays and class instances too, not only plain
+  objects) with `Reflect.deleteProperty`, and never throws: a frozen body or a proxy that refuses keeps the field,
+  a `null` or primitive body is left alone. `req.inrRef` is set as before.
+- **`forget()` stops a running send chain.** Before each in-process retry the chain checks that its outbox row (or
+  spill entry) still exists; once `forget(clickId)` purged it, no further attempt is sent. An outbox that errors or
+  times out on that check keeps the chain sending (as before).
+- **`forget()` during a drain tick's spill move.** The drainer moved a snapshot of the in-memory spill, so a spilled
+  report that `forget(clickId)` removed while an earlier entry was being written was inserted into the outbox after
+  the purge (and `forget()` had returned `true`); the next tick sent the erased click id again. The move now skips an
+  entry no longer spilled, and removes the row again when the entry left the spill while its own write was in flight
+  (forget, or a send that finished). A failed write still leaves the entry spilled for the next tick.
+
+### Verifier (`@intenque/network-sdk/react`, the manifest verifier)
+
+- **Destination URLs: RFC 3986 characters only after the authority** (unreserved, sub-delims, `:`, `@`, `/`, `?`,
+  `%XX`, one `#`). The hub now stores business URLs with `^`, `|`, a backtick, `{`, `}`, `[`, `]` and non-ASCII
+  percent-encoded and refuses
+  to sign anything else, so the SDK and the hub agree on every URL in every engine (a raw `^` or `|` used to pass
+  the hub and fail the SDK in browsers, taking the whole manifest down).
+- **Signer dates must be their own `toISOString()`** (`2027-02-30`, `T24:00`, second 60 are `malformed`), the same
+  rule as the hub's verifier: engines disagree on those dates.
+- **A root key that is not exactly `crv: 'P-256'` never verifies** (Firefox's WebCrypto accepts `p-256`).
+- **A root key must have the shape the hub requires of its own roots** (`PublicJwkSchema`: `kty: 'EC'`,
+  `crv: 'P-256'`, `x` / `y` canonical base64url of 32 bytes), else `root_sig`; other members are ignored, as
+  before. The SDK handed WebCrypto `kty: 'EC'` whatever the site's `manifestRootKeys` said, so `kty: 'ec'`, `'RSA'`
+  or none verified in every engine while the hub refuses such a key, and a padded `x` verified in WebKit only.
+- **Hosts with right-to-left text** (hub side, no SDK change): the hub now refuses a business URL whose host breaks
+  the RFC 5893 bidi rule (e.g. `24.בדיקה.co.il`, `1shop.عرب.com`, `aא.com`, `٣.com`), which Firefox's URL parser
+  refuses, so a signed manifest can no longer be `malformed` in Firefox alone. The SDK schema does not repeat that
+  check (bundle size; the hub never signs such a host).
+
+## 2.2.0-beta.1
+
+### Server entry (`@intenque/network-sdk/server`)
+
+- **Signing binds the identifiers.** The v1 HMAC base is `ts.nonce.siteKey.keyId.METHOD.path.sha256(body)`;
+  `hmacBase`, `signRequest` and `verifySignature` take `siteKey` and `keyId`. The key is the UTF-8 bytes of the
+  `INR_SITE_SECRET` string. The hub's committed vectors pass byte for byte. (2.0 and 2.1 never sent a request, so no
+  signature in the old form exists.)
+- **Conversions are sent.** `report()` used to queue only. It now sends with global `fetch` (`redirect: 'error'`,
+  `User-Agent: intenque-network-sdk/<version>`, per-attempt timeout `INR_TIMEOUT_MS`, default 3000 ms, clamped to
+  500–30 000). Answers: any 2xx and `409 NONCE_REUSED` count as success; 408, 425, 429, 5xx and network errors are
+  retried after 2, 8 and 30 s, honouring `Retry-After` (above 30 s the row waits in the outbox, capped at 1 h);
+  `400 TIMESTAMP_SKEW` re-signs once with a process-wide clock offset from the hub's `Date`, else `INR_CLOCK_SKEW`;
+  401 and missing or invalid config are retried every 10 min for 24 h (`unauthorizedSince`), then
+  `INR_UNAUTHORIZED`; other 4xx (including `CURRENCY_NOT_ALLOWED`) are dropped with an `inr_outbox_dropped_total`
+  warn line. `classifyResponse(status, code)` is exported.
+- **`report()` is bounded.** It resolves after the outbox write or 2 s, whichever comes first, and never rejects or
+  waits for the network. A new result `spilled`: the outbox write failed or timed out, so the report is held in
+  memory (≤ 1000, oldest dropped as `memory_full`; `INR_OUTBOX_UNAVAILABLE` at most once a minute) and still sent.
+  New rows carry a 150 s lease in `nextAttemptAt`. Outbox rows gain `lastStatus`, `lastError { status, code }` and
+  `unauthorizedSince`. `idle()` resolves once the running send chains have settled.
+- **The body rules match the hub.** `CONVERSION_TYPES` has 12 entries (new `fee_charged`: `feeCents ≥ 1`,
+  `valueCents: null`, a currency, `reverses` → the `booking_no_show` / `booking_cancelled` it belongs to).
+  `eventId` and `reverses.eventId` follow the hub's pattern: a lower-case prefix, `:`, then letters, digits, `_` or
+  `-`, at most 64 characters in all (the 200-character cap is gone), never `erased:`. Each type has the hub's
+  amount rules. Any amount needs a currency. `reverses` is required on the linked types and must name one of
+  `LINK_TARGETS[type]`; on every other type it must be null. A failing event resolves
+  `{ status: 'invalid', error: '<field>' }` and is never sent. `occurredAt` is a valid `Date` or an ISO datetime
+  string with `Z` or an offset (sent as ISO UTC); other strings (`'1'`, a space for the `T`, no zone) are `invalid`,
+  no longer parsed leniently in local time. `LINK_TARGETS` and `REVERSAL_TYPES` are exported.
+- **`verifyEnv()`** also reports malformed values (`INR_HUB_URL (invalid)`: not an origin; `INR_SITE_KEY (invalid)`:
+  not a site slug; `INR_KEY_ID (invalid)`; `INR_SITE_SECRET (invalid)`), never their content, and throws in
+  production when `INR_STRICT_ENV=true`.
+- A throwing site `logger` is ignored (it never rejects `report()` or a send chain). A blank `INR_TIMEOUT_MS` means
+  the 3000 ms default.
+- **Outbox v2.** The schema declares no index and sets `autoIndex: false`; the reporter creates the three helper
+  indexes itself (`createdAt` TTL 1 209 600 s, `nextAttemptAt`, unique `(eventType, eventId)`, default names), so
+  they exist on sites that turn `autoIndex` off. Each index is tried on its own and a failed one is retried at the
+  next drain tick; failures are one `INR_OUTBOX_INDEX_FAILED` warn. The collection is `outbox.collection`, else
+  `INR_OUTBOX_COLLECTION`, else `inrConversionOutbox`. A 2.0 / 2.1 row's string `lastError` is read as
+  `{ status: 0, code }`. Mongoose 7.8.6 and 8 are both tested.
+- **Drainer.** First tick 10–20 s after start, then every 60 s ± 10 s (unref'd, never overlapping): the spill moves
+  into Mongo, then up to 50 due rows are claimed (`findOneAndUpdate`: lease `nextAttemptAt = now + 150 s`,
+  `attempts + 1`) and sent one at a time; a 429 or 503 ends the tick. A claimed row is owned by one sender on any
+  number of instances; an in-process send chain renews its lease before each retry. Backoff
+  `min(60 s × 2^max(0, attempts − 4), 30 min) × U(0.8, 1.2)`, raised to `Retry-After` (≤ 1 h), no attempt cap. Rows
+  older than 14 d − 1 h are dropped as `expired`. Every drained attempt re-reads `INR_KEY_ID` / `INR_SITE_SECRET`.
+  New `drainNow()` → `{ sent, retried, dropped }` and `close()` (stops the timer, waits ≤ 5 s).
+- **`forget(clickId)`** is implemented: invalid id → `false`; otherwise queued outbox and spill rows naming the id
+  (`clickId` or `firstClickId`) are deleted, then the signed `DELETE /v1/referrals/:clickId` (empty body) is sent,
+  with up to 4 attempts for retryable answers (Retry-After ≤ 30 s honoured) and one skew re-sign. `true` on 2xx
+  only; 401, other 4xx (a 409 `NONCE_REUSED` included), exhausted retries, missing credentials or an outbox that
+  cannot be purged → `false` and `INR_FORGET_FAILED { status, code }`. Never queued; ignores `enabled`.
+- **`landingRelay(opts?)`** is implemented: `{ c, scope, ph, d }` (JSON or text/plain, ≤ 1 KB, parsed by the site or
+  read from the request) → one signed `POST /v1/landings` with the 2.2 relay body (`visitorIp`, `visitorUa`,
+  `visitorOrigin`; `visitorIp` is `opts.visitorIp?.(req) ?? req.ip`). Without Express `trust proxy` nothing is
+  forwarded (with or without `opts.visitorIp`) and `INR_RELAY_TRUST_PROXY` is logged once. Limits: 10 / min per
+  visitor IP, 300 / min per process, shared by every handler. The browser always gets an empty 204 (it was 202).
+- **`referralMiddleware()`** removes `inrRef` from a plain-object `req.body` after setting `req.inrRef`.
+  `referralFromRequest` is unchanged (pure).
+- **Capture: `attachReferral(api, { routes })`** (and `attachReferralHeader`): with `routes: (string | RegExp)[]`, only
+  mutating requests whose path (a relative `url` appended to `baseURL`, as axios does) equals a string or matches a
+  RegExp (`lastIndex` ignored) carry the referral. Capture measured 1 499 B gzip with it (budget 1 500 B unchanged).
+- **CLI: `doctor --backend [--mongo-uri <uri>]`** for split repos: root `--root` or the cwd, package.json optional
+  (`file:` / `link:` SDK dependency warns), no `src/network.config.js` needed, frontend checks skipped. Fails on Node
+  < 18, a missing `createConversionReporter`, missing `referralFromRequest` and `referralMiddleware`, or any missing
+  `INR_*` value (process env, else `<root>/.env`; printed as set/unset only). Signs `POST /v1/conversions/ping` `{}`
+  (5 s): 204 ok; 401, `TIMESTAMP_SKEW` (with the offset), 404 and network errors fail; 429 / 503 warn. With
+  `--mongo-uri` it checks the three outbox indexes through the site's own `mongodb` (`createRequire(root)`), else
+  prints `skip`. No env value, URI or host name is printed. Plain `doctor` also signs the ping when the backend env
+  is found.
+- The `server` size budget is 8 100 B gzip: 5.98 KB before this step, 8 051 B measured with the drainer, `forget()`
+  and `landingRelay()`, rounded up to 50 B (addendum "Size budgets" row).
+
+### Packaging (WP18)
+
+- Published by `.github/workflows/sdk-publish.yml` on a `network-sdk-v<version>` tag (the tag must equal
+  `package.json`'s version or the run fails), GitHub environment `npm-publish`, npm trusted publishing (OIDC, no
+  token); a pre-release goes to the dist-tag `beta`, a release to `latest`. `publishConfig.provenance` is `false`
+  (the source repository is private; addendum deviation row). `repository` points at
+  `IntenqueSecurity/intenque-network-hub`, directory `packages/network-sdk`. The tarball is `dist`, `README.md`,
+  `CHANGELOG.md` and `package.json`. Owner steps: `docs/runbooks/sdk-publish.md`.
+
+## 2.1.0-beta.1
+
+Impression, click and landing signals (spec §5.1); `doctor` sends a test impression.
+
+## 2.0.0-beta.1
+
+Manifest schema 2: the "Discover Other Businesses" section, the signed-manifest verifier with the committed
+fallback, referral capture, the CLI (`init`, `sync-fallback`, `doctor`, `print-config`) and the server API surface.

package/README.md

@@ -1,3 +1,255 @@
-# Temporary Holding Version
+# @intenque/network-sdk
 
-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.
+Adds the **"Discover Other Businesses"** section, referral capture and conversion reporting to an Intenque
+network site. Spec: `docs/Network_CrossPromo_Plan.md` §6 in the hub repository; the timed per-site checklist is
+`docs/install-guide.md`.
+
+Version `2.2.0-beta.1` reads manifest **schema 2** (SDK major = manifest schema major). Zero runtime dependencies;
+`react` / `react-dom` ^18 || ^19 are optional peers (only the `react` entry needs them).
+
+| Entry                              | Exports                                                                                                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@intenque/network-sdk/react`      | `NetworkProvider`, `DiscoverBusinesses`, `useNetworkDirectory`, `useNetworkLink`, `defineNetworkConfig`, `DEFAULT_CDN_BASE`, `rootPublicKeys`, verifier    |
+| `@intenque/network-sdk/capture`    | `captureReferral`, `getReferral`, `clearReferral`, `setConsent`, `attachReferral`, `attachReferralHeader` (≤ 1.5 KB gzip, no imports)                      |
+| `@intenque/network-sdk/server`     | `createConversionReporter`, `referralFromRequest`, `referralMiddleware`, `signRequest`, `verifyEnv`, `CONVERSION_TYPES` (Node ≥ 18)                        |
+| `@intenque/network-sdk/styles.css` | optional default styles on `--inr-*` variables for sites without Tailwind                                                                                  |
+| `npx network-sdk`                  | `init`, `sync-fallback`, `doctor`, `print-config` (Node ≥ 18; WebCrypto is polyfilled from `node:crypto` on 18, else the CLI exits 1 with a clear message) |
+
+## Install (frontend, ≤ 30 minutes)
+
+```sh
+cd frontend
+npm i @intenque/network-sdk
+npx network-sdk init --site-key <site-key>        # writes src/network.config.js + src/data/network.fallback.json,
+                                                   # adds "network:sync" / "prebuild" and inlines sync-fallback into "build"
+```
+
+`init` fails with `site <key> has no published manifest; Publish in the admin first` when the hub has not published
+the site yet (step 1 of the checklist). While no production root key ships in the SDK, pass the hub's root and CDN
+explicitly: `--url <cdn-base> --root-keys '<MANIFEST_ROOT_PUBLIC_KEYS json>'` (development only; the flags are
+inlined into the generated scripts and removed by re-running `init` once production is live).
+
+Then paste what `init` prints:
+
+```jsx
+// main.jsx — before ReactDOM.createRoot, before any tracker or GA snippet
+import { captureReferral } from '@intenque/network-sdk/capture'
+import { NetworkProvider } from '@intenque/network-sdk/react'
+import networkConfig from './network.config'
+captureReferral(networkConfig.capture)
+ReactDOM.createRoot(el).render(
+  <NetworkProvider config={networkConfig}>
+    <App />
+  </NetworkProvider>,
+)
+
+// Home.jsx — after <ReviewCarousel />
+import { DiscoverBusinesses } from '@intenque/network-sdk/react'
+;<DiscoverBusinesses />
+
+// ConsentBanner.jsx — next to grantConsent() / denyConsent()
+import { setConsent } from '@intenque/network-sdk/capture'
+setConsent('granted') / setConsent('denied')
+
+// api/axios.js — body mode, no CORS change
+import { attachReferral } from '@intenque/network-sdk/capture'
+attachReferral(api)
+```
+
+App Platform: the frontend component's **Build Command must be `npm run build`** so `sync-fallback` refreshes the
+bundled fallback on every deploy. `npx network-sdk doctor` checks all of the above (import-based, any file layout).
+
+## Install (backend, ≤ 10 minutes)
+
+The timed steps 7–8 of `docs/install-guide.md`, as made on JCM. Node ≥ 18, ESM or CJS, Mongoose 7 or 8.
+
+```sh
+cd backend
+npm i @intenque/network-sdk@2.2.0-beta.1
+```
+
+Env, as `SECRET` values on the backend component (names only in `.env.example`): `INR_ENABLED=false` (only the
+literal `true` turns reporting and referral storage on), `INR_HUB_URL`, `INR_SITE_KEY`, `INR_KEY_ID`,
+`INR_SITE_SECRET` (Admin → Sites → Keys, shown once); `INR_STRICT_ENV=true` on staging only.
+
+```js
+// config/inr.js — imported only from server.js, controllers and scripts, after dotenv has run
+import mongoose from 'mongoose'
+const enabled = process.env.INR_ENABLED === 'true' // default OFF
+const sdk = await import('@intenque/network-sdk/server').catch((err) => {
+  if (err?.code === 'ERR_MODULE_NOT_FOUND' || err?.code === 'MODULE_NOT_FOUND') return null
+  throw err
+})
+if (!sdk && enabled) throw new Error('INR_ENABLED=true but @intenque/network-sdk is not installed')
+// !sdk && !enabled: export a passthrough middleware (req.inrRef = null, inrRef stripped) and a no-op reporter
+if (enabled) sdk.verifyEnv()
+export const inr = sdk.createConversionReporter({
+  hubUrl: process.env.INR_HUB_URL,
+  siteKey: process.env.INR_SITE_KEY,
+  keyId: process.env.INR_KEY_ID,
+  secret: process.env.INR_SITE_SECRET,
+  enabled,
+  outbox: { mongoose },
+})
+export const referralMiddleware = sdk.referralMiddleware
+export const reportAll = (events) => Promise.all(events.map((e) => inr.report(e))).catch(() => {})
+
+// server.js — right after express.json()
+app.use('/api', referralMiddleware())
+
+// booking: store the referral, report nothing yet
+referral: enabled ? req.inrRef : undefined // { clickId, firstClickId, tokenScope, capturedAt }
+
+// report points: one line after the commit or update, never inside a transaction, never changes the response
+await reportAll(paidReports({ appt, session, eventCreated })) // Stripe webhook: await, before the 200
+void reportAll(cancelReport({ appt, at: new Date() })) //        request handler: void
+```
+
+The mapping functions (`paidReports`, `cancelReport`, `noShowReport`, `feeChargedReport`, `refundReports`) are the
+site's own pure module returning `ConversionEvent[]` (`[]` without a referral), so each report point stays one line.
+Then `npx network-sdk doctor --backend --root backend [--mongo-uri <uri>]` (signed ping, env names, indexes), the
+§5.9 privacy text, and only then `INR_ENABLED=true`.
+
+## How it renders
+
+`DiscoverBusinesses` fetches `<cdnBase>/sites/<siteKey>/manifest.json` after mount (4 s timeout, `cache: 'default'`),
+verifies it in the browser with WebCrypto (root certificate → signer window → ES256 P1363 low-S signature → revocation
+list from the **bundled** fallback → identity `site`/`channel`/`utmSource` → rollback floor with one `cache: 'reload'`
+retry), and otherwise renders the committed `network.fallback.json` (verified the same way, time window skipped). It
+renders `null` while loading or when empty, never throws and never toasts. Markup: `<section aria-labelledby>` →
+heading with one accent word → optional subtitle → 1/2/3-column grid of cards (lazy `640×360` image with `srcSet`,
+`h3`, `category · location`, 3-line description, "Visit Website" link with UTMs from `manifest.links`, `target=_blank`,
+`rel="noopener noreferrer"`, `aria-label="Visit {name} website (opens in a new tab)"`).
+
+Styling is headless: pass Tailwind classes per slot in `theme` (`unstyled: true` drops the `inr-*` class names), or
+import `styles.css` and set `--inr-*` variables. Slots: `section container heading accentWord subheading grid card
+imageBox image placeholder body name meta description button buttonIcon`.
+
+## Signals (2.1, spec §5.1)
+
+Everything is switched by the signed manifest, so turning analytics on or off, or changing the sample rate, is a
+publish in the hub — never a site deploy.
+
+- **Nothing** leaves the section unless `analytics.enabled` is true. Click ids and click signals additionally need
+  `analytics.clicks` (with clicks off the link is never rewritten); impressions need `analytics.impressions` and a
+  sampled-in page view.
+- **Page view.** One per mounted section: a random `pv` (kept in memory only), the mount time `m`, and a sampling roll
+  made once (`Math.random() * 1000 < analytics.samplePermille`; `samplePermille: 0` = impressions off, `sp: 0, smp: 0`).
+- **Impression.** One `IntersectionObserver` (threshold 0.5) watches the section and every card. A card is `seen` after
+  ≥ 1 s continuously ≥ 50 % visible; `ms` counts only while the tab is visible; `fv` is the first visible time after
+  mount. The section counts while it, or any of its cards, is ≥ 50 % visible (a one-column phone cannot show half of
+  a tall section). The impression is sent 10 s after the section first appeared, or earlier at the first card click,
+  `visibilitychange → hidden`, `pagehide` or an SPA unmount; later `hidden` / `pagehide` re-send only when something
+  changed, and a click re-sends first when what the hub scores it on changed (the section became seen, a card was
+  first seen) (≤ 10 sends; the hub merges them). Nothing is sent for a page view in which nothing was ever on screen.
+  Prerendered pages attach nothing until `prerenderingchange`; a back/forward-cache restore keeps the page view. The
+  page view never depends on prop identity: an inline `onEvent={() => …}`, `theme={{…}}` or `config` on a parent
+  that re-renders keeps one page view and one manifest fetch.
+- **Click.** `pointerdown` mints the self-describing click id (site index, business index, minute, 16 random bytes)
+  and rewrites the link to `…&inr=<id>` (the href at rest has UTMs only, and goes back to it 2 s after the gesture
+  ends, or at once on blur). A destination whose `instrumentation` is `none` never gets `inr` (it has no
+  `captureReferral` to strip it); its click is still signalled. `click` / middle-button `auxclick` flush the
+  impression first, then send the click; `contextmenu` and `dragstart` send an indirect click (`btn: 2`) because "Open
+  in new tab" and drag-to-tab-bar navigate without a click event. Each id is sent once. Nothing awaits or calls
+  `preventDefault`; navigation is never blocked.
+- **Consent and DEV.** On a `require-consent` site the device bits and the viewport are sent as `hd: 0`, `vp: 0×0`
+  until consent is granted (GPC counts as a denial). A DEV build or a localhost page of a production-channel site
+  sends nothing unless its signal endpoint is a local hub (preview-channel sites always send).
+- **Transport.** `navigator.sendBeacon(url, text)`; when it is missing or returns `false`, `fetch(url, { method:
+'POST', mode: 'no-cors', keepalive: true, credentials: 'omit' })`; when that rejects (it shares the browser's 64 KB
+  keepalive quota) and the page is still visible, one retry without `keepalive`. Nothing is logged; the `signal`
+  event reports `sent: false` when every path failed. An `http:` endpoint is never used from an `https:` page (a dev
+  fallback shipped by mistake sends nothing).
+- **Directory flags** (`sig_fail`, `rev_rollback` with the rejected revision `rr`, `stale_cache`, `fallback_invalid`,
+  `fallback_key_expired`, `sitekey_from_fallback`, `sdk_outdated`) travel on the impression as `fl`.
+- **`onEvent`** mirrors `directory`, `impression` (rendered ids), `click` (with the href **without** the click id, so
+  the site's own tracker never stores it) and `signal` (`{ kind, sent, why? }`).
+- **Custom cards** (`renderCard`): spread `linkProps` on the card's `<a>` (handlers included; a handler you set after
+  the spread replaces ours), pass `observe` as the card element's `ref` for per-card viewability, and call
+  `trackClick(via)` from a control that is not an anchor — it returns the href to open. `useNetworkLink(business)`
+  takes the section's hooks from context; a 2.0-style second argument `onClick(business, href, via)` still works as a
+  deprecated mirror (`trackClick` returns its string) and never throws.
+- **Landing** (`capture`): `captureReferral` sends `{ v: 2, k, c, scope, ph, sdk, t, d }` to `<endpoint>/landing`
+  once per click id — at capture, or after `setConsent('granted')` in `require-consent` mode (`d` = the wait; under
+  GPC the buffered referral is dropped instead: GPC is a denial at all times). It is
+  governed by the destination's own `analytics.landings`, enforced by the hub against the live switch (so a publish,
+  not a rebuild, turns it on or off); `capture.endpoint` is the bundled fallback's endpoint either way, and `null` only
+  for a DEV build of a production site with a non-local hub. Not `analytics.enabled`. `ph` (sha256 of the path, 16
+  hex) is omitted without `crypto.subtle`.
+- **`doctor`** sends one test impression (`src: 'doctor'`, the live manifest's token) to the hub; `--no-impression`
+  skips it, and a failure is a warning.
+
+## Conversion reporting (2.2, spec §6.5)
+
+Backend only (`@intenque/network-sdk/server`, Node ≥ 18, global `fetch`). Four env values: `INR_HUB_URL` (an origin:
+`https://…`, or `http://localhost` / `127.0.0.1` / `[::1]`), `INR_SITE_KEY`, `INR_KEY_ID` (8 hex) and
+`INR_SITE_SECRET` (`inrs1_…`). Call `verifyEnv()` at boot: it names missing or malformed values, throws outside production, or anywhere
+with `INR_STRICT_ENV=true` (set it on staging, which runs `NODE_ENV=production`), and never prints a value.
+
+- **`report(event)`** checks the event against the hub's rules (the same `eventId` shape, per-type amounts, currency
+  with any amount, `reverses` on the linked types; a bad event resolves `invalid` with the failing field), writes the
+  unsigned body to the Mongo outbox and starts sending. It resolves within 2 s whatever Mongo does, never rejects
+  and never waits for the network: `queued`, `spilled` (outbox unavailable; held in memory, ≤ 1000), `disabled` or
+  `invalid`. Request handlers may `void inr.report(…)`; **Stripe webhook handlers `await` it** before answering 200.
+- **Fees** are reported only as `fee_charged` (`feeCents`, `reverses` → the no-show or cancel), once the charge
+  succeeds. Fee refunds are never reported.
+- **Delivery.** Every attempt re-signs `JSON.stringify(body)` with a fresh timestamp and nonce and posts it with
+  `redirect: 'error'` (timeout `INR_TIMEOUT_MS`, default 3000 ms). Any 2xx (202 accepted, 200 duplicate) and
+  409 `NONCE_REUSED` delete the row. 408 / 425 / 429 / 5xx / network errors are retried in process after 2, 8 and
+  30 s (a longer `Retry-After` wins; above 30 s, e.g. `503 BREAKER_OPEN` with `Retry-After: 60`, the row waits in the
+  outbox). `400 TIMESTAMP_SKEW` corrects the process clock from the hub's `Date` and re-signs once. A 401 (or missing
+  config) is retried every 10 min for 24 h, re-reading `INR_KEY_ID` / `INR_SITE_SECRET`, so a redeploy after a key
+  rotation loses nothing. Other 400s (`CURRENCY_NOT_ALLOWED`, `TYPE_NOT_ALLOWED`, `UNKNOWN_FIELD`, …) are dropped
+  with a `warn` `inr_outbox_dropped_total { eventType, eventId, status, code, reason }` line (never a click id).
+- **Outbox and drainer.** The reporter creates the outbox's three indexes itself (`createdAt` TTL 14 d,
+  `nextAttemptAt`, unique `(eventType, eventId)`), so `autoIndex: false` sites get them too; each failed index is
+  retried at the next drain tick, with one `INR_OUTBOX_INDEX_FAILED` warning. The collection is
+  `outbox.collection`, else `INR_OUTBOX_COLLECTION`, else `inrConversionOutbox`. Mongoose 7 and 8 both work. Every
+  60 s (± 10 s; the first tick 10–20 s after start) a drain moves the in-memory spill into Mongo and sends up to 50 due rows. `nextAttemptAt` is a lease: a row
+  is claimed atomically for 150 s, so several backend instances never send it twice and a crashed sender's row goes
+  out again 150 s later with a fresh signature. Retries back off from 1 to 30 min (or the hub's `Retry-After`, up to
+  1 h) with no attempt limit; a 429 or 503 ends the tick; rows older than 14 d − 1 h are dropped as `expired`.
+  `drainNow()` runs a tick now; call `close()` on shutdown (stops the timer, waits ≤ 5 s).
+- **`forget(clickId)`** (DSAR, §5.9): deletes queued reports naming the id, then sends the signed
+  `DELETE /v1/referrals/:clickId`, retrying 503 / 429 / 5xx up to 4 times (2, 8, 30 s). It resolves `true` once the
+  hub answered 2xx and `false` otherwise (401, other 4xx, missing env, Mongo down; warn `INR_FORGET_FAILED`). Keep
+  the booking's referral until it returns `true`. It works with `enabled: false`.
+- **`referralMiddleware()`** sets `req.inrRef` and removes `inrRef` from a plain-object body, so `new Model(req.body)`
+  never sees it. `referralFromRequest(req)` leaves the body alone.
+- **`landingRelay(opts?)`** (optional; JCM does not mount it): `app.post('/inr/landing', inr.landingRelay())` takes
+  `{ c, scope, ph, d }` (JSON or text, ≤ 1 KB) from the site's own frontend and forwards a signed `POST /v1/landings`
+  with the visitor's IP, user agent and `Origin` (the hub hashes and discards them). Express needs `trust proxy` set,
+  even with `visitorIp: (req) => …` (otherwise nothing is forwarded and `INR_RELAY_TRUST_PROXY` is logged once). At
+  most 10 per minute per visitor IP and 300 per process (all handlers together) are forwarded. The browser always
+  gets 204.
+- **Capture `routes`.** `attachReferral(api, { routes: ['/api/appointments/book'] })` adds the referral only to
+  mutating requests whose path equals a string or matches a RegExp entry. The path is the one axios requests: a
+  relative `url` is appended to `baseURL` (`baseURL: '/api'` + `'/appointments/book'` → `/api/appointments/book`).
+- **`doctor --backend [--root <dir>] [--mongo-uri <uri>]`** for a split backend (no `src/`, no `network.config.js`
+  needed): Node ≥ 18, the reporter and referral imports, the SDK dependency, the four env names (from the process
+  env or `<root>/.env`, printed as set/unset only), a signed `POST /v1/conversions/ping` (204 ok; 401 "key id or
+  secret rejected"; 404 "wrong INR_HUB_URL?"), and with `--mongo-uri` the outbox indexes through the site's own
+  `mongodb` driver. No value and no URI is printed.
+
+## Phase status
+
+- Phase 1: rendering, verification, fallback/floor, `capture` (consent transitions, body-mode `attachReferral`), CLI,
+  `server` API surface with `signRequest` and the Mongo outbox model.
+- Phase 2: impression, click and landing signals; `doctor`'s test impression.
+- Phase 3 (this release): conversion reporting (above): signed delivery, the outbox drainer, `forget()`,
+  `landingRelay()`, `referralMiddleware` stripping `inrRef`, the capture `routes` allowlist and `doctor --backend`.
+
+## Development
+
+```sh
+npm run build            # tsup → dist (esm + cjs + d.ts, styles.css, cli)
+npm test                 # build + size-limit budgets + vitest: the SDK suite (the hub's shared vectors must pass
+                         # byte-for-byte) and an e2e project that posts SDK-made bodies to the real hub ingest
+                         # (apps/api test app on mongodb-memory-server)
+npm run size             # react ≤ 12 KB gz (incl. verifier + signals), capture ≤ 1.5 KB, server ≤ 8 100 B, styles ≤ 3 KB
+npm run version:bump -- minor   # bumps package.json + SDK_VERSION together; then tag network-sdk-v<version> and push:
+                                # .github/workflows/sdk-publish.yml publishes via npm trusted publishing (OIDC),
+                                # environment npm-publish, --tag beta for pre-releases (docs/runbooks/sdk-publish.md)
+```
+
+Production root keys are added in `src/rootPublicKeys.ts` (see the comment there and `docs/install-guide.md`).

package/dist/capture/index.cjs

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var C=(n,e)=>{for(var t in e)u(n,t,{get:e[t],enumerable:!0})},M=(n,e,t,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of y(e))!k.call(n,r)&&r!==t&&u(n,r,{get:()=>e[r],enumerable:!(o=m(e,r))||o.enumerable});return n};var L=n=>M(u({},"__esModule",{value:!0}),n);var w={};C(w,{attachReferral:()=>A,attachReferralHeader:()=>O,captureReferral:()=>b,clearReferral:()=>N,getReferral:()=>I,onConsentChange:()=>T,setConsent:()=>E});module.exports=L(w);var _="2.2.0-beta.2";function S(n,e,t){let o=s=>{try{t?.(s)}catch{}return s};try{if(location.protocol=="https:"&&/^http:/i.test(n))return o(!1)}catch{}try{if(navigator.sendBeacon(n,e))return o(!0)}catch{}let r=s=>fetch(n,{method:"POST",mode:"no-cors",keepalive:s,credentials:"omit",body:e});try{return r(!0).then(()=>o(!0),()=>{try{if(document.visibilityState=="visible")return void r(!1).then(()=>o(!0),()=>o(!1))}catch{}o(!1)}),!0}catch{return o(!1)}}var f="inr_ref",h=2592e6,a={},l=null,c=(n,e)=>{try{let t=n?localStorage:sessionStorage;if(e===void 0)return JSON.parse(t.getItem(f)||"null");e?t.setItem(f,JSON.stringify(e)):t.removeItem(f)}catch{}return null},R=()=>!!navigator.globalPrivacyControl,p=()=>a.consent?.get()=="granted"&&!R(),g="",x=n=>{let e=a.endpoint,t=n.last.c;if(!e||!a.siteKey||g==t)return;g=t;let o=r=>{let s=Date.now();S(e.replace(/\/+$/,"")+"/landing",JSON.stringify({v:2,k:a.siteKey,c:t,scope:"session",ph:r&&[...new Uint8Array(r,0,8)].map(i=>(i+256).toString(16).slice(1)).join(""),sdk:_,t:s,d:Math.min(h,Math.max(0,s-n.last.t))}))};try{crypto.subtle.digest("SHA-256",new TextEncoder().encode(location.pathname)).then(o,()=>o())}catch{o()}};function b(n={}){a=n;try{let e=new URL(location.href),t=e.searchParams.get("inr");if(!t||(e.searchParams.delete("inr"),history.replaceState(history.state,"",e.href),!/^[A-Za-z0-9_-]{32}$/.test(t)))return;let o={c:t,t:Date.now(),from:e.searchParams.get("utm_source")},r=c(0),s={last:o,first:r?.first||o};if(n.consentMode=="require-consent"&&!p()){l=s;return}c(0,s),p()&&c(1,s),x(s)}catch{}}function E(n){try{if(n=="granted"){let e=l;if(l=null,e&&R())return;let t=e||c(0);t&&(c(0,t),p()&&c(1,t),e&&x(e))}else l=null,c(1,null)}catch{}}var T=E;function N(){l=null,c(0,null),c(1,null)}function I(){try{let n=c(0),e=c(1),t=n&&(!e||n.last.t>=e.last.t)?n:e;return!t||Date.now()-t.last.t>h?null:{clickId:t.last.c,firstClickId:t.first.c==t.last.c?null:t.first.c,capturedAt:t.last.t,tokenScope:n&&n.last.c==t.last.c?"session":"persistent",consented:!!p()}}catch{return null}}function A(n,e={}){n.interceptors.request.use(t=>{try{if(/^(get|head|options)?$/i.test(t.method||""))return t;let o=new URL((t.baseURL||n.defaults?.baseURL||"").replace(/\/*$/,"/"),location.origin),r=new URL((t.url||"").replace(/^\/(?!\/)/,""),o),s=r.pathname;if(r.origin!=o.origin&&!e.origins?.includes(r.origin)||e.routes&&!e.routes.some(d=>d.test?~s.search(d):d==s))return t;let i=I();if(!i)return t;e.mode=="header"?(t.headers=t.headers||{},t.headers["X-INR-Ref"]=i.clickId,t.headers["X-INR-Ref-Scope"]=i.tokenScope,i.firstClickId&&(t.headers["X-INR-Ref-First"]=i.firstClickId)):(t.data==null||Object.getPrototypeOf(t.data)==Object.prototype)&&(t.data={...t.data,inrRef:{clickId:i.clickId,firstClickId:i.firstClickId,tokenScope:i.tokenScope}})}catch{}return t})}var O=(n,e={})=>A(n,{...e,mode:"header"});

package/dist/capture/index.d.cts

@@ -0,0 +1,57 @@
+type Consent = 'granted' | 'denied' | null;
+type CaptureOptions = {
+    siteKey?: string;
+    endpoint?: string | null;
+    consent?: {
+        get: () => Consent;
+    } | undefined;
+    consentMode?: 'session-default' | 'require-consent' | undefined;
+};
+type Referral = {
+    clickId: string;
+    firstClickId: string | null;
+    capturedAt: number;
+    tokenScope: 'session' | 'persistent';
+    consented: boolean;
+};
+declare function captureReferral(o?: CaptureOptions): void;
+declare function setConsent(state: 'granted' | 'denied'): void;
+/** @deprecated use setConsent */
+declare const onConsentChange: typeof setConsent;
+declare function clearReferral(): void;
+declare function getReferral(): Referral | null;
+type Req = {
+    url?: string;
+    baseURL?: string;
+    method?: string;
+    data?: unknown;
+    headers?: Record<string, unknown>;
+};
+type Axios = {
+    defaults?: {
+        baseURL?: string | undefined;
+    };
+    interceptors: {
+        request: {
+            use: (f: (r: Req) => Req) => unknown;
+        };
+    };
+};
+/**
+ * `routes` (2.2 data minimisation): when given, only mutating requests whose path equals a string entry or matches a
+ * RegExp entry carry the referral. The path is the one axios requests: a relative `url` (leading `/` or not) is
+ * appended to `baseURL` (axios `combineURLs`), never URL-resolved against it (only an empty `url` differs: it reads as
+ * `baseURL/`). A RegExp's `g` / `y` `lastIndex` is ignored (`search`).
+ */
+declare function attachReferral(api: Axios, o?: {
+    mode?: 'body' | 'header';
+    origins?: string[];
+    routes?: (string | RegExp)[];
+}): void;
+/** Alias for `attachReferral(api, { mode: 'header' })`. */
+declare const attachReferralHeader: (api: Axios, o?: {
+    origins?: string[];
+    routes?: (string | RegExp)[];
+}) => void;
+
+export { type CaptureOptions, type Referral, attachReferral, attachReferralHeader, captureReferral, clearReferral, getReferral, onConsentChange, setConsent };

package/dist/capture/index.d.ts

@@ -0,0 +1,57 @@
+type Consent = 'granted' | 'denied' | null;
+type CaptureOptions = {
+    siteKey?: string;
+    endpoint?: string | null;
+    consent?: {
+        get: () => Consent;
+    } | undefined;
+    consentMode?: 'session-default' | 'require-consent' | undefined;
+};
+type Referral = {
+    clickId: string;
+    firstClickId: string | null;
+    capturedAt: number;
+    tokenScope: 'session' | 'persistent';
+    consented: boolean;
+};
+declare function captureReferral(o?: CaptureOptions): void;
+declare function setConsent(state: 'granted' | 'denied'): void;
+/** @deprecated use setConsent */
+declare const onConsentChange: typeof setConsent;
+declare function clearReferral(): void;
+declare function getReferral(): Referral | null;
+type Req = {
+    url?: string;
+    baseURL?: string;
+    method?: string;
+    data?: unknown;
+    headers?: Record<string, unknown>;
+};
+type Axios = {
+    defaults?: {
+        baseURL?: string | undefined;
+    };
+    interceptors: {
+        request: {
+            use: (f: (r: Req) => Req) => unknown;
+        };
+    };
+};
+/**
+ * `routes` (2.2 data minimisation): when given, only mutating requests whose path equals a string entry or matches a
+ * RegExp entry carry the referral. The path is the one axios requests: a relative `url` (leading `/` or not) is
+ * appended to `baseURL` (axios `combineURLs`), never URL-resolved against it (only an empty `url` differs: it reads as
+ * `baseURL/`). A RegExp's `g` / `y` `lastIndex` is ignored (`search`).
+ */
+declare function attachReferral(api: Axios, o?: {
+    mode?: 'body' | 'header';
+    origins?: string[];
+    routes?: (string | RegExp)[];
+}): void;
+/** Alias for `attachReferral(api, { mode: 'header' })`. */
+declare const attachReferralHeader: (api: Axios, o?: {
+    origins?: string[];
+    routes?: (string | RegExp)[];
+}) => void;
+
+export { type CaptureOptions, type Referral, attachReferral, attachReferralHeader, captureReferral, clearReferral, getReferral, onConsentChange, setConsent };

package/dist/capture/index.js

@@ -0,0 +1 @@
+var f="2.2.0-beta.2";function _(n,e,t){let o=r=>{try{t?.(r)}catch{}return r};try{if(location.protocol=="https:"&&/^http:/i.test(n))return o(!1)}catch{}try{if(navigator.sendBeacon(n,e))return o(!0)}catch{}let s=r=>fetch(n,{method:"POST",mode:"no-cors",keepalive:r,credentials:"omit",body:e});try{return s(!0).then(()=>o(!0),()=>{try{if(document.visibilityState=="visible")return void s(!1).then(()=>o(!0),()=>o(!1))}catch{}o(!1)}),!0}catch{return o(!1)}}var u="inr_ref",g=2592e6,a={},l=null,c=(n,e)=>{try{let t=n?localStorage:sessionStorage;if(e===void 0)return JSON.parse(t.getItem(u)||"null");e?t.setItem(u,JSON.stringify(e)):t.removeItem(u)}catch{}return null},h=()=>!!navigator.globalPrivacyControl,p=()=>a.consent?.get()=="granted"&&!h(),S="",R=n=>{let e=a.endpoint,t=n.last.c;if(!e||!a.siteKey||S==t)return;S=t;let o=s=>{let r=Date.now();_(e.replace(/\/+$/,"")+"/landing",JSON.stringify({v:2,k:a.siteKey,c:t,scope:"session",ph:s&&[...new Uint8Array(s,0,8)].map(i=>(i+256).toString(16).slice(1)).join(""),sdk:f,t:r,d:Math.min(g,Math.max(0,r-n.last.t))}))};try{crypto.subtle.digest("SHA-256",new TextEncoder().encode(location.pathname)).then(o,()=>o())}catch{o()}};function C(n={}){a=n;try{let e=new URL(location.href),t=e.searchParams.get("inr");if(!t||(e.searchParams.delete("inr"),history.replaceState(history.state,"",e.href),!/^[A-Za-z0-9_-]{32}$/.test(t)))return;let o={c:t,t:Date.now(),from:e.searchParams.get("utm_source")},s=c(0),r={last:o,first:s?.first||o};if(n.consentMode=="require-consent"&&!p()){l=r;return}c(0,r),p()&&c(1,r),R(r)}catch{}}function x(n){try{if(n=="granted"){let e=l;if(l=null,e&&h())return;let t=e||c(0);t&&(c(0,t),p()&&c(1,t),e&&R(e))}else l=null,c(1,null)}catch{}}var M=x;function L(){l=null,c(0,null),c(1,null)}function E(){try{let n=c(0),e=c(1),t=n&&(!e||n.last.t>=e.last.t)?n:e;return!t||Date.now()-t.last.t>g?null:{clickId:t.last.c,firstClickId:t.first.c==t.last.c?null:t.first.c,capturedAt:t.last.t,tokenScope:n&&n.last.c==t.last.c?"session":"persistent",consented:!!p()}}catch{return null}}function I(n,e={}){n.interceptors.request.use(t=>{try{if(/^(get|head|options)?$/i.test(t.method||""))return t;let o=new URL((t.baseURL||n.defaults?.baseURL||"").replace(/\/*$/,"/"),location.origin),s=new URL((t.url||"").replace(/^\/(?!\/)/,""),o),r=s.pathname;if(s.origin!=o.origin&&!e.origins?.includes(s.origin)||e.routes&&!e.routes.some(d=>d.test?~r.search(d):d==r))return t;let i=E();if(!i)return t;e.mode=="header"?(t.headers=t.headers||{},t.headers["X-INR-Ref"]=i.clickId,t.headers["X-INR-Ref-Scope"]=i.tokenScope,i.firstClickId&&(t.headers["X-INR-Ref-First"]=i.firstClickId)):(t.data==null||Object.getPrototypeOf(t.data)==Object.prototype)&&(t.data={...t.data,inrRef:{clickId:i.clickId,firstClickId:i.firstClickId,tokenScope:i.tokenScope}})}catch{}return t})}var b=(n,e={})=>I(n,{...e,mode:"header"});export{I as attachReferral,b as attachReferralHeader,C as captureReferral,L as clearReferral,E as getReferral,M as onConsentChange,x as setConsent};