@vskstudio/takt-astro 0.6.1 → 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 +45 -14
  2. package/package.json +1 -1
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,21 +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. |
59
64
  | `exclude` | `string[]` | – | Path prefixes never tracked, e.g. `['/app', '/account']` (segment-bounded, checked at send time). |
60
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. |
61
- | `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. |
62
67
 
63
68
  > **`scrubUrl` note.** Unlike the other options, `scrubUrl` is a **function**, so it
64
69
  > is supported **only via the integration**, not the `<Takt />` component. The
@@ -77,12 +82,16 @@ Astro's client router runs several history operations per navigation (scroll-res
77
82
 
78
83
  ## Custom events
79
84
 
80
- 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):
81
86
 
82
- ```js
83
- import { track } from '@vskstudio/takt-astro'
84
-
85
- 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>
86
95
  ```
87
96
 
88
97
  ## Widgets
@@ -98,19 +107,41 @@ import Embed from '@vskstudio/takt-astro/Embed.astro'
98
107
  <Embed domain="example.com" theme="dark" />
99
108
  ```
100
109
 
101
- `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.
102
113
 
103
114
  ## Public stats
104
115
 
105
116
  `createStats` (re-exported from core) reads public analytics:
106
117
 
118
+ Every method takes the domain first and the params second — the domain is optional once `createStats` is bound to one:
119
+
107
120
  ```js
108
- import { createStats } from '@vskstudio/takt-astro'
121
+ import { createStats, PublicApiError } from '@vskstudio/takt-astro'
109
122
 
110
123
  const stats = createStats({ domain: 'example.com' })
111
- 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
+ }
112
132
  ```
113
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
+
114
145
  ## License
115
146
 
116
147
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vskstudio/takt-astro",
3
- "version": "0.6.1",
3
+ "version": "0.6.2",
4
4
  "description": "Astro integration for Takt privacy-friendly analytics",
5
5
  "license": "MIT",
6
6
  "author": "VSK Studio",