@vskstudio/takt-astro 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +46 -14
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,5 +1,8 @@
1
1
  # @vskstudio/takt-astro
2
2
 
3
+
4
+ > 📚 **Documentation** — [taktlytics.com/docs/wrappers/astro](https://taktlytics.com/docs/wrappers/astro)
5
+
3
6
  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/).
4
7
 
5
8
  ## Install
@@ -8,9 +11,11 @@ Astro integration for [Takt](https://github.com/vskstudio/takt-core), privacy-fr
8
11
  pnpm add @vskstudio/takt-astro @vskstudio/takt-core
9
12
  ```
10
13
 
14
+ Both are peer dependencies: `astro` (`>=4`) and `@vskstudio/takt-core` (`>=0.8.1`).
15
+
11
16
  ## Usage
12
17
 
13
- Pick **one** of the two paths below — not both. Both boot core's default instance, so combining them would just re-initialise.
18
+ 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.
14
19
 
15
20
  ### Integration (recommended)
16
21
 
@@ -44,20 +49,21 @@ Both the integration and the component accept the same options, with one excepti
44
49
  | Option | Type | Default | Description |
45
50
  | --- | --- | --- | --- |
46
51
  | `domain` | `string` | `location.hostname` | Site identifier sent with every event. |
47
- | `endpoint` | `string` | `/api/event` | Ingestion endpoint. |
52
+ | `endpoint` | `string` | `https://taktlytics.com/api/event` | Ingestion endpoint. Pass `/api/event` for a same-origin first-party proxy. |
48
53
  | `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). |
49
54
  | `outbound` | `boolean` | `false` | Auto-track outbound link clicks. |
50
- | `files` | `boolean` | `false` | Auto-track file downloads. |
55
+ | `files` | `boolean` | `false` | Auto-track file downloads, using core's default extension list (this integration does not expose an extension override). |
51
56
  | `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). |
52
57
  | `spa` | `boolean` | `true` | Track client-side navigations. |
53
58
  | `respectDnt` | `boolean` | `true` | Suppress events when Do Not Track is on. |
54
59
  | `excludeLocalhost` | `boolean` | `true` | Suppress events on localhost / private IPs. |
55
60
  | `enabled` | `boolean` | `true` | Master kill switch — set `false` to suppress every event. |
56
61
  | `sampleRate` | `number` | `1` | Fraction of visitors to track, `0`–`1`. |
57
- | `trackQuery` | `boolean` | `false` | Send the full query string with pageviews instead of stripping it. |
58
- | `queryParams` | `string[]` | – | Whitelist of query params to keep when `trackQuery` is off. |
62
+ | `trackQuery` | `boolean` | `false` | Keep the full query string and hash instead of stripping them. Wins over `queryParams`. |
63
+ | `queryParams` | `string[]` | – | Allowlist of query params to keep, applied only when `trackQuery` is off. |
64
+ | `exclude` | `string[]` | – | Path prefixes never tracked, e.g. `['/app', '/account']` (segment-bounded, checked at send time). |
59
65
  | `scrubUrl` | `(url: string) => string` | – | **Integration only.** Rewrite each URL before it is sent (e.g. strip a fragment or PII). See the note below. |
60
- | `tagged` | `boolean` | `false` | Auto-track elements marked with `data-takt-event`. |
66
+ | `tagged` | `boolean` | `false` | Auto-track clicks on `[data-takt-event]` elements; `data-takt-prop-*` attributes become event props. |
61
67
 
62
68
  > **`scrubUrl` note.** Unlike the other options, `scrubUrl` is a **function**, so it
63
69
  > is supported **only via the integration**, not the `<Takt />` component. The
@@ -76,12 +82,16 @@ Astro's client router runs several history operations per navigation (scroll-res
76
82
 
77
83
  ## Custom events
78
84
 
79
- Re-exported from core for convenience:
85
+ `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):
80
86
 
81
- ```js
82
- import { track } from '@vskstudio/takt-astro'
83
-
84
- track('Signup', { revenue: { amount: '9.00', currency: 'USD' } })
87
+ ```astro
88
+ <button id="signup">Sign up</button>
89
+ <script>
90
+ import { track } from '@vskstudio/takt-astro'
91
+ document.getElementById('signup')?.addEventListener('click', () => {
92
+ track('Signup', { props: { plan: 'pro' }, revenue: { amount: '9.00', currency: 'USD' } })
93
+ })
94
+ </script>
85
95
  ```
86
96
 
87
97
  ## Widgets
@@ -97,19 +107,41 @@ import Embed from '@vskstudio/takt-astro/Embed.astro'
97
107
  <Embed domain="example.com" theme="dark" />
98
108
  ```
99
109
 
100
- `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.
110
+ `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.
111
+
112
+ `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.
101
113
 
102
114
  ## Public stats
103
115
 
104
116
  `createStats` (re-exported from core) reads public analytics:
105
117
 
118
+ Every method takes the domain first and the params second — the domain is optional once `createStats` is bound to one:
119
+
106
120
  ```js
107
- import { createStats } from '@vskstudio/takt-astro'
121
+ import { createStats, PublicApiError } from '@vskstudio/takt-astro'
108
122
 
109
123
  const stats = createStats({ domain: 'example.com' })
110
- const summary = await stats.summary({ period: '7d' })
124
+
125
+ try {
126
+ const summary = await stats.summary(undefined, { period: '7d' })
127
+ const rows = await stats.breakdown('page', undefined, { period: '7d' })
128
+ const live = await stats.realtime()
129
+ } catch (err) {
130
+ if (err instanceof PublicApiError) console.error(err.status, err.message)
131
+ }
111
132
  ```
112
133
 
134
+ ## Public exports
135
+
136
+ From `@vskstudio/takt-astro`:
137
+
138
+ - `default` / `takt` — the integration factory (same function under both names)
139
+ - `resolveOptions`, `assertNoScrubUrl`, `buildRuntime` — the internals the `.astro` components build on, exported so you can drive the runtime yourself
140
+ - Re-exported from core: `track`, `pageview`, `optOut`, `optIn`, `createStats`, `PublicApiError`, `badgeUrl`, `embedUrl`
141
+ - 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
142
+
143
+ Component subpaths: `@vskstudio/takt-astro/Takt.astro`, `/Badge.astro`, `/Embed.astro`.
144
+
113
145
  ## License
114
146
 
115
147
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vskstudio/takt-astro",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "description": "Astro integration for Takt privacy-friendly analytics",
5
5
  "license": "MIT",
6
6
  "author": "VSK Studio",
@@ -56,14 +56,14 @@
56
56
  "release": "pnpm build && changeset publish"
57
57
  },
58
58
  "peerDependencies": {
59
- "@vskstudio/takt-core": ">=0.8.0",
59
+ "@vskstudio/takt-core": ">=0.8.1",
60
60
  "astro": ">=4"
61
61
  },
62
62
  "devDependencies": {
63
63
  "@changesets/cli": "^2.31.0",
64
64
  "@playwright/test": "^1.50.0",
65
65
  "@size-limit/preset-small-lib": "^11.1.6",
66
- "@vskstudio/takt-core": "^0.8.0",
66
+ "@vskstudio/takt-core": "^0.8.1",
67
67
  "astro": "^5.0.0",
68
68
  "eslint": "^9.0.0",
69
69
  "size-limit": "^11.1.6",