@vskstudio/takt-astro 0.4.2 → 0.5.0

package/README.md

@@ -39,7 +39,7 @@ import Takt from '@vskstudio/takt-astro/Takt.astro'
 
 ## Options
 
-Both the integration and the component accept the same options:
+Both the integration and the component accept the same options, with one exception: `scrubUrl` is a function and works **only via the integration** (see the note below).
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -52,6 +52,23 @@ Both the integration and the component accept the same options:
 | `spa` | `boolean` | `true` | Track client-side navigations. |
 | `respectDnt` | `boolean` | `true` | Suppress events when Do Not Track is on. |
 | `excludeLocalhost` | `boolean` | `true` | Suppress events on localhost / private IPs. |
+| `enabled` | `boolean` | `true` | Master kill switch — set `false` to suppress every event. |
+| `sampleRate` | `number` | `1` | Fraction of visitors to track, `0`–`1`. |
+| `trackQuery` | `boolean` | `false` | Send the full query string with pageviews instead of stripping it. |
+| `queryParams` | `string[]` | – | Whitelist of query params to keep when `trackQuery` is off. |
+| `scrubUrl` | `(url: string) => string` | – | **Integration only.** Rewrite each URL before it is sent (e.g. strip a fragment or PII). See the note below. |
+| `tagged` | `boolean` | `false` | Auto-track elements marked with `data-takt-event`. |
+
+> **`scrubUrl` note.** Unlike the other options, `scrubUrl` is a **function**, so it
+> is supported **only via the integration**, not the `<Takt />` component. The
+> integration serializes config into a build-time runtime string, so `scrubUrl` is
+> stringified with `.toString()` and re-evaluated in the browser. It MUST be a
+> **self-contained** function — no closure variables or outer-scope references — and
+> must be **developer-controlled**: never build it from user input.
+>
+> The `<Takt />` component serializes its config as a JSON data island, which cannot
+> carry a function — so passing `scrubUrl` to `<Takt />` **throws at build time**
+> rather than silently doing nothing. Use the integration if you need it.
 
 ## View Transitions
 

package/Takt.astro

@@ -1,10 +1,15 @@
 ---
 // Import from the built output: the published package ships dist/ + this file,
 // not src/, so a src import would break on install.
-import { resolveOptions, type TaktOptions } from './dist/index.js'
+import { resolveOptions, assertNoScrubUrl, type TaktOptions } from './dist/index.js'
 
 type Props = TaktOptions
 
+// Fail fast: scrubUrl is a function and cannot survive the JSON data island
+// below, so accepting it here would be a silent no-op. The integration path
+// supports it (embeds it as build-time JS); the component cannot.
+assertNoScrubUrl(Astro.props)
+
 // Options travel as a JSON data island, NOT interpolated into JS, so a domain or
 // endpoint containing `</script>`/quotes can't break out. `<` is escaped so the
 // value can't terminate the island's <script> tag either.

package/dist/index.d.ts

@@ -31,7 +31,41 @@ interface TaktOptions {
     respectDnt?: boolean;
     /** Suppress events on localhost and private IP ranges. Default `true`. */
     excludeLocalhost?: boolean;
+    /** Master kill switch — when `false`, every event is suppressed. */
+    enabled?: boolean;
+    /** Fraction of visitors to track, `0`–`1`. Defaults to tracking everyone. */
+    sampleRate?: number;
+    /** Send the full query string with pageviews instead of stripping it. */
+    trackQuery?: boolean;
+    /** Whitelist of query params to keep when `trackQuery` is off. */
+    queryParams?: string[];
+    /**
+     * 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
+     * re-evaluated in the browser, so it cannot reference closure/outer-scope
+     * variables. Never build it from user input.
+     *
+     * Integration-only: a function cannot survive the `<Takt />` component's
+     * JSON data island, so it is supported solely via the `takt()` integration in
+     * `astro.config`. Passing it to `<Takt />` throws — see {@link assertNoScrubUrl}.
+     */
+    scrubUrl?: (url: string) => string;
+    /** Auto-track elements marked with `data-takt-event`. */
+    tagged?: boolean;
 }
+/**
+ * Guard the `<Takt />` component path against `scrubUrl`. The component
+ * serializes its config as a JSON data island (`JSON.stringify` → `JSON.parse`),
+ * which silently drops functions — so accepting `scrubUrl` there would be a
+ * silent no-op. Fail fast at build time and point to the integration, which
+ * embeds `scrubUrl` as build-time JS instead.
+ */
+declare function assertNoScrubUrl(options?: TaktOptions): void;
+/**
+ * Map user options to core's {@link InitOptions} for JSON serialization.
+ * `scrubUrl` is intentionally absent here — it is a function and cannot survive
+ * `JSON.stringify`, so it is threaded separately to {@link buildRuntime}.
+ */
 declare function resolveOptions(options?: TaktOptions): InitOptions;
 
 /** Pick ONE install path — this integration OR the `<Takt />` component — not both. */
@@ -42,7 +76,10 @@ declare function takt(options?: TaktOptions): AstroIntegration;
  *
  * Returned as a source string because Astro's `injectScript` and the `<Takt />`
  * component both take a raw module body.
+ *
+ * `scrubUrl` is threaded separately because it is a function: `JSON.stringify`
+ * would silently drop it, so it is embedded as raw JS via `.toString()` instead.
  */
-declare function buildRuntime(options: InitOptions): string;
+declare function buildRuntime(options: InitOptions, scrubUrl?: (url: string) => string): string;
 
-export { type TaktOptions, buildRuntime, takt as default, resolveOptions, takt };
+export { type TaktOptions, assertNoScrubUrl, buildRuntime, takt as default, resolveOptions, takt };

package/dist/index.js

@@ -1,4 +1,11 @@
 // src/options.ts
+function assertNoScrubUrl(options = {}) {
+  if (options.scrubUrl !== void 0) {
+    throw new Error(
+      "Takt: scrubUrl is a function and cannot be serialized into the <Takt /> component's config. Use the Takt integration in astro.config instead (it embeds scrubUrl as build-time JS)."
+    );
+  }
+}
 function resolveOptions(options = {}) {
   return {
     domain: options.domain,
@@ -9,20 +16,26 @@ function resolveOptions(options = {}) {
     notFound: options.track404 ?? false,
     respectDnt: options.respectDnt ?? true,
     excludeLocalhost: options.excludeLocalhost ?? true,
-    auto: options.spa ?? true
+    auto: options.spa ?? true,
+    enabled: options.enabled,
+    sampleRate: options.sampleRate,
+    trackQuery: options.trackQuery,
+    queryParams: options.queryParams,
+    tagged: options.tagged
   };
 }
 
 // src/runtime.ts
-function buildRuntime(options) {
+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;
   return [
     `import { init, pageview } from '@vskstudio/takt-core';`,
     // SSR/prerender guard: this module is evaluated under Node when Astro
     // prerenders, where window/init's browser APIs are absent.
     `if (typeof window !== 'undefined' && !window.__takt) {`,
-    `  const o = ${json};`,
+    `  const o = ${config};`,
     // Idempotent across both entry paths (integration + <Takt/>): the flag stops
     // a second boot from re-registering listeners or re-firing the initial view.
     `  window.__takt = true;`,
@@ -39,7 +52,7 @@ function buildRuntime(options) {
 
 // src/integration.ts
 function takt(options = {}) {
-  const runtime = buildRuntime(resolveOptions(options));
+  const runtime = buildRuntime(resolveOptions(options), options.scrubUrl);
   return {
     name: "@vskstudio/takt-astro",
     hooks: {
@@ -55,6 +68,7 @@ import { track, pageview, optOut, optIn } from "@vskstudio/takt-core";
 import { createStats, PublicApiError, badgeUrl, embedUrl } from "@vskstudio/takt-core";
 export {
   PublicApiError,
+  assertNoScrubUrl,
   badgeUrl,
   buildRuntime,
   createStats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vskstudio/takt-astro",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Astro integration for Takt privacy-friendly analytics",
   "license": "MIT",
   "author": "VSK Studio",
@@ -45,25 +45,15 @@
   "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.4.2",
+    "@vskstudio/takt-core": ">=0.5.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.4.2",
+    "@vskstudio/takt-core": "^0.5.0",
     "astro": "^5.0.0",
     "eslint": "^9.0.0",
     "size-limit": "^11.1.6",
@@ -72,5 +62,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"
+  }
+}