tallymark 0.0.0-stage → 0.1.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 (68) hide show
  1. package/LICENSE +661 -0
  2. package/README.md +234 -2
  3. package/SECURITY.md +37 -0
  4. package/dist/cli.d.ts +2 -0
  5. package/dist/cli.js +124 -0
  6. package/dist/cloudflare.d.ts +9 -0
  7. package/dist/cloudflare.js +53 -0
  8. package/dist/hit.d.ts +83 -0
  9. package/dist/hit.js +301 -0
  10. package/dist/http.d.ts +36 -0
  11. package/dist/http.js +393 -0
  12. package/dist/index.d.ts +7 -0
  13. package/dist/index.js +4 -0
  14. package/dist/node.d.ts +40 -0
  15. package/dist/node.js +66 -0
  16. package/dist/query.d.ts +31 -0
  17. package/dist/query.js +699 -0
  18. package/dist/react.d.ts +27 -0
  19. package/dist/react.js +34 -0
  20. package/dist/script.d.ts +17 -0
  21. package/dist/script.js +147 -0
  22. package/dist/stores.d.ts +129 -0
  23. package/dist/stores.js +393 -0
  24. package/dist/tallymark.d.ts +49 -0
  25. package/dist/tallymark.js +265 -0
  26. package/dist/types.d.ts +306 -0
  27. package/dist/types.js +1 -0
  28. package/dist/vercel.d.ts +33 -0
  29. package/dist/vercel.js +36 -0
  30. package/dist/webhook.d.ts +27 -0
  31. package/dist/webhook.js +61 -0
  32. package/docs/DEPLOYMENT.md +155 -0
  33. package/docs/HOW_IT_WORKS.md +106 -0
  34. package/docs/USAGE.md +237 -0
  35. package/examples/README.md +39 -0
  36. package/examples/browser/index.html +32 -0
  37. package/examples/browser/server.ts +34 -0
  38. package/examples/events/index.html +89 -0
  39. package/examples/events/server.ts +101 -0
  40. package/examples/frameworks/astro/[...path].ts +21 -0
  41. package/examples/frameworks/bun.ts +23 -0
  42. package/examples/frameworks/cloudflare.ts +37 -0
  43. package/examples/frameworks/deno.ts +26 -0
  44. package/examples/frameworks/express.ts +57 -0
  45. package/examples/frameworks/hono.ts +38 -0
  46. package/examples/frameworks/nextjs/app/api/analytics/[...route]/route.ts +7 -0
  47. package/examples/frameworks/nextjs/app/api/analytics-cron/route.ts +6 -0
  48. package/examples/frameworks/nextjs/app/layout.tsx +15 -0
  49. package/examples/frameworks/nextjs/app/page.tsx +21 -0
  50. package/examples/frameworks/nextjs/lib/analytics.ts +14 -0
  51. package/examples/frameworks/nextjs/vercel.json +3 -0
  52. package/examples/frameworks/react/main.tsx +32 -0
  53. package/examples/frameworks/sveltekit/+server.ts +26 -0
  54. package/examples/frameworks/vercel/api/analytics-cron.ts +9 -0
  55. package/examples/frameworks/vercel/api/analytics.ts +22 -0
  56. package/examples/frameworks/vercel/vercel.json +4 -0
  57. package/examples/http/Java.java +74 -0
  58. package/examples/http/curl.sh +46 -0
  59. package/examples/http/go.go +93 -0
  60. package/examples/http/php.php +74 -0
  61. package/examples/http/python.py +62 -0
  62. package/examples/http/ruby.rb +60 -0
  63. package/examples/library/basic.ts +95 -0
  64. package/examples/library/reports.ts +136 -0
  65. package/examples/library/stores.ts +57 -0
  66. package/examples/library/webhook-receiver.ts +30 -0
  67. package/llms.txt +235 -0
  68. package/package.json +116 -4
@@ -0,0 +1,61 @@
1
+ const enc = new TextEncoder();
2
+ async function hmacHex(secret, body) {
3
+ const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
4
+ const sig = await crypto.subtle.sign('HMAC', key, enc.encode(body));
5
+ return Array.from(new Uint8Array(sig), (b) => b.toString(16).padStart(2, '0')).join('');
6
+ }
7
+ /**
8
+ * Third-party fan-out: POST every event as JSON to any URL (Zapier, n8n, Slack
9
+ * relay, your own queue). Use as `forward`:
10
+ *
11
+ * createTallymark({ forward: webhookSink({ url, secret }) })
12
+ *
13
+ * Throws on final failure, which the engine routes to `onError`; it never fails
14
+ * the visitor's hit.
15
+ */
16
+ export function webhookSink(options) {
17
+ const f = options.fetch ?? fetch;
18
+ const attempts = 1 + Math.max(0, options.retries ?? 1);
19
+ return async (event) => {
20
+ const body = JSON.stringify({ type: 'tallymark.event', event });
21
+ const headers = {
22
+ 'content-type': 'application/json',
23
+ ...options.headers,
24
+ };
25
+ if (options.secret)
26
+ headers['x-tallymark-signature'] = `sha256=${await hmacHex(options.secret, body)}`;
27
+ let lastError;
28
+ for (let i = 0; i < attempts; i++) {
29
+ try {
30
+ const res = await f(options.url, {
31
+ method: 'POST',
32
+ headers,
33
+ body,
34
+ signal: AbortSignal.timeout(options.timeoutMs ?? 5000),
35
+ });
36
+ if (res.ok)
37
+ return;
38
+ lastError = new Error(`webhook responded ${res.status}`);
39
+ if (res.status < 500)
40
+ break; // 4xx will not get better on retry
41
+ }
42
+ catch (error) {
43
+ lastError = error;
44
+ }
45
+ }
46
+ throw lastError;
47
+ };
48
+ }
49
+ /** Verify a delivery on the receiving end. Constant-time. */
50
+ export async function verifyWebhookSignature(secret, rawBody, header) {
51
+ if (!header?.startsWith('sha256='))
52
+ return false;
53
+ const expected = await hmacHex(secret, rawBody);
54
+ const got = header.slice(7);
55
+ if (got.length !== expected.length)
56
+ return false;
57
+ let diff = 0;
58
+ for (let i = 0; i < expected.length; i++)
59
+ diff |= expected.charCodeAt(i) ^ got.charCodeAt(i);
60
+ return diff === 0;
61
+ }
@@ -0,0 +1,155 @@
1
+ # DEPLOYMENT
2
+
3
+ Pick the platform you already use. Every option serves the same routes. Examples that run are in [../examples/frameworks](../examples/frameworks).
4
+
5
+ Before anything else, in every deployment:
6
+
7
+ - Set `secret` and `apiKey` to long random values (`openssl rand -hex 32`) and keep them in your platform's secret store.
8
+ - Decide `trustProxy`. It is `true` for the library by default and `false` for the CLI. Set it to `true` only when Cloudflare, Vercel or a proxy you control sets the client-IP headers. Otherwise visitors can forge them.
9
+ - Put your site in `allowedHosts` (and turn on `strictOrigin`) so other sites cannot write to your numbers.
10
+ - Connect `onError` to a logger.
11
+ - Set `retentionDays` and arrange for `prune()` to run.
12
+
13
+ | Platform | Store | Notes |
14
+ |---|---|---|
15
+ | [Cloudflare Workers](#cloudflare-workers) | D1 | Location is built in |
16
+ | [Vercel and Next.js](#vercel-and-nextjs) | Postgres, Upstash, Turso | Location is built in |
17
+ | [Bun, Docker, any server](#bun-docker-and-any-server) | SQLite, Postgres, Upstash | |
18
+ | [Node and Express](#node-and-express) | any | |
19
+ | [Other Fetch frameworks](#other-fetch-frameworks) | any | |
20
+
21
+ ## Cloudflare Workers
22
+
23
+ ```ts
24
+ import { cloudflare } from 'tallymark/cloudflare'
25
+ import { d1Store } from 'tallymark/stores'
26
+
27
+ export default cloudflare<Env>((env) => ({
28
+ store: d1Store(env.DB),
29
+ secret: env.SECRET,
30
+ apiKey: env.API_KEY,
31
+ retentionDays: 395,
32
+ }))
33
+ ```
34
+
35
+ ```bash
36
+ wrangler d1 create stats # then bind it as DB in wrangler.toml
37
+ wrangler secret put SECRET && wrangler secret put API_KEY
38
+ wrangler deploy
39
+ ```
40
+
41
+ Add `[triggers] crons = ["0 3 * * *"]` and the adapter prunes old events daily. The table is created on first use. Country, region, city and timezone come from Cloudflare's `request.cf`, so there is nothing to configure. Work after the response (forwarding) runs through `ctx.waitUntil`. The full file is [examples/frameworks/cloudflare.ts](../examples/frameworks/cloudflare.ts).
42
+
43
+ ## Vercel and Next.js
44
+
45
+ Pick a store that suits serverless: Postgres through Neon (`pgStore(neon(url))`), Upstash Redis (`upstashRestStore`), or Turso (`libsqlStore`). Vercel provides the visitor's IP, country, region, city and timezone as headers, and Tallymark reads them.
46
+
47
+ **Next.js (App Router):**
48
+
49
+ ```ts
50
+ // lib/analytics.ts
51
+ export const analytics = createTallymark({
52
+ store: pgStore(new Pool({ connectionString: process.env.DATABASE_URL })),
53
+ secret: process.env.ANALYTICS_SECRET,
54
+ apiKey: process.env.ANALYTICS_API_KEY,
55
+ basePath: '/api/analytics',
56
+ })
57
+
58
+ // app/api/analytics/[...route]/route.ts
59
+ import { waitUntil } from '@vercel/functions'
60
+ export const { GET, POST, OPTIONS } = vercel(analytics, { waitUntil })
61
+
62
+ // app/api/analytics-cron/route.ts
63
+ export const GET = vercelCron(analytics, { secret: process.env.CRON_SECRET })
64
+
65
+ // app/layout.tsx, inside <body>
66
+ <Analytics api="/api/analytics" outbound downloads />
67
+ ```
68
+
69
+ ```json
70
+ { "crons": [{ "path": "/api/analytics-cron", "schedule": "0 3 * * *" }] }
71
+ ```
72
+
73
+ `waitUntil` is optional; with it, forwarding and mirroring continue after the response is sent. Vercel Cron sends `Authorization: Bearer $CRON_SECRET`, so set `CRON_SECRET` in the project settings; `vercelCron` refuses every call without it.
74
+
75
+ **Without a framework**, put the same `vercel(analytics)` in `/api/analytics.ts` and add a rewrite so sub-paths reach it ([example](../examples/frameworks/vercel)).
76
+
77
+ ## Bun, Docker and any server
78
+
79
+ ```bash
80
+ # A SQLite file (the default)
81
+ TALLYMARK_SECRET=… TALLYMARK_API_KEY=… bunx tallymark
82
+
83
+ # PostgreSQL
84
+ TALLYMARK_DB=postgres://user:pass@host/db bunx tallymark
85
+
86
+ # Upstash Redis
87
+ UPSTASH_REDIS_REST_URL=… UPSTASH_REDIS_REST_TOKEN=… bunx tallymark
88
+ ```
89
+
90
+ ```bash
91
+ docker build -t tallymark .
92
+ docker run -p 3000:3000 -v stats:/data \
93
+ -e TALLYMARK_SECRET=… -e TALLYMARK_API_KEY=… tallymark
94
+ ```
95
+
96
+ The image runs as an unprivileged user, keeps its data in the `/data` volume, and has a health check on `/health`. Every variable is listed in [USAGE.md](./USAGE.md#the-command-line).
97
+
98
+ ### Behind a reverse proxy
99
+
100
+ Set `TALLYMARK_TRUST_PROXY=true` **only** when a proxy you control sits in front, and make sure it overwrites client-supplied forwarding headers. Otherwise a visitor can invent their IP, which forges visitor ids and dodges the rate limit. Terminate TLS at the proxy.
101
+
102
+ ```
103
+ # Caddy: X-Forwarded-For is replaced with the real address by default
104
+ stats.example.com {
105
+ request_header -CF-Connecting-IP
106
+ request_header -X-Real-IP
107
+ reverse_proxy 127.0.0.1:3000
108
+ }
109
+ ```
110
+
111
+ ```
112
+ # nginx
113
+ location / {
114
+ proxy_set_header X-Real-IP $remote_addr;
115
+ proxy_set_header X-Forwarded-For $remote_addr;
116
+ proxy_pass http://127.0.0.1:3000;
117
+ }
118
+ ```
119
+
120
+ Without `TALLYMARK_TRUST_PROXY`, the socket address is used, which is right when the server is exposed directly.
121
+
122
+ ## Node and Express
123
+
124
+ ```ts
125
+ import { nodeHandler, nodeRequest, nodeConn } from 'tallymark/node'
126
+
127
+ app.use('/analytics', nodeHandler(analytics, { trustProxy: true })) // trustProxy only behind a proxy you control
128
+
129
+ // In your own routes:
130
+ await analytics.trackRequest(nodeRequest(req), { name: 'Subscribe' }, nodeConn(req, { trustProxy: true }))
131
+ ```
132
+
133
+ Set `basePath: '/analytics'` to match the mount path. The adapter is structural and imports nothing from Node.
134
+
135
+ ## Other Fetch frameworks
136
+
137
+ `analytics.handle` is `(Request) => Promise<Response>`, so it mounts directly. Set `basePath` to match where you mount it.
138
+
139
+ ```ts
140
+ app.all('/analytics/*', (c) => analytics.handle(c.req.raw)) // Hono
141
+ export { handler as GET, handler as POST, handler as OPTIONS } // SvelteKit +server.ts
142
+ export const ALL = ({ request }) => analytics.handle(request) // Astro
143
+ Deno.serve((req, info) => analytics.handle(req, { ip: info.remoteAddr.hostname }))
144
+ ```
145
+
146
+ ## Retention and backups
147
+
148
+ Set `retentionDays`, and run `prune()` on a schedule: the CLI does it at boot and daily, Cloudflare uses the cron trigger, Vercel uses `vercelCron`. For anything else, call it from your own scheduler.
149
+
150
+ For a live backup, wrap your store: `mirrorStore(primary, [backup])`. For point-in-time backups and moves between stores:
151
+
152
+ ```bash
153
+ curl -H "Authorization: Bearer $KEY" "$HOST/api/export.ndjson?range=365d" > backup.ndjson
154
+ curl -X POST -H "Authorization: Bearer $KEY" --data-binary @backup.ndjson "$OTHER_HOST/api/import"
155
+ ```
@@ -0,0 +1,106 @@
1
+ # HOW IT WORKS
2
+
3
+ This page explains what Tallymark records, how it counts people without cookies, and where its limits are. For how to call it, see [USAGE.md](./USAGE.md).
4
+
5
+ ## The life of a hit
6
+
7
+ 1. **A hit arrives.** Either the browser script sends it to `/collect`, or your server code calls `track()` or `trackRequest()`.
8
+ 2. **It is checked.** Bots, Do-Not-Track and Global Privacy Control, browser prefetches, your own excluded IPs, referrer spam, hosts you did not allow, and oversize or malformed bodies are dropped. A dropped hit is not an error: the endpoint still answers `202`, so a scraper learns nothing about what tripped it.
9
+ 3. **It is cleaned.** The URL is reduced to hostname, path and campaign parameters (every other query parameter is discarded, because they often carry tokens). The User-Agent becomes a browser, a version, an OS and a device class. The IP and the platform's geo headers become a country, region, city and timezone. The language header becomes one tag such as `en-US`.
10
+ 4. **The visitor is hashed.** See below. The raw IP and User-Agent are used here and then forgotten.
11
+ 5. **The event is stored.** One row, or one sorted-set entry, in the store you chose.
12
+ 6. **Questions are answered later.** `summary()`, `top()`, `sessions()` and the rest read events from the store for the range you ask about and compute the answer in memory.
13
+
14
+ ## What an event contains
15
+
16
+ | Field | Meaning |
17
+ |---|---|
18
+ | `type`, `name` | `pageview`, a custom `event` (and its name), or an `engagement` beacon (time on a page) |
19
+ | `ts` | When it happened, in milliseconds |
20
+ | `visitor` | The anonymous daily hash |
21
+ | `hostname`, `path` | Which site and page. No query string except campaign parameters. |
22
+ | `referrer`, `referrerHost` | The external site the visitor came from, if any |
23
+ | `utm` | `source`, `medium`, `campaign`, `term`, `content` from the URL |
24
+ | `browser`, `browserVersion` | `Chrome`, `130` |
25
+ | `os`, `osVersion` | `Windows`; the version is kept only for Android and iOS, because other user agents hide it |
26
+ | `device`, `screen` | `desktop` / `mobile` / `tablet`; and `mobile` / `tablet` / `laptop` / `desktop` from the window width |
27
+ | `country`, `region`, `city`, `timezone` | From your host's headers. Coarse, never coordinates. |
28
+ | `language` | The primary tag of `Accept-Language` |
29
+ | `props`, `value` | Properties and a number you attached to a custom event |
30
+ | `duration`, `scroll` | On `engagement` events: seconds on the page and how far it was scrolled |
31
+
32
+ An event never contains an IP address, a raw User-Agent, a cookie, or a user id.
33
+
34
+ ## The visitor
35
+
36
+ ```
37
+ visitor = sha256( secret : UTC date : hostname : IP : User-Agent )
38
+ ```
39
+
40
+ - **No cookies and no storage.** Nothing is written to the visitor's device. The same inputs give the same hash, so repeat hits are recognised without remembering anyone.
41
+ - **It resets at midnight UTC.** The date is an input, so the same person looks like a different visitor tomorrow. This is deliberate: it is what stops anyone from following a person across days.
42
+ - **It differs per site.** The hostname is an input, so one person on two of your sites is two visitors.
43
+ - **Your `secret` matters.** Anyone who has it and can guess an IP and a User-Agent could recompute that visitor's hash. Keep it private. Changing it makes every existing visitor look new.
44
+
45
+ Consequences you should know about:
46
+
47
+ - "Unique visitors" over several days is the sum of each day's unique visitors, not true uniques.
48
+ - There are no "returning visitors" reports and no long-term cohorts. That is the cost of not tracking people.
49
+ - People who share an IP and have an identical User-Agent (an office, a school) count as one.
50
+ - Funnels and session paths cover a single day. A session that crosses midnight UTC becomes two.
51
+
52
+ ## The session
53
+
54
+ A session is one visit. Events from the same visitor belong to the same session until they are quiet for 30 minutes (`sessionMinutes`). An engagement beacon is activity on the page it belongs to, so a long read stays one visit even when the beacon arrives after that gap. Sessions are not stored; they are rebuilt from events whenever a question needs them. That is how Tallymark answers:
55
+
56
+ - **Bounce rate**: the share of sessions that were a single pageview.
57
+ - **Time on site**: from the first event to the last sign of activity, including time spent reading the last page.
58
+ - **Entry and exit pages**: the first and last pageview of each session.
59
+ - **The path travelled**: the ordered pages and events of a session, with seconds and scroll depth per page. `sessions()` returns these, and `journeys()` counts the most common routes.
60
+
61
+ ## Where a visit came from
62
+
63
+ Only a session's first page carries a referrer or a campaign, so the rest of the visit inherits it. A visitor who arrives from Google and views five pages is one Google visitor, and a purchase they make is credited to Google. A page that brings its own campaign (a new `?utm_*` landing) replaces the inherited source, and a new session after 30 quiet minutes starts fresh.
64
+
65
+ The **channel** is derived from the source:
66
+
67
+ | Channel | When |
68
+ |---|---|
69
+ | Paid | `utm_medium` is `cpc`, `ppc`, `paid…`, `display`, `cpm`, `banner` or `retargeting` |
70
+ | Email | `utm_medium` is `email` or `newsletter`, or `utm_source` is `email` or `newsletter` |
71
+ | Social | `utm_medium=social`, or the referrer is a known social site (Facebook, X, LinkedIn, Reddit, YouTube, Hacker News, …) |
72
+ | Organic Search | The referrer is a known search engine (Google, Bing, DuckDuckGo, Yahoo, Baidu, Yandex, Ecosia, Brave, …). A lookalike such as `google.evil.com` stays a referral |
73
+ | Referral | Any other referring site |
74
+ | Campaign | A `utm_*` parameter with no referrer |
75
+ | Direct | None of the above |
76
+
77
+ The **source** is `utm_source` when present, else the referring host, else `Direct`.
78
+
79
+ ## Time on page and scroll depth
80
+
81
+ The browser script measures *engaged* time: seconds the tab was visible. It also tracks the deepest scroll position. When the page is hidden, left, or replaced by a single-page-app navigation, it sends one `engagement` beacon with the running total. A later beacon for the same page replaces the earlier one, so the total is cumulative and a tab that goes to the background does not count the time it was away.
82
+
83
+ Engagement beacons are stored as events of their own type, but they are not pageviews or custom events: they never change visitor, pageview, event or bounce counts. They only add time and scroll to the page they belong to. Turn them off with `data-engagement="false"`, which also removes one stored row per pageview.
84
+
85
+ Without the script (for example, server-side tracking only), time on a page falls back to the gap to the visitor's next hit. The last page of a session has no next hit, so its time is unknown.
86
+
87
+ ## Bots and noise
88
+
89
+ A request is ignored when the User-Agent looks automated (crawlers, headless browsers, HTTP libraries, uptime monitors), when it carries `DNT: 1` or `Sec-GPC: 1` (turn this off with `respectDnt: false`), when it is a browser prefetch or prerender, when the IP is in `excludeIps`, when the referrer is on a spam list (`blockedReferrers` extends it), or when the host is not in `allowedHosts`. The browser script additionally does nothing in an automated browser (`navigator.webdriver`), on the loopback hosts `localhost`, `127.0.0.1` and `::1` unless you ask, or when `localStorage.tallymark_ignore = 'true'` (a way for you to exclude yourself). Other hostnames, including `localhost.com`, are recorded.
90
+
91
+ ## Privacy
92
+
93
+ Tallymark reduces what you hold; it does not decide whether you need a consent notice. That depends on your jurisdiction, on what you put in event properties, and on whether you forward data to third parties. Check with counsel for your case.
94
+
95
+ - **Never stored:** IP addresses, raw User-Agents, full query strings, cookies, anything that identifies a person.
96
+ - **Kept:** the fields in the table above, which are aggregate-friendly and coarse.
97
+ - **Your responsibility:** do not put personal data (emails, names, user ids) into event names or properties. `forward` and `mirrorStore` send events elsewhere; those recipients are part of your privacy story.
98
+ - **Retention:** set `retentionDays` and run `prune()` on a schedule (the CLI does it daily; Cloudflare and Vercel have cron helpers). To delete everything, drop the table or the key.
99
+
100
+ ## Limits
101
+
102
+ - **Not a data warehouse.** A question reads the events in its time range and computes the answer in memory. That is quick up to a few hundred thousand events per question. For very large sites, ask about shorter ranges, or write a store that pre-aggregates.
103
+ - **The ingest endpoint is public**, as in every analytics tool, so anyone can send fake events. `allowedHosts`, `strictOrigin`, rate limiting, bot filtering and spam filtering raise the cost of that; they cannot remove it. Put Cloudflare or your platform's rate limiting in front for hard limits. The built-in limiter is per process.
104
+ - **Geography needs a host that provides it.** Cloudflare and Vercel send country, region, city and timezone. Elsewhere those fields stay empty unless you pass `country` and friends yourself. Tallymark never calls a third-party geolocation service.
105
+ - **Times are UTC.** `weekday`, `hour` and the buckets of `timeseries()` use UTC.
106
+ - **ESM only.** There is no CommonJS build.
package/docs/USAGE.md ADDED
@@ -0,0 +1,237 @@
1
+ # USAGE
2
+
3
+ The complete reference. For the ideas behind it, read [HOW_IT_WORKS.md](./HOW_IT_WORKS.md). For deployment, read [DEPLOYMENT.md](./DEPLOYMENT.md).
4
+
5
+ ## Contents
6
+
7
+ - [Entry points](#entry-points)
8
+ - [Creating an instance](#creating-an-instance)
9
+ - [Recording events](#recording-events)
10
+ - [Asking questions](#asking-questions)
11
+ - [The browser script](#the-browser-script)
12
+ - [The HTTP API](#the-http-api)
13
+ - [The command line](#the-command-line)
14
+ - [Backups, forwarding and hooks](#backups-forwarding-and-hooks)
15
+
16
+ ## Entry points
17
+
18
+ | Import | What it gives you |
19
+ |---|---|
20
+ | `tallymark` | `createTallymark`, `memoryStore`, `mirrorStore`, `webhookSink`, `verifyWebhookSignature`, and every type |
21
+ | `tallymark/stores` | `bunSqliteStore`, `pgStore`, `postgresJsStore`, `d1Store`, `libsqlStore`, `upstashRestStore`, `upstashStore`, `redisStore`, `sqlStore`, plus `memoryStore` and `mirrorStore` |
22
+ | `tallymark/react` | `<Analytics />` and `track()` |
23
+ | `tallymark/node` | `nodeHandler`, `nodeRequest`, `nodeConn` for Express, Fastify and Node `http` |
24
+ | `tallymark/cloudflare` | `cloudflare()`, a Worker with a scheduled retention sweep |
25
+ | `tallymark/vercel` | `vercel()` route handlers and `vercelCron()` |
26
+
27
+ The package is ESM only and has no runtime dependencies. The core uses only web-standard APIs, so it runs on Bun, Node, Deno, Cloudflare Workers and Vercel.
28
+
29
+ ## Creating an instance
30
+
31
+ ```ts
32
+ import { createTallymark } from 'tallymark'
33
+
34
+ const tm = createTallymark({ secret: process.env.SECRET })
35
+ ```
36
+
37
+ Every option is optional.
38
+
39
+ | Option | Default | Meaning |
40
+ |---|---|---|
41
+ | `secret` | random per process | Salts the visitor hash. **Set it in production**; with the default, visitors reset on every restart. |
42
+ | `store` | `memoryStore()` | Where events are kept. See [Storage](../README.md#storage). |
43
+ | `apiKey` | none | Bearer token for the read API. Without it, `/api/*` answers `401` to everyone. |
44
+ | `allowedOrigins` | `'*'` | Origins allowed to post hits from a browser (CORS). |
45
+ | `allowedHosts` | any | Only record hits for these hostnames. |
46
+ | `strictOrigin` | `false` | Require the browser's `Origin` or `Referer` host to be in `allowedHosts`. |
47
+ | `excludeIps` | none | Ignore hits from these IP addresses. |
48
+ | `blockedReferrers` | none | Extra referrer hosts to treat as spam, on top of a built-in list. |
49
+ | `respectDnt` | `true` | Ignore hits that send `DNT: 1` or `Sec-GPC: 1`. |
50
+ | `rateLimit` | 120 per minute per IP | `{ max, windowMs }`, or `false`. Per process, best effort. |
51
+ | `trustProxy` | `true` | Read the visitor's IP and location from proxy headers (Cloudflare, Vercel, `X-Forwarded-For`). Set `false` unless a proxy you control sets them. |
52
+ | `basePath` | `''` | The prefix the HTTP handler is mounted under, such as `/api/analytics`. |
53
+ | `retentionDays` | keep forever | Age after which `prune()` deletes events. |
54
+ | `sessionMinutes` | `30` | Inactivity that ends a session. |
55
+ | `forward` | none | Called with every recorded event, to send it elsewhere. See [webhookSink](#backups-forwarding-and-hooks). |
56
+ | `onError` | none | Called for failures that are swallowed (storage errors, exceptions). **Connect it to your logger.** |
57
+
58
+ ## Recording events
59
+
60
+ Pageviews come from the [browser script](#the-browser-script). Use these for events from your own code.
61
+
62
+ ### `trackRequest(request, event?, info?)`
63
+
64
+ Use this when you are handling a visitor's request. It reads their IP, browser, language, location and referrer from it.
65
+
66
+ ```ts
67
+ await tm.trackRequest(request, {
68
+ name: 'Signup', // omit for a pageview
69
+ props: { plan: 'pro' }, // flat: strings, numbers, booleans; at most 20, short keys and values
70
+ value: 49, // a number to add up, such as revenue
71
+ url: 'https://…', // optional: defaults to the request URL
72
+ })
73
+ ```
74
+
75
+ `info` carries what only your platform knows: `{ ip, geo, waitUntil }`. For Node and Express, build the `Request` with `nodeRequest(req)` and the info with `nodeConn(req)`.
76
+
77
+ ### `track(input, info?)`
78
+
79
+ Use this when there is no visitor request (a webhook, a job). Everything but `url` is optional.
80
+
81
+ ```ts
82
+ await tm.track({
83
+ url: 'https://shop.example/checkout/success',
84
+ name: 'Purchase', props: { sku: 'A1' }, value: 49,
85
+ ip, userAgent, // identify the visitor; hashed, never stored
86
+ referrer, language, country, region, city, timezone,
87
+ screenWidth: 1440, // bucketed into mobile / tablet / laptop / desktop
88
+ ts: Date.now(),
89
+ })
90
+ ```
91
+
92
+ Both return `{ ok: true, event }` or `{ ok: false, reason }` and **never throw**. Reasons: `bot`, `dnt`, `excluded`, `spam`, `host`, `prefetch`, `invalid`, `rate_limited`, `origin`, `too_large`, `storage`.
93
+
94
+ Event names are trimmed to 80 characters. `pageview` and `engagement` are reserved. `engagement` needs a `duration` in milliseconds (capped at four hours) and may carry a `scroll` from 0 to 100.
95
+
96
+ ## Asking questions
97
+
98
+ Every method takes a **range** first: `'1h'`, `'24h'`, `'7d'`, `'30d'`, `'90d'`, `'365d'`, or `{ from, to }` in epoch milliseconds, ending now by default. Most take **filters** second: `{ country: 'DE', device: 'mobile', 'prop:plan': 'pro' }`.
99
+
100
+ | Method | Returns |
101
+ |---|---|
102
+ | `summary(range, filters?)` | `pageviews`, `visitors`, `sessions`, `events`, `revenue`, `bounceRate`, `avgSessionSeconds`, `avgTimeOnPageSeconds`, `viewsPerSession` |
103
+ | `compare(range, filters?)` | `{ current, previous, delta }`, comparing with the equally long period before; `change` is `null` when the previous value was 0 |
104
+ | `timeseries(range, filters?, interval?)` | Buckets with `pageviews`, `visitors`, `events`. `interval` is `hour`, `day`, `week` (Monday start) or `month`; the default widens with the range. |
105
+ | `top(dimension, range, filters?, limit?)` | Rows of `{ key, visitors, count, value?, seconds?, scroll? }`, most common first. `limit` is 1 to 100. |
106
+ | `funnel(steps, range, filters?)` | One row per step: `visitors`, `rate` (of step 1), `dropoff` (from the previous step) |
107
+ | `sessions(range, filters?, limit?)` | Recent sessions, newest first, each with its ordered `steps` |
108
+ | `journeys(range, filters?, { depth, limit }?)` | The most common first `depth` pages of a session (default 3), with `sessions` and `share` |
109
+ | `realtime(minutes?)` | Visitors, pageviews and top pages in the last 5 minutes |
110
+ | `events(range, filters?, limit?)` | The raw events, oldest first |
111
+ | `export(range?, filters?)` / `import(ndjson)` | Backup and restore, one JSON event per line |
112
+ | `prune()` | Deletes events older than `retentionDays`; returns how many |
113
+
114
+ ### Dimensions
115
+
116
+ `top()` groups by a dimension, and every dimension is also a filter.
117
+
118
+ | Group | Dimensions |
119
+ |---|---|
120
+ | Pages | `path`, `entry_page`, `exit_page`, `hostname` |
121
+ | Sources | `referrer`, `source`, `channel`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
122
+ | Location | `country`, `continent`, `region`, `city`, `timezone`, `language` |
123
+ | Device | `browser`, `browser_version`, `os`, `os_version`, `device`, `screen` |
124
+ | Events | `event`, and `prop:<name>` for any custom property |
125
+ | Time (UTC) | `weekday` (`Mon`…`Sun`), `hour` (`00`…`23`) |
126
+
127
+ `entry_page` and `exit_page` work with `top()` only, not as filters.
128
+
129
+ `top('event')` counts events and adds up their `value`. `top('prop:plan')` does the same for events that carry a `plan` property, so `top('prop:plan', '30d', { event: 'Signup' })` is signups by plan, with revenue. Every other dimension counts pageviews, and `path` also reports average `seconds` on the page and average `scroll` depth.
130
+
131
+ Custom events and engagement beacons inherit the source of the visitor's session, so `top('event', '30d', { channel: 'Social' })` is the events that came from social traffic.
132
+
133
+ Funnel steps are `{ path: '/pricing' }` (a trailing `*` matches a prefix) or `{ event: 'Signup' }`, in order.
134
+
135
+ ## The browser script
136
+
137
+ Serve it from your Tallymark instance and add one tag:
138
+
139
+ ```html
140
+ <script defer src="https://stats.example.com/script.js"></script>
141
+ ```
142
+
143
+ It records a pageview on load and on every history navigation, plus time on page and scroll depth. It sets no cookies and writes nothing to storage. About 4 KB (1.7 KB gzipped).
144
+
145
+ Settings are `data-` attributes on the tag:
146
+
147
+ | Attribute | Default | Effect |
148
+ |---|---|---|
149
+ | `data-api` | where the script was served from | The base URL hits are sent to |
150
+ | `data-auto` | `true` | `"false"` turns off automatic pageviews (you call `tallymark.pageview()`) |
151
+ | `data-outbound` | off | `"true"` records clicks on links to other sites as `outbound` |
152
+ | `data-downloads` | off | `"true"` records clicks on files as `download` |
153
+ | `data-engagement` | on | `"false"` turns off time on page and scroll depth |
154
+ | `data-localhost` | off | `"true"` also records from `localhost`, `127.0.0.1` and `::1` |
155
+
156
+ `window.tallymark` has `track(name, props?, value?)` and `pageview()`. An element with `data-tally="Name"` sends that event when clicked, and `data-tally-<name>="value"` attributes become its properties.
157
+
158
+ The script ignores automated browsers (`navigator.webdriver`) and any browser where `localStorage.tallymark_ignore` is `'true'`.
159
+
160
+ In React, `<Analytics api="…" outbound downloads />` loads the script once, and `track(name, props?, value?)` sends an event.
161
+
162
+ ## The HTTP API
163
+
164
+ Mount the handler anywhere: `tm.handle(request)` takes a `Request` and returns a `Response`. Routes are relative to `basePath`.
165
+
166
+ ### Public
167
+
168
+ | Route | Purpose |
169
+ |---|---|
170
+ | `POST /collect` | Record a hit. JSON body: `url` (required), `name`, `referrer`, `props`, `value`. The script also sends `w` (window width), `d` (engaged milliseconds) and `s` (scroll depth). Send it as `text/plain` to avoid a CORS preflight. |
171
+ | `GET /script.js` | The browser script |
172
+ | `GET /health` | `{ "ok": true }` |
173
+
174
+ `/collect` answers `202` whether the hit was recorded or deliberately ignored. Other answers: `400` not JSON, `403` origin not allowed, `413` over 8 KB, `422` invalid URL, `429` rate limited, `503` the store is down (retry).
175
+
176
+ ### Authenticated
177
+
178
+ Send `Authorization: Bearer <apiKey>`. All answer `{ "ok": true, "data": … }`.
179
+
180
+ | Route | Parameters |
181
+ |---|---|
182
+ | `GET /api/summary` | range, filters |
183
+ | `GET /api/compare` | range, filters |
184
+ | `GET /api/timeseries` | range, filters, `interval=hour\|day\|week\|month` |
185
+ | `GET /api/top` | `by` (any dimension), `limit` (1 to 100), range, filters |
186
+ | `GET /api/funnel` | `steps=/pricing,/docs/*,event:Signup` (2 to 10), range, filters |
187
+ | `GET /api/sessions` | `limit` (1 to 500, default 50), range, filters |
188
+ | `GET /api/journeys` | `depth` (1 to 10, default 3), `limit` (1 to 100, default 10), range, filters |
189
+ | `GET /api/realtime` | none |
190
+ | `GET /api/events` | `limit` (up to 5000, default 100), range, filters |
191
+ | `GET /api/export.csv`, `GET /api/export.ndjson` | range, filters |
192
+ | `POST /api/import` | NDJSON body, up to 32 MB |
193
+
194
+ **Range** is `range=1h\|24h\|7d\|30d\|90d\|365d` (default `7d`), or `from=` and `to=` as an ISO date or epoch milliseconds. **Filters** are query parameters named after a dimension: `?country=DE&device=mobile&prop:plan=pro`. A bad parameter is a `400`, never a `500`.
195
+
196
+ ```bash
197
+ curl -H "Authorization: Bearer $KEY" "https://stats.example.com/api/top?by=channel&range=30d"
198
+ curl -H "Authorization: Bearer $KEY" "https://stats.example.com/api/top?by=prop:plan&event=Signup&range=30d"
199
+ ```
200
+
201
+ ## The command line
202
+
203
+ `bunx tallymark` runs the whole thing as a server. It needs Bun. Configuration is by environment variable.
204
+
205
+ | Variable | Meaning |
206
+ |---|---|
207
+ | `PORT` | Default `3000` |
208
+ | `TALLYMARK_SECRET`, `TALLYMARK_API_KEY` | The `secret` and `apiKey` options |
209
+ | `TALLYMARK_DB` | `./tallymark.db` (SQLite, the default), `:memory:`, or `postgres://user:pass@host/db` |
210
+ | `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | Use Upstash Redis instead (takes priority over `TALLYMARK_DB`) |
211
+ | `TALLYMARK_ORIGINS`, `TALLYMARK_HOSTS`, `TALLYMARK_EXCLUDE_IPS`, `TALLYMARK_BLOCKED_REFERRERS` | Comma-separated lists |
212
+ | `TALLYMARK_STRICT_ORIGIN` | `true` to enable `strictOrigin` (requires `TALLYMARK_HOSTS`) |
213
+ | `TALLYMARK_RETENTION_DAYS` | Delete older events, checked at boot and daily |
214
+ | `TALLYMARK_TRUST_PROXY` | `true` only behind a proxy you control. By default the socket address is used. |
215
+ | `TALLYMARK_WEBHOOK_URL`, `TALLYMARK_WEBHOOK_SECRET` | Forward every event to a URL |
216
+
217
+ Invalid values stop it at startup with a clear message. `SIGTERM` finishes in-flight requests and closes the database.
218
+
219
+ ## Backups, forwarding and hooks
220
+
221
+ ```ts
222
+ import { createTallymark, mirrorStore, webhookSink } from 'tallymark'
223
+
224
+ createTallymark({
225
+ // Every event goes to the primary, then to each backup. A backup failing never fails the hit.
226
+ store: mirrorStore(primary, [backup], { onError: (error, i) => log(error, i) }),
227
+
228
+ // Every recorded event is also POSTed, signed with HMAC-SHA256, to your URL. Retried on 5xx.
229
+ forward: webhookSink({ url: 'https://hooks.example.com/tallymark', secret: 'whsec_…' }),
230
+
231
+ onError: (error, { where }) => log(where, error), // where: 'track' | 'handle' | 'prune'
232
+ })
233
+ ```
234
+
235
+ Verify a delivery with `verifyWebhookSignature(secret, rawBody, request.headers.get('x-tallymark-signature'))`.
236
+
237
+ Move data between stores with `await other.import(await tm.export('365d'))`. Imports validate each line and skip anything malformed, and a repeated id is ignored, so a restore can be run twice safely.
@@ -0,0 +1,39 @@
1
+ # EXAMPLES
2
+
3
+ Every example here is commented, imports the package by its real name (`tallymark`), and says how to run it.
4
+
5
+ In your own project you install the package and the imports just work. In this repository there is nothing to install: `tsconfig.json` maps `tallymark` and `tallymark/*` to `src/` with `paths`, and **Bun** honours that mapping at runtime, so the examples run without building. `paths` only informs TypeScript and the runtime; Node does not read it. To run an example with Node, install the built package (`npm i tallymark`) instead.
6
+
7
+ Start with **events**, then pick the folder that matches your stack.
8
+
9
+ | Folder | What it shows | Verified by |
10
+ |---|---|---|
11
+ | [`events/`](./events) | **Every way to add a custom event**: HTML attributes, JavaScript, server-side, automatic outbound and download events, single-page navigation, and reading them back with a funnel, a session trace and revenue by source. | Run in a real browser (Edge), every button clicked, results read from `/stats`. |
12
+ | [`browser/`](./browser) | The smallest full loop: a page with the script tag, a server that mounts Tallymark, a `curl` to read it. | Run in a real browser. |
13
+ | [`library/`](./library) | Using it as a plain library: [`basic.ts`](./library/basic.ts) (first steps), [`reports.ts`](./library/reports.ts) (every report), [`stores.ts`](./library/stores.ts) (every storage backend), [`webhook-receiver.ts`](./library/webhook-receiver.ts) (the other end of `forward`). | `basic.ts` and `reports.ts` run; `stores.ts` type-checked against the real drivers. |
14
+ | [`frameworks/nextjs`](./frameworks/nextjs) | Next.js App Router on Vercel: the route handler, the layout component, a cron, `vercel.json`. | Route handlers called as Next.js calls them, against real PostgreSQL. |
15
+ | [`frameworks/vercel`](./frameworks/vercel) | Vercel Functions without a framework, using Upstash. | Type-checked. |
16
+ | [`frameworks/express.ts`](./frameworks/express.ts) | Express, including a server-side event from your own route. | Run, exercised with `curl`. |
17
+ | [`frameworks/hono.ts`](./frameworks/hono.ts) | Hono, including a server-side event. | Run, exercised with `curl`. |
18
+ | [`frameworks/bun.ts`](./frameworks/bun.ts), [`deno.ts`](./frameworks/deno.ts), [`cloudflare.ts`](./frameworks/cloudflare.ts) | The same handler on Bun (SQLite), Deno, and Cloudflare Workers (D1). | Bun and Cloudflare type-checked; Deno is a short snippet, not executed. |
19
+ | [`frameworks/sveltekit`](./frameworks/sveltekit), [`astro`](./frameworks/astro), [`react`](./frameworks/react) | One file each for SvelteKit and Astro, and a React app. | Type-checked. SvelteKit and Astro use the same `Request` to `Response` contract as the others; they were not run inside those frameworks. |
20
+ | [`http/`](./http) | Sending events and reading stats from **curl, Python, Go, PHP, Ruby and Java**, using only each language's standard library. | Every file run in its official Docker image against a live server. |
21
+
22
+ ## Running them
23
+
24
+ ```bash
25
+ bun examples/library/basic.ts
26
+ bun examples/events/server.ts # then open http://localhost:3000
27
+ bun examples/frameworks/express.ts
28
+ ```
29
+
30
+ For the language examples, start a server that trusts forwarded headers and run any file with your API key:
31
+
32
+ ```bash
33
+ TALLYMARK_SECRET=x TALLYMARK_API_KEY=k TALLYMARK_TRUST_PROXY=true TALLYMARK_DB=:memory: bun src/cli.ts &
34
+ TALLYMARK_API_KEY=k python3 examples/http/python.py
35
+ ```
36
+
37
+ ## What you do not have to write
38
+
39
+ Several examples feed made-up traffic into the library so they can run on their own. In a real project you write none of that. Add the script tag and Tallymark records pageviews, sources, devices, locations, time on page and scroll depth by itself. What you add are the **custom events** that matter to you, shown in [`events/`](./events).
@@ -0,0 +1,32 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <title>Tallymark demo</title>
6
+ <!--
7
+ This one tag is the whole integration.
8
+ data-localhost lets it record from localhost (it skips localhost by default).
9
+ data-outbound / data-downloads also track those link clicks.
10
+ -->
11
+ <script defer src="/analytics/script.js" data-localhost="true" data-outbound="true" data-downloads="true"></script>
12
+ </head>
13
+ <body>
14
+ <h1>Tallymark demo</h1>
15
+ <p>Loading this page already recorded a pageview.</p>
16
+
17
+ <!-- A custom event with props: just attributes, no JavaScript. -->
18
+ <button type="button" id="signup" data-tally="Signup" data-tally-plan="pro">Sign up (event + prop)</button>
19
+
20
+ <!-- A custom event with a numeric value (revenue), from JavaScript. -->
21
+ <button type="button" id="buy" onclick="tallymark.track('Purchase', { sku: 'A1' }, 49)">Buy (event + value)</button>
22
+
23
+ <!-- A single-page-app navigation: changes the URL without a page load. -->
24
+ <button type="button" id="spa" onclick="history.pushState({}, '', '/pricing')">Go to /pricing (SPA)</button>
25
+
26
+ <p>
27
+ <a id="out" href="https://example.org/docs?token=secret">Outbound link</a>
28
+ ·
29
+ <a id="dl" href="/report.pdf" onclick="return false">Download</a>
30
+ </p>
31
+ </body>
32
+ </html>