@founderroute/analytics 0.1.0-beta.1 → 1.0.0-rc.1

package/collection.js

@@ -0,0 +1,60 @@
+// Collection permission never renders UI or implies a visitor consented.
+export class CollectionState {
+  constructor({ mode, preferenceKey, storage, changed, error }) {
+    if (mode != null && !['automatic', 'consent'].includes(mode)) throw new Error('Invalid collection mode');
+    this.mode = mode ?? null;
+    this.permission = 'not_provided';
+    this.refused = false;
+    this.destroyed = false;
+    this.preferenceKey = preferenceKey;
+    this.storage = storage;
+    this.changed = changed;
+    this.error = error;
+    this.refresh();
+  }
+  get enabled() {
+    return !this.destroyed && !this.refused && (this.mode === 'automatic' || (this.mode === 'consent' && this.permission === 'granted'));
+  }
+  refresh() {
+    try { this.refused = this.storage()?.getItem(this.preferenceKey) === 'refused'; }
+    catch { this.error('preference_storage_unavailable'); }
+  }
+  saveRefusal(refused) {
+    this.refused = refused;
+    try {
+      const storage = this.storage();
+      if (!storage) throw new Error('Storage unavailable');
+      if (refused) storage.setItem(this.preferenceKey, 'refused');
+      else storage.removeItem(this.preferenceKey);
+    } catch { this.error('preference_storage_unavailable'); }
+  }
+  setMode(mode) {
+    if (!['automatic', 'consent'].includes(mode)) throw new Error('Invalid collection mode');
+    this.mode = mode;
+    this.changed();
+  }
+  setConsent(granted) {
+    this.permission = granted ? 'granted' : 'denied';
+    this.saveRefusal(!granted);
+    this.changed();
+  }
+  optOut() {
+    this.permission = 'denied';
+    this.saveRefusal(true);
+    this.changed();
+  }
+  optIn() {
+    this.saveRefusal(false);
+    if (this.permission === 'denied') this.permission = 'not_provided';
+    this.changed();
+  }
+  receiveRefusal() {
+    // Other tabs may stop this instance, but never grant permission on its behalf.
+    this.refused = true;
+    this.permission = 'denied';
+    this.changed();
+  }
+  metadata() {
+    return { collection_mode: this.mode, consent_state: this.permission === 'granted' ? 'granted' : 'not_provided' };
+  }
+}

package/index.d.ts

@@ -1,8 +1,12 @@
 export type Scalar = string | number | boolean | null;
-export type AnalyticsOptions = { key: string; endpoint: string; verificationId?: string; autoPage?: boolean; allowedProperties?: string[]; allowedTraits?: string[]; storage?: Pick<Storage,"getItem"|"setItem"|"removeItem">; fetch?: typeof fetch };
+export type AnalyticsOptions = { key: string; endpoint: string; propertyId?: string; environment?: "production" | "test"; collectionMode?: "automatic" | "consent"; verificationId?: string; autoPage?: boolean; allowedProperties?: string[]; allowedTraits?: string[]; storage?: Pick<Storage,"getItem"|"setItem"|"removeItem">; fetch?: typeof fetch };
 export class FounderRouteAnalytics {
   constructor(options: AnalyticsOptions);
+  readonly ready: Promise<void>;
   setConsent(granted: boolean): void;
+  optOut(): void;
+  optIn(): void;
+  setCollectionMode(mode: "automatic" | "consent"): void;
   identify(userId: string, options?: {token?: string;traits?: Record<string,Scalar>}): void;
   setAccount(accountId: string | null): void;
   track(name: string, properties?: Record<string,Scalar>, options?: {outcomeId?: string}): string | null;
@@ -12,7 +16,7 @@ export class FounderRouteAnalytics {
   flush(): Promise<void>;
   decorateLink(url:string,destinationPropertyId:string):Promise<string>;
   consumeHandoff(token:string):Promise<void>;
-  getDiagnostics(): {consent:boolean;queued:number;dropped:number;rejected:number;acknowledged:number;lastError:string|null;anonymousId:string|null};
+  getDiagnostics(): {collectionMode:"automatic"|"consent"|null;consentState:"not_provided"|"granted"|"denied";optedOut:boolean;collectionEnabled:boolean;consent:boolean;queued:number;dropped:number;rejected:number;acknowledged:number;lastError:string|null;anonymousId:string|null};
   destroy(): void;
 }
 export function init(options: AnalyticsOptions): FounderRouteAnalytics;

package/index.js

@@ -1,4 +1,5 @@
-const VERSION = "0.1.0-beta.1";
+import { CollectionState } from "./collection.js";
+const VERSION = "1.0.0-rc.1";
 const MAX_BYTES = 1024 * 1024;
 const MAX_EVENTS = 1000;
 const TTL = 86400000;
@@ -14,34 +15,81 @@ export class FounderRouteAnalytics {
   constructor(options) {
     if (!options?.key || !options?.endpoint) throw new Error("FounderRoute requires a public key and collector origin.");
     this.options = options; this.endpoint = options.endpoint.replace(/\/$/, "");
-    this.storageKey = `founderroute:${options.key}`; this.consent = false; this.queue = [];
+    this.configurationReady = false; this.storageKey = `founderroute:${options.key}`; this.collecting = false; this.queue = [];
     this.identity = null; this.session = null; this.user = null; this.account = null; this.token = null; this.traits = {};
     this.dropped = 0; this.rejected = 0; this.sent = 0; this.lastError = null; this.inFlight = null; this.retryAt = 0; this.failures = 0;
     this.generation = 0; this.cleanups = []; this.timer = null; this.lastInteraction = 0; this.lastTick = 0; this.lastPage = null;
+    this.collection = new CollectionState({
+      mode: null, preferenceKey: `founderroute:${options.key}:preference`,
+      storage: () => options.storage ?? globalThis.localStorage,
+      error: reason => { this.lastError = reason; }, changed: () => this.reconcileCollection(),
+    });
+    this.preferenceListener = event => {
+      if (event.key === this.collection.preferenceKey && event.newValue === 'refused') this.collection.receiveRefusal();
+    };
+    globalThis.addEventListener?.('storage', this.preferenceListener);
+    if (options.propertyId && ['production','test'].includes(options.environment) && options.collectionMode) {
+      this.configureCollection(options.propertyId, options.environment, options.collectionMode);
+      this.ready = Promise.resolve();
+    } else {
+      this.ready = this.resolveConfiguration();
+    }
   }
-  setConsent(granted) {
-    if (Boolean(granted) === this.consent) return;
-    this.consent = Boolean(granted); this.generation++;
-    if (!this.consent) {
-      this.controller?.abort(); clearInterval(this.timer); this.timer = null;
+  setConsent(granted) { this.collection.setConsent(Boolean(granted)); }
+  optOut() { this.collection.optOut(); }
+  optIn() { this.collection.optIn(); }
+  setCollectionMode(mode) { this.collection.setMode(mode); }
+  async resolveConfiguration() {
+    try {
+      const response = await (this.options.fetch ?? globalThis.fetch)(`${this.endpoint}/api/analytics/v2/config?key=${encodeURIComponent(this.options.key)}`);
+      if (!response.ok) throw new Error('Configuration unavailable');
+      const config = await response.json();
+      if (!config.property_id || !['production','test'].includes(config.environment) || !['automatic','consent'].includes(config.collection_mode)) throw new Error('Invalid configuration');
+      if (this.collection.destroyed) return;
+      this.configureCollection(config.property_id, config.environment, this.options.collectionMode ?? config.collection_mode);
+    } catch { this.lastError = 'configuration_unavailable'; }
+  }
+  configureCollection(propertyId, environment, mode) {
+    this.propertyId = propertyId; this.environment = environment;
+    this.storageKey = `founderroute:${propertyId}:${environment}:events`;
+    this.collection.preferenceKey = `founderroute:${propertyId}:${environment}:preference`;
+    const refusedHere = this.collection.refused;
+    this.collection.refresh();
+    if (refusedHere) this.collection.saveRefusal(true);
+    this.configurationReady = true;
+    this.collection.setMode(mode);
+  }
+  reconcileCollection() {
+    const granted = this.configurationReady && this.collection.enabled;
+    if (!granted && this.collection.refused) {
+      try { const storage = this.options.storage ?? globalThis.localStorage; storage?.removeItem(this.storageKey); storage?.removeItem(`founderroute:${this.options.key}`); }
+      catch { /* preference persistence reports storage failure separately */ }
+    }
+    if (granted === this.collecting) return;
+    this.collecting = granted; this.generation++;
+    if (!this.collecting) {
+      this.controller?.abort(); this.inFlight = null; clearInterval(this.timer); this.timer = null;
       for (const remove of this.cleanups.splice(0)) remove();
       this.queue = []; this.identity = null; this.session = null; this.user = null; this.token = null; this.account = null; this.traits = {}; this.lastPage = null;
-      try { this.options.storage?.removeItem(this.storageKey); if (!this.options.storage) globalThis.localStorage?.removeItem(this.storageKey); } catch { /* unavailable storage is not fatal */ }
+      try { const storage = this.options.storage ?? globalThis.localStorage; storage?.removeItem(this.storageKey); storage?.removeItem(`founderroute:${this.options.key}`); } catch { /* unavailable storage is not fatal */ }
       return;
     }
     try {
-      const stored = (this.options.storage ?? globalThis.localStorage)?.getItem(this.storageKey);
+      const storage = this.options.storage ?? globalThis.localStorage;
+      const stored = storage?.getItem(this.storageKey) ?? storage?.getItem(`founderroute:${this.options.key}`);
       if (stored) { const saved = JSON.parse(stored); this.queue = Array.isArray(saved.queue) ? saved.queue : []; this.identity = saved.identity; }
     } catch { this.queue = []; }
     this.identity ||= uuid(); this.lastInteraction = Date.now(); this.lastTick = Date.now();
-    this.prune(); this.persist(); this.attach();
+    this.prune(); this.persist();
+    try { const storage = this.options.storage ?? globalThis.localStorage; if (storage?.getItem(this.storageKey)) storage.removeItem(`founderroute:${this.options.key}`); } catch { /* keep legacy delivery if migration did not persist */ }
+    this.attach();
     this.timer = setInterval(() => { this.engagement(); void this.flush(); }, 15000);
     this.timer?.unref?.();
     if (this.options.autoPage !== false && globalThis.location) this.page();
     void this.flush();
   }
   persist() {
-    if (!this.consent) return;
+    if (!this.collecting) return;
     try { (this.options.storage ?? globalThis.localStorage)?.setItem(this.storageKey, JSON.stringify({ identity:this.identity,queue:this.queue })); }
     catch { this.lastError = "storage_unavailable"; }
   }
@@ -52,14 +100,14 @@ export class FounderRouteAnalytics {
     while (this.queue.length>MAX_EVENTS || encoder.encode(JSON.stringify(this.queue)).length>MAX_BYTES) { this.queue.shift(); this.dropped++; }
   }
   event(name, properties = {}, extra = {}) {
-    if (!this.consent) return null;
+    if (!this.collecting) return null;
     const now = Date.now();
     if (!this.session || now-this.session.last >= 1800000) this.session = { id:uuid(),last:now };
     this.session.last = now;
     const event = {
-      event_id:uuid(),protocol:1,name,kind:extra.kind ?? "custom",occurred_at:new Date(now).toISOString(),anonymous_id:this.identity,
+      event_id:uuid(),protocol:2,name,kind:extra.kind ?? "custom",occurred_at:new Date(now).toISOString(),anonymous_id:this.identity,
       ...(this.user ? {user_id:this.user} : {}),...(this.token ? {identity_token:this.token} : {}),...(this.account ? {account_id:this.account} : {}),
-      session_id:this.session.id,consent:true,properties:clean(properties,this.options.allowedProperties),traits:clean(this.traits,this.options.allowedTraits),
+      session_id:this.session.id,...this.collection.metadata(),properties:clean(properties,this.options.allowedProperties),traits:clean(this.traits,this.options.allowedTraits),
       context:{sdk:"browser",sdk_version:VERSION,...(this.options.verificationId?{verification_id:this.options.verificationId}:{}),...this.campaignContext(),...extra.context},...(extra.outcomeId ? {outcome_id:extra.outcomeId} : {}),
     };
     if (encoder.encode(JSON.stringify(event)).length>8192) { this.rejected++; this.lastError="event_too_large"; return null; }
@@ -67,7 +115,7 @@ export class FounderRouteAnalytics {
   }
   track(name, properties = {}, options = {}) { return this.event(name,properties,{outcomeId:options.outcomeId}); }
   page(path) {
-    if (!this.consent) return null;
+    if (!this.collecting) return null;
     const route = normalizePath(path ?? globalThis.location?.pathname ?? "/");
     if (route === this.lastPage) return null;
     this.engagement(); this.lastPage=route;
@@ -75,14 +123,14 @@ export class FounderRouteAnalytics {
   }
   screen(name) { return this.event("screen_view",{},{kind:"screen",context:{screen:String(name).slice(0,150)}}); }
   identify(userId, { token, traits = {} } = {}) {
-    if (!this.consent || !userId) return;
+    if (!this.collecting || !userId) return;
     if (this.user && this.user !== String(userId)) this.reset();
     this.user=String(userId); this.token=token; this.traits={...traits};
     this.event("fr_identify",{},{kind:"identify"});
   }
-  setAccount(accountId) { if (this.consent) this.account=accountId ? String(accountId) : null; }
+  setAccount(accountId) { if (this.collecting) this.account=accountId ? String(accountId) : null; }
   reset() {
-    if (!this.consent) return;
+    if (!this.collecting) return;
     this.engagement(); this.user=null; this.token=null; this.account=null; this.traits={}; this.identity=uuid(); this.session=null; this.lastPage=null; this.persist();
   }
   campaignContext() {
@@ -95,7 +143,7 @@ export class FounderRouteAnalytics {
     return result;
   }
   engagement() {
-    if (!this.consent) return;
+    if (!this.collecting) return;
     const now=Date.now(); const elapsed=Math.min(15000,Math.max(0,now-this.lastTick)); this.lastTick=now;
     if (globalThis.document?.visibilityState === "hidden" || now-this.lastInteraction>60000 || !elapsed) return;
     this.event("fr_session",{},{kind:"session",context:{active_ms:elapsed,path:this.lastPage??"/"}});
@@ -124,44 +172,52 @@ export class FounderRouteAnalytics {
     return events;
   }
   beacon() {
-    if(!this.consent||!globalThis.navigator?.sendBeacon) return;
+    if(!this.collecting||!globalThis.navigator?.sendBeacon) return;
     const events=this.batch(); if(!events.length)return;
-    try { navigator.sendBeacon(`${this.endpoint}/api/analytics/v1/collect`,new Blob([JSON.stringify({key:this.options.key,events})],{type:"text/plain"})); }
+    try { navigator.sendBeacon(`${this.endpoint}/api/analytics/v2/collect`,new Blob([JSON.stringify({key:this.options.key,events})],{type:"text/plain"})); }
     catch { /* retained until acknowledged by fetch */ }
   }
   async flush() {
-    if(!this.consent||Date.now()<this.retryAt) return;
+    if(!this.collecting||Date.now()<this.retryAt) return;
     if(this.inFlight)return this.inFlight;
     const generation=this.generation; const events=this.batch(); if(!events.length)return;
     this.controller=new AbortController();
+    const delivery = {}; this.delivery = delivery;
     this.inFlight=(async()=>{
       try {
-        const response=await (this.options.fetch??globalThis.fetch)(`${this.endpoint}/api/analytics/v1/collect`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({key:this.options.key,events}),signal:this.controller.signal});
-        if(!this.consent||this.generation!==generation)return;
+        const response=await (this.options.fetch??globalThis.fetch)(`${this.endpoint}/api/analytics/v2/collect`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({key:this.options.key,events}),signal:this.controller.signal});
+        if(!this.collecting||this.generation!==generation)return;
         if(response.status===429||response.status>=500){this.failures++;this.retryAt=Date.now()+Math.max(Number(response.headers.get("Retry-After")??0)*1000,Math.min(300000,1000*2**Math.min(this.failures,8)));this.lastError=`delivery_${response.status}`;return;}
         const result=await response.json();
+        if(!this.collecting||this.generation!==generation)return;
         if(!response.ok){this.lastError=result.error??"delivery_rejected";this.retryAt=Date.now()+300000;if([400,401,403,413].includes(response.status)){const ids=new Set(events.map(e=>e.event_id));this.queue=this.queue.filter(e=>!ids.has(e.event_id));this.rejected+=ids.size;}return;}
         const acknowledged=new Set();
         for(const receipt of result.results??[]){if(["accepted","duplicate","rejected"].includes(receipt.status))acknowledged.add(receipt.event_id);if(receipt.status==="rejected"){this.rejected++;this.lastError=receipt.reason;}else this.sent++;}
         this.queue=this.queue.filter(e=>!acknowledged.has(e.event_id));this.failures=0;this.retryAt=0;
-      }catch(error){if(error?.name!=="AbortError"){this.lastError="network_unavailable";this.failures++;this.retryAt=Date.now()+Math.min(300000,1000*2**Math.min(this.failures,8));}}
-      finally{if(this.consent&&this.generation===generation)this.persist();this.inFlight=null;}
+      }catch(error){if(this.collecting&&this.generation===generation&&error?.name!=="AbortError"){this.lastError="network_unavailable";this.failures++;this.retryAt=Date.now()+Math.min(300000,1000*2**Math.min(this.failures,8));}}
+      finally{if(this.collecting&&this.generation===generation)this.persist();if(this.delivery===delivery)this.inFlight=null;}
     })();
     return this.inFlight;
   }
   async decorateLink(url,destinationPropertyId) {
-    if(!this.consent)return url;
+    if(!this.collecting)return url;
     const destination=new URL(url,globalThis.location?.href);if(!["http:","https:"].includes(destination.protocol)||destination.username||destination.password)return url;
-    const response=await (this.options.fetch??fetch)(`${this.endpoint}/api/analytics/v1/link`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({consent:true,key:this.options.key,anonymousId:this.identity,destinationPropertyId,destinationUrl:destination.origin})});
+    const response=await (this.options.fetch??fetch)(`${this.endpoint}/api/analytics/v2/link`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({...this.collection.metadata(),key:this.options.key,anonymousId:this.identity,destinationPropertyId,destinationUrl:destination.origin})});
     if(!response.ok)return url;
     const {token}=await response.json();destination.searchParams.set("fr_handoff",token);return destination.toString();
   }
   async consumeHandoff(token) {
-    if(!this.consent)return;
-    await (this.options.fetch??fetch)(`${this.endpoint}/api/analytics/v1/link`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({consent:true,key:this.options.key,anonymousId:this.identity,token})});
+    if(!this.collecting)return;
+    await (this.options.fetch??fetch)(`${this.endpoint}/api/analytics/v2/link`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({...this.collection.metadata(),key:this.options.key,anonymousId:this.identity,token})});
+  }
+  getDiagnostics(){return {collectionMode:this.collection.mode,consentState:this.collection.permission,optedOut:this.collection.refused,collectionEnabled:this.collecting,consent:this.collection.permission==='granted',queued:this.queue.length,dropped:this.dropped,rejected:this.rejected,acknowledged:this.sent,lastError:this.lastError,anonymousId:this.collecting?this.identity:null};}
+  destroy(){
+    this.persist(); this.collection.destroyed = true; this.collecting = false; this.generation++;
+    this.controller?.abort(); clearInterval(this.timer); this.timer = null;
+    for (const remove of this.cleanups.splice(0)) remove();
+    globalThis.removeEventListener?.('storage', this.preferenceListener);
+    if (instances.get(this.options.key) === this) instances.delete(this.options.key);
   }
-  getDiagnostics(){return {consent:this.consent,queued:this.queue.length,dropped:this.dropped,rejected:this.rejected,acknowledged:this.sent,lastError:this.lastError,anonymousId:this.consent?this.identity:null};}
-  destroy(){this.setConsent(false);}
 }
 
 const instances=new Map();

package/next.d.ts

@@ -0,0 +1,2 @@
+import type {FounderRouteAnalytics} from './index.js';
+export function FounderRoutePageViews(props:{client:FounderRouteAnalytics}):null;

package/package.json

@@ -1,17 +1,53 @@
 {
   "name": "@founderroute/analytics",
-  "version": "0.1.0-beta.1",
-  "description": "Consent-first FounderRoute analytics for browsers, React, and Next.js",
+  "version": "1.0.0-rc.1",
+  "description": "FounderRoute analytics for browsers, React, and Next.js",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
-  "exports": { ".": { "types": "./index.d.ts", "default": "./index.js" }, "./react": "./react.js", "./next": "./next.js" },
-  "files": ["*.js", "*.d.ts", "LICENSE"],
-  "peerDependencies": { "react": ">=18 <20", "next": ">=15 <17" },
-  "peerDependenciesMeta": { "react": { "optional": true }, "next": { "optional": true } },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./react.js"
+    },
+    "./next": {
+      "types": "./next.d.ts",
+      "default": "./next.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18 <20",
+    "next": ">=15 <17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/itsreed/founderroute-analytics.git", "directory": "packages/browser" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsreed/founderroute-analytics.git",
+    "directory": "packages/browser"
+  },
   "homepage": "https://github.com/itsreed/founderroute-analytics#readme",
-  "bugs": { "url": "https://github.com/itsreed/founderroute-analytics/issues" },
-  "publishConfig": { "access": "public", "provenance": true }
+  "bugs": {
+    "url": "https://github.com/itsreed/founderroute-analytics/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
 }

package/react.d.ts

@@ -0,0 +1,3 @@
+import type {FounderRouteAnalytics} from './index.js';
+/** Applies the customer application's actual permission decision. Renders nothing. */
+export function useFounderRouteConsent(client:FounderRouteAnalytics,granted:boolean):void;

package/react.js

@@ -1,3 +1,6 @@
 "use client";
 import { useEffect } from "react";
-export function FounderRouteConsent({ client, granted, children }) { useEffect(()=>{client.setConsent(granted);},[client,granted]);return children??null; }
+// Integrates an application-owned permission decision without rendering anything.
+export function useFounderRouteConsent(client, granted) {
+  useEffect(() => { client.setConsent(granted); }, [client, granted]);
+}