pyxis-analytics 0.5.1 → 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 +46 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,15 +11,20 @@ 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
|
|
|
@@ -31,12 +36,12 @@ showing every batch it would send, with no request leaving the page.
|
|
|
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
|
|