@vskstudio/takt-astro 0.9.1 → 0.10.0

package/README.md

@@ -1,9 +1,9 @@
 # @vskstudio/takt-astro
 
 
-> 📚 **Documentation** — [taktlytics.com/docs/wrappers/astro](https://taktlytics.com/docs/wrappers/astro)
+> 📚 **Documentation**: [taktlytics.com/docs/wrappers/astro](https://taktlytics.com/docs/wrappers/astro)
 
-Astro integration for [Takt](https://github.com/taktlytics/takt-core), privacy-friendly analytics. It injects a tiny browser runtime that boots Takt, fires the initial pageview, and tracks client-side navigations — including [Astro View Transitions](https://docs.astro.build/en/guides/view-transitions/).
+Astro integration for [Takt](https://github.com/taktlytics/takt-core), privacy-friendly analytics. It injects a tiny browser runtime that boots Takt, fires the initial pageview, and tracks client-side navigations, including [Astro View Transitions](https://docs.astro.build/en/guides/view-transitions/).
 
 ## Install
 
@@ -11,11 +11,11 @@ Astro integration for [Takt](https://github.com/taktlytics/takt-core), privacy-f
 pnpm add @vskstudio/takt-astro @vskstudio/takt-core
 ```
 
-Both are peer dependencies: `astro` (`>=4`) and `@vskstudio/takt-core` (`>=0.10.0`).
+Both are peer dependencies: `astro` (`>=4`) and `@vskstudio/takt-core` (`>=0.12.1`).
 
 ## Usage
 
-Pick **one** of the two paths below — not both. Both boot core's default instance, guarded by a shared `window.__takt` flag: installing both does not double-count (the second boot is skipped), but it ships the runtime twice for nothing.
+Pick **one** of the two paths below, not both. Both boot core's default instance, guarded by a shared `window.__takt` flag: installing both does not double-count (the second boot is skipped), but it ships the runtime twice for nothing.
 
 ### Integration (recommended)
 
@@ -50,21 +50,23 @@ Both the integration and the component accept the same options, with one excepti
 | --- | --- | --- | --- |
 | `domain` | `string` | `location.hostname` | Site identifier sent with every event. |
 | `endpoint` | `string` | `https://taktlytics.com/api/event` | Ingestion endpoint. Pass `/api/event` for a same-origin first-party proxy. |
-| `scriptOrigin` | `string` | – | First-party origin to derive the endpoint from (`{origin}/api/event`) — your Takt domain or a custom domain to dodge ad-blockers (endpoint wins over it). |
+| `scriptOrigin` | `string` | n/a | First-party origin to derive the endpoint from (`{origin}/api/event`): your Takt domain or a custom domain to dodge ad-blockers (endpoint wins over it). |
 | `outbound` | `boolean` | `false` | Auto-track outbound link clicks. |
-| `files` | `boolean` | `false` | Auto-track file downloads, using core's default extension list (this integration does not expose an extension override). |
+| `files` | `boolean` | `false` | Auto-track file downloads. Narrow the extensions with `fileExtensions`. |
+| `fileExtensions` | `string[]` | core's list | File extensions counted as downloads when `files` is on, e.g. `['pdf', 'zip']`. |
 | `track404` | `boolean` | `false` | Report a `404` event when the page is an error page (`[data-takt-404]` / `<meta name="takt:404">` marker, or a 404 HTTP status). |
 | `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`. |
+| `enabled` | `boolean` | `true` | Master kill switch: set `false` to suppress every event. |
+| `sampleRate` | `number` | `1` | Fraction of visitors to track, `0` to `1`. |
 | `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). |
+| `queryParams` | `string[]` | n/a | Allowlist of query params to keep, applied only when `trackQuery` is off. |
+| `exclude` | `string[]` | n/a | Path prefixes never tracked, e.g. `['/app', '/account']`. Segment-bounded, case-insensitive, blind to a trailing slash, and matched on the percent-decoded path (checked at send time). |
 | `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). |
+| `redactUndecodablePaths` | `boolean` | `true` | When a route is configured, a path that cannot be decoded is sent as `/[redacted]`. Set `false` to decode it leniently and match it against the routes instead. |
 | `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. |
+| `scrubUrl` | `(url: string) => string` | n/a | **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. |
 
@@ -72,16 +74,38 @@ Both the integration and the component accept the same options, with one excepti
 > 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
+> **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**
+> carry a function. So passing `scrubUrl` to `<Takt />` **throws at build time**
 > rather than silently doing nothing. Use the integration if you need it.
 
+### Examples
+
+Downloads of selected file types only, with `files` on and `fileExtensions` narrowing the default list:
+
+```js
+takt({ files: true, fileExtensions: ['pdf', 'zip'] })
+```
+
+Count 404 pages (the page must carry the `[data-takt-404]` marker or answer with a 404 status):
+
+```js
+takt({ track404: true })
+```
+
+Keep the real path for any route that does not decode, by setting `redactUndecodablePaths: false` (the default `true` sends it as `/[redacted]`):
+
+```js
+takt({ redactRoutes: ['/verify/[token]'], redactUndecodablePaths: false })
+```
+
+The same settings exist as attributes of the standalone `takt.auto.js` script: `redactRoutes` is `data-redact-routes`, `redactUndecodablePaths` is `data-redact-undecodable-paths`, `fileExtensions` is `data-downloads-ext`, and the opt-in features are listed in `data-auto` (`outbound`, `downloads` for `files`, `tagged`, `404` for `track404`).
+
 ## View Transitions
 
-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.
+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
 
@@ -91,7 +115,9 @@ Query strings are stripped by default, but path segments are sent as they are, s
 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 `*`.
+The rule covers the page URL, same-origin referrers, outbound and download link destinations, and 404 paths. Patterns use Astro's syntax (`[param]`, `[[optional]]`, `[...rest]`), the Vue / React / Angular / Solid syntax (`:param`, `:param?`, `*`, `**`), and the Laravel / Symfony braces (`{param}`, `{param?}`, `{param<regex>}`). Matching is case-insensitive and runs on the decoded path.
+
+A `{param<regex>}` constraint must follow a restricted grammar (printable ASCII, literals, `.`, `\d`, `\w`, `\s` and their negations, character classes, top-level alternation, bounded quantifiers). A route whose constraint falls outside it is never sent raw: every matching path is masked as `/[redacted]`. A path that cannot be decoded follows `redactUndecodablePaths` (see the options table).
 
 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:
 
@@ -166,15 +192,15 @@ import Embed from '@vskstudio/takt-astro/Embed.astro'
 <Embed domain="example.com" theme="dark" />
 ```
 
-`Badge` renders an `<img>` (props: `domain` — required —, `variant` `a` | `b` | `d`, `glyph` `unplug` | `dash` | `off` | `eyeoff`, `lang` `fr` | `en`, `host`). Its `alt` defaults to `"takt"` and can be overridden; `loading="lazy"` and `decoding="async"` are applied after your attributes and cannot.
+`Badge` renders an `<img>` (props: `domain` (required), `variant` `a` | `b` | `d`, `glyph` `unplug` | `dash` | `off` | `eyeoff`, `lang` `fr` | `en`, `host`). Its `alt` defaults to `"takt"` and can be overridden; `loading="lazy"` and `decoding="async"` are applied after your attributes and cannot.
 
-`Embed` renders an `<iframe>` (props: `domain` — required —, `theme` `light` | `dark` | `auto`, `lang`, `host`, plus `width` = `404`, `height` = `264`, `title` = `"takt"`); the iframe is sandboxed (`allow-scripts allow-same-origin`) and ships a fixed `referrerpolicy="strict-origin-when-cross-origin"`, a `loading="lazy"` and a zero border — all applied after your attributes, so a consumer cannot weaken them. Extra attributes pass through to the underlying element, but the built `src` is locked and cannot be overridden. The optional `host` must be an absolute `http(s)` URL — core validates it and throws on anything else (e.g. a `javascript:` URL), and reduces it to its origin (dropping path/query). Omitting `host` falls back to the hosted Takt origin (`https://taktlytics.com`), not to the current origin.
+`Embed` renders an `<iframe>` (props: `domain` (required), `theme` `light` | `dark` | `auto`, `lang`, `host`, plus `width` = `404`, `height` = `264`, `title` = `"takt"`); the iframe is sandboxed (`allow-scripts allow-same-origin`) and ships a fixed `referrerpolicy="strict-origin-when-cross-origin"`, a `loading="lazy"` and a zero border: all applied after your attributes, so a consumer cannot weaken them. Extra attributes pass through to the underlying element, but the built `src` is locked and cannot be overridden. The optional `host` must be an absolute `http(s)` URL. Core validates it and throws on anything else (e.g. a `javascript:` URL), and reduces it to its origin (dropping path/query). Omitting `host` falls back to the hosted Takt origin (`https://taktlytics.com`), not to the current origin.
 
 ## Public stats
 
 `createStats` (re-exported from core) reads public analytics:
 
-Every method takes the domain first and the params second — the domain is optional once `createStats` is bound to one:
+Every method takes the domain first and the params second: the domain is optional once `createStats` is bound to one:
 
 ```js
 import { createStats, PublicApiError } from '@vskstudio/takt-astro'
@@ -194,10 +220,10 @@ try {
 
 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`, `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
+- `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`, `isOptedOut`, `createStats`, `PublicApiError`, `badgeUrl`, `embedUrl`, `normalizeHost`
+- Types: `TaktOptions`, plus `InitOptions`, `TrackOptions`, `Payload`, `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`, `/TaktRoute.astro`, `/Badge.astro`, `/Embed.astro`.
 

package/Takt.astro

@@ -21,7 +21,7 @@ const config = JSON.stringify(resolveOptions(Astro.props))
 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. -->
+<!-- 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
      is:inline module would leave it unresolved in the browser. -->

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, isOptedOut, optIn, optOut, pageview, track } from '@vskstudio/takt-core';
+export { BadgeGlyph, BadgeOptions, BadgeVariant, EmbedOptions, EmbedTheme, InitOptions, Payload, PublicApiError, StatsBreakdown, StatsBreakdownRow, StatsClient, StatsClientOptions, StatsDimension, StatsMetrics, StatsParams, StatsPeriod, StatsPoint, StatsRealtime, StatsSummary, StatsTimeseries, TrackOptions, WidgetLang, badgeUrl, createStats, embedUrl, isOptedOut, normalizeHost, optIn, optOut, pageview, track } from '@vskstudio/takt-core';
 
 /**
  * Options for the Takt integration and `<Takt />` component. Mirrors core's
@@ -12,7 +12,7 @@ interface TaktOptions {
     /** Ingestion endpoint. Defaults to `https://taktlytics.com/api/event` (the hosted Takt origin); pass `/api/event` for a same-origin first-party proxy. */
     endpoint?: string;
     /**
-     * First-party origin to derive the endpoint from (`{origin}/api/event`) — a
+     * First-party origin to derive the endpoint from (`{origin}/api/event`): a
      * custom domain you proxy through to dodge ad-blockers. `endpoint` wins over it.
      */
     scriptOrigin?: string;
@@ -20,6 +20,7 @@ interface TaktOptions {
     outbound?: boolean;
     /** Auto-track file downloads. */
     files?: boolean;
+    fileExtensions?: string[];
     /**
      * Report a `404` event when the page is an error page (`[data-takt-404]` /
      * `<meta name="takt:404">` marker, or a 404 HTTP status).
@@ -31,9 +32,9 @@ 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. */
+    /** Master kill switch: when `false`, every event is suppressed. */
     enabled?: boolean;
-    /** Fraction of visitors to track, `0`–`1`. Defaults to tracking everyone. */
+    /** Fraction of visitors to track, `0` to `1`. Defaults to tracking everyone. */
     sampleRate?: number;
     /** Send the full query string with pageviews instead of stripping it. */
     trackQuery?: boolean;
@@ -42,6 +43,7 @@ interface TaktOptions {
     /** Path prefixes never tracked, e.g. `['/app','/account']`. Segment-bounded: `'/app'` matches `'/app'` and `'/app/…'` but not `'/application'`. */
     exclude?: string[];
     redactRoutes?: string[];
+    redactUndecodablePaths?: boolean;
     routeTemplates?: boolean;
     /**
      * Rewrite each URL before it is sent (e.g. strip a fragment or PII).
@@ -51,7 +53,7 @@ interface TaktOptions {
      *
      * 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}.
+     * `astro.config`. Passing it to `<Takt />` throws: see {@link assertNoScrubUrl}.
      */
     scrubUrl?: (url: string) => string;
     /** Auto-track elements marked with `data-takt-event`. */
@@ -61,19 +63,19 @@ interface TaktOptions {
 /**
  * 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
+ * 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
+ * `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. */
+/** Pick ONE install path: this integration OR the `<Takt />` component, not both. */
 declare function takt(options?: TaktOptions): AstroIntegration;
 
 /**

package/dist/index.js

@@ -13,6 +13,7 @@ function resolveOptions(options = {}) {
     scriptOrigin: options.scriptOrigin,
     outbound: options.outbound ?? false,
     files: options.files ?? false,
+    fileExtensions: options.fileExtensions,
     notFound: options.track404 ?? false,
     respectDnt: options.respectDnt ?? true,
     excludeLocalhost: options.excludeLocalhost ?? true,
@@ -23,6 +24,7 @@ function resolveOptions(options = {}) {
     queryParams: options.queryParams,
     exclude: options.exclude,
     redactRoutes: options.redactRoutes,
+    redactUndecodablePaths: options.redactUndecodablePaths,
     routeTemplates: options.routeTemplates,
     tagged: options.tagged,
     debug: options.debug
@@ -74,7 +76,7 @@ function takt(options = {}) {
 
 // src/index.ts
 import { track, pageview, optOut, optIn, isOptedOut } from "@vskstudio/takt-core";
-import { createStats, PublicApiError, badgeUrl, embedUrl } from "@vskstudio/takt-core";
+import { createStats, PublicApiError, badgeUrl, embedUrl, normalizeHost } from "@vskstudio/takt-core";
 export {
   PublicApiError,
   assertNoScrubUrl,
@@ -84,6 +86,7 @@ export {
   takt as default,
   embedUrl,
   isOptedOut,
+  normalizeHost,
   optIn,
   optOut,
   pageview,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vskstudio/takt-astro",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Astro integration for Takt privacy-friendly analytics",
   "license": "MIT",
   "author": "VSK Studio",
@@ -58,14 +58,14 @@
     "release": "pnpm build && changeset publish"
   },
   "peerDependencies": {
-    "@vskstudio/takt-core": ">=0.11.0",
+    "@vskstudio/takt-core": ">=0.12.1",
     "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.11.0",
+    "@vskstudio/takt-core": "^0.12.1",
     "astro": "^5.0.0",
     "eslint": "^9.0.0",
     "size-limit": "^11.1.6",