@hifilabs/pixel 0.7.1 → 0.9.0

package/dist/browser.js

@@ -8,7 +8,7 @@ var BalancePixel = (() => {
 
   // src/browser.ts
   (function() {
-    const PIXEL_VERSION = "0.7.0";
+    const PIXEL_VERSION = "0.9.0";
     function parseUserAgent(ua) {
       let device_type = "desktop";
       if (/ipad|tablet|android(?!.*mobile)/i.test(ua))
@@ -74,6 +74,9 @@ var BalancePixel = (() => {
     const consentStyle = currentScript?.dataset.consentStyle || "brutalist";
     const consentPrimaryColor = currentScript?.dataset.primaryColor;
     const consentBannerPosition = currentScript?.dataset.bannerPosition || "bottom";
+    const excludePatterns = currentScript?.dataset.excludePages?.split(",").filter(Boolean) || [];
+    const trackFileDownloads = currentScript?.dataset.trackFileDownloads === "true";
+    const hashRoutingEnabled = currentScript?.dataset.hashRouting === "true";
     function detectTrackingSource() {
       if (explicitSource)
         return explicitSource;
@@ -99,7 +102,88 @@ var BalancePixel = (() => {
     const CONSENT_REFRESH_THRESHOLD = 30 * 24 * 60 * 60 * 1e3;
     const SESSION_DURATION = 60 * 60 * 1e3;
     const STORAGE_PREFIX = "balance_";
-    const API_ENDPOINT = customEndpoint ? customEndpoint : useEmulator ? `http://localhost:5001/artist-os-distro/us-central1/ingestEvents` : `https://us-central1-artist-os-distro.cloudfunctions.net/ingestEvents`;
+    function globToRegex(pattern) {
+      const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+      return new RegExp("^" + escaped + "$");
+    }
+    function isExcludedPage(url) {
+      if (excludePatterns.length === 0)
+        return false;
+      try {
+        const pathname = new URL(url, window.location.origin).pathname;
+        return excludePatterns.some((pattern) => {
+          const regex = globToRegex(pattern);
+          return regex.test(pathname);
+        });
+      } catch {
+        return false;
+      }
+    }
+    const DOWNLOAD_EXTENSIONS = [
+      ".pdf",
+      ".zip",
+      ".tar",
+      ".gz",
+      ".rar",
+      ".7z",
+      ".doc",
+      ".docx",
+      ".xls",
+      ".xlsx",
+      ".ppt",
+      ".pptx",
+      ".mp3",
+      ".wav",
+      ".flac",
+      ".aac",
+      ".ogg",
+      ".mp4",
+      ".mov",
+      ".avi",
+      ".mkv",
+      ".webm",
+      ".exe",
+      ".dmg",
+      ".pkg",
+      ".deb",
+      ".rpm",
+      ".csv",
+      ".json",
+      ".xml",
+      ".txt"
+    ];
+    function isFileDownload(url) {
+      try {
+        const pathname = new URL(url, window.location.origin).pathname.toLowerCase();
+        return DOWNLOAD_EXTENSIONS.some((ext) => pathname.endsWith(ext));
+      } catch {
+        return false;
+      }
+    }
+    function trackFileDownload(url, element) {
+      try {
+        const pathname = new URL(url, window.location.origin).pathname;
+        const fileName = pathname.split("/").pop() || "unknown";
+        const fileExtension = fileName.includes(".") ? fileName.split(".").pop() : "unknown";
+        log("File download tracked:", { url, fileName, fileExtension });
+        const event = buildEvent({
+          event_name: "custom",
+          metadata: {
+            event_type: "file_download",
+            file_url: url,
+            file_name: fileName,
+            file_extension: fileExtension,
+            link_text: element?.textContent?.trim().substring(0, 100) || ""
+          }
+        });
+        enqueueEvent(event);
+      } catch (e) {
+        logError("Failed to track file download:", e);
+      }
+    }
+    const PIXEL_PROXY_URL = "https://balance-pixel-proxy.jassin.workers.dev";
+    const FIREBASE_DIRECT_URL = "https://us-central1-artist-os-distro.cloudfunctions.net/ingestEvents";
+    const API_ENDPOINT = customEndpoint ? customEndpoint : useEmulator ? `http://localhost:5001/artist-os-distro/us-central1/ingestEvents` : PIXEL_PROXY_URL;
     let sessionId = null;
     let visitorId = null;
     let fanIdHash = null;
@@ -582,7 +666,23 @@ var BalancePixel = (() => {
         }
         log("Events sent successfully");
       } catch (error) {
-        logError(" Failed to send events:", error);
+        logError(" Failed to send events, trying fallback:", error);
+        if (API_ENDPOINT !== FIREBASE_DIRECT_URL && !useEmulator) {
+          try {
+            const fallbackResponse = await fetch(FIREBASE_DIRECT_URL, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ events }),
+              keepalive: true
+            });
+            if (fallbackResponse.ok) {
+              log("Events sent via fallback (no geo)");
+              return;
+            }
+          } catch (fallbackError) {
+            logError(" Fallback also failed:", fallbackError);
+          }
+        }
         if (eventQueue.length < 50) {
           eventQueue.push(...events);
         }
@@ -677,10 +777,15 @@ var BalancePixel = (() => {
       }
     }
     function trackPageView(options = {}) {
+      const pageUrl = options.url || window.location.href;
+      if (isExcludedPage(pageUrl)) {
+        log("Page excluded from tracking:", pageUrl);
+        return;
+      }
       const event = buildEvent({
         event_name: "pageview",
         page_title: options.title || document.title,
-        source_url: options.url || window.location.href
+        source_url: pageUrl
       });
       enqueueEvent(event);
     }
@@ -798,6 +903,119 @@ var BalancePixel = (() => {
       ["mousemove", "keydown", "scroll", "touchstart"].forEach((eventType) => {
         document.addEventListener(eventType, resetIdleTimer, { passive: true });
       });
+      const currentHost = window.location.hostname;
+      function detectPlatform(url) {
+        try {
+          const hostname = new URL(url).hostname.toLowerCase();
+          if (hostname.includes("spotify"))
+            return "spotify";
+          if (hostname.includes("apple") || hostname.includes("music.apple"))
+            return "apple_music";
+          if (hostname.includes("youtube") || hostname.includes("youtu.be"))
+            return "youtube";
+          if (hostname.includes("soundcloud"))
+            return "soundcloud";
+          if (hostname.includes("tidal"))
+            return "tidal";
+          if (hostname.includes("deezer"))
+            return "deezer";
+          if (hostname.includes("amazon") || hostname.includes("music.amazon"))
+            return "amazon_music";
+          if (hostname.includes("bandcamp"))
+            return "bandcamp";
+          if (hostname.includes("lnk.to") || hostname.includes("linkfire"))
+            return "linkfire";
+          if (hostname.includes("linktr.ee"))
+            return "linktree";
+          if (hostname.includes("shop") || hostname.includes("store") || hostname.includes("merch"))
+            return "shop";
+          if (hostname.includes("ticketmaster") || hostname.includes("eventbrite") || hostname.includes("dice.fm"))
+            return "tickets";
+          if (hostname.includes("instagram"))
+            return "instagram";
+          if (hostname.includes("twitter") || hostname.includes("x.com"))
+            return "twitter";
+          if (hostname.includes("tiktok"))
+            return "tiktok";
+          if (hostname.includes("facebook"))
+            return "facebook";
+          return "external";
+        } catch {
+          return "external";
+        }
+      }
+      function isExternalLink(url) {
+        try {
+          const linkHost = new URL(url, window.location.origin).hostname;
+          return linkHost !== currentHost;
+        } catch {
+          return false;
+        }
+      }
+      function trackExternalClick(url, element) {
+        const platform = detectPlatform(url);
+        const linkText = element?.textContent?.trim().substring(0, 100) || "";
+        const linkId = element?.id || element?.getAttribute("data-link-id") || void 0;
+        log("External link clicked:", { url, platform, linkText });
+        track("page_link_click", {
+          link_url: url,
+          link_text: linkText,
+          link_id: linkId,
+          platform,
+          link_type: "external"
+        });
+      }
+      const originalWindowOpen = window.open;
+      window.open = function(url, target, features) {
+        if (url) {
+          const urlString = url.toString();
+          if (isExternalLink(urlString)) {
+            trackExternalClick(urlString);
+          }
+        }
+        return originalWindowOpen.call(window, url, target, features);
+      };
+      log("window.open interception enabled (always on)");
+      const autoTrackLinks = currentScript?.dataset.autoTrackLinks === "true";
+      if (autoTrackLinks) {
+        document.addEventListener("click", (e) => {
+          const target = e.target;
+          const anchor = target.closest("a");
+          if (anchor && anchor.href && isExternalLink(anchor.href)) {
+            if (trackFileDownloads && (isFileDownload(anchor.href) || anchor.hasAttribute("download"))) {
+              return;
+            }
+            trackExternalClick(anchor.href, anchor);
+          }
+        }, { capture: true, passive: true });
+        log("External link click listener enabled (opt-in)");
+      }
+      if (trackFileDownloads) {
+        document.addEventListener("click", (e) => {
+          const target = e.target;
+          const anchor = target.closest("a");
+          if (anchor?.href && (isFileDownload(anchor.href) || anchor.hasAttribute("download"))) {
+            trackFileDownload(anchor.href, anchor);
+          }
+        }, { capture: true, passive: true });
+        log("File download tracking enabled");
+      }
+      if (hashRoutingEnabled) {
+        let lastUrl = window.location.href;
+        window.addEventListener("hashchange", () => {
+          const newUrl = window.location.href;
+          if (newUrl !== lastUrl) {
+            lastUrl = newUrl;
+            setTimeout(() => {
+              trackPageView({
+                title: document.title,
+                url: newUrl
+              });
+            }, 0);
+          }
+        });
+        log("Hash routing tracking enabled");
+      }
       window.addEventListener("beforeunload", () => {
         stopHeartbeat();
         flush();

package/dist/browser.min.js

@@ -1,4 +1,4 @@
-var BalancePixel=(()=>{var ze=Object.defineProperty;var Ve=(l,d,c)=>d in l?ze(l,d,{enumerable:!0,configurable:!0,writable:!0,value:c}):l[d]=c;var A=(l,d,c)=>(Ve(l,typeof d!="symbol"?d+"":d,c),c);(function(){let l="0.7.0";function d(e){let t="desktop";/ipad|tablet|android(?!.*mobile)/i.test(e)?t="tablet":/mobile|iphone|android.*mobile|blackberry|iemobile/i.test(e)&&(t="mobile");let n="Unknown";/edg/i.test(e)?n="Edge":/opr|opera/i.test(e)?n="Opera":/firefox/i.test(e)?n="Firefox":/chrome/i.test(e)?n="Chrome":/safari/i.test(e)&&(n="Safari");let o="Unknown";return/iphone|ipad/i.test(e)?o="iOS":/android/i.test(e)?o="Android":/windows/i.test(e)?o="Windows":/mac os/i.test(e)?o="macOS":/linux/i.test(e)?o="Linux":/cros/i.test(e)&&(o="ChromeOS"),{device_type:t,browser:n,os:o}}let c=null;function be(){if(!c)try{c=d(navigator.userAgent)}catch{c={device_type:"desktop",browser:"Unknown",os:"Unknown"}}return c}let a=document.currentScript,O=a?.dataset.artistId,N=a?.dataset.projectId,L=N?he(N):void 0;function he(e){return!e||e.startsWith("release_")||e.startsWith("merch_")||e.startsWith("link_")||e.startsWith("custom_")?e:`custom_${e}`}let K=a?.dataset.emulator==="true",Y=a?.dataset.debug==="true",R=parseInt(a?.dataset.heartbeatInterval||"30000",10),J=a?.dataset.heartbeat!=="false",G=a?.dataset.source,Q=a?.dataset.endpoint,U=a?.dataset.consentUi==="true",ye=a?.dataset.consentStyle||"brutalist",ve=a?.dataset.primaryColor,we=a?.dataset.bannerPosition||"bottom";function Ie(){if(G)return G;let e=typeof window.dataLayer<"u"&&Array.isArray(window.dataLayer),t=typeof window.gtag=="function";return e&&t?"gtm":"pixel"}let k="pixel";if(!O){x(" Error: data-artist-id attribute is required");return}let X="session_id",M="session_timestamp",Z="attribution",ee="fan_id_hash",F="visitor_id",C="balance_consent",xe=365*24*60*60*1e3,Se=30*24*60*60*1e3,_e=60*60*1e3,p="balance_",H=Q||(K?"http://localhost:5001/artist-os-distro/us-central1/ingestEvents":"https://us-central1-artist-os-distro.cloudfunctions.net/ingestEvents"),E=null,s=null,u=null,i=null,m={},f=[],j=null,g="session",b=null,ke=0,B=0,h=0,w=!0,Ce=2*60*1e3,te=Date.now(),I=!1,Ee=!Y,r=(...e)=>{Y&&console.log("[BLN]",...e)},x=(...e)=>{Ee||console.error("[BLN]",...e)},$={base:`
+var BalancePixel=(()=>{var it=Object.defineProperty;var rt=(g,p,u)=>p in g?it(g,p,{enumerable:!0,configurable:!0,writable:!0,value:u}):g[p]=u;var F=(g,p,u)=>(rt(g,typeof p!="symbol"?p+"":p,u),u);(function(){let g="0.9.0";function p(e){let t="desktop";/ipad|tablet|android(?!.*mobile)/i.test(e)?t="tablet":/mobile|iphone|android.*mobile|blackberry|iemobile/i.test(e)&&(t="mobile");let n="Unknown";/edg/i.test(e)?n="Edge":/opr|opera/i.test(e)?n="Opera":/firefox/i.test(e)?n="Firefox":/chrome/i.test(e)?n="Chrome":/safari/i.test(e)&&(n="Safari");let r="Unknown";return/iphone|ipad/i.test(e)?r="iOS":/android/i.test(e)?r="Android":/windows/i.test(e)?r="Windows":/mac os/i.test(e)?r="macOS":/linux/i.test(e)?r="Linux":/cros/i.test(e)&&(r="ChromeOS"),{device_type:t,browser:n,os:r}}let u=null;function Ie(){if(!u)try{u=p(navigator.userAgent)}catch{u={device_type:"desktop",browser:"Unknown",os:"Unknown"}}return u}let l=document.currentScript,H=l?.dataset.artistId,M=l?.dataset.projectId,z=M?Se(M):void 0;function Se(e){return!e||e.startsWith("release_")||e.startsWith("merch_")||e.startsWith("link_")||e.startsWith("custom_")?e:`custom_${e}`}let j=l?.dataset.emulator==="true",ee=l?.dataset.debug==="true",$=parseInt(l?.dataset.heartbeatInterval||"30000",10),te=l?.dataset.heartbeat!=="false",ne=l?.dataset.source,ie=l?.dataset.endpoint,B=l?.dataset.consentUi==="true",Ee=l?.dataset.consentStyle||"brutalist",Ce=l?.dataset.primaryColor,Te=l?.dataset.bannerPosition||"bottom",re=l?.dataset.excludePages?.split(",").filter(Boolean)||[],oe=l?.dataset.trackFileDownloads==="true",Le=l?.dataset.hashRouting==="true";function De(){if(ne)return ne;let e=typeof window.dataLayer<"u"&&Array.isArray(window.dataLayer),t=typeof window.gtag=="function";return e&&t?"gtm":"pixel"}let P="pixel";if(!H){w(" Error: data-artist-id attribute is required");return}let ae="session_id",W="session_timestamp",se="attribution",ce="fan_id_hash",V="visitor_id",R="balance_consent",Pe=365*24*60*60*1e3,Re=30*24*60*60*1e3,Oe=60*60*1e3,x="balance_";function Ae(e){let t=e.replace(/[.+?^${}()|[\]\\]/g,"\\$&").replace(/\*/g,".*");return new RegExp("^"+t+"$")}function Ne(e){if(re.length===0)return!1;try{let t=new URL(e,window.location.origin).pathname;return re.some(n=>Ae(n).test(t))}catch{return!1}}let Ue=[".pdf",".zip",".tar",".gz",".rar",".7z",".doc",".docx",".xls",".xlsx",".ppt",".pptx",".mp3",".wav",".flac",".aac",".ogg",".mp4",".mov",".avi",".mkv",".webm",".exe",".dmg",".pkg",".deb",".rpm",".csv",".json",".xml",".txt"];function le(e){try{let t=new URL(e,window.location.origin).pathname.toLowerCase();return Ue.some(n=>t.endsWith(n))}catch{return!1}}function Fe(e,t){try{let r=new URL(e,window.location.origin).pathname.split("/").pop()||"unknown",f=r.includes(".")?r.split(".").pop():"unknown";i("File download tracked:",{url:e,fileName:r,fileExtension:f});let L=y({event_name:"custom",metadata:{event_type:"file_download",file_url:e,file_name:r,file_extension:f,link_text:t?.textContent?.trim().substring(0,100)||""}});v(L)}catch(n){w("Failed to track file download:",n)}}let He="https://balance-pixel-proxy.jassin.workers.dev",de="https://us-central1-artist-os-distro.cloudfunctions.net/ingestEvents",O=ie||(j?"http://localhost:5001/artist-os-distro/us-central1/ingestEvents":He),A=null,d=null,m=null,s=null,k={},h=[],q=null,b="session",_=null,Me=0,K=0,I=0,S=!0,ze=2*60*1e3,ue=Date.now(),E=!1,je=!ee,i=(...e)=>{ee&&console.log("[BLN]",...e)},w=(...e)=>{je||console.error("[BLN]",...e)},Y={base:`
       :host {
         font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
         position: fixed;
@@ -83,12 +83,12 @@ var BalancePixel=(()=>{var ze=Object.defineProperty;var Ve=(l,d,c)=>d in l?ze(l,
       }
       .btn.accept { background: #fff; color: #000; border-color: #fff; }
       .btn:hover { opacity: 0.8; }
-    `};class Te{constructor(t){A(this,"container",null);A(this,"shadow",null);A(this,"config");if(this.config=t,this.hasStoredConsent()){r("ConsentManager: Consent already exists, not showing banner");return}this.container=document.createElement("div"),this.container.id="balance-consent-manager",this.shadow=this.container.attachShadow({mode:"closed"}),this.render(),document.body.appendChild(this.container),r("ConsentManager: Banner rendered")}hasStoredConsent(){try{return window._balanceConsentNeedsRefresh?!1:localStorage.getItem(C)!==null}catch{return!1}}render(){if(!this.shadow)return;let t=this.config.style||"brutalist",n=$.base,o=$[t]||$.brutalist,_=this.config.position==="top"?"top: 0;":"bottom: 0;",me=this.config.primaryColor?`.btn.accept { background: ${this.config.primaryColor} !important; border-color: ${this.config.primaryColor} !important; color: #fff !important; }`:"";this.shadow.innerHTML=`
+    `};class $e{constructor(t){F(this,"container",null);F(this,"shadow",null);F(this,"config");if(this.config=t,this.hasStoredConsent()){i("ConsentManager: Consent already exists, not showing banner");return}this.container=document.createElement("div"),this.container.id="balance-consent-manager",this.shadow=this.container.attachShadow({mode:"closed"}),this.render(),document.body.appendChild(this.container),i("ConsentManager: Banner rendered")}hasStoredConsent(){try{return window._balanceConsentNeedsRefresh?!1:localStorage.getItem(R)!==null}catch{return!1}}render(){if(!this.shadow)return;let t=this.config.style||"brutalist",n=Y.base,r=Y[t]||Y.brutalist,f=this.config.position==="top"?"top: 0;":"bottom: 0;",L=this.config.primaryColor?`.btn.accept { background: ${this.config.primaryColor} !important; border-color: ${this.config.primaryColor} !important; color: #fff !important; }`:"";this.shadow.innerHTML=`
         <style>
           ${n}
-          :host { ${_} }
-          ${o}
-          ${me}
+          :host { ${f} }
+          ${r}
+          ${L}
         </style>
         <div class="banner" role="dialog" aria-label="Cookie consent" aria-modal="false">
           <p class="text">
@@ -99,4 +99,4 @@ var BalancePixel=(()=>{var ze=Object.defineProperty;var Ve=(l,d,c)=>d in l?ze(l,
             <button id="accept" class="btn accept">Accept</button>
           </div>
         </div>
-      `,this.shadow.getElementById("accept")?.addEventListener("click",()=>this.handleConsent(!0)),this.shadow.getElementById("decline")?.addEventListener("click",()=>this.handleConsent(!1))}handleConsent(t){window.balance?.setConsent&&window.balance.setConsent({analytics:t,marketing:t,personalization:t,timestamp:new Date().toISOString()}),t&&!window._balanceInitialPageviewFired&&(window._balanceInitialPageviewFired=!0,window.balance?.page&&window.balance.page(),W(),r("Initial pageview fired after consent granted")),this.remove()}remove(){this.container&&(this.container.remove(),this.container=null,this.shadow=null,r("ConsentManager: Banner removed"))}}function ne(){try{return g==="local"?localStorage:sessionStorage}catch{return null}}function T(e){let t=ne();if(!t)return null;try{let n=p+e,o=t.getItem(n);if(!o&&g==="session")try{o=localStorage.getItem(n)}catch{}return o}catch{return null}}function S(e,t){let n=ne();if(n)try{n.setItem(p+e,t)}catch{}}function re(){if(g!=="local"){r("Upgrading storage tier: session -> local");try{let e=[];for(let t=0;t<sessionStorage.length;t++){let n=sessionStorage.key(t);n?.startsWith(p)&&e.push(n)}for(let t of e){let n=sessionStorage.getItem(t);n&&localStorage.setItem(t,n)}for(let t of e)sessionStorage.removeItem(t);g="local",r(`Storage tier upgraded, migrated ${e.length} items`)}catch(e){x(" Storage migration failed:",e)}}}function z(){return crypto&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,e=>{let t=Math.random()*16|0;return(e==="x"?t:t&3|8).toString(16)})}function De(){try{let e=T(X),t=T(M);if(e&&t&&Date.now()-parseInt(t,10)<_e)return S(M,Date.now().toString()),e;let n=z();return S(X,n),S(M,Date.now().toString()),n}catch{return z()}}function Pe(){let e=new URLSearchParams(window.location.search),t={};return["source","medium","campaign","content","term"].forEach(n=>{let o=e.get(`utm_${n}`);o&&(t[`utm_${n}`]=o)}),t}function Ae(){try{let e=T(Z);if(e){m=JSON.parse(e),r("Loaded attribution:",m);return}let t=Pe();Object.keys(t).length>0&&(m=t,S(Z,JSON.stringify(t)),r("Captured attribution:",m))}catch{}}function Oe(){try{u=T(ee)}catch{}}function oe(){if(!i?.analytics)return null;try{let e=localStorage.getItem(p+F);if(e)return e;let t=z();return localStorage.setItem(p+F,t),r("Created persistent visitor ID:",t.substring(0,8)+"..."),t}catch{return null}}function Ne(){if(!i?.analytics){s=null;return}try{s=localStorage.getItem(p+F),s&&r("Loaded visitor ID:",s.substring(0,8)+"...")}catch{}}function Le(){try{let e=localStorage.getItem(C);if(e){let t=JSON.parse(e);if(t.expiresAt&&Date.now()>t.expiresAt){r("Consent expired - clearing stored consent"),localStorage.removeItem(C),i=null;return}if(t.expiresAt){let n=t.expiresAt-Date.now();n>0&&n<Se&&(r("Consent nearing expiration - will prompt for refresh"),window._balanceConsentNeedsRefresh=!0)}i=t.preferences||null,r("Loaded consent:",i)}}catch{}}function ie(e){let t=i;i=e;try{let o={preferences:e,method:"explicit",version:1,expiresAt:Date.now()+xe};localStorage.setItem(C,JSON.stringify(o)),r("Consent saved with TTL:",e),window._balanceConsentNeedsRefresh=!1}catch(o){x(" Could not save consent:",o)}e.analytics===!0&&(re(),s||(s=oe()));let n=y({event_name:"consent_updated",metadata:{consent_preferences:e,consent_method:"explicit",previous_consent:t||void 0}});v(n);try{window.dispatchEvent(new CustomEvent("balance:consent:updated",{detail:e})),r("DOM event balance:consent:updated dispatched")}catch{}}function Re(){return i}function Ue(e){return i?.[e]===!0}async function Me(e){let t=e.toLowerCase().trim(),o=new TextEncoder().encode(t),_=await crypto.subtle.digest("SHA-256",o);return Array.from(new Uint8Array(_)).map($e=>$e.toString(16).padStart(2,"0")).join("")}function y(e){let t=be(),n={artist_id:O,fan_session_id:E,visitor_id:s||void 0,fan_id_hash:u||void 0,timestamp:new Date().toISOString(),source_url:window.location.href,referrer_url:document.referrer||void 0,user_agent:navigator.userAgent,device_type:t.device_type,browser:t.browser,os:t.os,tracking_source:k,...e,...m};return L&&!e.projectId&&(n.projectId=L),n}function v(e){f.push(e),r("Event queued:",e.event_name,"(queue:",f.length,")"),f.length>=10&&D()}async function D(){if(f.length===0)return;let e=[...f];f=[],r("Flushing",e.length,"events to",H);try{let t=await fetch(H,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({events:e}),keepalive:!0});if(!t.ok)throw new Error(`HTTP ${t.status}`);r("Events sent successfully")}catch(t){x(" Failed to send events:",t),f.length<50&&f.push(...e)}}function Fe(){j&&clearInterval(j),j=window.setInterval(()=>{f.length>0&&D()},5e3)}function V(){h||(ke=Date.now()),h=Date.now(),w=!0,r("Active time tracking started/resumed")}function ae(){h&&w&&(B+=Date.now()-h),w=!1,r("Active time tracking paused, accumulated:",B,"ms")}function He(){let e=B;return w&&h&&(e+=Date.now()-h),e}function je(){te=Date.now(),I&&(I=!1,V(),r("User returned from idle"))}function se(){if(document.visibilityState==="hidden"){r("Skipping heartbeat - tab hidden");return}if(Date.now()-te>Ce){I||(I=!0,ae(),r("User idle - pausing heartbeat"));return}let e=He(),t=Math.round(e/1e3),n=y({event_name:"engagement_heartbeat",metadata:{time_on_page_seconds:t,time_on_page_ms:e,heartbeat_interval_ms:R,is_active:w&&!I}});v(n),r("Heartbeat sent:",t,"seconds active")}function W(){if(!J){r('Heartbeat disabled via data-heartbeat="false"');return}b&&clearInterval(b),V(),b=window.setInterval(()=>{se()},R),r("Heartbeat started with interval:",R,"ms")}function Be(){b&&(clearInterval(b),b=null),J&&(se(),r("Heartbeat stopped, final time sent"))}function P(e={}){let t=y({event_name:"pageview",page_title:e.title||document.title,source_url:e.url||window.location.href});v(t)}function ce(e,t={}){let n=y({event_name:"custom",metadata:{event_type:e,...t}});v(n)}async function le(e,t={}){try{if(i&&i.analytics===!1){r("Identify skipped - user declined analytics consent");return}u=await Me(e),i?.analytics===!0&&re(),S(ee,u);let n=e.split("@"),o=n[0].charAt(0)+"***@"+(n[1]||"");r("Fan identified:",{name:t.name||"(no name)",email:o,hash:u.substring(0,16)+"...",traits:t,storageTier:g});let _=y({event_name:"identify",fan_id_hash:u,metadata:{email_sha256:u,email_display:o,traits:t,consent_preferences:i||void 0,storage_tier:g}});v(_)}catch(n){x(" Failed to identify:",n)}}function de(e,t="USD",n={}){let o=y({event_name:"purchase",metadata:{revenue:e,currency:t,...n}});v(o)}function ue(){k=Ie(),r("Tracking source detected:",k),Le(),i?.analytics===!0?(g="local",r("Storage tier: local (analytics consent granted)")):(g="session",r("Storage tier: session (privacy by default)")),E=De(),Oe(),Ne(),i||r(U?"Consent UI enabled, waiting for explicit user consent (Tier 0 mode)":"No consent - operating in privacy-first mode (session storage only, limited tracking)"),i?.analytics&&!s&&(s=oe()),Ae(),Fe(),r("Initialized",{artistId:O,projectId:L||"(none - will track to all projects)",rawProjectId:N||"(none)",sessionId:E,visitorId:s?s.substring(0,8)+"...":null,fanIdHash:u,consent:i,storageTier:g,trackingSource:k,useEmulator:K,endpoint:H}),i?.analytics===!0?(window._balanceInitialPageviewFired=!0,P(),W(),r("Full tracking enabled (user consented)")):U?r("Tracking dormant - waiting for explicit consent via ConsentManager"):(window._balanceInitialPageviewFired=!0,P(),W(),r("Privacy-first tracking enabled (session-scoped, no persistent IDs)")),["mousemove","keydown","scroll","touchstart"].forEach(e=>{document.addEventListener(e,je,{passive:!0})}),window.addEventListener("beforeunload",()=>{Be(),D()}),document.addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"?(ae(),D()):V()})}if(window.balance?._version&&window.balance._version!==l){console.warn(`[BLN] Version conflict: ${window.balance._version} already loaded, skipping ${l}`);return}let q=window.balance?.q||[];function fe(){if(q.length>0){r("Processing",q.length,"queued commands");for(let e of q){let[t,...n]=e;switch(t){case"track":ce(n[0],n[1]);break;case"identify":le(n[0],n[1]);break;case"page":P(n[0]);break;case"purchase":de(n[0],n[1],n[2]);break;case"setConsent":ie(n[0]);break;default:r("Unknown queued command:",t)}}}}window.balance={track:ce,identify:le,page:P,purchase:de,getSessionId:()=>E,getVisitorId:()=>s,getFanIdHash:()=>u,getAttribution:()=>m,setConsent:ie,getConsent:Re,hasConsent:Ue,_version:l};function ge(){U&&!i&&new Te({style:ye,primaryColor:ve,position:we})}let pe=window.requestIdleCallback||(e=>setTimeout(e,1));document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>{ue(),fe(),pe(()=>ge())}):(ue(),fe(),pe(()=>ge())),r("Pixel script loaded")})();})();
+      `,this.shadow.getElementById("accept")?.addEventListener("click",()=>this.handleConsent(!0)),this.shadow.getElementById("decline")?.addEventListener("click",()=>this.handleConsent(!1))}handleConsent(t){window.balance?.setConsent&&window.balance.setConsent({analytics:t,marketing:t,personalization:t,timestamp:new Date().toISOString()}),t&&!window._balanceInitialPageviewFired&&(window._balanceInitialPageviewFired=!0,window.balance?.page&&window.balance.page(),G(),i("Initial pageview fired after consent granted")),this.remove()}remove(){this.container&&(this.container.remove(),this.container=null,this.shadow=null,i("ConsentManager: Banner removed"))}}function fe(){try{return b==="local"?localStorage:sessionStorage}catch{return null}}function N(e){let t=fe();if(!t)return null;try{let n=x+e,r=t.getItem(n);if(!r&&b==="session")try{r=localStorage.getItem(n)}catch{}return r}catch{return null}}function C(e,t){let n=fe();if(n)try{n.setItem(x+e,t)}catch{}}function ge(){if(b!=="local"){i("Upgrading storage tier: session -> local");try{let e=[];for(let t=0;t<sessionStorage.length;t++){let n=sessionStorage.key(t);n?.startsWith(x)&&e.push(n)}for(let t of e){let n=sessionStorage.getItem(t);n&&localStorage.setItem(t,n)}for(let t of e)sessionStorage.removeItem(t);b="local",i(`Storage tier upgraded, migrated ${e.length} items`)}catch(e){w(" Storage migration failed:",e)}}}function J(){return crypto&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,e=>{let t=Math.random()*16|0;return(e==="x"?t:t&3|8).toString(16)})}function Be(){try{let e=N(ae),t=N(W);if(e&&t&&Date.now()-parseInt(t,10)<Oe)return C(W,Date.now().toString()),e;let n=J();return C(ae,n),C(W,Date.now().toString()),n}catch{return J()}}function We(){let e=new URLSearchParams(window.location.search),t={};return["source","medium","campaign","content","term"].forEach(n=>{let r=e.get(`utm_${n}`);r&&(t[`utm_${n}`]=r)}),t}function Ve(){try{let e=N(se);if(e){k=JSON.parse(e),i("Loaded attribution:",k);return}let t=We();Object.keys(t).length>0&&(k=t,C(se,JSON.stringify(t)),i("Captured attribution:",k))}catch{}}function qe(){try{m=N(ce)}catch{}}function pe(){if(!s?.analytics)return null;try{let e=localStorage.getItem(x+V);if(e)return e;let t=J();return localStorage.setItem(x+V,t),i("Created persistent visitor ID:",t.substring(0,8)+"..."),t}catch{return null}}function Ke(){if(!s?.analytics){d=null;return}try{d=localStorage.getItem(x+V),d&&i("Loaded visitor ID:",d.substring(0,8)+"...")}catch{}}function Ye(){try{let e=localStorage.getItem(R);if(e){let t=JSON.parse(e);if(t.expiresAt&&Date.now()>t.expiresAt){i("Consent expired - clearing stored consent"),localStorage.removeItem(R),s=null;return}if(t.expiresAt){let n=t.expiresAt-Date.now();n>0&&n<Re&&(i("Consent nearing expiration - will prompt for refresh"),window._balanceConsentNeedsRefresh=!0)}s=t.preferences||null,i("Loaded consent:",s)}}catch{}}function me(e){let t=s;s=e;try{let r={preferences:e,method:"explicit",version:1,expiresAt:Date.now()+Pe};localStorage.setItem(R,JSON.stringify(r)),i("Consent saved with TTL:",e),window._balanceConsentNeedsRefresh=!1}catch(r){w(" Could not save consent:",r)}e.analytics===!0&&(ge(),d||(d=pe()));let n=y({event_name:"consent_updated",metadata:{consent_preferences:e,consent_method:"explicit",previous_consent:t||void 0}});v(n);try{window.dispatchEvent(new CustomEvent("balance:consent:updated",{detail:e})),i("DOM event balance:consent:updated dispatched")}catch{}}function Je(){return s}function Xe(e){return s?.[e]===!0}async function Ge(e){let t=e.toLowerCase().trim(),r=new TextEncoder().encode(t),f=await crypto.subtle.digest("SHA-256",r);return Array.from(new Uint8Array(f)).map(a=>a.toString(16).padStart(2,"0")).join("")}function y(e){let t=Ie(),n={artist_id:H,fan_session_id:A,visitor_id:d||void 0,fan_id_hash:m||void 0,timestamp:new Date().toISOString(),source_url:window.location.href,referrer_url:document.referrer||void 0,user_agent:navigator.userAgent,device_type:t.device_type,browser:t.browser,os:t.os,tracking_source:P,...e,...k};return z&&!e.projectId&&(n.projectId=z),n}function v(e){h.push(e),i("Event queued:",e.event_name,"(queue:",h.length,")"),h.length>=10&&U()}async function U(){if(h.length===0)return;let e=[...h];h=[],i("Flushing",e.length,"events to",O);try{let t=await fetch(O,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({events:e}),keepalive:!0});if(!t.ok)throw new Error(`HTTP ${t.status}`);i("Events sent successfully")}catch(t){if(w(" Failed to send events, trying fallback:",t),O!==de&&!j)try{if((await fetch(de,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({events:e}),keepalive:!0})).ok){i("Events sent via fallback (no geo)");return}}catch(n){w(" Fallback also failed:",n)}h.length<50&&h.push(...e)}}function Qe(){q&&clearInterval(q),q=window.setInterval(()=>{h.length>0&&U()},5e3)}function X(){I||(Me=Date.now()),I=Date.now(),S=!0,i("Active time tracking started/resumed")}function he(){I&&S&&(K+=Date.now()-I),S=!1,i("Active time tracking paused, accumulated:",K,"ms")}function Ze(){let e=K;return S&&I&&(e+=Date.now()-I),e}function et(){ue=Date.now(),E&&(E=!1,X(),i("User returned from idle"))}function be(){if(document.visibilityState==="hidden"){i("Skipping heartbeat - tab hidden");return}if(Date.now()-ue>ze){E||(E=!0,he(),i("User idle - pausing heartbeat"));return}let e=Ze(),t=Math.round(e/1e3),n=y({event_name:"engagement_heartbeat",metadata:{time_on_page_seconds:t,time_on_page_ms:e,heartbeat_interval_ms:$,is_active:S&&!E}});v(n),i("Heartbeat sent:",t,"seconds active")}function G(){if(!te){i('Heartbeat disabled via data-heartbeat="false"');return}_&&clearInterval(_),X(),_=window.setInterval(()=>{be()},$),i("Heartbeat started with interval:",$,"ms")}function tt(){_&&(clearInterval(_),_=null),te&&(be(),i("Heartbeat stopped, final time sent"))}function T(e={}){let t=e.url||window.location.href;if(Ne(t)){i("Page excluded from tracking:",t);return}let n=y({event_name:"pageview",page_title:e.title||document.title,source_url:t});v(n)}function Q(e,t={}){let n=y({event_name:"custom",metadata:{event_type:e,...t}});v(n)}async function we(e,t={}){try{if(s&&s.analytics===!1){i("Identify skipped - user declined analytics consent");return}m=await Ge(e),s?.analytics===!0&&ge(),C(ce,m);let n=e.split("@"),r=n[0].charAt(0)+"***@"+(n[1]||"");i("Fan identified:",{name:t.name||"(no name)",email:r,hash:m.substring(0,16)+"...",traits:t,storageTier:b});let f=y({event_name:"identify",fan_id_hash:m,metadata:{email_sha256:m,email_display:r,traits:t,consent_preferences:s||void 0,storage_tier:b}});v(f)}catch(n){w(" Failed to identify:",n)}}function ye(e,t="USD",n={}){let r=y({event_name:"purchase",metadata:{revenue:e,currency:t,...n}});v(r)}function ve(){P=De(),i("Tracking source detected:",P),Ye(),s?.analytics===!0?(b="local",i("Storage tier: local (analytics consent granted)")):(b="session",i("Storage tier: session (privacy by default)")),A=Be(),qe(),Ke(),s||i(B?"Consent UI enabled, waiting for explicit user consent (Tier 0 mode)":"No consent - operating in privacy-first mode (session storage only, limited tracking)"),s?.analytics&&!d&&(d=pe()),Ve(),Qe(),i("Initialized",{artistId:H,projectId:z||"(none - will track to all projects)",rawProjectId:M||"(none)",sessionId:A,visitorId:d?d.substring(0,8)+"...":null,fanIdHash:m,consent:s,storageTier:b,trackingSource:P,useEmulator:j,endpoint:O}),s?.analytics===!0?(window._balanceInitialPageviewFired=!0,T(),G(),i("Full tracking enabled (user consented)")):B?i("Tracking dormant - waiting for explicit consent via ConsentManager"):(window._balanceInitialPageviewFired=!0,T(),G(),i("Privacy-first tracking enabled (session-scoped, no persistent IDs)")),["mousemove","keydown","scroll","touchstart"].forEach(a=>{document.addEventListener(a,et,{passive:!0})});let e=window.location.hostname;function t(a){try{let o=new URL(a).hostname.toLowerCase();return o.includes("spotify")?"spotify":o.includes("apple")||o.includes("music.apple")?"apple_music":o.includes("youtube")||o.includes("youtu.be")?"youtube":o.includes("soundcloud")?"soundcloud":o.includes("tidal")?"tidal":o.includes("deezer")?"deezer":o.includes("amazon")||o.includes("music.amazon")?"amazon_music":o.includes("bandcamp")?"bandcamp":o.includes("lnk.to")||o.includes("linkfire")?"linkfire":o.includes("linktr.ee")?"linktree":o.includes("shop")||o.includes("store")||o.includes("merch")?"shop":o.includes("ticketmaster")||o.includes("eventbrite")||o.includes("dice.fm")?"tickets":o.includes("instagram")?"instagram":o.includes("twitter")||o.includes("x.com")?"twitter":o.includes("tiktok")?"tiktok":o.includes("facebook")?"facebook":"external"}catch{return"external"}}function n(a){try{return new URL(a,window.location.origin).hostname!==e}catch{return!1}}function r(a,o){let c=t(a),D=o?.textContent?.trim().substring(0,100)||"",nt=o?.id||o?.getAttribute("data-link-id")||void 0;i("External link clicked:",{url:a,platform:c,linkText:D}),Q("page_link_click",{link_url:a,link_text:D,link_id:nt,platform:c,link_type:"external"})}let f=window.open;if(window.open=function(a,o,c){if(a){let D=a.toString();n(D)&&r(D)}return f.call(window,a,o,c)},i("window.open interception enabled (always on)"),l?.dataset.autoTrackLinks==="true"&&(document.addEventListener("click",a=>{let c=a.target.closest("a");if(c&&c.href&&n(c.href)){if(oe&&(le(c.href)||c.hasAttribute("download")))return;r(c.href,c)}},{capture:!0,passive:!0}),i("External link click listener enabled (opt-in)")),oe&&(document.addEventListener("click",a=>{let c=a.target.closest("a");c?.href&&(le(c.href)||c.hasAttribute("download"))&&Fe(c.href,c)},{capture:!0,passive:!0}),i("File download tracking enabled")),Le){let a=window.location.href;window.addEventListener("hashchange",()=>{let o=window.location.href;o!==a&&(a=o,setTimeout(()=>{T({title:document.title,url:o})},0))}),i("Hash routing tracking enabled")}window.addEventListener("beforeunload",()=>{tt(),U()}),document.addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"?(he(),U()):X()})}if(window.balance?._version&&window.balance._version!==g){console.warn(`[BLN] Version conflict: ${window.balance._version} already loaded, skipping ${g}`);return}let Z=window.balance?.q||[];function xe(){if(Z.length>0){i("Processing",Z.length,"queued commands");for(let e of Z){let[t,...n]=e;switch(t){case"track":Q(n[0],n[1]);break;case"identify":we(n[0],n[1]);break;case"page":T(n[0]);break;case"purchase":ye(n[0],n[1],n[2]);break;case"setConsent":me(n[0]);break;default:i("Unknown queued command:",t)}}}}window.balance={track:Q,identify:we,page:T,purchase:ye,getSessionId:()=>A,getVisitorId:()=>d,getFanIdHash:()=>m,getAttribution:()=>k,setConsent:me,getConsent:Je,hasConsent:Xe,_version:g};function ke(){B&&!s&&new $e({style:Ee,primaryColor:Ce,position:Te})}let _e=window.requestIdleCallback||(e=>setTimeout(e,1));document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>{ve(),xe(),_e(()=>ke())}):(ve(),xe(),_e(()=>ke())),i("Pixel script loaded")})();})();

package/dist/index.esm.d.ts

@@ -617,3 +617,259 @@ export interface ConsentBridgeProps {
  * props happens in your app code, not in the SDK.
  */
 export declare function ConsentBridge(props: ConsentBridgeProps): null;
+
+// ============================================
+// ArtistOS - Unified Component (Recommended)
+// ============================================
+
+/**
+ * Consent mode for ArtistOS
+ */
+export type ConsentMode = 'built-in' | 'c15t' | 'external' | 'disabled';
+
+/**
+ * Consent configuration for ArtistOS
+ */
+export interface ConsentConfig {
+  /**
+   * How consent is managed
+   * - 'built-in': Use ArtistOS built-in consent manager (default)
+   * - 'c15t': Use c15t consent manager (requires @c15t/react)
+   * - 'external': Consent managed by external system (use ConsentBridge)
+   * - 'disabled': No consent management
+   */
+  mode?: ConsentMode;
+  /** Show consent banner */
+  showBanner?: boolean;
+  /** Delay before showing banner in ms */
+  bannerDelay?: number;
+  /** Show "Manage Preferences" button on banner */
+  showManageButton?: boolean;
+}
+
+/**
+ * Resolved config after merging props with env vars
+ */
+export interface ResolvedConfig {
+  artistId: string | undefined;
+  gtmId: string | undefined;
+  endpoint: string | undefined;
+  consent: Required<ConsentConfig>;
+  debug: boolean;
+  disabled: boolean;
+  scriptUrl: string;
+  useEmulator: boolean;
+  projectId: string | undefined;
+}
+
+/**
+ * Consent state from built-in consent manager
+ */
+export interface ConsentState {
+  /** Current consent preferences */
+  consent: ConsentPreferences | null;
+  /** Whether consent is still loading */
+  loading: boolean;
+  /** Whether user has made a consent choice */
+  hasConsented: boolean;
+  /** Whether to show the consent banner */
+  showBanner: boolean;
+  /** Set banner visibility */
+  setShowBanner: (show: boolean) => void;
+  /** Whether to show the consent dialog */
+  showDialog: boolean;
+  /** Set dialog visibility */
+  setShowDialog: (show: boolean) => void;
+  /** Accept all consent */
+  acceptAll: () => void;
+  /** Decline all consent */
+  declineAll: () => void;
+  /** Update specific consent preferences */
+  updateConsent: (prefs: ConsentPreferences) => void;
+  /** Check if specific consent type is granted */
+  hasConsent: (type: 'analytics' | 'marketing' | 'personalization') => boolean;
+}
+
+/**
+ * ArtistOS Context Value
+ */
+export interface ArtistOSContextValue {
+  config: ResolvedConfig;
+  consentState: ConsentState;
+}
+
+/**
+ * ArtistOS Props - Zero-config unified component
+ */
+export interface ArtistOSProps {
+  /** Artist ID (reads from NEXT_PUBLIC_ARTIST_ID if not provided) */
+  artistId?: string;
+  /** GTM container ID (reads from NEXT_PUBLIC_GTM_ID if not provided) */
+  gtmId?: string;
+  /** Pixel endpoint (reads from NEXT_PUBLIC_PIXEL_ENDPOINT if not provided) */
+  endpoint?: string;
+  /** Consent configuration */
+  consent?: ConsentConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Disable tracking entirely */
+  disabled?: boolean;
+  /** Custom pixel script URL */
+  scriptUrl?: string;
+  /** Use Firebase emulator */
+  useEmulator?: boolean;
+  /** Project ID for multi-project tracking */
+  projectId?: string;
+  /** Optional children */
+  children?: React.ReactNode;
+}
+
+/**
+ * ArtistOS - Unified component for pixel loading, consent management, and GTM integration
+ *
+ * Zero-config usage:
+ * ```tsx
+ * <ArtistOS />
+ * ```
+ *
+ * With explicit artistId:
+ * ```tsx
+ * <ArtistOS artistId="artist_123" />
+ * ```
+ */
+export declare function ArtistOS(props: ArtistOSProps): JSX.Element;
+
+/**
+ * Hook to access ArtistOS context
+ * @throws Error if used outside ArtistOS
+ */
+export declare function useArtistOS(): ArtistOSContextValue;
+
+/**
+ * Hook to optionally access ArtistOS context
+ * Returns null if not inside ArtistOS
+ */
+export declare function useArtistOSOptional(): ArtistOSContextValue | null;
+
+/**
+ * Built-in consent hook for ArtistOS
+ */
+export declare function useBuiltInConsent(config: Required<ConsentConfig>): ConsentState;
+
+/**
+ * @deprecated Use ArtistOS with consent={{ mode: 'c15t' }} instead
+ */
+export declare function useC15tConsent(config: Required<ConsentConfig>): ConsentState;
+
+/**
+ * ArtistOS with Built-in Consent (used internally by ArtistOS)
+ */
+export declare function ArtistOSWithBuiltIn(props: {
+  config: ResolvedConfig;
+  children?: React.ReactNode;
+}): JSX.Element;
+
+/**
+ * ArtistOS Core - No consent UI (used for external/disabled modes)
+ */
+export declare function ArtistOSCore(props: {
+  config: ResolvedConfig;
+  children?: React.ReactNode;
+}): JSX.Element;
+
+/**
+ * ArtistOS with c15t Integration
+ * Requires @c15t/react to be installed
+ */
+export declare function ArtistOSWithC15t(props: {
+  config: ResolvedConfig;
+  children?: React.ReactNode;
+}): JSX.Element;
+
+/**
+ * ArtistOS Context - for building custom integrations
+ */
+export declare const ArtistOSContext: React.Context<ArtistOSContextValue | null>;
+
+/**
+ * Pixel Script Loader component
+ */
+export declare function PixelScriptLoader(props: { config: ResolvedConfig }): JSX.Element | null;
+
+/**
+ * GTM Script Loader component
+ */
+export declare function GTMScriptLoader(props: { config: ResolvedConfig }): JSX.Element | null;
+
+/**
+ * Consent UI Manager component
+ */
+export declare function ConsentUIManager(props: {
+  config: ResolvedConfig;
+  consentState: ConsentState;
+}): JSX.Element | null;
+
+/**
+ * Hook to sync GTM consent with Balance consent
+ */
+export declare function useGTMConsentSync(
+  config: ResolvedConfig,
+  consentState: ConsentState
+): void;
+
+// ============================================
+// c15t Integration Types
+// ============================================
+
+/**
+ * c15t Consent Manager interface (from @c15t/react)
+ */
+export interface C15tConsentManager {
+  consents: Record<string, boolean> | null;
+  hasConsented: () => boolean;
+  hasConsentFor: (category: string) => boolean;
+  setConsent: (category: string, value: boolean) => void;
+  saveConsents: (source?: string) => void;
+  acceptAll: () => void;
+  rejectAll: () => void;
+}
+
+/**
+ * Hook that bridges c15t consent to ArtistOS ConsentState
+ */
+export declare function useC15tConsentState(
+  c15tManager: C15tConsentManager,
+  config: Required<ConsentConfig>
+): ConsentState;
+
+// ============================================
+// Consent Mapping Helpers
+// ============================================
+
+/**
+ * Mapping from c15t consent categories to Balance consent types
+ */
+export declare const C15T_TO_BALANCE_MAP: {
+  measurement: 'analytics';
+  marketing: 'marketing';
+  experience: 'personalization';
+};
+
+/**
+ * Mapping from Balance consent types to c15t categories
+ */
+export declare const BALANCE_TO_C15T_MAP: {
+  analytics: 'measurement';
+  marketing: 'marketing';
+  personalization: 'experience';
+};
+
+/**
+ * Convert c15t consent state to Balance format
+ */
+export declare function toBalanceConsent(c15tConsents: Record<string, boolean>): ConsentPreferences;
+
+/**
+ * Convert Balance consent to c15t format
+ */
+export declare function fromBalanceConsent(balanceConsent: ConsentPreferences): Record<string, boolean>;