@storewatch/browser 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edin Skeja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @storewatch/browser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Storewatch browser SDK: live, consent-aware commerce tracking in about 3 KB
+(gzipped). Tracking never blocks or breaks your store: events are queued and
+sent in the background, with bounded retries.
+
+```ts
+import { init, money } from "@storewatch/browser";
+
+const sw = init({ publicKey: "sw_pk_…", endpoint: "https://ingest.example.com/v1/batch" });
+sw.track("product_viewed", { productId: "prod_123", price: money(1249, "SEK") });
+sw.setConsent("granted"); // "pending" (default, cookieless) | "granted" | "denied"
+```
+
+Use your **public** key here. Secret keys belong on your server
+(`@storewatch/node`). On Next.js, use `@storewatch/nextjs`.

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+import type { Storewatch, StorewatchOptions } from "./types.js";
+export declare function createStorewatch(options: StorewatchOptions): Storewatch;
+/**
+ * Idempotent page-level singleton: calling `init` twice (React StrictMode,
+ * remounts, HMR) returns the same client instead of double-tracking.
+ */
+export declare function init(options: StorewatchOptions): Storewatch;
+export declare function getStorewatch(): Storewatch;
+/** Test hook: forget the singleton and any queued calls. */
+export declare function resetForTests(): void;

package/dist/identity.d.ts

@@ -0,0 +1,31 @@
+import type { Consent } from "./types.js";
+/** A session ends after this much inactivity. */
+export declare const SESSION_IDLE_MS: number;
+type Utm = Partial<Record<"source" | "medium" | "campaign" | "term" | "content", string>>;
+export type Session = {
+    id: string;
+    last: number;
+    utm?: Utm;
+    referrer?: string;
+};
+/**
+ * Session and visitor identity under three consent states:
+ *  - pending: in memory only; nothing touches device storage
+ *  - granted: session and visitor IDs persisted in localStorage
+ *  - denied:  no IDs, storage cleared
+ */
+export declare function createIdentity(initial: Consent): {
+    consent: () => Consent;
+    setConsent(next: Consent): void;
+    /**
+     * The active session, rolled over after inactivity. Null when denied.
+     * `activity: false` (heartbeats) reads the session without extending it
+     * and never starts a new one: an open but untouched tab must not keep a
+     * session, or "online", alive forever.
+     */
+    touch(now?: number, activity?: boolean): Session | null;
+    current: () => Session | null;
+    visitorId: () => string | null;
+};
+export type Identity = ReturnType<typeof createIdentity>;
+export {};

package/dist/ids.d.ts

@@ -0,0 +1,7 @@
+/**
+ * UUIDv7: time-ordered, so events sort naturally and ClickHouse stores them
+ * compactly. Uses crypto.getRandomValues, which (unlike randomUUID) also
+ * works on plain-http staging sites.
+ */
+export declare function uuidv7(now?: number): string;
+export declare function shortId(): string;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createStorewatch, getStorewatch, init } from "./client.js";
+export { money, toMajor, type Money } from "@storewatch/schema/constants";
+export type { Consent, EventProperties, Storewatch, StorewatchOptions } from "./types.js";

package/dist/index.js

@@ -0,0 +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};

package/dist/transport.d.ts

@@ -0,0 +1,24 @@
+import type { OutgoingEvent } from "./types.js";
+export type TransportOptions = {
+    endpoint: string;
+    publicKey: string;
+    flushAt: number;
+    flushIntervalMs: number;
+    maxQueue: number;
+    debug: boolean;
+};
+/**
+ * Batches events and delivers them without ever affecting the page: no
+ * exceptions, no unhandled rejections, bounded memory, bounded retries.
+ * Bodies are JSON sent as text/plain (a CORS "simple request", no preflight)
+ * with the public key in the body, which also makes sendBeacon possible.
+ */
+export declare function createTransport(o: TransportOptions): {
+    enqueue(event: OutgoingEvent): void;
+    flush: () => Promise<void>;
+    /** Last-chance delivery when the page is hidden or unloading. */
+    beacon(): void;
+    clear(): void;
+    size: () => number;
+};
+export type Transport = ReturnType<typeof createTransport>;

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+import type { CanonicalEventName, CanonicalProperties } from "@storewatch/schema";
+export type Consent = "pending" | "granted" | "denied";
+export type OutgoingEvent = {
+    eventId: string;
+    name: string;
+    timestamp: string;
+    sessionId: string;
+    anonymousId?: string;
+    customerId?: string;
+    properties: Record<string, unknown>;
+    context: Record<string, unknown>;
+};
+/** Canonical events get their typed properties; anything else is a custom event. */
+export type EventProperties<N extends string> = N extends CanonicalEventName ? CanonicalProperties[N] : Record<string, unknown>;
+export type StorewatchOptions = {
+    /** Public key (sw_pk_…). Never put a secret key in the browser. */
+    publicKey: string;
+    /** Ingest endpoint. Default: same-origin proxy `/_sw/v1/batch` (see @storewatch/nextjs). */
+    endpoint?: string;
+    /**
+     * Initial consent. "pending" (default) tracks without storing anything on
+     * the device (cookieless); "granted" persists visitor and session IDs;
+     * "denied" sends nothing.
+     */
+    consent?: Consent;
+    /** Track a page view on load and on every client-side navigation. Default true. */
+    autoPageViews?: boolean;
+    /** Classify a path for `pageType` (e.g. "/products/x" → "product"). */
+    pageType?: (path: string) => string | undefined;
+    /** Default ISO-4217 currency added to event context. */
+    currency?: string;
+    heartbeatIntervalMs?: number;
+    flushAt?: number;
+    flushIntervalMs?: number;
+    /** Log delivery problems to the console. Default false. */
+    debug?: boolean;
+};
+export type Storewatch = {
+    track<N extends string>(name: N, properties?: EventProperties<N>): void;
+    page(properties?: EventProperties<"page_viewed">): void;
+    /** Attach the merchant's own customer ID. Only sent once consent is granted. */
+    identify(customerId: string | null): void;
+    setConsent(consent: Consent): void;
+    /** IDs for server-side correlation, e.g. stored in cart metadata by an adapter. */
+    ids(): {
+        sessionId: string;
+        anonymousId: string | null;
+    };
+    flush(): void;
+    shutdown(): void;
+};

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@storewatch/browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Storewatch browser SDK: lightweight, consent-aware commerce tracking.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@storewatch/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "happy-dom": "^21.0.1",
+    "tsup": "^9.0.0",
+    "@storewatch/config": "0.0.0"
+  },
+  "keywords": [
+    "storewatch",
+    "analytics",
+    "ecommerce"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsup && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p .",
+    "test": "vitest run",
+    "size": "node scripts/size.mjs"
+  }
 }