pyxis-analytics 0.5.0 → 0.5.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.
- package/README.md +50 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,32 +11,37 @@ without cookies, without personal data and without a single runtime dependency.*
|
|
|
11
11
|
[](https://github.com/samuelcsantana/pyxis-sdk/actions/workflows/ci.yml)
|
|
12
12
|
[](https://codecov.io/gh/samuelcsantana/pyxis-sdk)
|
|
13
13
|
[](https://github.com/samuelcsantana/pyxis-sdk/actions/workflows/codeql.yml)
|
|
14
|
+
[](https://scorecard.dev/viewer/?uri=github.com/samuelcsantana/pyxis-sdk)
|
|
14
15
|
<br>
|
|
15
16
|
[](LICENSE)
|
|
16
17
|
[](tsconfig.json)
|
|
17
18
|
[](https://www.conventionalcommits.org)
|
|
19
|
+
[](https://www.npmjs.com/package/pyxis-analytics)
|
|
20
|
+
[](docs/adr/0004-five-kilobyte-budget.md)
|
|
18
21
|
[](package.json)
|
|
22
|
+
[](https://www.npmjs.com/package/pyxis-analytics#provenance)
|
|
19
23
|
|
|
20
24
|
**[Playground](https://samuelcsantana.github.io/pyxis-sdk/)** — the real tracker in dry-run mode,
|
|
21
25
|
showing every batch it would send, with no request leaving the page.
|
|
22
26
|
|
|
27
|
+
**[Pyxis](https://pyxis-analytics.dev)** · **[Live demo](https://demo.pyxis-analytics.dev)** ·
|
|
23
28
|
**[Dashboard Storybook](https://samuelcsantana.github.io/pyxis-web/)** ·
|
|
24
29
|
**[API reference](https://samuelcsantana.github.io/pyxis-api/)**
|
|
25
30
|
|
|
26
31
|
</div>
|
|
27
32
|
|
|
28
33
|
> **Status:** `pyxis-analytics` is on npm, every release published from GitHub Actions with
|
|
29
|
-
> provenance, and measures
|
|
30
|
-
> API's contract on each push (see [Roadmap](#roadmap)).
|
|
34
|
+
> provenance, and measures sites in production, the Pyxis home page among them. Every function
|
|
35
|
+
> below is validated against the API's contract on each push (see [Roadmap](#roadmap)).
|
|
31
36
|
|
|
32
37
|
## Ecosystem
|
|
33
38
|
|
|
34
|
-
| Repository | Role
|
|
35
|
-
| -------------------------------------------------------- |
|
|
36
|
-
| [pyxis-api](https://github.com/samuelcsantana/pyxis-api) | Ingestion,
|
|
37
|
-
| **pyxis-sdk** (this one) | Browser tracker published to npm as `pyxis-analytics`
|
|
38
|
-
| [pyxis-web](https://github.com/samuelcsantana/pyxis-web) | The dashboard
|
|
39
|
-
| [pyxis-mcp](https://github.com/samuelcsantana/pyxis-mcp) | MCP server: Claude and other agents read the dashboard's numbers
|
|
39
|
+
| Repository | Role |
|
|
40
|
+
| -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
41
|
+
| [pyxis-api](https://github.com/samuelcsantana/pyxis-api) | Ingestion, sign-in, dashboard queries, accounts and billing, erasure, the MCP endpoint |
|
|
42
|
+
| **pyxis-sdk** (this one) | Browser tracker published to npm as `pyxis-analytics` |
|
|
43
|
+
| [pyxis-web](https://github.com/samuelcsantana/pyxis-web) | The dashboard and the home page |
|
|
44
|
+
| [pyxis-mcp](https://github.com/samuelcsantana/pyxis-mcp) | MCP server: Claude and other agents read the dashboard's numbers |
|
|
40
45
|
|
|
41
46
|
## Why it exists
|
|
42
47
|
|
|
@@ -53,6 +58,36 @@ author's blog, also in [Portuguese][post-pt] and [Spanish][post-es].
|
|
|
53
58
|
[post-pt]: https://www.samuelsantana.dev/blog/pyxis-analytics-sem-cookie-sem-ip-sem-dado-pessoal
|
|
54
59
|
[post-es]: https://www.samuelsantana.dev/es/blog/pyxis-analytics-sin-cookies-sin-ip-sin-datos-personales
|
|
55
60
|
|
|
61
|
+
## Install
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm install pyxis-analytics
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Sign up at [app.pyxis-analytics.dev](https://app.pyxis-analytics.dev/sign-up) (the free plan needs
|
|
68
|
+
no card), create a project and call `init` once when the site loads, with the project's public key.
|
|
69
|
+
The project's Install page shows these snippets with its key already in them.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import { init } from 'pyxis-analytics';
|
|
73
|
+
|
|
74
|
+
init({ key: 'pyxis_pk_…', endpoint: 'https://api.pyxis-analytics.dev' });
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Without a bundler, load the same module from jsDelivr. `@0.5` follows the patches of that minor
|
|
78
|
+
version; the Install page pins the exact one:
|
|
79
|
+
|
|
80
|
+
```html
|
|
81
|
+
<script type="module">
|
|
82
|
+
import { init } from 'https://cdn.jsdelivr.net/npm/pyxis-analytics@0.5/dist/index.js';
|
|
83
|
+
init({ key: 'pyxis_pk_…', endpoint: 'https://api.pyxis-analytics.dev' });
|
|
84
|
+
</script>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
A self-hosted Pyxis passes its own API as `endpoint`. A coding agent asked to install Pyxis can
|
|
88
|
+
follow [llms.txt](https://pyxis-analytics.dev/llms.txt), which also lists the rules an
|
|
89
|
+
integration must keep.
|
|
90
|
+
|
|
56
91
|
## API
|
|
57
92
|
|
|
58
93
|
```ts
|
|
@@ -60,7 +95,7 @@ import { init, track, identify, reset } from 'pyxis-analytics';
|
|
|
60
95
|
|
|
61
96
|
init({
|
|
62
97
|
key: 'pyxis_pk_…',
|
|
63
|
-
endpoint: 'https://api.pyxis.
|
|
98
|
+
endpoint: 'https://api.pyxis-analytics.dev',
|
|
64
99
|
pathRules: ['/orders/:id'],
|
|
65
100
|
});
|
|
66
101
|
|
|
@@ -82,7 +117,7 @@ reset();
|
|
|
82
117
|
| Option | Default | Meaning |
|
|
83
118
|
| --------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
|
|
84
119
|
| `key` | required | The project's public key; empty or missing disables the SDK without an error |
|
|
85
|
-
| `endpoint` | required | The API's base URL, `http` or `https`
|
|
120
|
+
| `endpoint` | required | The API's base URL, `http` or `https`: `https://api.pyxis-analytics.dev`, or a self-hosted one |
|
|
86
121
|
| `pathRules` | `[]` | Templates tried before the default rules: `'/blog/:slug'` turns `/blog/hello` into `/blog/:slug` |
|
|
87
122
|
| `autoPageViews` | `true` | Record the landing page and every History API route change as a `page_view` |
|
|
88
123
|
| `referrer` | `document.referrer` | The address the visitor came from, for the first page view; `''` means none |
|
|
@@ -99,7 +134,7 @@ the visitor came from is lost and the visit counts as direct. Keep the first pag
|
|
|
99
134
|
`init` on the page it opens:
|
|
100
135
|
|
|
101
136
|
```ts
|
|
102
|
-
init({ key: 'pyxis_pk_…', endpoint: 'https://api.pyxis.
|
|
137
|
+
init({ key: 'pyxis_pk_…', endpoint: 'https://api.pyxis-analytics.dev', referrer: carriedReferrer });
|
|
103
138
|
```
|
|
104
139
|
|
|
105
140
|
Call `identify(userId)` on every load of the signed-in part of the site, not only right after
|
|
@@ -193,7 +228,8 @@ that tests replace with fakes ([ADR 0002](docs/adr/0002-functional-core.md)).
|
|
|
193
228
|
## Tech stack
|
|
194
229
|
|
|
195
230
|
TypeScript 6 (strict) · esbuild (one minified ES module) · Vitest 5 with jsdom · GitHub Actions
|
|
196
|
-
with CodeQL, Dependabot, Codecov and release-please · npm trusted publishing
|
|
231
|
+
with CodeQL, OpenSSF Scorecard, Dependabot, Codecov and release-please · npm trusted publishing
|
|
232
|
+
with provenance.
|
|
197
233
|
|
|
198
234
|
## Getting started
|
|
199
235
|
|
|
@@ -264,6 +300,8 @@ against the upstream document, so a breaking change in the API shows up here the
|
|
|
264
300
|
- [x] Playground on GitHub Pages
|
|
265
301
|
- [x] `trackingStatus()` for opt-out switches
|
|
266
302
|
- [x] Browsers driven by automation are not measured
|
|
303
|
+
- [x] `referrer` option, for a first page reached through a redirect
|
|
304
|
+
- [x] A page sends nothing more after the API refuses its batch
|
|
267
305
|
|
|
268
306
|
## Contributing and license
|
|
269
307
|
|