@openpartner/sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## 0.3.0
+
+Closes the places where a partner click could go missing in the browser, and
+reports clicks that arrive so Admin → Tracking health can show the ones that
+don't. No breaking API changes; the one new default behaviour is the landing
+report (see Compatibility).
+
+### Added
+
+- **Consent mode.** `consent: 'granted' | 'pending' | 'denied'` in
+  `OpenPartner.init()` (script tag: `data-consent="pending"`) and
+  `setConsent('granted' | 'denied')`.
+  - `'pending'` holds the click from the URL in memory only. Nothing is read
+    from or written to storage or cookies, no Stripe link is tagged and no
+    request is sent until `setConsent('granted')`, which then works even
+    after a single-page app has moved off the landing URL.
+  - `'denied'`, at load or later, deletes what an earlier visit stored and
+    takes the `client_reference_id` the SDK added back off Stripe Payment
+    Links and embeds. A reference you set yourself stays. Safe to call more
+    than once.
+  - The default is `'granted'`: integrations that don't set it behave as
+    before.
+- **Landing report.** When a click first arrives from the URL, the SDK posts
+  its id once to `POST /attribution/landing` (the page's hostname comes from
+  the browser's `Origin` header; nothing else about the visitor is sent).
+  Admin → Tracking health compares landings with clicks to show the clicks
+  lost between the partner link and your page. Turn it off with
+  `reportLanding: false` (script tag: `data-landing="off"`).
+- **Server-side referral cookie** in `@openpartner/sdk/server`, for Safari,
+  which deletes storage a page's scripts wrote after 7 days without a visit.
+  A cookie your own server sets on the landing response isn't capped that way,
+  and the browser SDK reads it back.
+  - `referralCookieHeader(url, options?)`: the `Set-Cookie` value for a
+    request whose URL carries `?cref=`, or `null`.
+  - `referralCookieMiddleware(options?)`: Express / Connect middleware that
+    sets it, adding to any `Set-Cookie` already queued.
+  - `readReferralCookie(cookieHeader, name?)`: the referral off a `Cookie`
+    header, for `identify()` from your backend or `client_reference_id` on a
+    Checkout Session.
+
+### Changed
+
+- **The referral is read back from the `op_ref` cookie** (or
+  `referralCookie.name`) when localStorage is empty: on a second subdomain
+  (land on `www.`, sign up on `app.` with `referralCookie.domain` /
+  `data-cookie-domain` set), after Safari clears localStorage, or where
+  localStorage is blocked. Previously only localStorage and the router's
+  `_cref` cookie were read.
+- **An `op_ref` cookie that already holds the referral isn't rewritten** from
+  script, so one your server set keeps its lifetime in Safari. A new click
+  still replaces it.
+- **A click from the URL is kept in memory as well,** so the referral cookie,
+  Stripe tagging and `identify()` still get it where localStorage throws.
+- **`clear()` also expires the referral cookie** and removes the Stripe
+  references the SDK added.
+- **`onError`'s default log line** is now `[openpartner] request failed` (was
+  `identify failed`): it also covers the landing report.
+
+### Compatibility
+
+- The landing report is on by default and needs an OpenPartner API that has
+  `POST /attribution/landing` (OpenPartner Cloud, or a self-hosted instance
+  from October 24 2026 on). An older API answers 404, and the SDK ignores it:
+  only a `click_not_found` from a current API reaches `onError`, because that
+  usually means `apiUrl` names another program.
+- The script tag an OpenPartner portal serves at `/op.js` is built from this
+  source and already behaves this way.
+
+## 0.2.0
+
+Published to npm on October 20 2026: Stripe Payment Link and Pricing Table /
+Buy Button linking, the script-tag build, the `op_ref` referral cookie, and the
+server SDK (`trackEvent`, `trackConversion`, `identify`).
+
+## 0.1.0
+
+The first published version.

package/README.md

@@ -2,7 +2,7 @@
 
 Client + server SDK for [OpenPartner](https://github.com/getcoherence/openpartner).
 
-- **Browser** — captures the `cref` attribution token from landing URLs and the first-party cookie, survives Safari / ITP cookie expiry via localStorage, and stitches to a logged-in user on auth.
+- **Browser** — captures the `cref` attribution token from landing URLs and first-party cookies, keeps it across pages and subdomains, waits for consent when you ask it to, and stitches to a logged-in user on auth.
 - **Server** — posts conversion events, stitches server-side where needed, with typed errors.
 
 Zero runtime dependencies. ~4 KB gzipped browser bundle.
@@ -13,7 +13,7 @@ npm install @openpartner/sdk
 
 ## Browser
 
-Embed once on every page of your marketing site and product. The SDK runs on init, pulling the cref out of `?cref=…` (first visit from a partner link) or the `_cref` cookie (subsequent pages) and stashing it in localStorage.
+Embed once on every page of your marketing site and product. The SDK runs on init, pulling the cref out of `?cref=…` (first visit from a partner link), or on later pages out of localStorage or a first-party cookie (`_cref` from the click router, `op_ref` from a sibling subdomain or your server), and stashing it in localStorage.
 
 ```ts
 import { OpenPartner } from '@openpartner/sdk';
@@ -38,9 +38,84 @@ OpenPartner.init({
   queryParam: 'cref',           // query param on landing URLs
   storageKey: 'openpartner:cref', // localStorage key
   onError: (err) => Sentry.captureException(err),
+  stripe: { linkHosts: ['pay.yourbrand.com'] }, // or false — see below
+  referralCookie: { name: 'op_ref', domain: '.yourbrand.com' }, // off by default
+  consent: 'pending',           // default 'granted' — see Consent below
+  reportLanding: true,          // default on — see Landing report below
 });
 ```
 
+### Subdomains
+
+A visitor who lands on `www.yourbrand.com` and signs up on `app.yourbrand.com` has two localStorages, one per subdomain. Share the referral through a cookie on the parent domain: `referralCookie: { domain: '.yourbrand.com' }` (script tag: `data-cookie-domain=".yourbrand.com"`) on every subdomain. The SDK on `app.` reads `op_ref` back when its own storage is empty, so `identify()` and Stripe links work there too. A journey across two different domains (`yourbrand.com` → `yourbrand-shop.com`) has no shared cookie: carry `?cref=` on the link between them.
+
+### Safari and long gaps
+
+Safari deletes storage a page's scripts wrote (localStorage, and cookies set through `document.cookie`) after 7 days without a visit. A visitor who clicks, comes back after a fortnight and buys without signing up first would arrive with nothing. Two things close that gap:
+
+- **Call `identify()` as early as you can.** Once a click is stitched to a user, the link lives on OpenPartner's side and no browser storage matters. An email capture or account creation before checkout is enough.
+- **Set the referral cookie from your own server**, on the landing page's response. A cookie your server sets keeps its full lifetime in Safari, and the browser SDK reads it back:
+
+  ```ts
+  import { referralCookieHeader, referralCookieMiddleware } from '@openpartner/sdk/server';
+
+  // Express / Connect:
+  app.use(referralCookieMiddleware({ domain: '.yourbrand.com' }));
+
+  // Anything else (Next.js middleware, a Worker): set the header yourself.
+  const header = referralCookieHeader(request.url, { domain: '.yourbrand.com' });
+  if (header) response.headers.append('Set-Cookie', header);
+  ```
+
+  Set it from the server that serves the page. Safari caps a cookie at 7 days when it comes from a server on a different IP address than the site, such as an API hosted on another provider. The SDK never rewrites an `op_ref` cookie that already holds the referral, because rewriting it from script would bring the 7-day cap back.
+
+### Consent
+
+Behind a consent banner, start the SDK with `consent: 'pending'` and tell it the answer:
+
+```ts
+const op = OpenPartner.init({ apiUrl, consent: 'pending' });
+
+yourConsentBanner.onChange((choices) => {
+  op.setConsent(choices.marketing ? 'granted' : 'denied');
+});
+```
+
+While consent is pending, the SDK keeps the click from the URL in memory and does nothing else: it doesn't read or write storage or cookies, tag Stripe links, or call OpenPartner. `setConsent('granted')` then works as if the page had just loaded, even after the visitor has navigated within a single-page app. `setConsent('denied')` stops everything, takes the references the SDK added back off Stripe links and embeds (one you set yourself stays), and deletes what was stored. Starting with `consent: 'denied'` deletes what an earlier visit stored. `getReferral()` and `identify()` return `null` until consent is granted. Script tag: `data-consent="pending"`, then `openpartner.setConsent('granted')`.
+
+Clicks from visitors who never consent can't be credited, and Admin → Tracking health counts them among the clicks that never landed.
+
+### Landing report
+
+When a partner click first arrives from the URL, the SDK tells OpenPartner (`POST /attribution/landing`, the click id and nothing else; the page's hostname comes from the browser's `Origin` header). **Admin → Tracking health** compares landings with clicks to show the ones lost between the partner link and your page: a redirect that dropped `?cref=`, a page without the script, a consent banner. A `click_not_found` from it reaches `onError` and usually means `apiUrl` names another program; any other failure is dropped, because the report is a diagnostic and never part of attribution. Turn it off with `reportLanding: false` (script tag: `data-landing="off"`).
+
+### Stripe links and embeds
+
+When the visitor came from a partner link, the SDK hands that click to Stripe for you:
+
+- Every Payment Link on the page (`buy.stripe.com`, plus any `linkHosts` you list for a custom Payment Link domain) gets `client_reference_id`.
+- Every `<stripe-pricing-table>` and `<stripe-buy-button>` embed gets `client-reference-id`.
+
+That includes elements added after the page loads. A link or embed that already carries a reference keeps it. With your Stripe account connected to OpenPartner (or your self-host's webhook pointed at it), those checkouts then credit the partner with no code at all. `stripe: false` turns it off. For an app-created Checkout Session, pass `op.getReferral()`, or the `op_ref` cookie with `referralCookie` set, as `client_reference_id`.
+
+Pricing Table and Buy Button embeds read `client-reference-id` when Stripe renders them, so load the SDK before Stripe's embed script.
+
+### Script tag (no bundler)
+
+An OpenPartner portal serves a self-starting build of this SDK at `/op.js`. Paste it into your site's `<head>`:
+
+```html
+<script src="https://app.openpartner.dev/op.js" data-api-url="https://app.openpartner.dev/api/t/your-slug"></script>
+```
+
+**Admin → Integrations** shows the exact tag for your program. It does everything above, keeps the referral in an `op_ref` cookie on your domain, and exposes `window.openpartner` (`openpartner.identify(userId)`, `openpartner.getReferral()`, `openpartner.setConsent('granted')`). Optional attributes:
+- `data-stripe-hosts="pay.yourbrand.com"`: a custom Payment Link domain.
+- `data-cookie-domain=".yourbrand.com"`: share `op_ref` across subdomains.
+- `data-consent="pending"`: wait for `openpartner.setConsent()` (see [Consent](#consent)).
+- `data-stripe="off"`, `data-cookie="off"`, `data-landing="off"`: turn any of them off.
+
+The npm package carries the same file at `dist-global/openpartner.js`.
+
 ### Framework notes
 
 - **React / Vue / SolidJS**: call `OpenPartner.init()` once at the top of your app. Call `op.identify()` from your auth callback.
@@ -68,10 +143,13 @@ await op.trackEvent({
   type: 'invoice_paid',
   value: 249,
   currency: 'USD',
+  externalEventId: invoice.id, // makes retries safe; see below
   metadata: { stripeInvoiceId: invoice.id },
 });
 ```
 
+Pass `externalEventId` on every call. Use your system's stable id for that one event, such as the invoice id or order id. Your job queue or HTTP client will retry when a request times out. Without a key, each retry records a second event and pays a second commission. With a key, a retry resolves with the original `eventId` and attribution plus `replayed: true`, and nothing new is written. That includes duplicates sent at the same moment. Use one key per event, not per order: an order's `subscription_created` and its `invoice_paid` need different keys. Reusing a key for a different `userId`, `type`, `value` or `currency` throws an `OpenPartnerError` with code `external_event_id_conflict` (409).
+
 The response includes the attribution result:
 
 ```ts
@@ -88,15 +166,71 @@ The response includes the attribution result:
 }
 ```
 
+A replay adds `replayed: true`. Its `attribution` is rebuilt from the rows the first call wrote. If that call didn't attribute, the status is `'not_attributed'`, because the specific reason isn't stored.
+
 For multi-touch campaigns (`linear`, `position`, etc.) `touches` will contain one entry per attributed click with a fractional `weight`.
 
-### Stripe webhooks
+### Conversions by click id
+
+Sometimes the system that learns about the conversion only has the click id, not a user you `identify()`'d. A lender funds a loan, or a CRM closes a deal from a lead form that captured the click id. The click id reaches it from the partner link: as `?cref=…` on the destination URL, or in any parameter you choose, by putting `{click_id}` in the program's destination URL (`https://apply.example.com/?ref={click_id}`). Report the conversion in one call:
+
+```ts
+await op.trackConversion({
+  clickId,                          // from ?cref= or your {click_id} parameter
+  type: 'loan_funded',
+  value: 5000,
+  currency: 'USD',
+  externalEventId: `${loan.id}:funded`, // required
+});
+```
+
+OpenPartner stitches the click and records the event together. Without a `userId` the conversion goes to the click's own user (`click:<clickId>`), so every conversion you report for that click is credited to it, and a "first" commission rule fires once. Pass `userId` when you also identify that user elsewhere. Attribution then follows the program's model across all of that user's clicks. `externalEventId` is required and behaves as on `trackEvent`. An unknown click throws `click_not_found` (404). A click flagged as fraud throws `click_flagged` (422). The response adds `userId` to `trackEvent`'s shape.
+
+Senders that can only fire a URL (affiliate networks, many lenders) use the postback URL from the admin Integrations page instead: `GET /postback?click_id=…&type=…&amount=…&currency=…&txn_id=…&token=…`. Its token records conversions and nothing else.
+
+### Stripe
+
+How Stripe revenue reaches OpenPartner depends on where OpenPartner runs.
+
+**Hosted OpenPartner.** Connect your Stripe account under **Admin → Integrations → Connect Stripe**. That installs the OpenPartner Stripe App on it (beta; read-only except coupons and promotion codes), and your Checkout and Payment Link purchases, invoices, renewals, refunds and disputes are then recorded from Stripe, with no `trackEvent` for them. Customers are linked to the partner click the same way as on self-host, below: the [script tag](#script-tag-no-bundler) does it for Payment Links and embeds on your site, and a Checkout Session your backend creates passes `client_reference_id`. With Stripe connected, a `trackEvent` keyed on a Stripe invoice or Checkout Session id (`in_…`, `cs_…`) throws `recorded_from_stripe` (409): Stripe's record of the payment wins. See [openpartner.dev/docs/stripe-app](https://openpartner.dev/docs/stripe-app). Don't point a webhook from your Stripe account at OpenPartner's `/webhooks/stripe`: on hosted it accepts only events signed with OpenPartner's own Stripe signing secrets.
+
+**Self-hosted, single tenant.** If the instance's `STRIPE_SECRET_KEY` and webhook signing secret (`STRIPE_WEBHOOK_SECRET_PLATFORM`, or the legacy `STRIPE_WEBHOOK_SECRET`) belong to *your* Stripe account, you can skip `trackEvent` for Stripe revenue. OpenPartner takes revenue from `invoice.paid` (subscriptions and other invoices) and from paid one-time Checkout Sessions (`mode: 'payment'`, including Payment Links). Point a webhook in your Stripe account at `https://<your-openpartner-api>/webhooks/stripe`. Subscribe it to `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `customer.created`, `customer.subscription.created`, `invoice.paid`, `charge.refunded` and `charge.dispute.created`.
+
+The endpoint can use any Stripe API version, including the one Stripe preselects when you create it. Version `2025-03-31.basil` removed the invoice ↔ payment pointers from webhook payloads (`Invoice.charge`, `Invoice.payment_intent`, `Charge.invoice`). On basil and later, OpenPartner reads a refunded charge's invoice back from Stripe's InvoicePayments: one Stripe API call per refund of an invoice's charge.
+
+OpenPartner has to know which Stripe customer is which referred user. Link them in one of two ways:
+
+- **Checkout `client_reference_id`.** Pass the captured referral through when you create the Checkout Session:
+
+  ```ts
+  // Browser: the captured referral, or null if the visitor didn't come from a partner link.
+  const ref = op.getReferral();
+
+  // Your backend, with `ref` sent up from the browser:
+  const session = await stripe.checkout.sessions.create({
+    client_reference_id: ref ?? undefined,
+    // ...line_items, mode, success_url, etc.
+  });
+  ```
+
+  With the [script tag](#script-tag-no-bundler) (or `referralCookie` set), your backend can read the referral straight off the request instead: `client_reference_id: req.cookies.op_ref`, or `readReferralCookie(req.headers.cookie)` from `@openpartner/sdk/server` without a cookie parser. The same call lets your backend stitch at signup, which works even where browser scripts are blocked: `await op.identify({ cref, userId: user.id })`.
+
+  A Stripe Payment Link can't run your code, so let the partner link fill it in: set the program's destination URL to the Payment Link with `?client_reference_id={click_id}`, and the click router puts the click id there.
+
+  On `checkout.session.completed`, OpenPartner stitches the session's customer to that click and records a `signup` event. A paid one-time session also records its `amount_total` as an `invoice_paid` event, keyed on the session id. A guest checkout with no Stripe Customer, the Payment Link default, is keyed to the click's own user (`click:<clickId>`). A delayed payment method (SEPA, ACH, Bacs) records the revenue at `checkout.session.async_payment_succeeded`, when the money actually clears. Subscription sessions record no revenue at checkout, because their `invoice.paid` carries it. Neither does a session with `invoice_creation` enabled, for the same reason. The customer's events are keyed to the Stripe customer id (`cus_…`). Stripe doesn't deliver events in order. If the first `invoice.paid` or `customer.subscription.created` arrives before `checkout.session.completed`, OpenPartner looks up the customer's completed Checkout Sessions in Stripe and stitches then.
+- **Customer metadata `openpartner_user_id`.** Set it on the Stripe Customer to the user id you pass to `identify()`. Set it before the customer pays, for example by creating the Customer with the metadata and passing `customer` when you create the Checkout Session. An invoice that arrives before the metadata is set is skipped, and Stripe won't redeliver it.
+
+You can use both. If the Customer already carries your `openpartner_user_id` when the checkout completes, OpenPartner stitches the click to that id instead of the `cus_…` id and leaves your metadata as you set it. The user gets one signup, although `customer.created` and `checkout.session.completed` both report it.
+
+Once a customer is linked, OpenPartner ingests and attributes their `customer.subscription.created` and `invoice.paid` automatically, and their later one-time Checkout purchases even without a `client_reference_id`. A refund of an invoice's or one-time purchase's charge (`charge.refunded`) leaves each of that payment's commissions worth its original amount times the share of the collected amount the customer kept, so a full refund keeps nothing. Partial refunds add up. Accrued and approved commissions are reversed, and on a partial refund a replacement for the kept share is accrued with the same status and accrual date. Paid commissions stay paid: a `refund_clawback` adjustment records what the partner holds, and OpenPartner takes it off that partner's next manual or self-hosted Stripe Connect payout. Stripe Connect payouts on hosted OpenPartner don't deduct it, so recover those by hand. A commission in a payout that's in progress is held until the next refund of that charge. Since `2025-03-31.basil`, an invoice can be paid in several payments, and one payment can pay several invoices. A refund of such a payment is recorded but reverses nothing, because the charge doesn't say how much of which invoice it gave back. Report it with `POST /attribution/refunds` and the amount. A dispute is recorded and reverses nothing. If you lose it, report the chargeback with `POST /attribution/refunds` (`"kind": "chargeback"`). Don't also `trackEvent` the same invoices from your backend, or the revenue is counted twice.
 
-OpenPartner's API has a built-in `/webhooks/stripe` handler that ingests `customer.created`, `customer.subscription.created`, and `invoice.paid` automatically. If you're already using Stripe with OpenPartner, point your Stripe webhook at OpenPartner's API directly — you don't need to call `trackEvent` from your own code.
+If `STRIPE_SECRET_KEY` is a restricted key, give it read access to Customers, Checkout Sessions and Invoices. Invoices covers a promo code applied to an invoice, and on API versions from `2025-03-31.basil` the InvoicePayment that names a refunded charge's invoice. When the key isn't allowed to read one of them, OpenPartner skips that lookup instead of failing the webhook, and the event can go unattributed.
 
 Call `trackEvent` from your backend when:
 
-- You don't use Stripe (or Stripe isn't the source of the conversion).
+- You're on hosted OpenPartner and haven't connected Stripe.
+- You don't use Stripe, or the customer is linked neither by a Checkout `client_reference_id` nor by `openpartner_user_id` metadata.
+- The revenue doesn't come through Stripe Checkout or an invoice, such as a PaymentIntent your backend charges directly. `payment_intent.*` and `charge.succeeded` aren't ingested as revenue.
 - You want to track custom event types (`trial_started`, `feature_activated`, etc.).
 - You want to override the event timestamp (`ts: '2026-04-20T12:00:00Z'`).
 
@@ -144,7 +278,7 @@ attribution engine             ← Applies campaign model, emits Attribution + C
 
 - **click** — visitor lands on `https://vendor.example.com/r/<slug>`. The OpenPartner router sets `_cref` cookie and writes a `Click` row.
 - **identify** — once the visitor authenticates on the vendor's site, the browser SDK (or server SDK) calls `/attribution/identify` which writes an `Identity` row stitching `cref → userId`.
-- **trackEvent** — any subsequent conversion event is written as an `Event` row. The attribution engine walks `Event.userId → Identity → Click → Campaign`, checks the attribution window, applies the configured model (`last_click` / `first_click` / `linear` / `position`), and writes `Attribution` + `Commission` rows.
+- **trackEvent** — any subsequent conversion event is written as an `Event` row. The attribution engine walks `Event.userId → Identity → Click → Campaign`, checks the attribution window (a repeat of a conversion the user already made, such as a renewal, keeps that conversion's partner past it), applies the configured model (`last_click` / `first_click` / `linear` / `position`), and writes `Attribution` + `Commission` rows.
 
 ## License
 

package/dist/browser.cjs

@@ -73,23 +73,44 @@ var DEFAULTS = {
   cookieName: "_cref",
   queryParam: "cref",
   storageKey: "openpartner:cref",
+  stripe: true,
+  referralCookie: false,
+  consent: "granted",
+  reportLanding: true,
   onError: (err) => {
-    console.warn("[openpartner] identify failed", err);
+    console.warn("[openpartner] request failed", err);
   }
 };
+var STRIPE_REFERENCE_RE = /^[A-Za-z0-9_-]{1,200}$/;
+var STRIPE_EMBED_SELECTOR = "stripe-pricing-table, stripe-buy-button";
+var REFERRAL_COOKIE_DEFAULT = "op_ref";
 var OpenPartner = class _OpenPartner {
   constructor(config) {
     __publicField(this, "config");
+    __publicField(this, "observer", null);
+    __publicField(this, "consent");
+    /** The URL's referral while consent is pending, held in memory only. */
+    __publicField(this, "held", null);
+    /** This page's referral, kept here too: where localStorage throws it is
+     *  the only copy until the cookie is written. */
+    __publicField(this, "current", null);
+    /** The Stripe links and embeds this SDK tagged, and with what, so a
+     *  withdrawn consent can take the tags back off. */
+    __publicField(this, "tagged", []);
     this.config = { ...DEFAULTS, ...config };
-    this.captureCref();
+    this.consent = this.config.consent;
+    if (this.consent === "granted") this.start();
+    else if (this.consent === "pending") this.held = this.queryCref();
+    else this.clear();
   }
   static init(config) {
     return new _OpenPartner(config);
   }
-  /** The cref we're holding onto, if any. Useful for debugging. */
+  /** The cref we're holding onto, if any. Useful for debugging. Null until
+   *  consent is granted. */
   getCref() {
-    if (typeof localStorage === "undefined") return null;
-    return localStorage.getItem(this.config.storageKey);
+    if (this.consent !== "granted") return null;
+    return this.storageGet() ?? this.current ?? this.readCookie(this.referralCookieName());
   }
   /**
    * Captured referral token for this visitor. Pass to Stripe Checkout
@@ -101,47 +122,260 @@ var OpenPartner = class _OpenPartner {
    *     // ...
    *   });
    *
-   * Returns null if the visitor didn't arrive via a partner link.
+   * Returns null if the visitor didn't arrive via a partner link, or
+   * hasn't agreed to tracking yet.
    */
   getReferral() {
     return this.getCref();
   }
-  /** Explicitly discard the captured cref. */
+  /** Explicitly discard the captured cref, the referral cookie, and the
+   *  references this SDK added to Stripe links and embeds. */
   clear() {
-    if (typeof localStorage === "undefined") return;
-    localStorage.removeItem(this.config.storageKey);
+    this.held = null;
+    this.current = null;
+    this.untagStripe();
+    this.storageRemove();
+    if (typeof document === "undefined") return;
+    const name = this.referralCookieName();
+    if (!this.readCookie(name)) return;
+    const cfg = this.config.referralCookie;
+    document.cookie = `${name}=; Max-Age=0; Path=/`;
+    if (cfg && cfg.domain) document.cookie = `${name}=; Max-Age=0; Path=/; Domain=${cfg.domain}`;
   }
   /**
-   * Capture the cref from query string or cookie and stash in
-   * localStorage. Runs on init so the value survives SPA navigations,
-   * ITP cookie expiry, and subsequent page loads.
+   * Record the visitor's answer to your consent banner. `'granted'` stores
+   * the referral (the one held since the page loaded, or one already
+   * stored), starts tagging Stripe links and sends the landing report.
+   * `'denied'` stops all of it, takes the references it added off Stripe
+   * links and embeds, and deletes what was stored. Calling it again is
+   * safe.
    */
-  captureCref() {
-    if (typeof window === "undefined" || typeof localStorage === "undefined") return;
-    const url = new URL(window.location.href);
-    const queryCref = url.searchParams.get(this.config.queryParam);
-    if (queryCref) {
-      localStorage.setItem(this.config.storageKey, queryCref);
+  setConsent(state) {
+    if (state === "granted") {
+      if (this.consent === "granted") return;
+      this.consent = state;
+      this.start();
       return;
     }
-    const cookieCref = this.readCookie(this.config.cookieName);
-    if (cookieCref && !localStorage.getItem(this.config.storageKey)) {
-      localStorage.setItem(this.config.storageKey, cookieCref);
+    this.consent = state;
+    this.stopLinkingStripe();
+    this.clear();
+  }
+  /**
+   * Add the referral to every Stripe Payment Link and Pricing Table / Buy
+   * Button embed under `root` that doesn't carry a reference already.
+   * Runs on its own at init and for anything added later; call it yourself
+   * only if you build Stripe elements inside a shadow root. Returns how
+   * many it changed.
+   */
+  linkStripe(root = document) {
+    const referral = this.getReferral();
+    if (!referral || !STRIPE_REFERENCE_RE.test(referral) || typeof document === "undefined") return 0;
+    const hosts = /* @__PURE__ */ new Set(["buy.stripe.com", ...this.stripeLinkHosts()]);
+    let changed = 0;
+    const anchors = [];
+    if (root instanceof HTMLAnchorElement) anchors.push(root);
+    anchors.push(...Array.from(root.querySelectorAll("a[href]")));
+    for (const a of anchors) {
+      let url;
+      try {
+        url = new URL(a.href);
+      } catch {
+        continue;
+      }
+      if (!hosts.has(url.hostname.toLowerCase()) || url.searchParams.has("client_reference_id")) continue;
+      url.searchParams.set("client_reference_id", referral);
+      a.href = url.toString();
+      this.remember(a, referral);
+      changed += 1;
+    }
+    const embeds = [];
+    if (root instanceof Element && root.matches(STRIPE_EMBED_SELECTOR)) embeds.push(root);
+    embeds.push(...Array.from(root.querySelectorAll(STRIPE_EMBED_SELECTOR)));
+    for (const el of embeds) {
+      if (el.hasAttribute("client-reference-id")) continue;
+      el.setAttribute("client-reference-id", referral);
+      this.remember(el, referral);
+      changed += 1;
+    }
+    return changed;
+  }
+  remember(el, value) {
+    this.tagged = this.tagged.filter((t) => t.el.isConnected);
+    this.tagged.push({ el, value });
+  }
+  /** Take back the references this SDK added. One the brand set, or one
+   *  changed since, stays. */
+  untagStripe() {
+    for (const { el, value } of this.tagged) {
+      if (el instanceof HTMLAnchorElement) {
+        let url;
+        try {
+          url = new URL(el.href);
+        } catch {
+          continue;
+        }
+        if (url.searchParams.get("client_reference_id") !== value) continue;
+        url.searchParams.delete("client_reference_id");
+        el.href = url.toString();
+      } else if (el.getAttribute("client-reference-id") === value) {
+        el.removeAttribute("client-reference-id");
+      }
+    }
+    this.tagged = [];
+  }
+  /** Stop watching the page for new Stripe links and embeds. */
+  stopLinkingStripe() {
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+  stripeLinkHosts() {
+    const cfg = this.config.stripe;
+    return typeof cfg === "object" && cfg.linkHosts ? cfg.linkHosts.map((h) => h.trim().toLowerCase()).filter(Boolean) : [];
+  }
+  /** Everything the SDK does once it may: store, mirror, link, report. */
+  start() {
+    const landed = this.captureCref(this.held);
+    this.held = null;
+    this.writeReferralCookie();
+    if (this.config.stripe !== false) this.watchStripe();
+    if (landed && this.config.reportLanding !== false) void this.reportLanding(landed);
+  }
+  /**
+   * Link what's on the page now, then anything added or re-pointed later
+   * (SPAs, Stripe embeds mounted on demand). Only with a referral: a visitor
+   * who didn't come from a partner link costs nothing.
+   *
+   * Pricing Table and Buy Button embeds read client-reference-id when
+   * Stripe's script renders them, so the script tag belongs in <head>,
+   * ahead of the embed: the observer then sets the attribute as the
+   * element is parsed, before Stripe upgrades it.
+   */
+  watchStripe() {
+    if (typeof document === "undefined" || this.observer || !this.getReferral()) return;
+    this.linkStripe(document);
+    if (typeof MutationObserver === "undefined") return;
+    this.observer = new MutationObserver((records) => {
+      for (const record of records) {
+        if (record.type === "attributes") {
+          if (record.target instanceof HTMLAnchorElement) this.linkStripe(record.target);
+          continue;
+        }
+        for (const node of Array.from(record.addedNodes)) {
+          if (node instanceof Element) this.linkStripe(node);
+        }
+      }
+    });
+    this.observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["href"]
+    });
+  }
+  /** The cref on the landing URL, if any. */
+  queryCref() {
+    if (typeof window === "undefined") return null;
+    return new URL(window.location.href).searchParams.get(this.config.queryParam);
+  }
+  /**
+   * Capture the cref from the URL (or the one held while consent was
+   * pending), else the router's cookie, else the referral cookie, and
+   * stash it in localStorage so it survives SPA navigations and later
+   * page loads. Returns the cref when it's a click arriving now, one this
+   * browser didn't have yet, for the landing report.
+   */
+  captureCref(held) {
+    if (typeof window === "undefined") return null;
+    const incoming = held ?? this.queryCref();
+    if (incoming) {
+      const isNew = this.storageGet() !== incoming;
+      this.current = incoming;
+      this.storageSet(incoming);
+      return isNew ? incoming : null;
+    }
+    if (this.storageGet()) return null;
+    const restored = this.readCookie(this.config.cookieName) ?? this.readCookie(this.referralCookieName());
+    if (restored) {
+      this.current = restored;
+      this.storageSet(restored);
     }
+    return null;
+  }
+  referralCookieName() {
+    const cfg = this.config.referralCookie;
+    return cfg && cfg.name || REFERRAL_COOKIE_DEFAULT;
+  }
+  /**
+   * Mirror the referral into the brand's own first-party cookie (when
+   * configured). Left alone when it already holds this referral: in Safari
+   * rewriting it from script would trade a server-set cookie's full
+   * lifetime for the 7-day cap. A new click overwrites it.
+   */
+  writeReferralCookie() {
+    const cfg = this.config.referralCookie;
+    if (!cfg || typeof document === "undefined") return;
+    const referral = this.getReferral();
+    if (!referral || !STRIPE_REFERENCE_RE.test(referral)) return;
+    const name = this.referralCookieName();
+    if (this.readCookie(name) === referral) return;
+    const maxAge = Math.round((cfg.days ?? 90) * 86400);
+    const secure = typeof location !== "undefined" && location.protocol === "https:" ? "; Secure" : "";
+    const domain = cfg.domain ? `; Domain=${cfg.domain}` : "";
+    document.cookie = `${name}=${encodeURIComponent(referral)}; Max-Age=${maxAge}; Path=/; SameSite=Lax${domain}${secure}`;
   }
   readCookie(name) {
     if (typeof document === "undefined") return null;
     const match = document.cookie.match(new RegExp(`(^|; )${name}=([^;]+)`));
-    return match ? decodeURIComponent(match[2]) : null;
+    if (!match) return null;
+    try {
+      return decodeURIComponent(match[2]);
+    } catch {
+      return null;
+    }
+  }
+  // localStorage throws in some sandboxed iframes and with site data
+  // blocked; the referral then lives in the cookie alone.
+  storageGet() {
+    try {
+      return typeof localStorage === "undefined" ? null : localStorage.getItem(this.config.storageKey);
+    } catch {
+      return null;
+    }
+  }
+  storageSet(value) {
+    try {
+      if (typeof localStorage !== "undefined") localStorage.setItem(this.config.storageKey, value);
+    } catch {
+    }
+  }
+  storageRemove() {
+    try {
+      if (typeof localStorage !== "undefined") localStorage.removeItem(this.config.storageKey);
+    } catch {
+    }
+  }
+  /** Tell OpenPartner the click arrived. Best-effort, once per click. */
+  async reportLanding(cref) {
+    if (!STRIPE_REFERENCE_RE.test(cref) || typeof fetch === "undefined") return;
+    try {
+      await requestJson(`${this.config.apiUrl}/attribution/landing`, {
+        method: "POST",
+        body: { cref },
+        keepalive: true
+      });
+    } catch (err) {
+      if (err instanceof OpenPartnerError && err.code === "click_not_found") this.config.onError(err);
+    }
   }
   /**
    * Stitch the current captured click to an authenticated user. Call
    * this on login, signup, or anywhere the user becomes known.
    *
-   * No-op if no cref was captured. Errors are reported through
-   * `config.onError` by default — attribution is best-effort from the
-   * browser — but you can await this and try/catch if you want to
-   * surface failures explicitly.
+   * No-op if no cref was captured, or consent isn't granted. Errors are
+   * reported through `config.onError` by default — attribution is
+   * best-effort from the browser — but you can await this and try/catch
+   * if you want to surface failures explicitly.
    */
   async identify(userId) {
     const cref = this.getCref();