@vio-live/web-sdk 0.23.1 → 0.26.0

package/README.md

@@ -179,36 +179,94 @@ template that wants slots shared across articles simply sets no scope.
 
 ### Declaration
 
-Every mounted element registers its id (and label); after the first successful
-`Vio.bootstrap()` the SDK sends **one** manifest for the whole page
-(`POST /v2/mobile/components/manifest`, `mode: 'merge'`, so one page never
-deprecates another page's slots) and again whenever a new id or label appears.
-The browser remembers **each id (under its label) for 24 h** in `localStorage`
-(under the platform and a hash of the key — never the key itself), so a
-multi-page site posts only the ids a page adds, a revisit posts nothing, a
-renamed block posts again; without storage it simply posts each load. A failed
+Every mounted element registers its id, its label and its **kind** (`card` |
+`carousel` | `detail` — each manifest location is `{ id, displayName, kind }`; the
+campaigns micro stores the kind from 2026-10 on and ignored the key before); after
+the first successful `Vio.bootstrap()` the SDK sends **one** manifest for the whole
+page (`POST /v2/mobile/components/manifest`, `mode: 'merge'`, so one page never
+deprecates another page's slots) and again whenever a new id, label or kind appears.
+The browser remembers **each id — under its label and the campaign it was
+declared with — for 24 h** in `localStorage` (under the platform and a hash of
+the key — never the key itself; one state per id), so a multi-page site posts
+only the ids a page adds, a revisit posts nothing, a renamed block or a page that
+changed campaign posts again; without storage it simply posts each load. A failed
 attempt (or a server that ignored `merge`) is not retried for 1 h; a declaration
 sends at most 100 locations and a page load at most 3 manifests (each cap warns
 once). Best-effort, never throws. By hand, e.g. from an editor (`force` re-sends
 everything and ignores the per-load cap):
 
 ```ts
-await Vio.declareSlots(['hero', { id: 'sidebar', displayName: 'Sidebar' }], { force: true })
+await Vio.declareSlots(['hero', { id: 'sidebar', displayName: 'Sidebar', kind: 'carousel' }], { force: true })
 // → ManifestResult | null (null = skipped as already declared, or failed — see the console)
+
+// What an element does on mount (a host block can too). `(id, name, campaignId)` still works.
+const release = Vio.registerSlot('sidebar', 'Sidebar', { kind: 'carousel', campaignId: 12 })
 ```
 
+The first kind an id gets stays — the cards a carousel renders share the carousel's
+id, and the slot is the carousel's.
+
 ### Which campaign a slot shows
 
 Among the active campaigns of the bootstrap, the one whose assignment names the
 slot (for this platform, or for all) and whose window is open right now; if
-several, the default campaign, else the first listed. No assignment → the default
+several, the default campaign, else the first listed. No assignment → the page's
+campaign (see *Page campaign*) when the bootstrap lists it as active → the default
 campaign. `Vio.campaignForSlot('hero')` answers from the last bootstrap (`null`
-before it); the pure `resolveSlotCampaign(boot, slot, now?, platform?)` is exported
-from `/core`. A carousel or card **without a `sponsor-id`** uses the primary sponsor
+before it); the pure `resolveSlotCampaign(boot, slot, now?, platform?, pageCampaignId?)`
+is exported from `/core`. A carousel or card **without a `sponsor-id`** uses the primary sponsor
 of its slot's campaign (the default campaign's when the slot has none), and the
 detail opened by such a card does the same — before 0.23 a sponsorless card did
 nothing. An explicit `sponsor-id` still wins.
 
+### Page campaign — an editorial page that belongs to one campaign
+
+Native-SDK style placements stay the primary model: the **dashboard assigns**
+a campaign to a slot. But an editorial page — a Vev article, a Replit article —
+often *is* part of one campaign, and the page can say so:
+
+```ts
+Vio.init({ apiKey: '…', campaignId: 12 })          // the whole page
+```
+
+```html
+<body data-vio-campaign="12">                        <!-- inheritable, like the scope -->
+<vio-product-carousel vio-campaign="10" …>          <!-- one element of another campaign -->
+```
+
+Precedence per element: `vio-campaign` on the element → the nearest ancestor's
+`data-vio-campaign` → `Vio.init({ campaignId })`; an unusable level (not a positive
+integer, paused, unknown) falls through to the next. The attributes are read when
+the element mounts or its own attribute changes — there is no observer on the
+ancestors. On web/Replit a **per-article** campaign needs a per-article scope too
+(`data-vio-scope`, see above): without it the auto ids of every article are the
+same `carousel-1`, and the articles' campaigns would overwrite one another's
+assignment; Vev ids are per block, so it does not apply there. What it does:
+
+- **Declaration.** The manifest carries the page's campaign (top-level) and an
+  element's own campaign per location when it differs. The campaigns service
+  (campaigns micro PR #16) turns that into assignments of the page's slots
+  (`source: 'page'`) — **unless the dashboard already assigned the slot: the
+  dashboard wins**, and the SDK warns once per such slot (and once when this page
+  moved a slot from an earlier page assignment). A page that changes campaign
+  declares again; a campaign the micro did not take up is retried after an hour.
+- **Resolution, immediately.** `Vio.campaignForSlot()` / `Vio.attribution()` (and
+  so the elements, the cart origins and the events) resolve as: the slot's
+  assignment (a dashboard one always; a page-sourced one unless the page now
+  declares a different active campaign or the known sponsor takes no part in it)
+  → the page's campaign, when the bootstrap lists it as active and — with a known
+  sponsor — that sponsor takes part in it → the sponsor's campaign → the default. An editor sees the effect in the Vev
+  editor before the manifest round-trips.
+- `Vio.pageCampaign()` returns the init-level campaign as the bootstrap lists it
+  (active), else `null`.
+- With a **known sponsor** (a card with `sponsor-id`), the page's campaign — and a
+  slot assignment the page made itself (`source: 'page'`) — count only when that
+  sponsor takes part in the campaign; otherwise the sponsor's own campaign applies.
+  A dashboard assignment counts unconditionally.
+- `Vio.init({ debug: true })` logs the micro's `assignment` per slot at
+  `console.debug`. It is independent of `Vio.analytics.start({ debug })`, which
+  logs the analytics events.
+
 ## Attribution — the slot, the campaign, the article
 
 `Vio.attribution(slot?)` is **the** attribution helper — the SDK elements use it,
@@ -216,7 +274,7 @@ and so do the Vev blocks and the Replit site:
 
 ```ts
 Vio.attribution('hero')
-// → { slot: 'hero', campaignId: 12, sponsorId: 7, contentId: 'article-42', contentTitle: 'Why the lamp matters' }
+// → { slot: 'hero', campaignId: 12, sponsorId: 7, contentId: 'article-42', contentTitle: 'Why the lamp matters', contentUrl: 'https://host.example/article-42' } // contentUrl: origin + path
 ```
 
 `campaignId`/`sponsorId` are the slot's campaign and its primary sponsor (`{}` before
@@ -241,17 +299,25 @@ titles are cut — in one place, before anything is sent. Per element,
 tracks carries `slot` (the effective id), `location_id` (= the slot), `content_id`
 and `content_title`. `campaign_id` resolves as explicit `campaignId` (the element's
 own attribution travels in its event detail and is honored as such) → the slot's
-assigned campaign → the sponsor's campaign → the default. Two things changed from
+assigned campaign → the page's campaign (when the sponsor takes part in it) → the
+sponsor's campaign → the default. Two things changed from
 0.22 for carousels: a carousel's impressions and `view_item_list` report
 `location_id` as its slot id (`carousel-1`, or the `vio-slot`) instead of its
 `label`, and every event now carries `content_id` / `content_title` — including
-the single-campaign `begin_checkout` / `purchase`.
+the single-campaign `begin_checkout` / `purchase`. Since 0.25 every element also
+says **what it is**: `component_template_id` is `product-card` for a card,
+`product-carousel` for a carousel — and for the cards it renders, so a carousel's
+impressions and its clicks count under one component type — and `product-detail`
+for the detail (its `view_item`, `add_to_cart` and `begin_checkout`). A host that
+lays cards out itself can set `component-template-id` on them (`product-grid`).
 
 ### Cart origins and the purchase per campaign
 
 The cart remembers **where every unit came from**. The add paths take an optional
-`origin` (`{ campaignId?, slot?, contentId? }` — what `Vio.attribution(slot)`
-answers), and so does `adjustQuantity(lineItemId, sponsorId, delta, { origin })`:
+`origin` (`{ campaignId?, slot?, contentId?, componentKind?, contentUrl?, contentTitle? }`
+— what `Vio.attribution(slot)` answers, plus the kind of element; the elements pass
+their `componentTemplateId` as it), and so does
+`adjustQuantity(lineItemId, sponsorId, delta, { origin })`:
 
 ```ts
 Vio.cart.addProduct({ product, sponsorId: 1, origin: Vio.attribution('hero') })
@@ -259,10 +325,13 @@ Vio.cart.addProduct({ product, sponsorId: 1, origin: Vio.attribution('hero') })
 onProductAdd={(e) => Vio.cart.addProduct({ product, sponsorId, origin: e.detail.origin })}
 ```
 
-Each line keeps `origins: Array<{ campaignId?, slot?, contentId?, quantity }>`: an
-add with an origin increments that origin, without one the most recent (the
-`<vio-cart>` +/− buttons pass none), and −1/remove comes off the most recent first.
-They persist with the cart; carts from before origins read as one empty origin.
+Each line keeps `origins: Array<{ campaignId?, slot?, contentId?, componentKind?,
+contentUrl?, contentTitle?, quantity }>`: an add with an origin increments that
+origin, without one the most recent (the `<vio-cart>` +/− buttons pass none), and
+−1/remove comes off the most recent first. A place is campaign + slot + content +
+kind of element (an add from a card and one from the detail of the same slot are two
+origins); the page's URL and title are attributes of it. They persist with the cart;
+carts from before origins read as one empty origin.
 
 At checkout and purchase the cart is **split per campaign**: `begin_checkout` and
 `purchase` go out **once per campaign in the cart**, each with that campaign's
@@ -283,6 +352,107 @@ Vio.cartSlices(undefined, { items }) // pure, over a snapshot of lines
 // → CartSlice[]: { campaignId?, sponsorId?, slot?, contentId?, items: VioItem[], value, currency?, slice, slices }
 ```
 
+### Attribution on the order — what Commerce receives (0.26)
+
+Since 0.26 the origins do not stay in the browser: **Commerce receives them**
+(ADR-0035 phase B), so the order is born knowing where it was sold from.
+
+- **Per line.** Every `AddItem` carries the line's `origin` — `{ campaign_id,
+  location_id (the slot), component_kind, content_url, content_title }` — and a
+  quantity **increase** carries, on `UpdateItem`, the origin of the units it adds (the
+  given one, else the line's most recent; a burst of +1 from two places is two
+  updates, each with its own origin); a decrease and a removal carry none, and an add
+  without an origin sends none (the line inherits the order's campaign on the
+  server). `component_kind` is the kind of element as the collector names it too
+  (`card` | `carousel` | `detail`: the element's `componentTemplateId` without its
+  `product-` / `vev-` prefix, else the kind word in the slot id), so
+  `order_item.component_kind` and `breakdown?by=component_kind` agree. shopcart keeps
+  every origin of a line with its units and writes `order_item.campaign_id` /
+  `location_id` / `component_kind` from them.
+- **Per checkout.** `CreateCheckout` and the `UpdateCheckout` right before paying
+  carry `attribution`: `surface_key` (the SDK key — the gateway sets it from
+  `X-API-Key` anyway, and shopcart checks it against the cart's channel, so a page
+  cannot credit a sale to another surface), `campaign_id` (the page's campaign,
+  `Vio.pageCampaign()` — else the campaign that explains most units of the cart under
+  the same rule `purchase` is split by), `content_url` / `content_title` (the page at
+  pay time) and `entry` (`{ referrer, utm_source, utm_medium, utm_campaign,
+  landing_url }`: the landing the session **remembers** — the same memory the
+  `client` block reads, which now keeps the landing page too — never the page the
+  shopper pays on taken for a landing; without a remembered landing there is no
+  `entry`). They become `order.surface_id` / `campaign_id` / `content_url` /
+  `content_title` / `entry_source`. `Vio.orderAttribution(sponsorId?)` answers what
+  would be sent — synchronously: nothing on the way to a payment waits for it.
+- **`content_url` is origin + path**, no query string, no fragment — on the order,
+  on the lines and in the landing: the query is where a page carries e-mails, tokens
+  and tracking tails, and none of that belongs on an order row. A site whose article
+  lives in the query or the hash identifies it through `contentId` (`Vio.init({
+  contentId })`, `?vio_content=`, the `vio:content-id` meta), not through the URL.
+  The analytics events keep `location.href` as before.
+- **Privacy.** On a **`minimal`** surface what says *which screen* a unit was sold
+  from and *why the shopper was there* stays off Commerce — the same promise the
+  collector keeps for the events (vio-analytics `privacy.ts`): no `content_url`, no
+  `content_title`, no `location_id` on the lines, no `entry`; `surface_key`,
+  `campaign_id` and `component_kind` do travel. The mode comes from
+  `Vio.init({ privacyMode: 'minimal' })` when the host knows it (always wins), else
+  the bootstrap's `surface.privacyMode`, else the surface itself: `GET
+  /v2/mobile/surface`, asked **once at `Vio.init()`** (and again by `bootstrap()` if
+  that failed), given 1.5 s, believed for the page load — a failure or a timeout is
+  believed for a minute, then asked again; a service that predates the endpoint (404)
+  means `standard`; a word the SDK does not know does not. The payment path reads
+  what is known at that moment (`Vio.privacyModeNow()`) and never waits; an unknown
+  mode counts as `minimal`. The cart's lines wait for the ask in flight, at most its
+  cap (`Vio.privacyMode()`).
+- **A gateway that predates these arguments** (`origin` on `LineItemInput` /
+  `UpdateItem`, `attribution` on `CreateCheckout` / `UpdateCheckout`) refuses the
+  operation at validation, before anything runs: the SDK sends it again without them,
+  once per page load, says so in the console, and the cart works as in 0.25. Nothing
+  that ran — data in the answer, or an error with a `path` — is ever repeated.
+
+Everything is capped to Commerce's columns in one place (`lineOriginWire`,
+`checkoutAttributionOf`, exported from `/core`): slot 100, kind 32, URL 2 048, title
+255, referrer 2 048, utm 128; `campaign_id` only as a positive 32-bit `Int`.
+
+### The visit and the buyer — `client` and `buyer_id` (0.25)
+
+Every event carries a **`client`** block, the standard context of the visit:
+`language` (`navigator.language`), the **landing page's** `referrer` and
+`utm_source` / `utm_medium` / `utm_campaign` / `utm_term` / `utm_content`,
+`screen_w` / `screen_h` and `tz` (IANA). The landing is read once and remembered
+for the session in `sessionStorage` (`vio.landing.v1`), so the third page of a visit
+still says it came from the newsletter — a page's own internal referrer is never
+sent. The referrer is kept as origin + path (no query string, no fragment) and
+dropped when it is this same host (a self-referral says nothing about the entry). A
+URL with utm parameters is a new landing that replaces the memory — unless it was
+reached from this same host, i.e. an internal link that propagates utm, which keeps
+the landing that was. With `requireConsent` nothing is written until
+`setConsent(true)`, and `setConsent(false)` forgets it. Device type, OS, browser and
+country are **not** sent: the collector derives them from the request itself. The
+block is computed once per page load (capped to the collector's limits) and the
+same object rides on every event. `resolveClientContext()` / `resolveLanding()` are
+exported from `/core` for hosts with their own pipeline.
+
+A `purchase` carries **`commerce.buyer_id`**: shopcart's `buyer_ref`, the keyed hash
+Commerce computes from the buyer's email — one person, one ref across orders and
+devices, nothing reversible — so a campaign can count distinct and repeat buyers.
+The SDK never sends an email and never hashes one itself: it forwards the reference
+the checkout answers (the order-number query, the Apple Pay and the Klarna native
+confirmations select `buyer_ref`; a gateway that predates the field is asked again
+without it, once per page load) and omits it otherwise. `Vio.checkout.getOrderReference(checkoutId, sponsorId?)`
+answers `{ orderNumber, buyerRef }` (never throws; concurrent asks share one
+request); `getOrderNumber` is its order-number half. The `vio:payment-success`
+detail carries it as `buyerRef`; an emitter that has to ask for it asks at once (and
+again at 1.2 s while the checkout has neither order nor reference — a webhook may
+still be writing it), waits at most 2.5 s, fires the event at once without it when the
+page hides or the element is removed, and never asks when it cannot help (the
+gateway has no `buyer_ref` yet; a confirmation that already answered). The
+confirmation screen never waits. A host with its own checkout passes `buyerRef` (or
+`buyer_ref`) in its `vio:payment-success` / `vio:checkout-open` detail, or
+`commerce.buyerId` to `Vio.analytics.track()`; anything that is not a reference
+(an email, more than 128 chars, anything outside `[A-Za-z0-9._~-]`) is dropped
+(`normalizeBuyerRef` / `buyerRefOf`, exported from `/core`). **Without consent**
+(`requireConsent` until `setConsent(true)`) `buyer_id` is not sent at all: a visit
+measured with ephemeral ids carries no stable identifier of a person.
+
 ## Theming
 
 Every component reads its colors and fonts from `--vio-*` CSS custom properties