@jayfarei/lazyanalytics 0.1.0 → 0.3.0

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 (15) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +67 -9
  3. package/cli/dist/commands/active.d.ts +2 -0
  4. package/cli/dist/commands/active.js +30 -0
  5. package/cli/dist/commands/base.js +9 -83
  6. package/cli/dist/commands/setup.js +15 -2
  7. package/cli/dist/index.js +11 -0
  8. package/cli/dist/lib/api.d.ts +10 -0
  9. package/cli/dist/lib/api.js +78 -3
  10. package/cli/dist/lib/wrangler.d.ts +2 -0
  11. package/cli/dist/lib/wrangler.js +26 -0
  12. package/dist/worker.js +724 -52
  13. package/package.json +1 -1
  14. package/skill/SKILL.md +15 -1
  15. package/templates/wrangler.toml +3 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jayfarei/lazyanalytics",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "Agent-first web analytics on Cloudflare Workers + Analytics Engine. Self-hosted, privacy-friendly, queryable from the command line.",
5
5
  "license": "MIT",
6
6
  "author": "JayFarei",
package/skill/SKILL.md CHANGED
@@ -7,7 +7,7 @@ description: |
7
7
  user asks about website traffic ("how is my site doing", "pageviews for"), wants to set
8
8
  up or deploy analytics, add/remove a tracked site, get a tracking snippet, or check
9
9
  analytics usage and cost.
10
- version: 0.1.0
10
+ version: 0.3.0
11
11
  ---
12
12
 
13
13
  # lazyanalytics
@@ -60,6 +60,12 @@ Tracking snippet shape (place in the site's `<head>`):
60
60
  <script defer id="analytics" data-site-id="example.com" src="https://lazyanalytics.YOUR-SUBDOMAIN.workers.dev/tracker.js"></script>
61
61
  ```
62
62
 
63
+ To instrument a site, get the exact tag with `snippet -s <site>`, then add it once to the
64
+ global `<head>` (Astro base layout; Next.js App Router `app/layout.tsx` or Pages
65
+ `pages/_document.tsx` `<Head>`; plain HTML the shared header). It must appear once per page,
66
+ needs no cookie/consent banner (no cookies, no PII), and `data-site-id` must exactly match a
67
+ site in `ALLOWED_SITES`. After it ships, confirm with `stats -s <site> -p today`.
68
+
63
69
  ## 4. Querying
64
70
 
65
71
  All query commands: `npx @jayfarei/lazyanalytics <command> -s example.com [options]`
@@ -67,9 +73,15 @@ All query commands: `npx @jayfarei/lazyanalytics <command> -s example.com [optio
67
73
  | Command | Returns | Extra options |
68
74
  |---|---|---|
69
75
  | `stats` | Pageviews, approx visitors, avg screen width | — |
76
+ | `active` | Current active visitors | `--window 1..60` (default `5`) |
70
77
  | `pages` | Top pages by view count | — |
71
78
  | `referrers` | Top referrer domains | — |
72
79
  | `geo` | Breakdown by country | — |
80
+ | `channels` | Pageview-scoped acquisition channels | — |
81
+ | `crawlers` | JS-executing AI crawler/agent breakdown | `--type name\|operator\|class` |
82
+ | `bounce` | Approximate bounce rate | Returns `null` when sampled |
83
+ | `duration` | Average session duration, seconds | — |
84
+ | `history` | Live + R2 archive history | `--dimension totals\|pages\|referrers\|geo\|browsers`, `--days`, or `--from`/`--to` |
73
85
  | `browsers` | Browser/OS/device breakdown | `--type browser\|os\|device` (default `browser`) |
74
86
  | `timeseries` | Pageviews over time | `--unit hour\|day` (default `day`) |
75
87
  | `usage` | Worker request usage, free-plan headroom, est. cost | `-p today\|7d\|30d` (default `today`), `-w/--worker <name>`; needs `CF_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN`, not the analytics token |
@@ -98,6 +110,8 @@ Exit codes:
98
110
 
99
111
  Sampling: Analytics Engine samples data under load. If `meta.sampled` is `true`,
100
112
  numbers are extrapolated estimates — say so when reporting them to the user.
113
+ For bounce, sampled data returns `bounce_rate: null` because sampled row counts
114
+ make single-page session detection unreliable.
101
115
 
102
116
  ## 6. Error handling
103
117
 
package/templates/wrangler.toml CHANGED
@@ -8,7 +8,10 @@ compatibility_date = "2026-03-01"
8
8
  [vars]
9
9
  # Comma-separated list of sites to track
10
10
  ALLOWED_SITES = "__ALLOWED_SITES__"
11
+ TRACK_AI_CRAWLERS = "__TRACK_AI_CRAWLERS__"
11
12
 
12
13
  [[analytics_engine_datasets]]
13
14
  binding = "ANALYTICS"
14
15
  dataset = "agent_analytics"
16
+
17
+ __ARCHIVE_CONFIG__