@storewatch/browser 0.1.0 → 0.2.0

package/README.md

@@ -12,5 +12,20 @@ sw.track("product_viewed", { productId: "prod_123", price: money(1249, "SEK") })
 sw.setConsent("granted"); // "pending" (default, cookieless) | "granted" | "denied"
 ```
 
+**Payment redirects.** Before consent the session lives only in memory, so a
+shopper who leaves for Klarna, PayPal or 3-D Secure would come back as a new
+session. Pass the return URL through `linkUrl` and the session continues; the
+store page that receives it removes the parameter from the address bar:
+
+```ts
+stripe.confirmPayment({ elements, confirmParams: { return_url: sw.linkUrl(returnUrl) } });
+```
+
+If the return URL is a server route that redirects onwards, forward the `_sws`
+query parameter to the page it redirects to.
+
+A visible tab counts as online only while someone uses it: after 5 minutes
+without a click, scroll, tap or key press it stops (`presenceIdleMs`).
+
 Use your **public** key here. Secret keys belong on your server
 (`@storewatch/node`). On Next.js, use `@storewatch/nextjs`.

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { Storewatch, StorewatchOptions } from "./types.js";
+/** The session in a `linkUrl` link, if it's well-formed and recent enough to still be alive. */
+export declare function readSessionLink(value: string | null, now?: number): string | null;
 export declare function createStorewatch(options: StorewatchOptions): Storewatch;
 /**
  * Idempotent page-level singleton: calling `init` twice (React StrictMode,

package/dist/identity.d.ts

@@ -24,6 +24,12 @@ export declare function createIdentity(initial: Consent): {
      * session, or "online", alive forever.
      */
     touch(now?: number, activity?: boolean): Session | null;
+    /**
+     * Continue a session carried over a redirect (see `linkUrl`). It keeps
+     * the id but not the landing attribution: the payment page the shopper
+     * returns from is not where they came from.
+     */
+    adopt(id: string, now?: number): void;
     current: () => Session | null;
     visitorId: () => string | null;
 };

package/dist/index.js

@@ -1 +1 @@
-function b(t=Date.now()){let e=crypto.getRandomValues(new Uint8Array(16)),n=t;for(let o=5;o>=0;o--)e[o]=n&255,n=Math.floor(n/256);e[6]=e[6]&15|112,e[8]=e[8]&63|128;let r=Array.from(e,o=>o.toString(16).padStart(2,"0")).join("");return`${r.slice(0,8)}-${r.slice(8,12)}-${r.slice(12,16)}-${r.slice(16,20)}-${r.slice(20)}`}function _(){return b().replace(/-/g,"").slice(-20)}var w="sw_s",x="sw_v",N=30*6e4,R=t=>{try{return localStorage.getItem(t)}catch{return null}},g=(t,e)=>{try{e===null?localStorage.removeItem(t):localStorage.setItem(t,e)}catch{}};function F(){let t={};try{let e=new URLSearchParams(location.search),n={};for(let r of["source","medium","campaign","term","content"]){let o=e.get(`utm_${r}`);o&&(n[r]=o.slice(0,200))}Object.keys(n).length>0&&(t.utm=n),document.referrer&&(t.referrer=document.referrer)}catch{}return t}function L(t){let e=t,n=null,r=null;function o(){if(e==="granted"){try{let s=JSON.parse(R(w)??"null");s&&typeof s.id=="string"&&Date.now()-s.last<N&&(n??(n=s))}catch{}r=R(x),r||(r=_(),g(x,r))}}return o(),{consent:()=>e,setConsent(s){e=s,s==="denied"?(n=null,r=null,g(w,null),g(x,null)):s==="granted"&&(o(),n&&g(w,JSON.stringify(n)))},touch(s=Date.now(),h=!0){if(e==="denied")return null;let l=!n||s-n.last>=N;return h?(l&&(n={id:_(),last:s,...F()}),n?(n.last=s,e==="granted"&&g(w,JSON.stringify(n)),n):null):l?null:n},current:()=>n,visitorId:()=>e==="granted"?r:null}}var H=["page_viewed","product_viewed","collection_viewed","search_performed","add_to_cart","remove_from_cart","cart_updated","checkout_started","checkout_step_viewed","customer_information_entered","shipping_selected","payment_started","payment_failed","payment_authorized","order_completed","order_cancelled","refund_created","session_heartbeat"],ne=new Set(H);var I={batchMaxEvents:100,batchMaxBytes:256*1024,propertiesMaxBytes:4*1024,propertiesMaxDepth:4,stringMaxLength:1024,urlMaxLength:2048,idMaxLength:128,sessionIdMaxLength:64,eventNameMaxLength:64,searchQueryMaxLength:100,orderMaxItems:100};function P(t){return new Intl.NumberFormat("en",{style:"currency",currency:t}).resolvedOptions().maximumFractionDigits??2}function $(t,e){let n=e.toUpperCase(),r=10**P(n);return{amount:Math.round(t*r),currency:n}}function z(t){return t.amount/10**P(t.currency)}var B=5,Q=6e4,J=60*1024,K=(t,...e)=>{t&&console.warn("[storewatch]",...e)};function V(t){let e=[],n,r=!1,o=0,s=0,h=i=>JSON.stringify({key:t.publicKey,sentAt:new Date().toISOString(),batch:i});function l(i=t.flushIntervalMs){n===void 0&&(n=setTimeout(()=>(n=void 0,void m()),i))}async function m(){if(r||e.length===0)return;r=!0;let i=e.splice(0,I.batchMaxEvents),u=!1;try{let c=await fetch(t.endpoint,{method:"POST",body:h(i),headers:{"content-type":"text/plain;charset=UTF-8"},keepalive:!0,credentials:"omit"});u=c.status===429||c.status>=500,!u&&c.status>=400&&K(t.debug,`ingest rejected batch (${c.status})`)}catch(c){u=!0,K(t.debug,"ingest unreachable",c)}if(r=!1,u){s++,++o<B?e=i.concat(e).slice(-t.maxQueue):o=0,l(Math.min(Q,1e3*2**s));return}s=0,o=0,e.length>0&&l(e.length>=t.flushAt?0:t.flushIntervalMs)}return{enqueue(i){e.push(i),e.length>t.maxQueue&&e.shift(),e.length>=t.flushAt&&s===0?m():l()},flush:m,beacon(){for(n!==void 0&&clearTimeout(n),n=void 0;e.length>0;){let i=e.splice(0,I.batchMaxEvents);for(;i.length>1&&h(i).length>J;)e.unshift(...i.splice(Math.ceil(i.length/2)));let u=h(i),c=!1;try{c=navigator.sendBeacon(t.endpoint,new Blob([u],{type:"text/plain;charset=UTF-8"}))}catch{c=!1}c||fetch(t.endpoint,{method:"POST",body:u,keepalive:!0,credentials:"omit",headers:{"content-type":"text/plain;charset=UTF-8"}}).catch(()=>{})}},clear(){e=[],n!==void 0&&clearTimeout(n),n=void 0},size:()=>e.length}}var q="0.1.0",E={track(){},page(){},identify(){},setConsent(){},ids:()=>({sessionId:"",anonymousId:null}),flush(){},shutdown(){}};function d(t,e,n){return(...r)=>{try{return e(...r)}catch(o){return t&&console.warn("[storewatch]",o),n}}}function D(t){if(typeof window>"u"||typeof document>"u")return E;if(!/^sw_pk_/.test(t.publicKey))return console.error("[storewatch] publicKey must be a public key (sw_pk_\u2026). Secret keys must never reach the browser."),E;let e=t.debug??!1,n=L(t.consent??"pending"),r=V({endpoint:t.endpoint??"/_sw/v1/batch",publicKey:t.publicKey,flushAt:t.flushAt??20,flushIntervalMs:t.flushIntervalMs??2e3,maxQueue:500,debug:e}),o=null,s="";function h(a,y){let f=n.touch(Date.now(),a!=="session_heartbeat");if(!f)return null;let C=n.visitorId(),j=n.consent()==="granted";return{eventId:b(),name:a,timestamp:new Date().toISOString(),sessionId:f.id,...C?{anonymousId:C}:{},...j&&o?{customerId:o}:{},properties:y,context:{page:{url:location.href,path:location.pathname,title:document.title.slice(0,200),...f.referrer?{referrer:f.referrer}:{}},...f.utm?{utm:f.utm}:{},locale:navigator.language,timezone:Intl.DateTimeFormat().resolvedOptions().timeZone,screen:{width:innerWidth,height:innerHeight},...t.currency?{currency:t.currency}:{},library:{name:"@storewatch/browser",version:q},consent:n.consent()}}}let l=d(e,(a,y={})=>{let f=h(a,y);f&&r.enqueue(f)},void 0),m=d(e,(a={})=>{s=location.pathname;let y=t.pageType?.(location.pathname);l("page_viewed",{...y?{pageType:y}:{},...a})},void 0),i=!0,u=()=>{i&&location.pathname!==s&&m()},c=history.pushState,M=history.replaceState,T=function(...a){c.apply(this,a),u()},k=function(...a){M.apply(this,a),u()};(t.autoPageViews??!0)&&(history.pushState=T,history.replaceState=k,addEventListener("popstate",u));let U=setInterval(d(e,()=>{document.visibilityState==="visible"&&n.current()&&l("session_heartbeat")},void 0),t.heartbeatIntervalMs??2e4),O=d(e,()=>{document.visibilityState==="hidden"&&r.beacon()},void 0),A=d(e,()=>r.beacon(),void 0);return document.addEventListener("visibilitychange",O),addEventListener("pagehide",A),(t.autoPageViews??!0)&&m(),{track:l,page:m,identify:d(e,a=>{o=a},void 0),setConsent:d(e,a=>{n.setConsent(a),a==="denied"&&r.clear()},void 0),ids:d(e,()=>({sessionId:n.touch(Date.now(),!1)?.id??"",anonymousId:n.visitorId()}),{sessionId:"",anonymousId:null}),flush:d(e,()=>{r.flush()},void 0),shutdown:d(e,()=>{i=!1,clearInterval(U),r.beacon(),document.removeEventListener("visibilitychange",O),removeEventListener("pagehide",A),removeEventListener("popstate",u),history.pushState===T&&(history.pushState=c),history.replaceState===k&&(history.replaceState=M)},void 0)}}var p=null,W=100,v=[];function X(t){if(p?.key===t.publicKey)return p.client;p?.client.shutdown(),p={key:t.publicKey,client:D(t)};let e=v;v=[];for(let[n,r]of e)p.client[n](...r);return p.client}var S=t=>(...e)=>{if(p)return p.client[t](...e);v.length<W&&v.push([t,e])},Y={track:S("track"),page:S("page"),identify:S("identify"),setConsent:S("setConsent"),ids:()=>p?.client.ids()??E.ids(),flush:S("flush"),shutdown:()=>p?.client.shutdown()};function Z(){return Y}export{D as createStorewatch,Z as getStorewatch,X as init,$ as money,z as toMajor};
+function x(e=Date.now()){let t=crypto.getRandomValues(new Uint8Array(16)),n=e;for(let a=5;a>=0;a--)t[a]=n&255,n=Math.floor(n/256);t[6]=t[6]&15|112,t[8]=t[8]&63|128;let r=Array.from(t,a=>a.toString(16).padStart(2,"0")).join("");return`${r.slice(0,8)}-${r.slice(8,12)}-${r.slice(12,16)}-${r.slice(16,20)}-${r.slice(20)}`}function M(){return x().replace(/-/g,"").slice(-20)}var w="sw_s",k="sw_v",_=30*6e4,U=e=>{try{return localStorage.getItem(e)}catch{return null}},S=(e,t)=>{try{t===null?localStorage.removeItem(e):localStorage.setItem(e,t)}catch{}};function Q(){let e={};try{let t=new URLSearchParams(location.search),n={};for(let r of["source","medium","campaign","term","content"]){let a=t.get(`utm_${r}`);a&&(n[r]=a.slice(0,200))}Object.keys(n).length>0&&(e.utm=n),document.referrer&&(e.referrer=document.referrer)}catch{}return e}function V(e){let t=e,n=null,r=null;function a(){if(t==="granted"){try{let s=JSON.parse(U(w)??"null");s&&typeof s.id=="string"&&Date.now()-s.last<_&&(n??(n=s))}catch{}r=U(k),r||(r=M(),S(k,r))}}return a(),{consent:()=>t,setConsent(s){t=s,s==="denied"?(n=null,r=null,S(w,null),S(k,null)):s==="granted"&&(a(),n&&S(w,JSON.stringify(n)))},touch(s=Date.now(),u=!0){if(t==="denied")return null;let h=!n||s-n.last>=_;return u?(h&&(n={id:M(),last:s,...Q()}),n?(n.last=s,t==="granted"&&S(w,JSON.stringify(n)),n):null):h?null:n},adopt(s,u=Date.now()){t!=="denied"&&(n={id:s,last:u},t==="granted"&&S(w,JSON.stringify(n)))},current:()=>n,visitorId:()=>t==="granted"?r:null}}var q=["page_viewed","product_viewed","collection_viewed","search_performed","add_to_cart","remove_from_cart","cart_updated","checkout_started","checkout_step_viewed","customer_information_entered","shipping_selected","payment_started","payment_failed","payment_authorized","order_completed","order_cancelled","refund_created","session_heartbeat"],ue=new Set(q);var T={batchMaxEvents:100,batchMaxBytes:256*1024,propertiesMaxBytes:4*1024,propertiesMaxDepth:4,stringMaxLength:1024,urlMaxLength:2048,idMaxLength:128,sessionIdMaxLength:64,eventNameMaxLength:64,searchQueryMaxLength:100,orderMaxItems:100};function $(e){return new Intl.NumberFormat("en",{style:"currency",currency:e}).resolvedOptions().maximumFractionDigits??2}function W(e,t){let n=t.toUpperCase(),r=10**$(n);return{amount:Math.round(e*r),currency:n}}function X(e){return e.amount/10**$(e.currency)}var Y=5,Z=6e4,G=60*1024,j=(e,...t)=>{e&&console.warn("[storewatch]",...t)};function F(e){let t=[],n,r=!1,a=0,s=0,u=i=>JSON.stringify({key:e.publicKey,sentAt:new Date().toISOString(),batch:i});function h(i=e.flushIntervalMs){n===void 0&&(n=setTimeout(()=>(n=void 0,void g()),i))}async function g(){if(r||t.length===0)return;r=!0;let i=t.splice(0,T.batchMaxEvents),f=!1;try{let c=await fetch(e.endpoint,{method:"POST",body:u(i),headers:{"content-type":"text/plain;charset=UTF-8"},keepalive:!0,credentials:"omit"});f=c.status===429||c.status>=500,!f&&c.status>=400&&j(e.debug,`ingest rejected batch (${c.status})`)}catch(c){f=!0,j(e.debug,"ingest unreachable",c)}if(r=!1,f){s++,++a<Y?t=i.concat(t).slice(-e.maxQueue):a=0,h(Math.min(Z,1e3*2**s));return}s=0,a=0,t.length>0&&h(t.length>=e.flushAt?0:e.flushIntervalMs)}return{enqueue(i){t.push(i),t.length>e.maxQueue&&t.shift(),t.length>=e.flushAt&&s===0?g():h()},flush:g,beacon(){for(n!==void 0&&clearTimeout(n),n=void 0;t.length>0;){let i=t.splice(0,T.batchMaxEvents);for(;i.length>1&&u(i).length>G;)t.unshift(...i.splice(Math.ceil(i.length/2)));let f=u(i),c=!1;try{c=navigator.sendBeacon(e.endpoint,new Blob([f],{type:"text/plain;charset=UTF-8"}))}catch{c=!1}c||fetch(e.endpoint,{method:"POST",body:f,keepalive:!0,credentials:"omit",headers:{"content-type":"text/plain;charset=UTF-8"}}).catch(()=>{})}},clear(){t=[],n!==void 0&&clearTimeout(n),n=void 0},size:()=>t.length}}var ee="0.2.0",I="_sws",te=5*6e4;function ne(e,t=Date.now()){let n=e?.match(/^([0-9a-f]{20})\.([0-9a-z]{1,11})$/);if(!n)return null;let r=t-parseInt(n[2],36);return r>=-6e4&&r<_?n[1]:null}var O={track(){},page(){},identify(){},setConsent(){},ids:()=>({sessionId:"",anonymousId:null}),linkUrl:e=>e,flush(){},shutdown(){}};function d(e,t,n){return(...r)=>{try{return t(...r)}catch(a){return e&&console.warn("[storewatch]",a),n}}}function H(e){if(typeof window>"u"||typeof document>"u")return O;if(!/^sw_pk_/.test(e.publicKey))return console.error("[storewatch] publicKey must be a public key (sw_pk_\u2026). Secret keys must never reach the browser."),O;let t=e.debug??!1,n=V(e.consent??"pending"),r=F({endpoint:e.endpoint??"/_sw/v1/batch",publicKey:e.publicKey,flushAt:e.flushAt??20,flushIntervalMs:e.flushIntervalMs??2e3,maxQueue:500,debug:t}),a=null,s="",u=Date.now();d(t,()=>{let o=new URL(location.href);if(!o.searchParams.has(I))return;let l=ne(o.searchParams.get(I));l&&!n.touch(Date.now(),!1)&&n.adopt(l),o.searchParams.delete(I),history.replaceState(history.state,"",o.pathname+o.search+o.hash)},void 0)();function h(o,l){let m=o!=="session_heartbeat";m&&(u=Date.now());let y=n.touch(Date.now(),m);if(!y)return null;let K=n.visitorId(),J=n.consent()==="granted";return{eventId:x(),name:o,timestamp:new Date().toISOString(),sessionId:y.id,...K?{anonymousId:K}:{},...J&&a?{customerId:a}:{},properties:l,context:{page:{url:location.href,path:location.pathname,title:document.title.slice(0,200),...y.referrer?{referrer:y.referrer}:{}},...y.utm?{utm:y.utm}:{},locale:navigator.language,timezone:Intl.DateTimeFormat().resolvedOptions().timeZone,screen:{width:innerWidth,height:innerHeight},...e.currency?{currency:e.currency}:{},library:{name:"@storewatch/browser",version:ee},consent:n.consent()}}}let g=d(t,(o,l={})=>{let m=h(o,l);m&&r.enqueue(m)},void 0),i=d(t,(o={})=>{s=location.pathname;let l=e.pageType?.(location.pathname);g("page_viewed",{...l?{pageType:l}:{},...o})},void 0),f=!0,c=()=>{f&&location.pathname!==s&&i()},A=history.pushState,L=history.replaceState,N=function(...o){A.apply(this,o),c()},R=function(...o){L.apply(this,o),c()};(e.autoPageViews??!0)&&(history.pushState=N,history.replaceState=R,addEventListener("popstate",c));let z=e.presenceIdleMs??te,E=()=>{u=Date.now()},C=["pointerdown","pointermove","keydown","scroll","wheel","touchstart"];for(let o of C)addEventListener(o,E,{capture:!0,passive:!0});let B=setInterval(d(t,()=>{document.visibilityState==="visible"&&Date.now()-u<z&&n.current()&&g("session_heartbeat")},void 0),e.heartbeatIntervalMs??2e4),P=d(t,()=>{document.visibilityState==="hidden"?r.beacon():E()},void 0),D=d(t,()=>r.beacon(),void 0);return document.addEventListener("visibilitychange",P),addEventListener("pagehide",D),(e.autoPageViews??!0)&&i(),{track:g,page:i,identify:d(t,o=>{a=o},void 0),setConsent:d(t,o=>{n.setConsent(o),o==="denied"&&r.clear()},void 0),ids:d(t,()=>({sessionId:n.touch(Date.now(),!1)?.id??"",anonymousId:n.visitorId()}),{sessionId:"",anonymousId:null}),linkUrl:o=>{try{let l=n.touch(Date.now(),!1);if(!l)return o;let m=new URL(o,location.href);return m.searchParams.set(I,`${l.id}.${Date.now().toString(36)}`),m.toString()}catch(l){return t&&console.warn("[storewatch]",l),o}},flush:d(t,()=>{r.flush()},void 0),shutdown:d(t,()=>{f=!1,clearInterval(B);for(let o of C)removeEventListener(o,E,{capture:!0});r.beacon(),document.removeEventListener("visibilitychange",P),removeEventListener("pagehide",D),removeEventListener("popstate",c),history.pushState===N&&(history.pushState=A),history.replaceState===R&&(history.replaceState=L)},void 0)}}var p=null,re=100,b=[];function oe(e){if(p?.key===e.publicKey)return p.client;p?.client.shutdown(),p={key:e.publicKey,client:H(e)};let t=b;b=[];for(let[n,r]of t)p.client[n](...r);return p.client}var v=e=>(...t)=>{if(p)return p.client[e](...t);b.length<re&&b.push([e,t])},se={track:v("track"),page:v("page"),identify:v("identify"),setConsent:v("setConsent"),ids:()=>p?.client.ids()??O.ids(),linkUrl:e=>p?.client.linkUrl(e)??e,flush:v("flush"),shutdown:()=>p?.client.shutdown()};function ae(){return se}export{H as createStorewatch,ae as getStorewatch,oe as init,W as money,X as toMajor};

package/dist/types.d.ts

@@ -30,6 +30,11 @@ export type StorewatchOptions = {
     /** Default ISO-4217 currency added to event context. */
     currency?: string;
     heartbeatIntervalMs?: number;
+    /**
+     * A visible tab only counts as "online" if the shopper moved, scrolled,
+     * tapped or typed within this long. Default 5 minutes.
+     */
+    presenceIdleMs?: number;
     flushAt?: number;
     flushIntervalMs?: number;
     /** Log delivery problems to the console. Default false. */
@@ -46,6 +51,14 @@ export type Storewatch = {
         sessionId: string;
         anonymousId: string | null;
     };
+    /**
+     * `url` with the current session attached, for a page that leaves the
+     * store and comes back (a payment provider's return URL). Without stored
+     * consent the session lives only in memory, so the full page load on
+     * return would otherwise start a new one. The receiving page picks the
+     * parameter up and removes it from the address bar.
+     */
+    linkUrl(url: string): string;
     flush(): void;
     shutdown(): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storewatch/browser",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Storewatch browser SDK: lightweight, consent-aware commerce tracking.",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
     "dist"
   ],
   "dependencies": {
-    "@storewatch/schema": "0.1.0"
+    "@storewatch/schema": "0.2.0"
   },
   "devDependencies": {
     "happy-dom": "^21.0.1",