@vskstudio/takt-astro 0.6.1 → 0.7.0

package/README.md

@@ -1,5 +1,8 @@
 # @vskstudio/takt-astro
 
+
+> 📚 **Documentation** — [taktlytics.com/docs/wrappers/astro](https://taktlytics.com/docs/wrappers/astro)
+
 Astro integration for [Takt](https://github.com/vskstudio/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
@@ -8,9 +11,11 @@ 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.9.0`).
+
 ## Usage
 
-Pick **one** of the two paths below — not both. Both boot core's default instance, so combining them would just re-initialise.
+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)
 
@@ -44,21 +49,22 @@ Both the integration and the component accept the same options, with one excepti
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `domain` | `string` | `location.hostname` | Site identifier sent with every event. |
-| `endpoint` | `string` | `/api/event` | Ingestion endpoint. |
+| `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). |
 | `outbound` | `boolean` | `false` | Auto-track outbound link clicks. |
-| `files` | `boolean` | `false` | Auto-track file downloads. |
+| `files` | `boolean` | `false` | Auto-track file downloads, using core's default extension list (this integration does not expose an extension override). |
 | `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`. |
-| `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. |
+| `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. |
-| `tagged` | `boolean` | `false` | Auto-track elements marked with `data-takt-event`. |
+| `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
@@ -77,12 +83,36 @@ Astro's client router runs several history operations per navigation (scroll-res
 
 ## Custom events
 
-Re-exported from core for convenience:
+`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):
 
-```js
-import { track } from '@vskstudio/takt-astro'
+```astro
+<button id="signup">Sign up</button>
+<script>
+  import { track } from '@vskstudio/takt-astro'
+  document.getElementById('signup')?.addEventListener('click', () => {
+    track('Signup', { props: { plan: 'pro' }, revenue: { amount: '9.00', currency: 'USD' } })
+  })
+</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.
 
-track('Signup', { revenue: { amount: '9.00', currency: 'USD' } })
+```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
@@ -98,19 +128,41 @@ import Embed from '@vskstudio/takt-astro/Embed.astro'
 <Embed domain="example.com" theme="dark" />
 ```
 
-`Badge` renders an `<img>` (props: `domain`, `variant`, `glyph`, `lang`, `host`). Its `alt` defaults to `"takt"` and can be overridden. `Embed` renders an `<iframe>` (props: `domain`, `theme`, `lang`, `host`, `width`, `height`, `title`); the iframe is sandboxed (`allow-scripts allow-same-origin`) and ships a fixed `referrerpolicy="strict-origin-when-cross-origin"` — both are locked and cannot be weakened by a consumer. 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). An empty `host` resolves same-origin.
+`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.
 
 ## 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:
+
 ```js
-import { createStats } from '@vskstudio/takt-astro'
+import { createStats, PublicApiError } from '@vskstudio/takt-astro'
 
 const stats = createStats({ domain: 'example.com' })
-const summary = await stats.summary({ period: '7d' })
+
+try {
+  const summary = await stats.summary(undefined, { period: '7d' })
+  const rows = await stats.breakdown('page', undefined, { period: '7d' })
+  const live = await stats.realtime()
+} catch (err) {
+  if (err instanceof PublicApiError) console.error(err.status, err.message)
+}
 ```
 
+## Public exports
+
+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
+
+Component subpaths: `@vskstudio/takt-astro/Takt.astro`, `/Badge.astro`, `/Embed.astro`.
+
 ## License
 
 MIT

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
@@ -54,6 +54,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,7 +22,8 @@ function resolveOptions(options = {}) {
     trackQuery: options.trackQuery,
     queryParams: options.queryParams,
     exclude: options.exclude,
-    tagged: options.tagged
+    tagged: options.tagged,
+    debug: options.debug
   };
 }
 
@@ -65,7 +66,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 +76,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.1",
+  "version": "0.7.0",
   "description": "Astro integration for Takt privacy-friendly analytics",
   "license": "MIT",
   "author": "VSK Studio",
@@ -56,14 +56,14 @@
     "release": "pnpm build && changeset publish"
   },
   "peerDependencies": {
-    "@vskstudio/takt-core": ">=0.8.1",
+    "@vskstudio/takt-core": ">=0.9.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.9.0",
     "astro": "^5.0.0",
     "eslint": "^9.0.0",
     "size-limit": "^11.1.6",