@stacksjs/analytics 0.74.32 → 0.74.34

package/dist/drivers/fathom.d.ts

@@ -1 +1,19 @@
-export declare const fathomWip: 1;
+import type { AnalyticsHeadTag } from './shared';
+/**
+ * Build the Fathom head tags.
+ *
+ * Values are raw; escaping happens when the tags are rendered.
+ */
+export declare function getFathomAnalyticsHead(config: FathomConfig): AnalyticsHeadTag[];
+/**
+ * Generate the Fathom tracking script tag.
+ */
+export declare function generateFathomScript(config: FathomConfig): string;
+/** Fathom's hosted script, used when `scriptUrl` is not set. */
+export declare const FATHOM_DEFAULT_SCRIPT_URL: 'https://cdn.usefathom.com/script.js';
+export declare interface FathomConfig {
+  siteId: string
+  scriptUrl?: string
+  honorDnt?: boolean
+  spa?: boolean
+}

package/dist/drivers/fathom.js

@@ -1 +1,2 @@
-export const fathomWip=1;
+import{renderHeadTags}from"./shared";export const FATHOM_DEFAULT_SCRIPT_URL="https://cdn.usefathom.com/script.js";export function getFathomAnalyticsHead(config){if(!config.siteId)return[];const attrs={src:config.scriptUrl||FATHOM_DEFAULT_SCRIPT_URL,"data-site":config.siteId,defer:""};if(config.honorDnt)attrs["data-honor-dnt"]="true";if(config.spa)attrs["data-spa"]="auto";return[["script",attrs]]}export function generateFathomScript(config){const tags=getFathomAnalyticsHead(config);if(!tags.length)return"";return`<!-- Stacks Fathom Analytics -->
+${renderHeadTags(tags)}`}

package/dist/drivers/google-analytics.d.ts

@@ -0,0 +1,17 @@
+import type { AnalyticsHeadTag } from './shared';
+/**
+ * Build the Google Analytics head tags.
+ *
+ * Values are raw; escaping happens when the tags are rendered.
+ */
+export declare function getGoogleAnalyticsHead(config: GoogleAnalyticsConfig): AnalyticsHeadTag[];
+/**
+ * Generate the Google Analytics tracking script tags.
+ */
+export declare function generateGoogleAnalyticsScript(config: GoogleAnalyticsConfig): string;
+/** The gtag.js loader, used to build the tag `src`. */
+export declare const GOOGLE_ANALYTICS_SCRIPT_URL: 'https://www.googletagmanager.com/gtag/js';
+export declare interface GoogleAnalyticsConfig {
+  trackingId: string
+  debug?: boolean
+}

package/dist/drivers/google-analytics.js

@@ -0,0 +1,2 @@
+import{jsString,renderHeadTags}from"./shared";export const GOOGLE_ANALYTICS_SCRIPT_URL="https://www.googletagmanager.com/gtag/js";export function getGoogleAnalyticsHead(config){if(!config.trackingId)return[];const id=jsString(config.trackingId),options=config.debug?",{debug_mode:true}":"";return[["script",{src:`${GOOGLE_ANALYTICS_SCRIPT_URL}?id=${encodeURIComponent(config.trackingId)}`,async:""}],["script",{innerHTML:`window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config',${id}${options});`}]]}export function generateGoogleAnalyticsScript(config){const tags=getGoogleAnalyticsHead(config);if(!tags.length)return"";return`<!-- Stacks Google Analytics -->
+${renderHeadTags(tags)}`}

package/dist/drivers/index.d.ts

@@ -1,2 +1,5 @@
 export * from './fathom';
+export * from './google-analytics';
+export * from './plausible';
 export * from './self-hosted';
+export * from './shared';

package/dist/drivers/index.js

@@ -1 +1 @@
-export*from"./fathom";export*from"./self-hosted";
+export*from"./fathom";export*from"./google-analytics";export*from"./plausible";export*from"./self-hosted";export*from"./shared";

package/dist/drivers/plausible.d.ts

@@ -0,0 +1,23 @@
+import type { AnalyticsHeadTag } from './shared';
+/**
+ * Build the URL of the hosted script variant matching the config.
+ */
+export declare function plausibleScriptUrl(config: PlausibleConfig): string;
+/**
+ * Build the Plausible head tags.
+ *
+ * Values are raw; escaping happens when the tags are rendered.
+ */
+export declare function getPlausibleAnalyticsHead(config: PlausibleConfig): AnalyticsHeadTag[];
+/**
+ * Generate the Plausible tracking script tag.
+ */
+export declare function generatePlausibleScript(config: PlausibleConfig): string;
+/** Plausible's hosted script host, used when `scriptUrl` is not set. */
+export declare const PLAUSIBLE_DEFAULT_HOST: 'https://plausible.io';
+export declare interface PlausibleConfig {
+  domain: string
+  scriptUrl?: string
+  trackLocalhost?: boolean
+  hashMode?: boolean
+}

package/dist/drivers/plausible.js

@@ -0,0 +1,2 @@
+import{renderHeadTags}from"./shared";export const PLAUSIBLE_DEFAULT_HOST="https://plausible.io";export function plausibleScriptUrl(config){if(config.scriptUrl)return config.scriptUrl;const extensions=[config.hashMode?"hash":"",config.trackLocalhost?"local":""].filter(Boolean);return`${PLAUSIBLE_DEFAULT_HOST}/js/script${extensions.map((e)=>`.${e}`).join("")}.js`}export function getPlausibleAnalyticsHead(config){if(!config.domain)return[];return[["script",{src:plausibleScriptUrl(config),"data-domain":config.domain,defer:""}]]}export function generatePlausibleScript(config){const tags=getPlausibleAnalyticsHead(config);if(!tags.length)return"";return`<!-- Stacks Plausible Analytics -->
+${renderHeadTags(tags)}`}

package/dist/drivers/self-hosted.d.ts

@@ -1,27 +1,15 @@
+import type { AnalyticsHeadTag } from './shared';
 /**
- * Generate the self-hosted analytics tracking script
- */
-export declare function generateSelfHostedScript(config: SelfHostedConfig): string;
-/**
- * Generate the head tag for including self-hosted analytics
- * Compatible with Stacks docs config.ts head array format
+ * Build the self-hosted head tags.
+ *
+ * Compatible with the Stacks/BunPress docs `head` array format. Values are raw;
+ * escaping happens when the tags are rendered.
  */
-export declare function getSelfHostedAnalyticsHead(config: SelfHostedConfig): [string, Record<string, string>][];
+export declare function getSelfHostedAnalyticsHead(config: SelfHostedConfig): AnalyticsHeadTag[];
 /**
- * Self-Hosted Analytics Driver
- *
- * This driver generates a minimal, privacy-focused tracking script
- * that sends analytics data to your own API endpoint (powered by dynamodb-tooling analytics).
- *
- * Features:
- * - No cookies required
- * - Privacy-focused (hashed visitor IDs)
- * - Do Not Track support
- * - Page view tracking
- * - Custom event tracking
- * - Outbound link tracking (optional)
- * - Hash-based routing support (optional)
+ * Generate the self-hosted analytics tracking script
  */
+export declare function generateSelfHostedScript(config: SelfHostedConfig): string;
 export declare interface SelfHostedConfig {
   siteId: string
   apiEndpoint: string

package/dist/drivers/self-hosted.js

@@ -1,51 +1,17 @@
-export function generateSelfHostedScript(config){if(!config.siteId||!config.apiEndpoint)return"";const siteId=escapeAttr(config.siteId),apiEndpoint=escapeAttr(config.apiEndpoint),honorDnt=config.honorDnt?'if(n.doNotTrack==="1")return;':"",hashTracking=config.trackHashChanges?"w.addEventListener('hashchange',pv);":"",outboundTracking=config.trackOutboundLinks?`
-  d.addEventListener('click',function(e){
-    var a=e.target.closest('a');
-    if(a&&a.hostname!==location.hostname){
-      t('outbound',{url:a.href});
-    }
-  });`:"";return`<!-- Stacks Self-Hosted Analytics -->
-<script data-site="${siteId}" data-api="${apiEndpoint}" defer>
-(function(){
-  'use strict';
-  var d=document,w=window,n=navigator,s=d.currentScript;
-  var site=s.dataset.site,api=s.dataset.api;
-  ${honorDnt}
-  var q=[],sid=Math.random().toString(36).slice(2);
-  function t(e,p){
-    var x=new XMLHttpRequest();
-    x.open('POST',api+'/collect',true);
-    x.setRequestHeader('Content-Type','application/json');
-    // Strip the URL's query string before sending. location.href includes
-    // tokens / session IDs / search terms that shouldn't reach the
-    // analytics backend. Same goes for document.referrer when it points
-    // back to our own domain (path is fine, query is not).
-    var safeUrl=location.origin+location.pathname+location.hash;
-    var safeRef=d.referrer?d.referrer.split('?')[0]:'';
-    x.send(JSON.stringify({
-      s:site,sid:sid,e:e,p:p||{},
-      u:safeUrl,r:safeRef,t:d.title,
-      sw:screen.width,sh:screen.height
-    }));
-  }
-  function pv(){t('pageview');}
-  ${hashTracking}
-  ${outboundTracking}
-  if(d.readyState==='complete')pv();
-  else w.addEventListener('load',pv);
-  w.stacksAnalytics={track:function(n,v){t('event',{name:n,value:v});}};
-})();
-</script>`}export function getSelfHostedAnalyticsHead(config){if(!config.siteId||!config.apiEndpoint)return[];return[["script",{"data-site":config.siteId,"data-api":config.apiEndpoint,defer:"",innerHTML:generateInlineScript(config)}]]}function generateInlineScript(config){const honorDnt=config.honorDnt?'if(n.doNotTrack==="1")return;':"",hashTracking=config.trackHashChanges?"w.addEventListener('hashchange',pv);":"",outboundTracking=config.trackOutboundLinks?"d.addEventListener('click',function(e){var a=e.target.closest('a');if(a&&a.hostname!==location.hostname){t('outbound',{url:a.href});}});":"";return`(function(){
+import{renderHeadTags}from"./shared";export function getSelfHostedAnalyticsHead(config){if(!config.siteId||!config.apiEndpoint)return[];return[["script",{"data-site":config.siteId,"data-api":config.apiEndpoint,defer:"",innerHTML:generateInlineScript(config)}]]}export function generateSelfHostedScript(config){const tags=getSelfHostedAnalyticsHead(config);if(!tags.length)return"";return`<!-- Stacks Self-Hosted Analytics -->
+${renderHeadTags(tags)}`}function generateInlineScript(config){const honorDnt=config.honorDnt?'if(n.doNotTrack==="1")return;':"",hashTracking=config.trackHashChanges?"w.addEventListener('hashchange',pv);":"",outboundTracking=config.trackOutboundLinks?"d.addEventListener('click',function(e){var a=e.target.closest('a');if(a&&a.hostname!==location.hostname){t('outbound',{url:a.href});}});":"";return`(function(){
 'use strict';
 var d=document,w=window,n=navigator,s=d.currentScript;
 var site=s.dataset.site,api=s.dataset.api;
 ${honorDnt}
-var q=[],sid=Math.random().toString(36).slice(2);
+var sid=Math.random().toString(36).slice(2);
 function t(e,p){
 var x=new XMLHttpRequest();
 x.open('POST',api+'/collect',true);
 x.setRequestHeader('Content-Type','application/json');
-var safeUrl=location.origin+location.pathname+location.hash;var safeRef=d.referrer?d.referrer.split('?')[0]:'';x.send(JSON.stringify({s:site,sid:sid,e:e,p:p||{},u:safeUrl,r:safeRef,t:d.title,sw:screen.width,sh:screen.height}));
+var safeUrl=location.origin+location.pathname+location.hash;
+var safeRef=d.referrer?d.referrer.split('?')[0]:'';
+x.send(JSON.stringify({s:site,sid:sid,e:e,p:p||{},u:safeUrl,r:safeRef,t:d.title,sw:screen.width,sh:screen.height}));
 }
 function pv(){t('pageview');}
 ${hashTracking}
@@ -53,4 +19,4 @@ ${outboundTracking}
 if(d.readyState==='complete')pv();
 else w.addEventListener('load',pv);
 w.stacksAnalytics={track:function(n,v){t('event',{name:n,value:v});}};
-})();`}function escapeAttr(str){return str.replace(/&/g,"&amp;").replace(/"/g,"&quot;").replace(/'/g,"&#39;").replace(/</g,"&lt;").replace(/>/g,"&gt;")}
+})();`}

package/dist/drivers/shared.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Escape a value for safe insertion into an HTML attribute.
+ */
+export declare function escapeAttr(str: string): string;
+/**
+ * Serialize a value as a JavaScript string literal for inline script bodies.
+ *
+ * `JSON.stringify` handles quoting and control characters; the `<` and `>`
+ * replacements stop a value containing `</script>` from closing the tag early.
+ */
+export declare function jsString(value: string): string;
+/**
+ * Render an `[tag, attributes]` pair as HTML.
+ *
+ * Head tags carry raw values; escaping happens here, so a driver never escapes
+ * twice. An `innerHTML` attribute becomes the tag body instead of an attribute,
+ * and an empty value renders as a bare attribute (`defer`, `async`).
+ */
+export declare function renderHeadTag([tag, attrs]: AnalyticsHeadTag): string;
+/**
+ * Render a driver's head tags as an HTML block.
+ */
+export declare function renderHeadTags(tags: AnalyticsHeadTag[]): string;
+/**
+ * Shared helpers for the analytics drivers.
+ *
+ * Every driver emits a `<script>` tag, either as raw HTML or as the
+ * `[tag, attributes]` pair the Stacks/BunPress docs `head` array expects, so the
+ * tag shape and the escaping live here rather than once per driver.
+ */
+/** A single head entry: the tag name plus its attributes. */
+export type AnalyticsHeadTag = [string, Record<string, string>];

package/dist/drivers/shared.js

@@ -0,0 +1,2 @@
+export function escapeAttr(str){return str.replace(/&/g,"&amp;").replace(/"/g,"&quot;").replace(/'/g,"&#39;").replace(/</g,"&lt;").replace(/>/g,"&gt;")}export function jsString(value){return JSON.stringify(value).replace(/</g,"\\u003C").replace(/>/g,"\\u003E")}export function renderHeadTag([tag,attrs]){const body=attrs.innerHTML??"",rendered=Object.entries(attrs).filter(([key])=>key!=="innerHTML").map(([key,value])=>value===""?` ${key}`:` ${key}="${escapeAttr(value)}"`).join("");return`<${tag}${rendered}>${body}</${tag}>`}export function renderHeadTags(tags){return tags.map(renderHeadTag).join(`
+`)}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { classifyAgent, isPageviewRequest, recordPageview, referrerHost } from './capture';
 export * from './drivers/index';
+export * from './registry';

package/dist/index.js

@@ -1 +1 @@
-export{classifyAgent,isPageviewRequest,recordPageview,referrerHost}from"./capture";export*from"./drivers";
+export{classifyAgent,isPageviewRequest,recordPageview,referrerHost}from"./capture";export*from"./drivers";export*from"./registry";

package/dist/registry.d.ts

@@ -0,0 +1,21 @@
+import type { AnalyticsConfig, AnalyticsOptions } from '@stacksjs/types';
+import type { AnalyticsHeadTag } from './drivers/shared';
+/**
+ * Is this a driver name Stacks implements?
+ */
+export declare function isAnalyticsDriver(value: unknown): value is AnalyticsDriverName;
+/**
+ * Resolve the configured driver's head tags.
+ *
+ * Returns an empty array when no driver is configured at all. Throws when a
+ * driver is named that Stacks does not implement, or when the named driver is
+ * missing the config it needs.
+ */
+export declare function getAnalyticsHead(config: AnalyticsConfig): AnalyticsHeadTag[];
+/**
+ * Render the configured driver's tracking script as HTML.
+ */
+export declare function generateAnalyticsScript(config: AnalyticsConfig): string;
+/** Every driver name that has an implementation behind it. */
+export declare const ANALYTICS_DRIVERS: readonly AnalyticsDriverName[];
+export type AnalyticsDriverName = AnalyticsOptions['driver'];

package/dist/registry.js

@@ -0,0 +1 @@
+import{getFathomAnalyticsHead}from"./drivers/fathom";import{getGoogleAnalyticsHead}from"./drivers/google-analytics";import{getPlausibleAnalyticsHead}from"./drivers/plausible";import{getSelfHostedAnalyticsHead}from"./drivers/self-hosted";import{renderHeadTags}from"./drivers/shared";export const ANALYTICS_DRIVERS=["google-analytics","fathom","plausible","self-hosted"];export function isAnalyticsDriver(value){return typeof value==="string"&&ANALYTICS_DRIVERS.includes(value)}function misconfigured(driver,key,field){return Error(`Analytics driver "${driver}" is selected but not configured: set \`drivers.${key}.${field}\` in config/analytics.ts, or change \`driver\`.`)}export function getAnalyticsHead(config){const driver=config.driver;if(!driver)return[];if(!isAnalyticsDriver(driver))throw Error(`Unknown analytics driver "${String(driver)}". Available drivers: ${ANALYTICS_DRIVERS.join(", ")}.`);switch(driver){case"google-analytics":{const options=config.drivers?.googleAnalytics;if(!options?.trackingId)throw misconfigured(driver,"googleAnalytics","trackingId");return getGoogleAnalyticsHead(options)}case"fathom":{const options=config.drivers?.fathom;if(!options?.siteId)throw misconfigured(driver,"fathom","siteId");return getFathomAnalyticsHead(options)}case"plausible":{const options=config.drivers?.plausible;if(!options?.domain)throw misconfigured(driver,"plausible","domain");return getPlausibleAnalyticsHead(options)}case"self-hosted":{const options=config.drivers?.selfHosted;if(!options?.siteId)throw misconfigured(driver,"selfHosted","siteId");if(!options.apiEndpoint)throw misconfigured(driver,"selfHosted","apiEndpoint");return getSelfHostedAnalyticsHead(options)}default:throw Error(`Analytics driver "${String(driver)}" has no implementation.`)}}export function generateAnalyticsScript(config){const tags=getAnalyticsHead(config);if(!tags.length)return"";return renderHeadTags(tags)}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/analytics",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.32",
+  "version": "0.74.34",
   "description": "Stacks Analytics. Privacy-friendly.",
   "author": "Chris Breuer",
   "contributors": [
@@ -51,7 +51,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/database": "0.74.32"
+    "@stacksjs/database": "0.74.34",
+    "@stacksjs/types": "0.74.34"
   },
   "devDependencies": {
     "better-dx": "^0.2.24"