@openpartner/sdk 0.2.0 → 0.3.0

package/dist/browser.d.cts

@@ -4,9 +4,9 @@ export { O as OpenPartnerError } from './shared-dh1vlldf.cjs';
 /**
  * Browser SDK — runs inside a merchant's web app. Captures the `cref`
  * attribution token from landing-page URLs and the first-party cookie
- * the click router sets, stashes it in localStorage so it survives
- * Safari / ITP cookie expiry and SPA navigations, and stitches to the
- * authenticated user on signup or login.
+ * the click router sets, stashes it in localStorage so it survives SPA
+ * navigations and later visits, and stitches to the authenticated user on
+ * signup or login.
  *
  * Typical integration:
  *
@@ -24,6 +24,25 @@ export { O as OpenPartnerError } from './shared-dh1vlldf.cjs';
  * to OpenPartner then needs no code for those checkouts. `stripe: false`
  * turns it off.
  *
+ * How long a referral lasts. Safari deletes storage that a page's own
+ * scripts wrote (localStorage, and cookies set through document.cookie)
+ * after 7 days without a visit, so a visitor who clicks, leaves for a
+ * fortnight and comes back to buy without signing up first arrives with
+ * nothing. A cookie the brand's own server sets on the landing response
+ * isn't capped that way: `referralCookieHeader` in `@openpartner/sdk/server`
+ * writes one, and this SDK reads it back (`op_ref`), on every subdomain it
+ * covers. Once identify() has run, the stitch lives server-side and no
+ * browser storage matters.
+ *
+ * Consent. `consent: 'pending'` holds the referral in memory until
+ * setConsent('granted'): nothing is read from or written to storage or
+ * cookies, no Stripe link is tagged and nothing is sent until then.
+ *
+ * Landing report. When a click first arrives from the URL the SDK tells
+ * OpenPartner (POST /attribution/landing), so Admin → Tracking health can
+ * count the clicks that never reached a page running it. `reportLanding:
+ * false` turns it off.
+ *
  * No bundler? The same SDK ships as a script tag that starts itself
  * (auto.ts), served at /op.js by an OpenPartner portal.
  */
@@ -33,6 +52,8 @@ interface StripeLinkingConfig {
      *  in Stripe (e.g. "pay.yourbrand.com"). buy.stripe.com is always on. */
     linkHosts?: string[];
 }
+/** Whether this visitor agreed to referral tracking. */
+type ConsentState = 'granted' | 'pending' | 'denied';
 interface OpenPartnerConfig {
     /** Base URL of your OpenPartner API, e.g. "https://openpartner.example.com". */
     apiUrl: string;
@@ -53,6 +74,11 @@ interface OpenPartnerConfig {
      * (`client_reference_id: req.cookies.op_ref`). Off by default; the
      * script-tag build turns it on. `domain` shares it across subdomains
      * (".yourbrand.com") when visitors land on one and check out on another.
+     *
+     * The SDK reads this cookie back whether or not it writes it (`op_ref`
+     * unless `name` says otherwise): that's how a page on another subdomain,
+     * or a visit after Safari cleared localStorage, finds the referral, and
+     * how one your server set (`referralCookieHeader`) reaches identify().
      */
     referralCookie?: false | {
         name?: string;
@@ -60,17 +86,46 @@ interface OpenPartnerConfig {
         days?: number;
     };
     /**
-     * Called when identify() fails. Default: log to console. Pass a noop
-     * to suppress entirely or hook into your observability stack.
+     * Whether the visitor has agreed to referral tracking. Default
+     * `'granted'`: the SDK stores the referral as soon as it loads. Behind a
+     * consent banner, start at `'pending'` and call `setConsent()` from its
+     * callback. Until then the referral from the URL is held in memory only,
+     * so a visitor who agrees on the landing page is still credited.
+     * `'denied'` uses nothing.
+     */
+    consent?: ConsentState;
+    /**
+     * Tell OpenPartner when a partner click arrives on your site, so Admin →
+     * Tracking health can show clicks lost between the partner link and your
+     * page. Sends the click id once per click, nothing about the visitor.
+     * Default on; `false` turns it off.
+     */
+    reportLanding?: boolean;
+    /**
+     * Called when a call to OpenPartner fails: identify(), or a landing
+     * report OpenPartner answered with `click_not_found` (which usually means
+     * `apiUrl` names another program; other landing failures are dropped).
+     * Default: log to console. Pass a noop to suppress entirely or
+     * hook into your observability stack.
      */
     onError?: (err: unknown) => void;
 }
 declare class OpenPartner {
     private config;
     private observer;
+    private consent;
+    /** The URL's referral while consent is pending, held in memory only. */
+    private held;
+    /** This page's referral, kept here too: where localStorage throws it is
+     *  the only copy until the cookie is written. */
+    private current;
+    /** The Stripe links and embeds this SDK tagged, and with what, so a
+     *  withdrawn consent can take the tags back off. */
+    private tagged;
     private constructor();
     static init(config: OpenPartnerConfig): OpenPartner;
-    /** 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(): string | null;
     /**
      * Captured referral token for this visitor. Pass to Stripe Checkout
@@ -82,11 +137,22 @@ declare 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(): string | null;
-    /** 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(): void;
+    /**
+     * 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.
+     */
+    setConsent(state: 'granted' | 'denied'): void;
     /**
      * Add the referral to every Stripe Payment Link and Pricing Table / Buy
      * Button embed under `root` that doesn't carry a reference already.
@@ -95,9 +161,15 @@ declare class OpenPartner {
      * many it changed.
      */
     linkStripe(root?: ParentNode): number;
+    private remember;
+    /** Take back the references this SDK added. One the brand set, or one
+     *  changed since, stays. */
+    private untagStripe;
     /** Stop watching the page for new Stripe links and embeds. */
     stopLinkingStripe(): void;
     private stripeLinkHosts;
+    /** Everything the SDK does once it may: store, mirror, link, report. */
+    private start;
     /**
      * 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
@@ -109,27 +181,41 @@ declare class OpenPartner {
      * element is parsed, before Stripe upgrades it.
      */
     private watchStripe;
+    /** The cref on the landing URL, if any. */
+    private queryCref;
     /**
-     * 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.
+     * 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.
      */
     private captureCref;
-    /** Mirror the referral into the brand's own first-party cookie (when
-     *  configured), refreshed on every page load that has one. */
+    private referralCookieName;
+    /**
+     * 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.
+     */
     private writeReferralCookie;
     private readCookie;
+    private storageGet;
+    private storageSet;
+    private storageRemove;
+    /** Tell OpenPartner the click arrived. Best-effort, once per click. */
+    private reportLanding;
     /**
      * 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.
      */
     identify(userId: string): Promise<IdentifyResponse | null>;
 }
 
 export { IdentifyResponse, OpenPartner };
-export type { OpenPartnerConfig, StripeLinkingConfig };
+export type { ConsentState, OpenPartnerConfig, StripeLinkingConfig };

package/dist/browser.d.ts

@@ -4,9 +4,9 @@ export { O as OpenPartnerError } from './shared-dh1vlldf.js';
 /**
  * Browser SDK — runs inside a merchant's web app. Captures the `cref`
  * attribution token from landing-page URLs and the first-party cookie
- * the click router sets, stashes it in localStorage so it survives
- * Safari / ITP cookie expiry and SPA navigations, and stitches to the
- * authenticated user on signup or login.
+ * the click router sets, stashes it in localStorage so it survives SPA
+ * navigations and later visits, and stitches to the authenticated user on
+ * signup or login.
  *
  * Typical integration:
  *
@@ -24,6 +24,25 @@ export { O as OpenPartnerError } from './shared-dh1vlldf.js';
  * to OpenPartner then needs no code for those checkouts. `stripe: false`
  * turns it off.
  *
+ * How long a referral lasts. Safari deletes storage that a page's own
+ * scripts wrote (localStorage, and cookies set through document.cookie)
+ * after 7 days without a visit, so a visitor who clicks, leaves for a
+ * fortnight and comes back to buy without signing up first arrives with
+ * nothing. A cookie the brand's own server sets on the landing response
+ * isn't capped that way: `referralCookieHeader` in `@openpartner/sdk/server`
+ * writes one, and this SDK reads it back (`op_ref`), on every subdomain it
+ * covers. Once identify() has run, the stitch lives server-side and no
+ * browser storage matters.
+ *
+ * Consent. `consent: 'pending'` holds the referral in memory until
+ * setConsent('granted'): nothing is read from or written to storage or
+ * cookies, no Stripe link is tagged and nothing is sent until then.
+ *
+ * Landing report. When a click first arrives from the URL the SDK tells
+ * OpenPartner (POST /attribution/landing), so Admin → Tracking health can
+ * count the clicks that never reached a page running it. `reportLanding:
+ * false` turns it off.
+ *
  * No bundler? The same SDK ships as a script tag that starts itself
  * (auto.ts), served at /op.js by an OpenPartner portal.
  */
@@ -33,6 +52,8 @@ interface StripeLinkingConfig {
      *  in Stripe (e.g. "pay.yourbrand.com"). buy.stripe.com is always on. */
     linkHosts?: string[];
 }
+/** Whether this visitor agreed to referral tracking. */
+type ConsentState = 'granted' | 'pending' | 'denied';
 interface OpenPartnerConfig {
     /** Base URL of your OpenPartner API, e.g. "https://openpartner.example.com". */
     apiUrl: string;
@@ -53,6 +74,11 @@ interface OpenPartnerConfig {
      * (`client_reference_id: req.cookies.op_ref`). Off by default; the
      * script-tag build turns it on. `domain` shares it across subdomains
      * (".yourbrand.com") when visitors land on one and check out on another.
+     *
+     * The SDK reads this cookie back whether or not it writes it (`op_ref`
+     * unless `name` says otherwise): that's how a page on another subdomain,
+     * or a visit after Safari cleared localStorage, finds the referral, and
+     * how one your server set (`referralCookieHeader`) reaches identify().
      */
     referralCookie?: false | {
         name?: string;
@@ -60,17 +86,46 @@ interface OpenPartnerConfig {
         days?: number;
     };
     /**
-     * Called when identify() fails. Default: log to console. Pass a noop
-     * to suppress entirely or hook into your observability stack.
+     * Whether the visitor has agreed to referral tracking. Default
+     * `'granted'`: the SDK stores the referral as soon as it loads. Behind a
+     * consent banner, start at `'pending'` and call `setConsent()` from its
+     * callback. Until then the referral from the URL is held in memory only,
+     * so a visitor who agrees on the landing page is still credited.
+     * `'denied'` uses nothing.
+     */
+    consent?: ConsentState;
+    /**
+     * Tell OpenPartner when a partner click arrives on your site, so Admin →
+     * Tracking health can show clicks lost between the partner link and your
+     * page. Sends the click id once per click, nothing about the visitor.
+     * Default on; `false` turns it off.
+     */
+    reportLanding?: boolean;
+    /**
+     * Called when a call to OpenPartner fails: identify(), or a landing
+     * report OpenPartner answered with `click_not_found` (which usually means
+     * `apiUrl` names another program; other landing failures are dropped).
+     * Default: log to console. Pass a noop to suppress entirely or
+     * hook into your observability stack.
      */
     onError?: (err: unknown) => void;
 }
 declare class OpenPartner {
     private config;
     private observer;
+    private consent;
+    /** The URL's referral while consent is pending, held in memory only. */
+    private held;
+    /** This page's referral, kept here too: where localStorage throws it is
+     *  the only copy until the cookie is written. */
+    private current;
+    /** The Stripe links and embeds this SDK tagged, and with what, so a
+     *  withdrawn consent can take the tags back off. */
+    private tagged;
     private constructor();
     static init(config: OpenPartnerConfig): OpenPartner;
-    /** 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(): string | null;
     /**
      * Captured referral token for this visitor. Pass to Stripe Checkout
@@ -82,11 +137,22 @@ declare 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(): string | null;
-    /** 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(): void;
+    /**
+     * 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.
+     */
+    setConsent(state: 'granted' | 'denied'): void;
     /**
      * Add the referral to every Stripe Payment Link and Pricing Table / Buy
      * Button embed under `root` that doesn't carry a reference already.
@@ -95,9 +161,15 @@ declare class OpenPartner {
      * many it changed.
      */
     linkStripe(root?: ParentNode): number;
+    private remember;
+    /** Take back the references this SDK added. One the brand set, or one
+     *  changed since, stays. */
+    private untagStripe;
     /** Stop watching the page for new Stripe links and embeds. */
     stopLinkingStripe(): void;
     private stripeLinkHosts;
+    /** Everything the SDK does once it may: store, mirror, link, report. */
+    private start;
     /**
      * 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
@@ -109,27 +181,41 @@ declare class OpenPartner {
      * element is parsed, before Stripe upgrades it.
      */
     private watchStripe;
+    /** The cref on the landing URL, if any. */
+    private queryCref;
     /**
-     * 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.
+     * 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.
      */
     private captureCref;
-    /** Mirror the referral into the brand's own first-party cookie (when
-     *  configured), refreshed on every page load that has one. */
+    private referralCookieName;
+    /**
+     * 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.
+     */
     private writeReferralCookie;
     private readCookie;
+    private storageGet;
+    private storageSet;
+    private storageRemove;
+    /** Tell OpenPartner the click arrived. Best-effort, once per click. */
+    private reportLanding;
     /**
      * 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.
      */
     identify(userId: string): Promise<IdentifyResponse | null>;
 }
 
 export { IdentifyResponse, OpenPartner };
-export type { OpenPartnerConfig, StripeLinkingConfig };
+export type { ConsentState, OpenPartnerConfig, StripeLinkingConfig };