@grainql/analytics-web 2.2.0 → 2.2.1

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v2.2.0 | MIT License | Development Build */
+/* Grain Analytics Web SDK v2.2.1 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;

package/dist/index.global.js

@@ -1,3 +1,3 @@
-/* Grain Analytics Web SDK v2.2.0 | MIT License */
+/* Grain Analytics Web SDK v2.2.1 | MIT License */
 "use strict";var Grain=(()=>{var C=Object.defineProperty;var R=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var x=(c,e)=>{for(var t in e)C(c,t,{get:e[t],enumerable:!0})},U=(c,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of A(e))!T.call(c,n)&&n!==t&&C(c,n,{get:()=>e[n],enumerable:!(r=R(e,n))||r.enumerable});return c};var D=c=>U(C({},"__esModule",{value:!0}),c);var $={};x($,{GrainAnalytics:()=>u,createGrainAnalytics:()=>P,default:()=>O});var I=["necessary","analytics","functional"],f="1.0.0",p=class{constructor(e,t="opt-out"){this.consentState=null;this.listeners=[];this.consentMode=t,this.storageKey=`grain_consent_${e}`,this.loadConsentState()}loadConsentState(){if(!(typeof window>"u"))try{let e=localStorage.getItem(this.storageKey);if(e){let t=JSON.parse(e);this.consentState={...t,timestamp:new Date(t.timestamp)}}else(this.consentMode==="opt-out"||this.consentMode==="disabled")&&(this.consentState={granted:!0,categories:I,timestamp:new Date,version:f},this.saveConsentState())}catch(e){console.error("[Grain Consent] Failed to load consent state:",e)}}saveConsentState(){if(!(typeof window>"u"||!this.consentState))try{localStorage.setItem(this.storageKey,JSON.stringify(this.consentState))}catch(e){console.error("[Grain Consent] Failed to save consent state:",e)}}grantConsent(e){let t=e||I;this.consentState={granted:!0,categories:t,timestamp:new Date,version:f},this.saveConsentState(),this.notifyListeners()}revokeConsent(e){this.consentState?e?this.consentState={...this.consentState,categories:this.consentState.categories.filter(t=>!e.includes(t)),granted:this.consentState.categories.length>0,timestamp:new Date}:this.consentState={granted:!1,categories:[],timestamp:new Date,version:f}:this.consentState={granted:!1,categories:[],timestamp:new Date,version:f},this.saveConsentState(),this.notifyListeners()}getConsentState(){return this.consentState?{...this.consentState}:null}hasConsent(e){return this.consentMode==="disabled"?!0:this.consentMode==="opt-in"&&!this.consentState||!this.consentState?.granted?!1:e?this.consentState.categories.includes(e):!0}shouldWaitForConsent(){return this.consentMode==="opt-in"&&!this.consentState?.granted}addListener(e){this.listeners.push(e)}removeListener(e){let t=this.listeners.indexOf(e);t>-1&&this.listeners.splice(t,1)}notifyListeners(){this.consentState&&this.listeners.forEach(e=>{try{e(this.consentState)}catch(t){console.error("[Grain Consent] Listener error:",t)}})}clearConsent(){if(!(typeof window>"u"))try{localStorage.removeItem(this.storageKey),this.consentState=null}catch(e){console.error("[Grain Consent] Failed to clear consent:",e)}}};function b(c,e,t){if(typeof document>"u")return;let r=[`${encodeURIComponent(c)}=${encodeURIComponent(e)}`];t?.maxAge!==void 0&&r.push(`max-age=${t.maxAge}`),t?.domain&&r.push(`domain=${t.domain}`),t?.path?r.push(`path=${t.path}`):r.push("path=/"),t?.sameSite&&r.push(`samesite=${t.sameSite}`),t?.secure&&r.push("secure"),document.cookie=r.join("; ")}function w(c){if(typeof document>"u")return null;let e=encodeURIComponent(c)+"=",t=document.cookie.split(";");for(let r=0;r<t.length;r++){let n=t[r];for(;n.charAt(0)===" ";)n=n.substring(1);if(n.indexOf(e)===0)return decodeURIComponent(n.substring(e.length))}return null}function L(c,e){if(typeof document>"u")return;let t=[`${encodeURIComponent(c)}=`,"max-age=0"];e?.domain&&t.push(`domain=${e.domain}`),e?.path?t.push(`path=${e.path}`):t.push("path=/"),document.cookie=t.join("; ")}function k(){if(typeof document>"u")return!1;try{let c="_grain_cookie_test";b(c,"test",{maxAge:1});let e=w(c)==="test";return L(c),e}catch{return!1}}var m=class{constructor(){this.activityThreshold=3e4;this.listeners=[];this.isDestroyed=!1;this.activityEvents=["mousemove","mousedown","keydown","scroll","touchstart","click"];this.lastActivityTime=Date.now(),this.boundActivityHandler=this.debounce(this.handleActivity.bind(this),500),this.setupListeners()}setupListeners(){if(!(typeof window>"u"))for(let e of this.activityEvents)window.addEventListener(e,this.boundActivityHandler,{passive:!0})}handleActivity(){this.isDestroyed||(this.lastActivityTime=Date.now(),this.notifyListeners())}debounce(e,t){let r=null;return()=>{r!==null&&clearTimeout(r),r=window.setTimeout(()=>{e(),r=null},t)}}isActive(e){let t=e??this.activityThreshold;return Date.now()-this.lastActivityTime<t}getTimeSinceLastActivity(){return Date.now()-this.lastActivityTime}getLastActivityTime(){return this.lastActivityTime}setActivityThreshold(e){this.activityThreshold=e}addListener(e){this.listeners.push(e)}removeListener(e){let t=this.listeners.indexOf(e);t>-1&&this.listeners.splice(t,1)}notifyListeners(){for(let e of this.listeners)try{e()}catch(t){console.error("[Activity Detector] Listener error:",t)}}destroy(){if(!this.isDestroyed){if(typeof window<"u")for(let e of this.activityEvents)window.removeEventListener(e,this.boundActivityHandler);this.listeners=[],this.isDestroyed=!0}}};var v=class{constructor(e,t,r){this.heartbeatTimer=null;this.isDestroyed=!1;this.hasSentPageLoadHeartbeat=!1;this.tracker=e,this.activityDetector=t,this.config=r,this.lastHeartbeatTime=Date.now(),this.currentInterval=r.activeInterval,this.sendPageLoadHeartbeat(),this.scheduleNextHeartbeat()}sendPageLoadHeartbeat(){if(!(this.isDestroyed||this.hasSentPageLoadHeartbeat))if(typeof window<"u"&&document.readyState!=="complete"){let e=()=>{this.sendHeartbeat("page_load"),this.hasSentPageLoadHeartbeat=!0,window.removeEventListener("load",e)};window.addEventListener("load",e)}else this.sendHeartbeat("page_load"),this.hasSentPageLoadHeartbeat=!0}scheduleNextHeartbeat(){if(this.isDestroyed)return;this.heartbeatTimer!==null&&clearTimeout(this.heartbeatTimer);let e=this.activityDetector.isActive(6e4);this.currentInterval=e?this.config.activeInterval:this.config.inactiveInterval,this.heartbeatTimer=window.setTimeout(()=>{this.sendHeartbeat("periodic"),this.scheduleNextHeartbeat()},this.currentInterval),this.config.debug&&console.log(`[Heartbeat] Scheduled next heartbeat in ${this.currentInterval/1e3}s (${e?"active":"inactive"})`)}sendHeartbeat(e="periodic"){if(this.isDestroyed)return;let t=Date.now(),r=this.activityDetector.isActive(6e4),n=this.tracker.hasConsent("analytics"),s={type:"heartbeat",heartbeat_type:e,status:r?"active":"inactive",timestamp:t};if(n){let i=this.tracker.getCurrentPage();i&&(s.page=i),e==="periodic"&&(s.duration=t-this.lastHeartbeatTime,s.event_count=this.tracker.getEventCountSinceLastHeartbeat(),this.tracker.resetEventCountSinceLastHeartbeat())}this.tracker.trackSystemEvent("_grain_heartbeat",s),this.lastHeartbeatTime=t,this.config.debug&&console.log("[Heartbeat] Sent heartbeat:",s)}destroy(){this.isDestroyed||(this.heartbeatTimer!==null&&(clearTimeout(this.heartbeatTimer),this.heartbeatTimer=null),this.isDestroyed=!0,this.config.debug&&console.log("[Heartbeat] Destroyed"))}};var y=class{constructor(e,t){this.isDestroyed=!1;this.currentPath=null;this.originalPushState=null;this.originalReplaceState=null;this.handlePopState=()=>{this.isDestroyed||this.trackCurrentPage()};this.handleHashChange=()=>{this.isDestroyed||this.trackCurrentPage()};this.tracker=e,this.config=t,this.trackCurrentPage(),this.setupHistoryListeners(),this.setupHashChangeListener()}setupHistoryListeners(){typeof window>"u"||typeof history>"u"||(this.originalPushState=history.pushState,history.pushState=(e,t,r)=>{this.originalPushState?.call(history,e,t,r),this.trackCurrentPage()},this.originalReplaceState=history.replaceState,history.replaceState=(e,t,r)=>{this.originalReplaceState?.call(history,e,t,r),this.trackCurrentPage()},window.addEventListener("popstate",this.handlePopState))}setupHashChangeListener(){typeof window>"u"||window.addEventListener("hashchange",this.handleHashChange)}trackCurrentPage(){if(this.isDestroyed||typeof window>"u")return;let e=this.extractPath(window.location.href);if(e===this.currentPath)return;this.currentPath=e;let t=this.tracker.hasConsent("analytics"),r={page:e,timestamp:Date.now()};t&&(r.referrer=document.referrer||"",r.title=document.title||"",r.full_url=window.location.href),this.tracker.trackSystemEvent("page_view",r),this.config.debug&&console.log("[Page Tracking] Tracked page view:",r)}extractPath(e){try{let t=new URL(e),r=t.pathname+t.hash;return!this.config.stripQueryParams&&t.search&&(r+=t.search),r}catch(t){return this.config.debug&&console.warn("[Page Tracking] Failed to parse URL:",e,t),e}}getCurrentPage(){return this.currentPath}trackPage(e,t){if(this.isDestroyed)return;let r=this.tracker.hasConsent("analytics"),n={page:e,timestamp:Date.now(),...t};r&&typeof document<"u"&&(n.referrer||(n.referrer=document.referrer||""),n.title||(n.title=document.title||""),!n.full_url&&typeof window<"u"&&(n.full_url=window.location.href)),this.tracker.trackSystemEvent("page_view",n),this.config.debug&&console.log("[Page Tracking] Manually tracked page:",n)}destroy(){this.isDestroyed||(typeof history<"u"&&(this.originalPushState&&(history.pushState=this.originalPushState),this.originalReplaceState&&(history.replaceState=this.originalReplaceState)),typeof window<"u"&&(window.removeEventListener("popstate",this.handlePopState),window.removeEventListener("hashchange",this.handleHashChange)),this.isDestroyed=!0,this.config.debug&&console.log("[Page Tracking] Destroyed"))}};var u=class{constructor(e){this.eventQueue=[];this.waitingForConsentQueue=[];this.flushTimer=null;this.isDestroyed=!1;this.globalUserId=null;this.persistentAnonymousUserId=null;this.configCache=null;this.configRefreshTimer=null;this.configChangeListeners=[];this.configFetchPromise=null;this.cookiesEnabled=!1;this.activityDetector=null;this.heartbeatManager=null;this.pageTrackingManager=null;this.ephemeralSessionId=null;this.eventCountSinceLastHeartbeat=0;this.config={apiUrl:"https://api.grainql.com",authStrategy:"NONE",batchSize:50,flushInterval:5e3,retryAttempts:3,retryDelay:1e3,maxEventsPerRequest:160,debug:!1,defaultConfigurations:{},configCacheKey:"grain_config",configRefreshInterval:3e5,enableConfigCache:!0,consentMode:"opt-out",waitForConsent:!1,enableCookies:!1,anonymizeIP:!1,disableAutoProperties:!1,enableHeartbeat:!0,heartbeatActiveInterval:12e4,heartbeatInactiveInterval:3e5,enableAutoPageView:!0,stripQueryParams:!0,...e,tenantId:e.tenantId},this.consentManager=new p(this.config.tenantId,this.config.consentMode),this.config.enableCookies&&(this.cookiesEnabled=k(),!this.cookiesEnabled&&this.config.debug&&console.warn("[Grain Analytics] Cookies are not available, falling back to localStorage")),e.userId&&(this.globalUserId=e.userId),this.validateConfig(),this.initializePersistentAnonymousUserId(),this.setupBeforeUnload(),this.startFlushTimer(),this.initializeConfigCache(),this.ephemeralSessionId=this.generateUUID(),typeof window<"u"&&this.initializeAutomaticTracking(),this.consentManager.addListener(t=>{t.granted&&this.handleConsentGranted()})}validateConfig(){if(!this.config.tenantId)throw new Error("Grain Analytics: tenantId is required");if(this.config.authStrategy==="SERVER_SIDE"&&!this.config.secretKey)throw new Error("Grain Analytics: secretKey is required for SERVER_SIDE auth strategy");if(this.config.authStrategy==="JWT"&&!this.config.authProvider)throw new Error("Grain Analytics: authProvider is required for JWT auth strategy")}generateUUID(){return typeof crypto<"u"&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,function(e){let t=Math.random()*16|0;return(e==="x"?t:t&3|8).toString(16)})}shouldAllowPersistentStorage(){let e=this.consentManager.hasConsent("analytics"),t=this.config.consentMode==="opt-in",r=!!this.globalUserId,n=this.config.authStrategy==="JWT";return e||!t||r||n}generateAnonymousUserId(){return this.generateUUID()}initializePersistentAnonymousUserId(){if(typeof window>"u")return;if(!this.shouldAllowPersistentStorage()){this.log("Opt-in mode without consent: skipping persistent ID initialization (GDPR compliance)");return}let e=`grain_anonymous_user_id_${this.config.tenantId}`,t="_grain_uid";try{if(this.cookiesEnabled){let n=w(t);if(n){this.persistentAnonymousUserId=n,this.log("Loaded persistent anonymous user ID from cookie:",this.persistentAnonymousUserId);return}}let r=localStorage.getItem(e);r?(this.persistentAnonymousUserId=r,this.log("Loaded persistent anonymous user ID from localStorage:",this.persistentAnonymousUserId),this.cookiesEnabled&&this.savePersistentAnonymousUserId(r)):(this.persistentAnonymousUserId=this.generateAnonymousUserId(),this.savePersistentAnonymousUserId(this.persistentAnonymousUserId),this.log("Generated new persistent anonymous user ID:",this.persistentAnonymousUserId))}catch(r){this.log("Failed to initialize persistent anonymous user ID:",r),this.persistentAnonymousUserId=this.generateAnonymousUserId()}}savePersistentAnonymousUserId(e){if(typeof window>"u")return;if(!this.shouldAllowPersistentStorage()){this.log("Opt-in mode without consent: skipping persistent ID save (GDPR compliance)");return}let t=`grain_anonymous_user_id_${this.config.tenantId}`,r="_grain_uid";try{if(this.cookiesEnabled){let n={maxAge:31536e3,sameSite:"lax",secure:typeof window<"u"&&window.location.protocol==="https:",...this.config.cookieOptions};b(r,e,n)}localStorage.setItem(t,e)}catch(n){this.log("Failed to save persistent anonymous user ID:",n)}}getEffectiveUserIdInternal(){return this.globalUserId?this.globalUserId:this.persistentAnonymousUserId?this.persistentAnonymousUserId:(this.persistentAnonymousUserId=this.generateAnonymousUserId(),this.savePersistentAnonymousUserId(this.persistentAnonymousUserId),this.persistentAnonymousUserId)}log(...e){this.config.debug&&console.log("[Grain Analytics]",...e)}createErrorDigest(e){let t=[...new Set(e.map(i=>i.eventName))],r=[...new Set(e.map(i=>i.userId))],n=0,s=0;return e.forEach(i=>{let o=i.properties||{};n+=Object.keys(o).length,s+=JSON.stringify(i).length}),{eventCount:e.length,totalProperties:n,totalSize:s,eventNames:t,userIds:r}}formatError(e,t,r){let n=r?this.createErrorDigest(r):{eventCount:0,totalProperties:0,totalSize:0,eventNames:[],userIds:[]},s="UNKNOWN_ERROR",i="An unknown error occurred";if(e instanceof Error)i=e.message,i.includes("fetch failed")||i.includes("network error")?s="NETWORK_ERROR":i.includes("timeout")?s="TIMEOUT_ERROR":i.includes("HTTP 4")?s="CLIENT_ERROR":i.includes("HTTP 5")?s="SERVER_ERROR":i.includes("JSON")?s="PARSE_ERROR":i.includes("auth")||i.includes("unauthorized")?s="AUTH_ERROR":i.includes("rate limit")||i.includes("429")?s="RATE_LIMIT_ERROR":s="GENERAL_ERROR";else if(typeof e=="string")i=e,s="STRING_ERROR";else if(e&&typeof e=="object"&&"status"in e){let o=e.status;s=`HTTP_${o}`,i=`HTTP ${o} error`}return{code:s,message:i,digest:n,timestamp:new Date().toISOString(),context:t,originalError:e}}logError(e){let{code:t,message:r,digest:n,timestamp:s,context:i}=e,o={"\u{1F6A8} Grain Analytics Error":{"Error Code":t,Message:r,Context:i,Timestamp:s,"Event Digest":{Events:n.eventCount,Properties:n.totalProperties,"Size (bytes)":n.totalSize,"Event Names":n.eventNames.length>0?n.eventNames.join(", "):"None","User IDs":n.userIds.length>0?n.userIds.slice(0,3).join(", ")+(n.userIds.length>3?"...":""):"None"}}};console.error("\u{1F6A8} Grain Analytics Error:",o),this.config.debug&&console.error(`[Grain Analytics] ${t}: ${r} (${i}) - Events: ${n.eventCount}, Props: ${n.totalProperties}, Size: ${n.totalSize}B`)}async safeExecute(e,t,r){try{return await e()}catch(n){let s=this.formatError(n,t,r);return this.logError(s),null}}formatEvent(e){return{eventName:e.eventName,userId:e.userId||this.getEffectiveUserIdInternal(),properties:e.properties||{}}}async getAuthHeaders(){let e={"Content-Type":"application/json"};switch(this.config.authStrategy){case"NONE":break;case"SERVER_SIDE":e.Authorization=`Chase ${this.config.secretKey}`;break;case"JWT":if(this.config.authProvider){let t=await this.config.authProvider.getToken();e.Authorization=`Bearer ${t}`}break}return e}async delay(e){return new Promise(t=>setTimeout(t,e))}isRetriableError(e){if(e instanceof Error){let t=e.message.toLowerCase();if(t.includes("fetch failed")||t==="network error"||t.includes("timeout")||t.includes("connection"))return!0}if(typeof e=="object"&&e!==null&&"status"in e){let t=e.status;return t>=500||t===429}return!1}async sendEvents(e){if(e.length===0)return;let t;for(let r=0;r<=this.config.retryAttempts;r++)try{let n=await this.getAuthHeaders(),s=`${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;this.log(`Sending ${e.length} events to ${s} (attempt ${r+1})`);let i=await fetch(s,{method:"POST",headers:n,body:JSON.stringify(e)});if(!i.ok){let o=`HTTP ${i.status}`;try{let h=await i.json();h?.message&&(o=h.message)}catch{let h=await i.text();h&&(o=h)}let a=new Error(`Failed to send events: ${o}`);throw a.status=i.status,a}this.log(`Successfully sent ${e.length} events`);return}catch(n){if(t=n,r===this.config.retryAttempts){let i=this.formatError(n,`sendEvents (attempt ${r+1}/${this.config.retryAttempts+1})`,e);this.logError(i);return}if(!this.isRetriableError(n)){let i=this.formatError(n,"sendEvents (non-retriable error)",e);this.logError(i);return}let s=this.config.retryDelay*Math.pow(2,r);this.log(`Retrying in ${s}ms after error:`,n),await this.delay(s)}}async sendEventsWithBeacon(e){if(e.length!==0)try{let t=await this.getAuthHeaders(),r=`${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`,n=JSON.stringify({events:e});if(typeof navigator<"u"&&"sendBeacon"in navigator){let s=new Blob([n],{type:"application/json"});if(navigator.sendBeacon(r,s)){this.log(`Successfully sent ${e.length} events via beacon`);return}}await fetch(r,{method:"POST",headers:t,body:n,keepalive:!0}),this.log(`Successfully sent ${e.length} events via fetch (keepalive)`)}catch(t){let r=this.formatError(t,"sendEventsWithBeacon",e);this.logError(r)}}startFlushTimer(){typeof window>"u"||(this.flushTimer&&clearInterval(this.flushTimer),this.flushTimer=window.setInterval(()=>{this.eventQueue.length>0&&this.flush().catch(e=>{let t=this.formatError(e,"auto-flush");this.logError(t)})},this.config.flushInterval))}setupBeforeUnload(){if(typeof window>"u")return;let e=()=>{if(this.eventQueue.length>0){let t=[...this.eventQueue];this.eventQueue=[];let r=this.chunkEvents(t,this.config.maxEventsPerRequest);r.length>0&&this.sendEventsWithBeacon(r[0]).catch(()=>{})}};window.addEventListener("beforeunload",e),window.addEventListener("pagehide",e),document.addEventListener("visibilitychange",()=>{if(document.visibilityState==="hidden"&&this.eventQueue.length>0){let t=[...this.eventQueue];this.eventQueue=[];let r=this.chunkEvents(t,this.config.maxEventsPerRequest);r.length>0&&this.sendEventsWithBeacon(r[0]).catch(()=>{})}})}initializeAutomaticTracking(){if(this.config.enableHeartbeat)try{this.activityDetector=new m,this.heartbeatManager=new v(this,this.activityDetector,{activeInterval:this.config.heartbeatActiveInterval,inactiveInterval:this.config.heartbeatInactiveInterval,debug:this.config.debug}),this.log("Heartbeat tracking initialized")}catch(e){this.log("Failed to initialize heartbeat tracking:",e)}if(this.config.enableAutoPageView)try{this.pageTrackingManager=new y(this,{stripQueryParams:this.config.stripQueryParams,debug:this.config.debug}),this.log("Auto page view tracking initialized")}catch(e){this.log("Failed to initialize page view tracking:",e)}}handleConsentGranted(){this.flushWaitingForConsentQueue(),this.persistentAnonymousUserId||(this.initializePersistentAnonymousUserId(),this.log("Initialized persistent ID after consent grant")),this.ephemeralSessionId&&this.trackSystemEvent("_grain_consent_granted",{previous_session_id:this.ephemeralSessionId,new_user_id:this.getEffectiveUserId(),timestamp:Date.now()})}trackSystemEvent(e,t){if(this.isDestroyed)return;let r=this.consentManager.hasConsent("analytics"),n={eventName:e,userId:r?this.getEffectiveUserId():this.getEphemeralSessionId(),properties:{...t,_minimal:!r,_consent_status:r?"granted":"pending"}};this.eventQueue.push(n),this.eventCountSinceLastHeartbeat++,this.log(`Queued system event: ${e}`,t),this.eventQueue.length>=this.config.batchSize&&this.flush().catch(s=>{let i=this.formatError(s,"flush system event");this.logError(i)})}getEphemeralSessionId(){return this.ephemeralSessionId||(this.ephemeralSessionId=this.generateUUID()),this.ephemeralSessionId}getCurrentPage(){return this.pageTrackingManager?.getCurrentPage()||null}getEventCountSinceLastHeartbeat(){return this.eventCountSinceLastHeartbeat}resetEventCountSinceLastHeartbeat(){this.eventCountSinceLastHeartbeat=0}getEffectiveUserId(){return this.getEffectiveUserIdInternal()}getSessionId(){return this.consentManager.hasConsent("analytics")?this.getEffectiveUserId():this.getEphemeralSessionId()}async track(e,t,r){try{if(this.isDestroyed){let o=new Error("Grain Analytics: Client has been destroyed"),a=this.formatError(o,"track (client destroyed)");this.logError(a);return}let n,s={};if(typeof e=="string"?(n={eventName:e,properties:t},s=r||{}):(n=e,s=t||{}),this.config.allowedProperties&&n.properties){let o={};for(let a of this.config.allowedProperties)a in n.properties&&(o[a]=n.properties[a]);n.properties=o}let i=this.formatEvent(n);if(this.consentManager.shouldWaitForConsent()&&this.config.waitForConsent){this.waitingForConsentQueue.push(i),this.log(`Event waiting for consent: ${n.eventName}`,n.properties);return}if(!this.consentManager.hasConsent("analytics")){this.log(`Event blocked by consent: ${n.eventName}`);return}this.eventQueue.push(i),this.eventCountSinceLastHeartbeat++,this.log(`Queued event: ${n.eventName}`,n.properties),(s.flush||this.eventQueue.length>=this.config.batchSize)&&await this.flush()}catch(n){let s=this.formatError(n,"track");this.logError(s)}}flushWaitingForConsentQueue(){this.waitingForConsentQueue.length!==0&&(this.log(`Flushing ${this.waitingForConsentQueue.length} events waiting for consent`),this.eventQueue.push(...this.waitingForConsentQueue),this.waitingForConsentQueue=[],this.flush().catch(e=>{let t=this.formatError(e,"flush waiting for consent queue");this.logError(t)}))}identify(e){this.log(`Identified user: ${e}`),this.globalUserId=e,this.persistentAnonymousUserId=null}setUserId(e){this.log(`Set global user ID: ${e}`),this.globalUserId=e,e?this.persistentAnonymousUserId=null:this.persistentAnonymousUserId||(this.persistentAnonymousUserId=this.generateAnonymousUserId(),this.savePersistentAnonymousUserId(this.persistentAnonymousUserId))}getUserId(){return this.globalUserId}getEffectiveUserIdPublic(){return this.getEffectiveUserIdInternal()}login(e){try{if(this.isDestroyed){let t=new Error("Grain Analytics: Client has been destroyed"),r=this.formatError(t,"login (client destroyed)");this.logError(r);return}e.userId&&(this.log(`Login: Setting user ID to ${e.userId}`),this.globalUserId=e.userId,this.persistentAnonymousUserId=null),e.authToken&&(this.log("Login: Setting auth token"),this.config.authStrategy==="NONE"&&(this.config.authStrategy="JWT"),this.config.authProvider={getToken:()=>e.authToken}),e.authStrategy&&(this.log(`Login: Setting auth strategy to ${e.authStrategy}`),this.config.authStrategy=e.authStrategy),this.log(`Login successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`)}catch(t){let r=this.formatError(t,"login");this.logError(r)}}logout(){try{if(this.isDestroyed){let e=new Error("Grain Analytics: Client has been destroyed"),t=this.formatError(e,"logout (client destroyed)");this.logError(t);return}if(this.log("Logout: Clearing user session"),this.globalUserId=null,this.config.authStrategy="NONE",this.config.authProvider=void 0,!this.persistentAnonymousUserId&&(this.persistentAnonymousUserId=this.generateAnonymousUserId(),typeof window<"u"))try{let e=`grain_anonymous_user_id_${this.config.tenantId}`;localStorage.setItem(e,this.persistentAnonymousUserId)}catch(e){this.log("Failed to persist new anonymous user ID after logout:",e)}this.log(`Logout successful. Effective user ID: ${this.getEffectiveUserIdInternal()}`)}catch(e){let t=this.formatError(e,"logout");this.logError(t)}}async setProperty(e,t){try{if(this.isDestroyed){let o=new Error("Grain Analytics: Client has been destroyed"),a=this.formatError(o,"setProperty (client destroyed)");this.logError(a);return}let r=t?.userId||this.getEffectiveUserIdInternal(),n=Object.keys(e);if(n.length>4){let o=new Error("Grain Analytics: Maximum 4 properties allowed per request"),a=this.formatError(o,"setProperty (validation)");this.logError(a);return}if(n.length===0){let o=new Error("Grain Analytics: At least one property is required"),a=this.formatError(o,"setProperty (validation)");this.logError(a);return}let s={};for(let[o,a]of Object.entries(e))a==null?s[o]="":typeof a=="string"?s[o]=a:s[o]=JSON.stringify(a);let i={userId:r,...s};await this.sendProperties(i)}catch(r){let n=this.formatError(r,"setProperty");this.logError(n)}}async sendProperties(e){let t;for(let r=0;r<=this.config.retryAttempts;r++)try{let n=await this.getAuthHeaders(),s=`${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/properties`;this.log(`Setting properties for user ${e.userId} (attempt ${r+1})`);let i=await fetch(s,{method:"POST",headers:n,body:JSON.stringify(e)});if(!i.ok){let o=`HTTP ${i.status}`;try{let h=await i.json();h?.message&&(o=h.message)}catch{let h=await i.text();h&&(o=h)}let a=new Error(`Failed to set properties: ${o}`);throw a.status=i.status,a}this.log(`Successfully set properties for user ${e.userId}`);return}catch(n){if(t=n,r===this.config.retryAttempts){let i=this.formatError(n,`sendProperties (attempt ${r+1}/${this.config.retryAttempts+1})`);this.logError(i);return}if(!this.isRetriableError(n)){let i=this.formatError(n,"sendProperties (non-retriable error)");this.logError(i);return}let s=this.config.retryDelay*Math.pow(2,r);this.log(`Retrying in ${s}ms after error:`,n),await this.delay(s)}}async trackLogin(e,t){try{return await this.track("login",e,t)}catch(r){let n=this.formatError(r,"trackLogin");this.logError(n)}}async trackSignup(e,t){try{return await this.track("signup",e,t)}catch(r){let n=this.formatError(r,"trackSignup");this.logError(n)}}async trackCheckout(e,t){try{return await this.track("checkout",e,t)}catch(r){let n=this.formatError(r,"trackCheckout");this.logError(n)}}async trackPageView(e,t){try{return await this.track("page_view",e,t)}catch(r){let n=this.formatError(r,"trackPageView");this.logError(n)}}async trackPurchase(e,t){try{return await this.track("purchase",e,t)}catch(r){let n=this.formatError(r,"trackPurchase");this.logError(n)}}async trackSearch(e,t){try{return await this.track("search",e,t)}catch(r){let n=this.formatError(r,"trackSearch");this.logError(n)}}async trackAddToCart(e,t){try{return await this.track("add_to_cart",e,t)}catch(r){let n=this.formatError(r,"trackAddToCart");this.logError(n)}}async trackRemoveFromCart(e,t){try{return await this.track("remove_from_cart",e,t)}catch(r){let n=this.formatError(r,"trackRemoveFromCart");this.logError(n)}}async flush(){try{if(this.eventQueue.length===0)return;let e=[...this.eventQueue];this.eventQueue=[];let t=this.chunkEvents(e,this.config.maxEventsPerRequest);for(let r of t)await this.sendEvents(r)}catch(e){let t=this.formatError(e,"flush");this.logError(t)}}initializeConfigCache(){if(!(!this.config.enableConfigCache||typeof window>"u"))try{let e=localStorage.getItem(this.config.configCacheKey);e&&(this.configCache=JSON.parse(e),this.log("Loaded configuration from cache:",this.configCache))}catch(e){this.log("Failed to load configuration cache:",e)}}saveConfigCache(e){if(!(!this.config.enableConfigCache||typeof window>"u"))try{localStorage.setItem(this.config.configCacheKey,JSON.stringify(e)),this.log("Saved configuration to cache:",e)}catch(t){this.log("Failed to save configuration cache:",t)}}getConfig(e){if(this.configCache?.configurations?.[e])return this.configCache.configurations[e];if(this.config.defaultConfigurations?.[e])return this.config.defaultConfigurations[e]}getAllConfigs(){let e={...this.config.defaultConfigurations};return this.configCache?.configurations&&Object.assign(e,this.configCache.configurations),e}async fetchConfig(e={}){try{if(this.isDestroyed){let o=new Error("Grain Analytics: Client has been destroyed"),a=this.formatError(o,"fetchConfig (client destroyed)");return this.logError(a),null}let t=e.userId||this.getEffectiveUserIdInternal(),r=e.immediateKeys||[],n=e.properties||{},s={userId:t,immediateKeys:r,properties:n},i;for(let o=0;o<=this.config.retryAttempts;o++)try{let a=await this.getAuthHeaders(),h=`${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/config/configurations`;this.log(`Fetching configurations for user ${t} (attempt ${o+1})`);let g=await fetch(h,{method:"POST",headers:a,body:JSON.stringify(s)});if(!g.ok){let E=`HTTP ${g.status}`;try{let d=await g.json();d?.message&&(E=d.message)}catch{let d=await g.text();d&&(E=d)}let S=new Error(`Failed to fetch configurations: ${E}`);throw S.status=g.status,S}let l=await g.json();return l.configurations&&this.updateConfigCache(l,t),this.log(`Successfully fetched configurations for user ${t}:`,l),l}catch(a){if(i=a,o===this.config.retryAttempts){let g=this.formatError(a,`fetchConfig (attempt ${o+1}/${this.config.retryAttempts+1})`);return this.logError(g),null}if(!this.isRetriableError(a)){let g=this.formatError(a,"fetchConfig (non-retriable error)");return this.logError(g),null}let h=this.config.retryDelay*Math.pow(2,o);this.log(`Retrying config fetch in ${h}ms after error:`,a),await this.delay(h)}return null}catch(t){let r=this.formatError(t,"fetchConfig");return this.logError(r),null}}async getConfigAsync(e,t={}){try{if(!t.forceRefresh&&this.configCache?.configurations?.[e])return this.configCache.configurations[e];if(!t.forceRefresh&&this.config.defaultConfigurations?.[e])return this.config.defaultConfigurations[e];let r=await this.fetchConfig(t);return r?r.configurations[e]:this.config.defaultConfigurations?.[e]}catch(r){let n=this.formatError(r,"getConfigAsync");return this.logError(n),this.config.defaultConfigurations?.[e]}}async getAllConfigsAsync(e={}){try{if(!e.forceRefresh&&this.configCache?.configurations)return{...this.config.defaultConfigurations,...this.configCache.configurations};let t=await this.fetchConfig(e);return t?{...this.config.defaultConfigurations,...t.configurations}:{...this.config.defaultConfigurations}}catch(t){let r=this.formatError(t,"getAllConfigsAsync");return this.logError(r),{...this.config.defaultConfigurations}}}updateConfigCache(e,t){let r={configurations:e.configurations,snapshotId:e.snapshotId,timestamp:e.timestamp,userId:t},n=this.configCache?.configurations||{};this.configCache=r,this.saveConfigCache(r),JSON.stringify(n)!==JSON.stringify(e.configurations)&&this.notifyConfigChangeListeners(e.configurations)}addConfigChangeListener(e){this.configChangeListeners.push(e)}removeConfigChangeListener(e){let t=this.configChangeListeners.indexOf(e);t>-1&&this.configChangeListeners.splice(t,1)}notifyConfigChangeListeners(e){this.configChangeListeners.forEach(t=>{try{t(e)}catch(r){console.error("[Grain Analytics] Config change listener error:",r)}})}startConfigRefreshTimer(){typeof window>"u"||(this.configRefreshTimer&&clearInterval(this.configRefreshTimer),this.configRefreshTimer=window.setInterval(()=>{this.isDestroyed||this.fetchConfig().catch(e=>{let t=this.formatError(e,"auto-config refresh");this.logError(t)})},this.config.configRefreshInterval))}stopConfigRefreshTimer(){this.configRefreshTimer&&(clearInterval(this.configRefreshTimer),this.configRefreshTimer=null)}async preloadConfig(e=[],t){try{let r=this.getEffectiveUserIdInternal();this.log(`Preloading config for user: ${r}`),await this.fetchConfig({immediateKeys:e,properties:t})&&this.startConfigRefreshTimer()}catch(r){let n=this.formatError(r,"preloadConfig");this.logError(n)}}chunkEvents(e,t){let r=[];for(let n=0;n<e.length;n+=t)r.push(e.slice(n,n+t));return r}grantConsent(e){try{this.consentManager.grantConsent(e),this.log("Consent granted",e)}catch(t){let r=this.formatError(t,"grantConsent");this.logError(r)}}revokeConsent(e){try{this.consentManager.revokeConsent(e),this.log("Consent revoked",e),this.eventQueue=[],this.waitingForConsentQueue=[]}catch(t){let r=this.formatError(t,"revokeConsent");this.logError(r)}}getConsentState(){return this.consentManager.getConsentState()}hasConsent(e){return this.consentManager.hasConsent(e)}onConsentChange(e){this.consentManager.addListener(e)}offConsentChange(e){this.consentManager.removeListener(e)}destroy(){if(this.isDestroyed=!0,this.flushTimer&&(clearInterval(this.flushTimer),this.flushTimer=null),this.stopConfigRefreshTimer(),this.configChangeListeners=[],this.heartbeatManager&&(this.heartbeatManager.destroy(),this.heartbeatManager=null),this.pageTrackingManager&&(this.pageTrackingManager.destroy(),this.pageTrackingManager=null),this.activityDetector&&(this.activityDetector.destroy(),this.activityDetector=null),this.eventQueue.length>0){let e=[...this.eventQueue];this.eventQueue=[];let t=this.chunkEvents(e,this.config.maxEventsPerRequest);if(t.length>0){this.sendEventsWithBeacon(t[0]).catch(()=>{});for(let r=1;r<t.length;r++)this.sendEventsWithBeacon(t[r]).catch(()=>{})}}}};function P(c){return new u(c)}var O=u;typeof window<"u"&&(window.Grain={GrainAnalytics:u,createGrainAnalytics:P});return D($);})();
 //# sourceMappingURL=index.global.js.map

package/dist/react/index.d.ts

@@ -1,522 +1,47 @@
 /**
- * Grain Analytics Web SDK
- * A lightweight, dependency-free TypeScript SDK for sending analytics events to Grain's REST API
+ * Grain Analytics React Hooks
+ *
+ * React integration for @grainql/analytics-web
+ *
+ * @example
+ * ```tsx
+ * import { GrainProvider, useConfig, useTrack } from '@grainql/analytics-web/react';
+ *
+ * // Pattern 1: Provider-managed client
+ * <GrainProvider config={{ tenantId: 'xxx' }}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Pattern 2: External client
+ * const grain = new GrainAnalytics({ tenantId: 'xxx' });
+ * <GrainProvider client={grain}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Use hooks in components
+ * function MyComponent() {
+ *   const { value } = useConfig('hero_variant');
+ *   const track = useTrack();
+ *
+ *   return <button onClick={() => track('clicked')}>Click</button>;
+ * }
+ * ```
  */
-import { ConsentState, ConsentMode } from './consent';
-import { CookieConfig } from './cookies';
-import { type HeartbeatTracker } from './heartbeat';
-import { type PageTracker } from './page-tracking';
-export interface GrainEvent {
-    eventName: string;
-    userId?: string;
-    properties?: Record<string, unknown>;
-    timestamp?: Date;
-}
-export interface EventPayload {
-    eventName: string;
-    userId: string;
-    properties: Record<string, unknown>;
-}
-export type AuthStrategy = 'NONE' | 'SERVER_SIDE' | 'JWT';
-export interface AuthProvider {
-    getToken(): Promise<string> | string;
-}
-export type { ConsentState, ConsentMode, CookieConfig };
-export interface GrainConfig {
-    tenantId: string;
-    apiUrl?: string;
-    authStrategy?: AuthStrategy;
-    secretKey?: string;
-    authProvider?: AuthProvider;
-    userId?: string;
-    batchSize?: number;
-    flushInterval?: number;
-    retryAttempts?: number;
-    retryDelay?: number;
-    maxEventsPerRequest?: number;
-    debug?: boolean;
-    defaultConfigurations?: Record<string, string>;
-    configCacheKey?: string;
-    configRefreshInterval?: number;
-    enableConfigCache?: boolean;
-    consentMode?: ConsentMode;
-    waitForConsent?: boolean;
-    enableCookies?: boolean;
-    cookieOptions?: CookieConfig;
-    anonymizeIP?: boolean;
-    disableAutoProperties?: boolean;
-    allowedProperties?: string[];
-    enableHeartbeat?: boolean;
-    heartbeatActiveInterval?: number;
-    heartbeatInactiveInterval?: number;
-    enableAutoPageView?: boolean;
-    stripQueryParams?: boolean;
-}
-export interface SendEventOptions {
-    flush?: boolean;
-}
-export interface SetPropertyOptions {
-    userId?: string;
-}
-export interface LoginOptions {
-    userId?: string;
-    authToken?: string;
-    authStrategy?: AuthStrategy;
-}
-export interface PropertyPayload {
-    userId: string;
-    [key: string]: string;
-}
-export interface RemoteConfigRequest {
-    userId: string;
-    immediateKeys: string[];
-    properties?: Record<string, string>;
-}
-export interface RemoteConfigResponse {
-    userId: string;
-    snapshotId: string;
-    configurations: Record<string, string>;
-    isFinal: boolean;
-    qualifiedSegments: string[];
-    qualifiedRuleSets: string[];
-    timestamp: string;
-    isFromCache: boolean;
-}
-export interface RemoteConfigOptions {
-    immediateKeys?: string[];
-    properties?: Record<string, string>;
-    userId?: string;
-    forceRefresh?: boolean;
-}
-export interface RemoteConfigCache {
-    configurations: Record<string, string>;
-    snapshotId: string;
-    timestamp: string;
-    userId: string;
-}
-export type ConfigChangeListener = (configurations: Record<string, string>) => void;
-export interface LoginEventProperties extends Record<string, unknown> {
-    method?: string;
-    success?: boolean;
-    errorMessage?: string;
-    loginAttempt?: number;
-    rememberMe?: boolean;
-    twoFactorEnabled?: boolean;
-}
-export interface SignupEventProperties extends Record<string, unknown> {
-    method?: string;
-    source?: string;
-    plan?: string;
-    success?: boolean;
-    errorMessage?: string;
-}
-export interface CheckoutEventProperties extends Record<string, unknown> {
-    orderId?: string;
-    total?: number;
-    currency?: string;
-    items?: Array<{
-        id: string;
-        name: string;
-        price: number;
-        quantity: number;
-    }>;
-    paymentMethod?: string;
-    success?: boolean;
-    errorMessage?: string;
-    couponCode?: string;
-    discount?: number;
-}
-export interface PageViewEventProperties extends Record<string, unknown> {
-    page?: string;
-    title?: string;
-    referrer?: string;
-    url?: string;
-    userAgent?: string;
-    screenResolution?: string;
-    viewportSize?: string;
-}
-export interface PurchaseEventProperties extends Record<string, unknown> {
-    orderId?: string;
-    total?: number;
-    currency?: string;
-    items?: Array<{
-        id: string;
-        name: string;
-        price: number;
-        quantity: number;
-        category?: string;
-    }>;
-    paymentMethod?: string;
-    shippingMethod?: string;
-    tax?: number;
-    shipping?: number;
-    discount?: number;
-    couponCode?: string;
-}
-export interface SearchEventProperties extends Record<string, unknown> {
-    query?: string;
-    results?: number;
-    filters?: Record<string, unknown>;
-    sortBy?: string;
-    category?: string;
-    success?: boolean;
-}
-export interface AddToCartEventProperties extends Record<string, unknown> {
-    itemId?: string;
-    itemName?: string;
-    price?: number;
-    quantity?: number;
-    currency?: string;
-    category?: string;
-    variant?: string;
-}
-export interface RemoveFromCartEventProperties extends Record<string, unknown> {
-    itemId?: string;
-    itemName?: string;
-    price?: number;
-    quantity?: number;
-    currency?: string;
-    category?: string;
-    variant?: string;
-}
-export interface ErrorDigest {
-    eventCount: number;
-    totalProperties: number;
-    totalSize: number;
-    eventNames: string[];
-    userIds: string[];
-}
-export interface FormattedError {
-    code: string;
-    message: string;
-    digest: ErrorDigest;
-    timestamp: string;
-    context: string;
-    originalError?: unknown;
-}
-export declare class GrainAnalytics implements HeartbeatTracker, PageTracker {
-    private config;
-    private eventQueue;
-    private waitingForConsentQueue;
-    private flushTimer;
-    private isDestroyed;
-    private globalUserId;
-    private persistentAnonymousUserId;
-    private configCache;
-    private configRefreshTimer;
-    private configChangeListeners;
-    private configFetchPromise;
-    private consentManager;
-    private cookiesEnabled;
-    private activityDetector;
-    private heartbeatManager;
-    private pageTrackingManager;
-    private ephemeralSessionId;
-    private eventCountSinceLastHeartbeat;
-    constructor(config: GrainConfig);
-    private validateConfig;
-    /**
-     * Generate a UUID v4 string
-     */
-    private generateUUID;
-    /**
-     * Check if we should allow persistent storage (GDPR compliance)
-     *
-     * Returns true if:
-     * - Consent has been granted, OR
-     * - Not in opt-in mode, OR
-     * - User has been explicitly identified by the site (login/identify), OR
-     * - Using JWT auth strategy (functional/essential purpose)
-     */
-    private shouldAllowPersistentStorage;
-    /**
-     * Generate a proper UUIDv4 identifier for anonymous user ID
-     */
-    private generateAnonymousUserId;
-    /**
-     * Initialize persistent anonymous user ID from cookies or localStorage
-     * Priority: Cookie → localStorage → generate new
-     *
-     * GDPR Compliance: In opt-in mode without consent, we skip loading/saving
-     * persistent IDs unless the user has been explicitly identified by the site
-     * or when using JWT auth (functional/essential purpose)
-     */
-    private initializePersistentAnonymousUserId;
-    /**
-     * Save persistent anonymous user ID to cookie and/or localStorage
-     *
-     * GDPR Compliance: In opt-in mode without consent, we don't persist IDs
-     * unless the user has been explicitly identified or using JWT auth
-     */
-    private savePersistentAnonymousUserId;
-    /**
-     * Get the effective user ID (global userId or persistent anonymous ID)
-     *
-     * GDPR Compliance: In opt-in mode without consent and no explicit user identification,
-     * this should not be called. Use getEphemeralSessionId() instead.
-     */
-    private getEffectiveUserIdInternal;
-    private log;
-    /**
-     * Create error digest from events
-     */
-    private createErrorDigest;
-    /**
-     * Format error with beautiful structure
-     */
-    private formatError;
-    /**
-     * Log formatted error gracefully
-     */
-    private logError;
-    /**
-     * Safely execute a function with error handling
-     */
-    private safeExecute;
-    private formatEvent;
-    private getAuthHeaders;
-    private delay;
-    private isRetriableError;
-    private sendEvents;
-    private sendEventsWithBeacon;
-    private startFlushTimer;
-    private setupBeforeUnload;
-    /**
-     * Initialize automatic tracking (heartbeat and page views)
-     */
-    private initializeAutomaticTracking;
-    /**
-     * Handle consent granted - upgrade ephemeral session to persistent user
-     */
-    private handleConsentGranted;
-    /**
-     * Track system events that bypass consent checks (for necessary/functional tracking)
-     */
-    trackSystemEvent(eventName: string, properties: Record<string, unknown>): void;
-    /**
-     * Get ephemeral session ID (memory-only, not persisted)
-     */
-    getEphemeralSessionId(): string;
-    /**
-     * Get the current page path from page tracker
-     */
-    getCurrentPage(): string | null;
-    /**
-     * Get event count since last heartbeat
-     */
-    getEventCountSinceLastHeartbeat(): number;
-    /**
-     * Reset event count since last heartbeat
-     */
-    resetEventCountSinceLastHeartbeat(): void;
-    /**
-     * Get the effective user ID (public method)
-     */
-    getEffectiveUserId(): string;
-    /**
-     * Get the session ID (ephemeral or persistent based on consent)
-     */
-    getSessionId(): string;
-    /**
-     * Track an analytics event
-     */
-    track(eventName: string, properties?: Record<string, unknown>, options?: SendEventOptions): Promise<void>;
-    track(event: GrainEvent, options?: SendEventOptions): Promise<void>;
-    /**
-     * Flush events that were waiting for consent
-     */
-    private flushWaitingForConsentQueue;
-    /**
-     * Identify a user (sets userId for subsequent events)
-     */
-    identify(userId: string): void;
-    /**
-     * Set global user ID for all subsequent events
-     */
-    setUserId(userId: string | null): void;
-    /**
-     * Get current global user ID
-     */
-    getUserId(): string | null;
-    /**
-     * Get current effective user ID (global userId or persistent anonymous ID)
-     */
-    getEffectiveUserIdPublic(): string;
-    /**
-     * Login with auth token or userId on the fly
-     *
-     * @example
-     * // Login with userId only
-     * client.login({ userId: 'user123' });
-     *
-     * // Login with auth token (automatically sets authStrategy to JWT)
-     * client.login({ authToken: 'jwt-token-here' });
-     *
-     * // Login with both userId and auth token
-     * client.login({ userId: 'user123', authToken: 'jwt-token-here' });
-     *
-     * // Override auth strategy
-     * client.login({ userId: 'user123', authStrategy: 'SERVER_SIDE' });
-     */
-    login(options: LoginOptions): void;
-    /**
-     * Logout and clear user session, fall back to UUIDv4 identifier
-     *
-     * @example
-     * // Logout user and return to anonymous mode
-     * client.logout();
-     *
-     * // After logout, events will use the persistent UUIDv4 identifier
-     * client.track('page_view', { page: 'home' });
-     */
-    logout(): void;
-    /**
-     * Set user properties
-     */
-    setProperty(properties: Record<string, unknown>, options?: SetPropertyOptions): Promise<void>;
-    /**
-     * Send properties to the API
-     */
-    private sendProperties;
-    /**
-     * Track user login event
-     */
-    trackLogin(properties?: LoginEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track user signup event
-     */
-    trackSignup(properties?: SignupEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track checkout event
-     */
-    trackCheckout(properties?: CheckoutEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track page view event
-     */
-    trackPageView(properties?: PageViewEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track purchase event
-     */
-    trackPurchase(properties?: PurchaseEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track search event
-     */
-    trackSearch(properties?: SearchEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track add to cart event
-     */
-    trackAddToCart(properties?: AddToCartEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Track remove from cart event
-     */
-    trackRemoveFromCart(properties?: RemoveFromCartEventProperties, options?: SendEventOptions): Promise<void>;
-    /**
-     * Manually flush all queued events
-     */
-    flush(): Promise<void>;
-    /**
-     * Initialize configuration cache from localStorage
-     */
-    private initializeConfigCache;
-    /**
-     * Save configuration cache to localStorage
-     */
-    private saveConfigCache;
-    /**
-     * Get configuration value with fallback to defaults
-     */
-    getConfig(key: string): string | undefined;
-    /**
-     * Get all configurations with fallback to defaults
-     */
-    getAllConfigs(): Record<string, string>;
-    /**
-     * Fetch configurations from API
-     */
-    fetchConfig(options?: RemoteConfigOptions): Promise<RemoteConfigResponse | null>;
-    /**
-     * Get configuration asynchronously (cache-first with fallback to API)
-     */
-    getConfigAsync(key: string, options?: RemoteConfigOptions): Promise<string | undefined>;
-    /**
-     * Get all configurations asynchronously (cache-first with fallback to API)
-     */
-    getAllConfigsAsync(options?: RemoteConfigOptions): Promise<Record<string, string>>;
-    /**
-     * Update configuration cache and notify listeners
-     */
-    private updateConfigCache;
-    /**
-     * Add configuration change listener
-     */
-    addConfigChangeListener(listener: ConfigChangeListener): void;
-    /**
-     * Remove configuration change listener
-     */
-    removeConfigChangeListener(listener: ConfigChangeListener): void;
-    /**
-     * Notify all configuration change listeners
-     */
-    private notifyConfigChangeListeners;
-    /**
-     * Start automatic configuration refresh timer
-     */
-    private startConfigRefreshTimer;
-    /**
-     * Stop automatic configuration refresh timer
-     */
-    private stopConfigRefreshTimer;
-    /**
-     * Preload configurations for immediate access
-     */
-    preloadConfig(immediateKeys?: string[], properties?: Record<string, string>): Promise<void>;
-    /**
-     * Split events array into chunks of specified size
-     */
-    private chunkEvents;
-    /**
-     * Grant consent for tracking
-     * @param categories - Optional array of consent categories (e.g., ['analytics', 'functional'])
-     */
-    grantConsent(categories?: string[]): void;
-    /**
-     * Revoke consent for tracking (opt-out)
-     * @param categories - Optional array of categories to revoke (if not provided, revokes all)
-     */
-    revokeConsent(categories?: string[]): void;
-    /**
-     * Get current consent state
-     */
-    getConsentState(): ConsentState | null;
-    /**
-     * Check if user has granted consent
-     * @param category - Optional category to check (if not provided, checks general consent)
-     */
-    hasConsent(category?: string): boolean;
-    /**
-     * Add listener for consent state changes
-     */
-    onConsentChange(listener: (state: ConsentState) => void): void;
-    /**
-     * Remove consent change listener
-     */
-    offConsentChange(listener: (state: ConsentState) => void): void;
-    /**
-     * Destroy the client and clean up resources
-     */
-    destroy(): void;
-}
-/**
- * Create a new Grain Analytics client
- */
-export declare function createGrainAnalytics(config: GrainConfig): GrainAnalytics;
-export default GrainAnalytics;
-declare global {
-    interface Window {
-        Grain?: {
-            GrainAnalytics: typeof GrainAnalytics;
-            createGrainAnalytics: typeof createGrainAnalytics;
-        };
-    }
-}
+export { GrainProvider } from './GrainProvider';
+export { useGrainAnalytics } from './hooks/useGrainAnalytics';
+export { useConfig } from './hooks/useConfig';
+export { useAllConfigs } from './hooks/useAllConfigs';
+export { useTrack } from './hooks/useTrack';
+export { useConsent } from './hooks/useConsent';
+export { usePrivacyPreferences } from './hooks/usePrivacyPreferences';
+export { useDataDeletion } from './hooks/useDataDeletion';
+export { ConsentBanner } from './components/ConsentBanner';
+export { PrivacyPreferenceCenter } from './components/PrivacyPreferenceCenter';
+export { CookieNotice } from './components/CookieNotice';
+export type { GrainProviderProps, UseConfigOptions, UseConfigResult, UseAllConfigsOptions, UseAllConfigsResult, TrackFunction, } from './types';
+export type { ConsentBannerProps } from './components/ConsentBanner';
+export type { PrivacyPreferenceCenterProps } from './components/PrivacyPreferenceCenter';
+export type { CookieNoticeProps } from './components/CookieNotice';
+export type { PrivacyPreferences } from './hooks/usePrivacyPreferences';
+export type { DataDeletionOptions } from './hooks/useDataDeletion';
 //# sourceMappingURL=index.d.ts.map