@vskstudio/takt-astro 0.6.2 → 0.8.0

package/README.md

@@ -11,7 +11,7 @@ Astro integration for [Takt](https://github.com/vskstudio/takt-core), privacy-fr
 pnpm add @vskstudio/takt-astro @vskstudio/takt-core
 ```
 
-Both are peer dependencies: `astro` (`>=4`) and `@vskstudio/takt-core` (`>=0.8.1`).
+Both are peer dependencies: `astro` (`>=4`) and `@vskstudio/takt-core` (`>=0.10.0`).
 
 ## Usage
 
@@ -62,8 +62,11 @@ Both the integration and the component accept the same options, with one excepti
 | `trackQuery` | `boolean` | `false` | Keep the full query string and hash instead of stripping them. Wins over `queryParams`. |
 | `queryParams` | `string[]` | – | Allowlist of query params to keep, applied only when `trackQuery` is off. |
 | `exclude` | `string[]` | – | Path prefixes never tracked, e.g. `['/app', '/account']` (segment-bounded, checked at send time). |
-| `scrubUrl` | `(url: string) => string` | – | **Integration only.** Rewrite each URL before it is sent (e.g. strip a fragment or PII). See the note below. |
+| `redactRoutes` | `string[]` | none | Route patterns sent in place of the real path, e.g. `['/verify/[token]']` sends `/verify/[token]` instead of `/verify/abc123`. See [Route redaction](#route-redaction). |
+| `routeTemplates` | `boolean` | `false` | Send every page as its Astro route template (`/blog/[slug]`), read from `Astro.routePattern`. Needs Astro 5 and the route meta, see [Route redaction](#route-redaction). |
+| `scrubUrl` | `(url: string) => string` | – | **Integration only.** Rewrite each URL before it is sent (page, referrer, and the `url` prop of outbound-link and file-download events), e.g. to strip a fragment or PII. See the note below. |
 | `tagged` | `boolean` | `false` | Auto-track clicks on `[data-takt-event]` elements; `data-takt-prop-*` attributes become event props. |
+| `debug` | `boolean` | `false` | Log each payload to the browser console before sending. |
 
 > **`scrubUrl` note.** Unlike the other options, `scrubUrl` is a **function**, so it
 > is supported **only via the integration**, not the `<Takt />` component. The
@@ -80,9 +83,45 @@ Both the integration and the component accept the same options, with one excepti
 
 Astro's client router runs several history operations per navigation (scroll-restoration `replaceState` plus `pushState`), so Takt does **not** rely on core's history patch here — it would over-count. Instead the runtime fires one explicit initial pageview and then one per Astro `astro:after-swap` event (including View Transitions DOM swaps and back/forward), so each navigation is counted exactly once. On a plain MPA (no client router) the script re-runs per page load, which fires the initial pageview each time. The runtime is SSR/prerender safe — it only runs in the browser.
 
+## Route redaction
+
+Query strings are stripped by default, but path segments are sent as they are, so `/verify/abc123` leaks the token. List the sensitive routes in `redactRoutes` and every matching path is sent as its pattern, while the other pages keep their real path:
+
+```js
+takt({ redactRoutes: ['/verify/[token]', '/invoices/[id].pdf'] })
+```
+
+The rule covers the page URL, same-origin referrers, outbound and download link destinations, and 404 paths. Patterns use Astro's syntax (`[param]`, `[...rest]`) and also accept `:param` and `*`.
+
+To send every page as its route template instead (`/blog/hello` becomes `/blog/[slug]`), turn on `routeTemplates`. Astro knows the template on the server (`Astro.routePattern`), so it travels in a `<meta name="takt:route">` tag that the runtime reads at each pageview, including after a ClientRouter navigation. With the integration, render that tag with `<TaktRoute />` in the `<head>` of your layout:
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  integrations: [takt({ routeTemplates: true })],
+})
+```
+
+```astro
+---
+import TaktRoute from '@vskstudio/takt-astro/TaktRoute.astro'
+---
+<head>
+  <TaktRoute />
+</head>
+```
+
+The `<Takt />` component renders the tag itself when `routeTemplates` is set:
+
+```astro
+<Takt domain="example.com" routeTemplates />
+```
+
+`Astro.routePattern` exists from Astro 5. On Astro 4 no tag is rendered, so `redactRoutes` still applies and the real path is sent otherwise. This mode merges every article of a public blog into one row, so it suits private areas better; `redactRoutes` is usually the right tool for a public site.
+
 ## Custom events
 
-`track`, `pageview`, `optOut` and `optIn` are re-exported from core for convenience. They act on core's default instance, which only exists in the browser once the injected runtime has booted — so call them from a client-side `<script>`, not from `.astro` frontmatter (where they are silent no-ops):
+`track`, `pageview`, `optOut`, `optIn` and `isOptedOut` are re-exported from core for convenience. `track` and `pageview` act on core's default instance, which only exists in the browser once the injected runtime has booted, so call them from a client-side `<script>`, not from `.astro` frontmatter (where they are silent no-ops):
 
 ```astro
 <button id="signup">Sign up</button>
@@ -94,6 +133,26 @@ Astro's client router runs several history operations per navigation (scroll-res
 </script>
 ```
 
+## Consent
+
+`optOut`, `optIn` and `isOptedOut` do not wait for the runtime to boot: they read and write the stored choice directly. A consent banner can therefore run before the injected runtime, and the instance it boots later honours the choice. Call them from a client-side `<script>`, since the choice lives in the browser.
+
+```astro
+<button id="analytics-toggle"></button>
+<script>
+  import { isOptedOut, optIn, optOut } from '@vskstudio/takt-astro'
+  const button = document.getElementById('analytics-toggle')
+  const render = () => {
+    if (button) button.textContent = isOptedOut() ? 'Enable analytics' : 'Disable analytics'
+  }
+  button?.addEventListener('click', () => {
+    isOptedOut() ? optIn() : optOut()
+    render()
+  })
+  render()
+</script>
+```
+
 ## Widgets
 
 Thin wrappers around Takt's server-rendered badge SVG and embed iframe.
@@ -137,10 +196,10 @@ From `@vskstudio/takt-astro`:
 
 - `default` / `takt` — the integration factory (same function under both names)
 - `resolveOptions`, `assertNoScrubUrl`, `buildRuntime` — the internals the `.astro` components build on, exported so you can drive the runtime yourself
-- Re-exported from core: `track`, `pageview`, `optOut`, `optIn`, `createStats`, `PublicApiError`, `badgeUrl`, `embedUrl`
+- Re-exported from core: `track`, `pageview`, `optOut`, `optIn`, `isOptedOut`, `createStats`, `PublicApiError`, `badgeUrl`, `embedUrl`
 - Types: `TaktOptions`, plus `InitOptions`, `TrackOptions`, `BadgeOptions`, `EmbedOptions`, `BadgeVariant`, `BadgeGlyph`, `EmbedTheme`, `WidgetLang`, `StatsClient`, `StatsClientOptions`, `StatsParams`, `StatsPeriod`, `StatsDimension`, `StatsMetrics`, `StatsSummary`, `StatsPoint`, `StatsTimeseries`, `StatsBreakdownRow`, `StatsBreakdown`, `StatsRealtime` re-exported from core
 
-Component subpaths: `@vskstudio/takt-astro/Takt.astro`, `/Badge.astro`, `/Embed.astro`.
+Component subpaths: `@vskstudio/takt-astro/Takt.astro`, `/TaktRoute.astro`, `/Badge.astro`, `/Embed.astro`.
 
 ## License
 

package/Takt.astro

@@ -17,7 +17,10 @@ const config = JSON.stringify(resolveOptions(Astro.props))
   .replace(/</g, '\\u003c')
   .replace(/>/g, '\\u003e')
   .replace(/&/g, '\\u0026')
+
+const route = Astro.props.routeTemplates ? Astro.routePattern : undefined
 ---
+{route && <meta name="takt:route" content={route} />}
 <!-- Pick ONE install path — this component OR the integration — not both. -->
 <script type="application/json" data-takt-config set:html={config}></script>
 <!-- A bundled (non-inline) module so Astro resolves the bare core import; an
@@ -29,9 +32,12 @@ const config = JSON.stringify(resolveOptions(Astro.props))
   if (el && !w.__takt) {
     const o = JSON.parse(el.textContent || '{}')
     w.__takt = true
+    const routeTemplate = o.routeTemplates
+      ? () => document.querySelector('meta[name="takt:route"]')?.getAttribute('content') ?? null
+      : undefined
     // auto forced off: Astro's ClientRouter runs several history ops per nav, so
     // core's history patch would over-count. Drive pageviews from after-swap.
-    init({ ...o, auto: false })
+    init({ ...o, auto: false, routeTemplate })
     pageview()
     if (o.auto !== false) document.addEventListener('astro:after-swap', () => pageview())
   }

package/TaktRoute.astro

@@ -0,0 +1,4 @@
+---
+const route = Astro.routePattern
+---
+{route && <meta name="takt:route" content={route} />}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroIntegration } from 'astro';
 import { InitOptions } from '@vskstudio/takt-core';
-export { BadgeGlyph, BadgeOptions, BadgeVariant, EmbedOptions, EmbedTheme, InitOptions, PublicApiError, StatsBreakdown, StatsBreakdownRow, StatsClient, StatsClientOptions, StatsDimension, StatsMetrics, StatsParams, StatsPeriod, StatsPoint, StatsRealtime, StatsSummary, StatsTimeseries, TrackOptions, WidgetLang, badgeUrl, createStats, embedUrl, optIn, optOut, pageview, track } from '@vskstudio/takt-core';
+export { BadgeGlyph, BadgeOptions, BadgeVariant, EmbedOptions, EmbedTheme, InitOptions, PublicApiError, StatsBreakdown, StatsBreakdownRow, StatsClient, StatsClientOptions, StatsDimension, StatsMetrics, StatsParams, StatsPeriod, StatsPoint, StatsRealtime, StatsSummary, StatsTimeseries, TrackOptions, WidgetLang, badgeUrl, createStats, embedUrl, isOptedOut, optIn, optOut, pageview, track } from '@vskstudio/takt-core';
 
 /**
  * Options for the Takt integration and `<Takt />` component. Mirrors core's
@@ -41,6 +41,8 @@ interface TaktOptions {
     queryParams?: string[];
     /** Path prefixes never tracked, e.g. `['/app','/account']`. Segment-bounded: `'/app'` matches `'/app'` and `'/app/…'` but not `'/application'`. */
     exclude?: string[];
+    redactRoutes?: string[];
+    routeTemplates?: boolean;
     /**
      * Rewrite each URL before it is sent (e.g. strip a fragment or PII).
      * MUST be a self-contained function: it is stringified at build time and
@@ -54,6 +56,7 @@ interface TaktOptions {
     scrubUrl?: (url: string) => string;
     /** Auto-track elements marked with `data-takt-event`. */
     tagged?: boolean;
+    debug?: boolean;
 }
 /**
  * Guard the `<Takt />` component path against `scrubUrl`. The component

package/dist/index.js

@@ -22,15 +22,23 @@ function resolveOptions(options = {}) {
     trackQuery: options.trackQuery,
     queryParams: options.queryParams,
     exclude: options.exclude,
-    tagged: options.tagged
+    redactRoutes: options.redactRoutes,
+    routeTemplates: options.routeTemplates,
+    tagged: options.tagged,
+    debug: options.debug
   };
 }
 
 // src/runtime.ts
+var ROUTE_TEMPLATE_RESOLVER = `() => document.querySelector('meta[name="takt:route"]')?.getAttribute('content') ?? null`;
 function buildRuntime(options, scrubUrl) {
   const spa = options.auto !== false;
   const json = JSON.stringify({ ...options, auto: false }).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
-  const config = scrubUrl ? `Object.assign(${json}, { scrubUrl: ${scrubUrl.toString()} })` : json;
+  const functions = [
+    ...scrubUrl ? [`scrubUrl: ${scrubUrl.toString()}`] : [],
+    ...options.routeTemplates ? [`routeTemplate: ${ROUTE_TEMPLATE_RESOLVER}`] : []
+  ];
+  const config = functions.length ? `Object.assign(${json}, { ${functions.join(", ")} })` : json;
   return [
     `import { init, pageview } from '@vskstudio/takt-core';`,
     // SSR/prerender guard: this module is evaluated under Node when Astro
@@ -65,7 +73,7 @@ function takt(options = {}) {
 }
 
 // src/index.ts
-import { track, pageview, optOut, optIn } from "@vskstudio/takt-core";
+import { track, pageview, optOut, optIn, isOptedOut } from "@vskstudio/takt-core";
 import { createStats, PublicApiError, badgeUrl, embedUrl } from "@vskstudio/takt-core";
 export {
   PublicApiError,
@@ -75,6 +83,7 @@ export {
   createStats,
   takt as default,
   embedUrl,
+  isOptedOut,
   optIn,
   optOut,
   pageview,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vskstudio/takt-astro",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Astro integration for Takt privacy-friendly analytics",
   "license": "MIT",
   "author": "VSK Studio",
@@ -32,6 +32,7 @@
       "default": "./dist/index.js"
     },
     "./Takt.astro": "./Takt.astro",
+    "./TaktRoute.astro": "./TaktRoute.astro",
     "./Badge.astro": "./Badge.astro",
     "./Embed.astro": "./Embed.astro",
     "./package.json": "./package.json"
@@ -39,31 +40,22 @@
   "files": [
     "dist",
     "Takt.astro",
+    "TaktRoute.astro",
     "Badge.astro",
     "Embed.astro"
   ],
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "e2e": "playwright test",
-    "size": "size-limit",
-    "prepublishOnly": "pnpm build",
-    "release": "pnpm build && changeset publish"
-  },
   "peerDependencies": {
-    "@vskstudio/takt-core": ">=0.8.1",
+    "@vskstudio/takt-core": ">=0.10.0",
     "astro": ">=4"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@playwright/test": "^1.50.0",
     "@size-limit/preset-small-lib": "^11.1.6",
-    "@vskstudio/takt-core": "^0.8.1",
+    "@vskstudio/takt-core": "^0.10.0",
     "astro": "^5.0.0",
     "eslint": "^9.0.0",
     "size-limit": "^11.1.6",
@@ -72,5 +64,13 @@
     "typescript-eslint": "^8.0.0",
     "vitest": "^2.1.0"
   },
-  "packageManager": "pnpm@9.0.0"
-}
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "e2e": "playwright test",
+    "size": "size-limit",
+    "release": "pnpm build && changeset publish"
+  }
+}