@vio-live/web-sdk 0.24.0 → 0.26.1

package/README.md

@@ -179,10 +179,12 @@ 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.
+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
@@ -194,10 +196,16 @@ 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
@@ -266,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
@@ -296,13 +304,20 @@ 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') })
@@ -310,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
@@ -334,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

package/dist/{chunk-N6U65DWG.js → chunk-6Q2M3MIK.js}

@@ -1,4 +1,4 @@
-import { Vio, __decorateClass, primaryImageUrl, displayPrice, toCampaignId, getGlobalCurrency, ensureVippsButton, formatPrice, nexiReturnPaymentId, readNexiPending, kustomReturnOutcome, KUSTOM_RETURN_QUERY_KEYS, ADYEN_RETURN_METHOD, adyenReturnParams, ADYEN_RETURN_QUERY_KEYS, adyenReturnOutcome, AdyenOriginError, normalizeSlotId, autoSlotDisplayName, autoSlotId, normalizeScope, campaignCandidates } from './chunk-AXJKB2CW.js';
+import { Vio, __decorateClass, primaryImageUrl, displayPrice, toCampaignId, getGlobalCurrency, ensureVippsButton, formatPrice, buyerRefOf, nexiReturnPaymentId, readNexiPending, kustomReturnOutcome, KUSTOM_RETURN_QUERY_KEYS, ADYEN_RETURN_METHOD, adyenReturnParams, ADYEN_RETURN_QUERY_KEYS, adyenReturnOutcome, gatewayHasBuyerRef, AdyenOriginError, normalizeSlotId, autoSlotDisplayName, autoSlotId, normalizeScope, campaignCandidates } from './chunk-NXIYIY2D.js';
 import { LitElement, css, html } from 'lit';
 import { property, state, query } from 'lit/decorators.js';
 
@@ -226,7 +226,7 @@ var SlotRegistration = class {
     this.unregister();
     if (!next) return;
     try {
-      this.release = typeof Vio.registerSlot !== "function" ? null : next.campaignId !== void 0 ? Vio.registerSlot(next.id, next.displayName, next.campaignId) : Vio.registerSlot(next.id, next.displayName);
+      this.release = typeof Vio.registerSlot !== "function" ? null : next.campaignId !== void 0 ? Vio.registerSlot(next.id, next.displayName, next.campaignId, { kind: this.kind }) : Vio.registerSlot(next.id, next.displayName, { kind: this.kind });
       this.identity = next;
     } catch {
       this.release = null;
@@ -339,6 +339,7 @@ var VioProduct = class extends LitElement {
     this.vioCampaign = "";
     this.vioContentId = "";
     this.vioContentTitle = "";
+    this.componentTemplateId = "";
     this.slotRegistration = new SlotRegistration(this, "card");
     this.hasVariants = false;
     this.variants = void 0;
@@ -383,6 +384,7 @@ var VioProduct = class extends LitElement {
     }) : { slot: this.effectiveSlot || void 0 };
     return {
       ...base,
+      componentTemplateId: this.componentTemplateId || "product-card",
       ...this.vioContentId ? { contentId: this.vioContentId } : {},
       ...this.vioContentTitle ? { contentTitle: this.vioContentTitle } : {}
     };
@@ -581,11 +583,15 @@ var VioProduct = class extends LitElement {
           // The host's sponsor-id wins; without one, the slot's campaign sponsor.
           sponsorId: this.sponsorId || this.sponsorFromAttribution(),
           // The host adds to the cart: pass this through as `origin` so the
-          // purchase is attributed to this place and campaign.
+          // purchase is attributed to this place, campaign, kind of element
+          // and page — the cart keeps it and Commerce receives it (ADR-0035).
           origin: {
             campaignId: attribution.campaignId,
             slot: attribution.slot,
-            contentId: attribution.contentId
+            contentId: attribution.contentId,
+            componentKind: attribution.componentTemplateId,
+            contentUrl: attribution.contentUrl,
+            contentTitle: attribution.contentTitle
           }
         }
       })
@@ -675,6 +681,9 @@ __decorateClass([
 __decorateClass([
   property({ type: String, attribute: "vio-content-title" })
 ], VioProduct.prototype, "vioContentTitle", 2);
+__decorateClass([
+  property({ type: String, attribute: "component-template-id" })
+], VioProduct.prototype, "componentTemplateId", 2);
 __decorateClass([
   property({ type: Boolean, attribute: "has-variants" })
 ], VioProduct.prototype, "hasVariants", 2);
@@ -753,6 +762,7 @@ var VioProductCarousel = class extends LitElement {
     }) : { slot: this.effectiveSlot || void 0 };
     return {
       ...base,
+      componentTemplateId: "product-carousel",
       ...this.vioContentId ? { contentId: this.vioContentId } : {},
       ...this.vioContentTitle ? { contentTitle: this.vioContentTitle } : {}
     };
@@ -994,7 +1004,6 @@ var VioProductCarousel = class extends LitElement {
         this,
         {
           sponsorId: this.sponsorId > 0 ? this.sponsorId : void 0,
-          componentTemplateId: "product-carousel",
           // The slot is the real location id; the label only stands in for it.
           locationId: this.effectiveSlot || this.label || void 0,
           ...this.attribution()
@@ -1022,7 +1031,6 @@ var VioProductCarousel = class extends LitElement {
       Vio.analytics.track("view_item_list", {
         context: {
           sponsorId: sponsorId > 0 ? sponsorId : void 0,
-          componentTemplateId: "product-carousel",
           locationId: this.effectiveSlot || this.label || void 0,
           ...this.attribution()
         },
@@ -1081,6 +1089,7 @@ var VioProductCarousel = class extends LitElement {
             image-url=${img}
             ?has-variants=${(p.variants?.length ?? 0) > 1}
             .vioSlot=${this.effectiveSlot}
+            .componentTemplateId=${"product-carousel"}
             .vioCampaign=${this.effectiveCampaignId !== void 0 ? String(this.effectiveCampaignId) : ""}
             .vioContentId=${this.vioContentId}
             .vioContentTitle=${this.vioContentTitle}
@@ -1519,6 +1528,7 @@ var VioProductDetail = class extends LitElement {
     const contentTitle = this.fromCard && this.eventContentTitle || this.vioContentTitle;
     return {
       ...base,
+      componentTemplateId: "product-detail",
       ...contentId ? { contentId } : {},
       ...contentTitle ? { contentTitle } : {}
     };
@@ -2055,7 +2065,6 @@ var VioProductDetail = class extends LitElement {
         Vio.analytics.track("view_item", {
           context: {
             sponsorId: this.sponsorId > 0 ? Number(this.sponsorId) : void 0,
-            componentTemplateId: "product-detail",
             ...this.attribution()
           },
           commerce: {
@@ -2378,14 +2387,14 @@ var VioProductDetail = class extends LitElement {
     const sponsor = Vio.bootstrapCache?.primarySponsor;
     const secondaries = Vio.bootstrapCache?.secondarySponsors ?? [];
     const sponsorName = sponsor?.id === this.sponsorId ? sponsor.name : secondaries.find((s) => s.id === this.sponsorId)?.name;
-    const { campaignId, slot, contentId } = this.attribution();
+    const { campaignId, slot, contentId, componentTemplateId, contentUrl, contentTitle } = this.attribution();
     Vio.cart.addProduct({
       product: this.product,
       sponsorId: this.sponsorId,
       sponsorName,
       quantity: this.quantity,
       variantId: variant?.id,
-      origin: { campaignId, slot, contentId }
+      origin: { campaignId, slot, contentId, componentKind: componentTemplateId, contentUrl, contentTitle }
     });
     return variant?.id;
   }
@@ -3353,11 +3362,12 @@ var VioCart = class extends LitElement {
       for (const sponsorId of [...this.carts.keys()]) {
         Vio.cart.clearSponsorCart(sponsorId);
       }
+      const buyerRef = buyerRefOf({ result });
       this.dispatchEvent(
         new CustomEvent("vio:payment-success", {
           bubbles: true,
           composed: true,
-          detail: { method: "apple-pay", result }
+          detail: { method: "apple-pay", result, ...buyerRef ? { buyerRef } : {} }
         })
       );
     });
@@ -3927,6 +3937,8 @@ var _VioCheckout = class _VioCheckout extends LitElement {
       this.paymentError = detail.method === "klarna" ? `Klarna-betalingen kunne ikke fullf\xF8res: ${detail.error}` : friendlyPaymentError(detail.error, detail.method);
       this.open = true;
     };
+    /** Payment events still waiting for their buyer reference: settled early (without it) when the page hides or the element leaves. */
+    this.pendingSuccessEmits = /* @__PURE__ */ new Set();
   }
   /** A payment is being started or confirmed right now: the overlay must not close under it. */
   get paymentInFlight() {
@@ -4617,13 +4629,7 @@ var _VioCheckout = class _VioCheckout extends LitElement {
       this.orderConfirmed = true;
       this.open = true;
       void this.fillOrderNumber(checkoutId, sponsorId);
-      this.dispatchEvent(
-        new CustomEvent("vio:payment-success", {
-          bubbles: true,
-          composed: true,
-          detail: { method: vioMethod, sponsorId, orderId: checkoutId }
-        })
-      );
+      void this.emitPaymentSuccess({ method: vioMethod, sponsorId, orderId: checkoutId }, checkoutId, sponsorId);
     } else if (outcome === "duplicate") {
       this.paymentError = CART_PAID_MESSAGE;
       this.open = true;
@@ -4965,6 +4971,7 @@ var _VioCheckout = class _VioCheckout extends LitElement {
     this.unmountKlarna();
     this.unmountNexi();
     this.unmountAdyen();
+    for (const settle of [...this.pendingSuccessEmits]) settle();
     super.disconnectedCallback();
   }
   updated(changed) {
@@ -5476,18 +5483,122 @@ var _VioCheckout = class _VioCheckout extends LitElement {
     this.confirmedMethod = method;
     this.orderConfirmed = true;
     this.open = true;
-    this.dispatchEvent(
-      new CustomEvent("vio:payment-success", {
+    void this.fillOrderNumber(checkoutId, sponsorId);
+    void this.emitPaymentSuccess(
+      { method, sponsorId, result, checkoutId },
+      checkoutId,
+      sponsorId,
+      () => Vio.cart.clearSponsorCart(sponsorId)
+    );
+  }
+  static {
+    /** Longest `vio:payment-success` waits for the checkout's buyer reference, and when it asks a second time. */
+    this.BUYER_REF_WAIT_MS = 2500;
+  }
+  static {
+    this.BUYER_REF_RETRY_AT_MS = 1200;
+  }
+  /**
+   * `vio:payment-success` for the host and analytics — with the buyer
+   * reference (`buyerRef`: shopcart's keyed hash of the email → analytics
+   * `buyer_id`) when the checkout can say it. An emitter whose own answer
+   * carried it (Apple Pay, Klarna native) sends at once; the others (a
+   * redirect return, Stripe / Adyen / Nexi in the drawer, a provider's
+   * receipt) ask the checkout — at once and, while it has neither order nor
+   * reference, again at 1.2 s, since a webhook may write the checkout a
+   * moment after the redirect — within 2.5 s, and
+   * send without it when the answer is late or empty. Nothing is asked when
+   * it cannot help (the gateway has no `buyer_ref` yet; a confirmation that
+   * already answered). Only the event waits — the screen is already the
+   * confirmation — and not past the page: when the page hides (`pagehide`,
+   * `visibilitychange`) or the element leaves, the event goes out at once
+   * without the reference. Exactly one event per call. `afterwards` runs
+   * right after the event, so a path keeps the order it always had (the cart
+   * is cleared after the event).
+   */
+  async emitPaymentSuccess(detail, checkoutId, sponsorId, afterwards) {
+    let done = false;
+    const finish = (buyerRef) => {
+      if (done) return;
+      done = true;
+      const event = new CustomEvent("vio:payment-success", {
         bubbles: true,
         composed: true,
-        // `checkoutId` is Vio's own reference for the purchase — what the
-        // redirect path already sends as `orderId`; analytics falls back to it
-        // when the provider's result carries no order id.
-        detail: { method, sponsorId, result, checkoutId }
-      })
-    );
-    Vio.cart.clearSponsorCart(sponsorId);
-    void this.fillOrderNumber(checkoutId, sponsorId);
+        detail: buyerRef ? { ...detail, buyerRef } : detail
+      });
+      this.dispatchEvent(event);
+      if (!this.isConnected && typeof window !== "undefined") {
+        window.dispatchEvent(new CustomEvent("vio:payment-success", { detail: event.detail }));
+      }
+      try {
+        afterwards?.();
+      } catch {
+      }
+    };
+    const known = buyerRefOf(detail);
+    if (known || !checkoutId || !this.shouldAskBuyerRef(detail)) {
+      finish(known);
+      return;
+    }
+    const settleEarly = () => finish();
+    const onVisibility = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") settleEarly();
+    };
+    this.pendingSuccessEmits.add(settleEarly);
+    window.addEventListener("pagehide", settleEarly);
+    document.addEventListener("visibilitychange", onVisibility);
+    try {
+      finish(await this.askBuyerRef(checkoutId, sponsorId, () => done));
+    } catch {
+      finish();
+    } finally {
+      this.pendingSuccessEmits.delete(settleEarly);
+      window.removeEventListener("pagehide", settleEarly);
+      document.removeEventListener("visibilitychange", onVisibility);
+    }
+  }
+  /** Whether asking the checkout for the buyer reference can still help. */
+  shouldAskBuyerRef(detail) {
+    if (typeof Vio.checkout.getOrderReference !== "function") return false;
+    if (!gatewayHasBuyerRef()) return false;
+    if ((detail.method === "apple-pay" || detail.method === "klarna") && detail.result) return false;
+    return true;
+  }
+  /**
+   * The buyer reference of a checkout: asked at once and, when that answer
+   * failed or has neither the reference nor an order yet (the webhook has not
+   * written the checkout), again at 1.2 s — all within 2.5 s. An order
+   * without a reference is a settled answer: the backend has none, asking
+   * again cannot help. `undefined` when the time is up, when the answer
+   * stopped mattering (`stopped()`) or on failure.
+   */
+  async askBuyerRef(checkoutId, sponsorId, stopped) {
+    const started = Date.now();
+    const remaining = () => _VioCheckout.BUYER_REF_WAIT_MS - (Date.now() - started);
+    let deadline;
+    const timeUp = new Promise((resolve) => {
+      deadline = setTimeout(() => resolve(null), _VioCheckout.BUYER_REF_WAIT_MS);
+    });
+    try {
+      for (const at of [0, _VioCheckout.BUYER_REF_RETRY_AT_MS]) {
+        const wait = Math.min(at - (Date.now() - started), remaining());
+        if (wait > 0) await Promise.race([new Promise((resolve) => setTimeout(resolve, wait)), timeUp]);
+        if (stopped() || remaining() <= 0) return void 0;
+        try {
+          const reference = await Promise.race([
+            Vio.checkout.getOrderReference(checkoutId, sponsorId || void 0),
+            timeUp
+          ]);
+          if (reference === null) return void 0;
+          if (reference.buyerRef) return reference.buyerRef;
+          if (reference.orderNumber !== null) return void 0;
+        } catch {
+        }
+      }
+      return void 0;
+    } finally {
+      clearTimeout(deadline);
+    }
   }
   static {
     /** Waits between asks for the Vio order number: the order is often born a
@@ -5638,19 +5749,14 @@ var _VioCheckout = class _VioCheckout extends LitElement {
     this.confirmedMethod = method;
     this.open = true;
     const checkoutId = returnCheckoutId || this.checkoutState?.checkoutId;
-    this.dispatchEvent(
-      new CustomEvent("vio:payment-success", {
-        bubbles: true,
-        composed: true,
-        detail: { method, sponsorId, result, checkoutId }
-      })
-    );
-    if (sponsorId) {
-      try {
-        Vio.cart.clearSponsorCart(sponsorId);
-      } catch {
+    void this.emitPaymentSuccess(
+      { method, sponsorId, result, checkoutId },
+      checkoutId,
+      sponsorId,
+      () => {
+        if (sponsorId) Vio.cart.clearSponsorCart(sponsorId);
       }
-    }
+    );
   }
   /** Back from the payment page, asking whether it was paid — and nothing
    * else on screen while we do. */
@@ -7105,5 +7211,5 @@ function registerVioElements() {
 }
 
 export { VioCart, VioCheckout, VioProduct, VioProductCarousel, VioProductDetail, VioTokens, applyVioTheme, registerVioElements };
-//# sourceMappingURL=chunk-N6U65DWG.js.map
-//# sourceMappingURL=chunk-N6U65DWG.js.map
+//# sourceMappingURL=chunk-6Q2M3MIK.js.map
+//# sourceMappingURL=chunk-6Q2M3MIK.js.map