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,57 @@
1
+ // Every storage backend, in one place. Pick ONE; they are interchangeable, and you can switch later
2
+ // (export from the old one, import into the new one). Tallymark creates its table or key on first use.
3
+ //
4
+ // How to choose:
5
+ // • just trying it / tests ........ memoryStore
6
+ // • one server, want it simple .... bunSqliteStore
7
+ // • you already run Postgres ...... pgStore (Supabase, Neon, RDS, anything)
8
+ // • Cloudflare Workers ............ d1Store
9
+ // • Vercel / other serverless ..... pgStore with Neon, upstashRestStore, or libsqlStore (Turso)
10
+ //
11
+ // This file only builds the stores (it does not connect), so it runs without any services.
12
+ import { Database } from 'bun:sqlite'
13
+ import { Redis } from '@upstash/redis'
14
+ import { Pool } from 'pg'
15
+ import { createTallymark } from 'tallymark'
16
+ import {
17
+ bunSqliteStore,
18
+ memoryStore,
19
+ mirrorStore,
20
+ pgStore,
21
+ upstashRestStore,
22
+ upstashStore,
23
+ } from 'tallymark/stores'
24
+
25
+ // Nothing to set up. Lost on restart. The default.
26
+ export const inMemory = memoryStore({ maxEvents: 50_000 })
27
+
28
+ // A file. Great for one server.
29
+ export const sqlite = bunSqliteStore(new Database('stats.db', { create: true }))
30
+
31
+ // PostgreSQL: Supabase, Neon, RDS, self-hosted. Any client with query(text, params) works.
32
+ export const postgres = pgStore(new Pool({ connectionString: process.env.DATABASE_URL }))
33
+ // Neon over HTTP (serverless): pgStore(neon(process.env.DATABASE_URL)) // from @neondatabase/serverless
34
+ // Vercel Postgres: pgStore(sql) // from @vercel/postgres
35
+ // postgres.js: postgresJsStore(postgres(url))
36
+ // Bun's built-in client: postgresJsStore(new SQL(url)) // import { SQL } from 'bun'
37
+
38
+ // Upstash Redis, over plain fetch (no SDK) or with the official client.
39
+ export const upstash = upstashRestStore({
40
+ url: process.env.UPSTASH_REDIS_REST_URL ?? '',
41
+ token: process.env.UPSTASH_REDIS_REST_TOKEN ?? '',
42
+ })
43
+ export const upstashSdk = upstashStore(Redis.fromEnv())
44
+
45
+ // Cloudflare D1: d1Store(env.DB) // inside a Worker, see ../frameworks/cloudflare.ts
46
+ // Turso / libSQL: libsqlStore(createClient({ url, authToken }))
47
+
48
+ // A live backup or a migration: every event goes to the primary and is copied to the mirrors.
49
+ // If a mirror fails the hit still succeeds, and onError tells you.
50
+ export const withBackup = mirrorStore(sqlite, [inMemory], {
51
+ onError: (error, i) => console.error(`mirror ${i} failed`, error),
52
+ })
53
+
54
+ // Your own store is three methods:
55
+ // { insert(event), list({ from, to, limit }), prune?(before) }
56
+
57
+ export const analytics = createTallymark({ store: withBackup, secret: 'change-me' })
@@ -0,0 +1,30 @@
1
+ // bun examples/library/webhook-receiver.ts
2
+ //
3
+ // The other end of `forward: webhookSink(...)`: a tiny service that receives every event Tallymark
4
+ // records (Zapier, n8n, a queue, your own app) and verifies it really came from Tallymark first.
5
+ //
6
+ // Every delivery carries x-tallymark-signature: sha256=<hex> , an HMAC of the exact body bytes
7
+ // using the shared secret. Anyone can POST to a public URL, so never trust a delivery without it.
8
+ import { verifyWebhookSignature } from 'tallymark'
9
+
10
+ const SECRET = process.env.WEBHOOK_SECRET ?? 'whsec_demo'
11
+
12
+ Bun.serve({
13
+ port: 4000,
14
+ async fetch(request) {
15
+ const body = await request.text() // verify the RAW body, not re-serialised JSON
16
+ const valid = await verifyWebhookSignature(
17
+ SECRET,
18
+ body,
19
+ request.headers.get('x-tallymark-signature'),
20
+ )
21
+ if (!valid) return new Response('bad signature', { status: 401 })
22
+
23
+ const { event } = JSON.parse(body)
24
+ console.log(`${event.type} ${event.name} ${event.path} from ${event.country ?? '?'}`)
25
+ return new Response('ok')
26
+ },
27
+ })
28
+
29
+ // On the Tallymark side:
30
+ // createTallymark({ forward: webhookSink({ url: 'https://receiver.example/', secret: 'whsec_demo' }) })
package/llms.txt ADDED
@@ -0,0 +1,235 @@
1
+ # tallymark
2
+
3
+ > Privacy-first, cookieless web analytics as a TypeScript library, an HTTP API, and a 4 KB browser script. It counts visitors, pageviews, sources, devices, locations, custom events, time on page and visitor paths, and stores nothing that identifies a person. Zero runtime dependencies. ESM only. License: AGPL-3.0-only.
4
+
5
+ Read this file first. It tells you which integration to pick, gives copy-exact code for each supported platform, the rules to follow, and how to verify the result. After `npm i tallymark` the same file, the docs and runnable examples are on disk at `node_modules/tallymark/llms.txt`, `node_modules/tallymark/docs/` and `node_modules/tallymark/examples/`.
6
+
7
+ ## What it is, in five facts
8
+
9
+ - One engine, three ways in: a **browser script** (`<script src=".../script.js">`), **server code** (`tm.trackRequest(request, ...)`), and an **HTTP API** (`POST /collect`, `GET /api/...`) usable from any language.
10
+ - A visitor is `sha256(secret + UTC date + hostname + IP + User-Agent)`. It changes every day. No cookies, no storage on the visitor's device, no IP or raw User-Agent stored.
11
+ - The browser script records pageviews (including single-page-app navigation), referrer, UTM campaign, browser, OS, device, language, screen size, time on page and scroll depth automatically. Country, region, city and timezone come from Cloudflare or Vercel headers automatically.
12
+ - The only code a developer writes is **custom events** (`Signup`, `Purchase`), and optionally reading numbers back.
13
+ - Storage is pluggable: memory (default, lost on restart), SQLite file, PostgreSQL, Cloudflare D1, Turso, Upstash Redis.
14
+
15
+ ## Choose the integration
16
+
17
+ | The user wants | Do this |
18
+ |---|---|
19
+ | Analytics on a website, no server code to write | Recipe 1 (run `bunx tallymark` or the Docker image, add one script tag) |
20
+ | Analytics inside a Next.js app on Vercel | Recipe 2 |
21
+ | Analytics on a Vercel project that is not Next.js | Recipe 3 |
22
+ | Analytics on Cloudflare Workers | Recipe 4 |
23
+ | Analytics inside an Express or plain Node server | Recipe 5 |
24
+ | Hono, Elysia, SvelteKit, Astro, Deno, Bun.serve, or any Fetch framework | Recipe 6 |
25
+ | A React, Vite or Create React App single-page app | Recipe 7, plus a server from Recipe 1 to 6 |
26
+ | Events from a Python, Go, PHP, Ruby, Java or other backend | Recipe 8 |
27
+ | Counting inside a program with no browser and no server | Recipe 9 |
28
+
29
+ Pick exactly one server recipe (1 to 6). Recipe 7 is an addition for client-side React. Do not install two instances.
30
+
31
+ ## Recipes
32
+
33
+ ### Recipe 1: standalone server, any website
34
+
35
+ ```bash
36
+ bunx tallymark # needs Bun. Or use the Docker image below.
37
+ ```
38
+
39
+ Required environment: `TALLYMARK_SECRET` (long random, `openssl rand -hex 32`), `TALLYMARK_API_KEY` (long random). Storage: `TALLYMARK_DB=./tallymark.db` (SQLite, default), `:memory:`, or `postgres://user:pass@host/db`; or `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`. Set `TALLYMARK_HOSTS=example.com` to record only your site. Set `TALLYMARK_TRUST_PROXY=true` only when a proxy you control (Caddy, nginx, Cloudflare) sets the client IP headers.
40
+
41
+ ```bash
42
+ docker build -t tallymark . && docker run -p 3000:3000 -v stats:/data -e TALLYMARK_SECRET=... -e TALLYMARK_API_KEY=... tallymark
43
+ ```
44
+
45
+ Add to every page, in `<head>`:
46
+
47
+ ```html
48
+ <script defer src="https://stats.example.com/script.js"></script>
49
+ ```
50
+
51
+ ### Recipe 2: Next.js App Router on Vercel
52
+
53
+ ```bash
54
+ npm i tallymark pg
55
+ ```
56
+
57
+ ```ts
58
+ // lib/analytics.ts
59
+ import { createTallymark } from 'tallymark'
60
+ import { pgStore } from 'tallymark/stores'
61
+ import { Pool } from 'pg'
62
+
63
+ export const analytics = createTallymark({
64
+ store: pgStore(new Pool({ connectionString: process.env.DATABASE_URL })),
65
+ secret: process.env.ANALYTICS_SECRET,
66
+ apiKey: process.env.ANALYTICS_API_KEY,
67
+ basePath: '/api/analytics',
68
+ onError: (error, { where }) => console.error('[tallymark]', where, error),
69
+ })
70
+ ```
71
+
72
+ ```ts
73
+ // app/api/analytics/[...route]/route.ts
74
+ import { vercel } from 'tallymark/vercel'
75
+ import { analytics } from '@/lib/analytics'
76
+ export const { GET, POST, OPTIONS } = vercel(analytics)
77
+ ```
78
+
79
+ ```tsx
80
+ // app/layout.tsx: inside <body>
81
+ import { Analytics } from 'tallymark/react'
82
+ <Analytics api="/api/analytics" outbound downloads />
83
+ ```
84
+
85
+ Environment variables: `DATABASE_URL`, `ANALYTICS_SECRET`, `ANALYTICS_API_KEY`. For Neon over HTTP use `pgStore(neon(process.env.DATABASE_URL!))` from `@neondatabase/serverless` instead of `pg`. Optional retention: set `retentionDays: 395` and add `app/api/analytics-cron/route.ts` with `export const GET = vercelCron(analytics, { secret: process.env.CRON_SECRET })` and `vercel.json` `{ "crons": [{ "path": "/api/analytics-cron", "schedule": "0 3 * * *" }] }`. Vercel supplies location headers; nothing else to configure. Do not use `memoryStore` or a SQLite file on Vercel: serverless instances do not share memory or disk.
86
+
87
+ ### Recipe 3: Vercel without Next.js
88
+
89
+ Create `api/analytics.ts` exporting `GET`, `POST`, `OPTIONS` from `vercel(analytics)`, using `basePath: '/api/analytics'` and a serverless store such as `upstashRestStore({ url: process.env.UPSTASH_REDIS_REST_URL!, token: process.env.UPSTASH_REDIS_REST_TOKEN! })`. Add to `vercel.json`: `{ "rewrites": [{ "source": "/api/analytics/:path*", "destination": "/api/analytics" }] }`. Add `<script defer src="/api/analytics/script.js"></script>` to your pages. Full files: `examples/frameworks/vercel/`.
90
+
91
+ ### Recipe 4: Cloudflare Workers
92
+
93
+ ```ts
94
+ import { cloudflare } from 'tallymark/cloudflare'
95
+ import { d1Store } from 'tallymark/stores'
96
+
97
+ export default cloudflare<Env>((env) => ({
98
+ store: d1Store(env.DB),
99
+ secret: env.SECRET,
100
+ apiKey: env.API_KEY,
101
+ retentionDays: 395,
102
+ }))
103
+ ```
104
+
105
+ `wrangler.toml` needs a `[[d1_databases]]` binding named `DB` and `[triggers] crons = ["0 3 * * *"]` for the retention sweep. Create secrets with `wrangler secret put SECRET` and `wrangler secret put API_KEY`. The table is created on first use. Location comes from `request.cf` automatically. Full file: `examples/frameworks/cloudflare.ts`.
106
+
107
+ ### Recipe 5: Express and Node
108
+
109
+ ```ts
110
+ import { createTallymark } from 'tallymark'
111
+ import { nodeHandler, nodeRequest, nodeConn } from 'tallymark/node'
112
+
113
+ const analytics = createTallymark({ secret, apiKey, basePath: '/analytics', trustProxy: false })
114
+ app.use('/analytics', nodeHandler(analytics))
115
+ // A server-side event from your own route (reads IP, browser, language, location from the request):
116
+ await analytics.trackRequest(nodeRequest(req), { name: 'Subscribe', props: { plan }, value: 5 }, nodeConn(req))
117
+ ```
118
+
119
+ `basePath` must equal the mount path. Set `trustProxy: true` (in both places) only behind a proxy you control. Page tag: `<script defer src="/analytics/script.js"></script>`.
120
+
121
+ ### Recipe 6: any Fetch framework
122
+
123
+ `analytics.handle(request)` takes a `Request` and returns a `Response`. Set `basePath` to the mount path.
124
+
125
+ ```ts
126
+ app.all('/analytics/*', (c) => analytics.handle(c.req.raw)) // Hono
127
+ export { handler as GET, handler as POST, handler as OPTIONS } // SvelteKit src/routes/analytics/[...path]/+server.ts, with handler = ({ request }) => analytics.handle(request)
128
+ export const ALL = ({ request }) => analytics.handle(request) // Astro src/pages/analytics/[...path].ts (SSR required)
129
+ Bun.serve({ fetch: (req, server) => analytics.handle(req, { ip: server.requestIP(req)?.address }) })
130
+ Deno.serve((req, info) => analytics.handle(req, { ip: info.remoteAddr.hostname }))
131
+ ```
132
+
133
+ ### Recipe 7: React single-page app
134
+
135
+ ```tsx
136
+ import { Analytics, track } from 'tallymark/react'
137
+ <Analytics api="https://stats.example.com" outbound downloads /> // once, near the root; renders nothing
138
+ track('Purchase', { sku: 'A1' }, 49) // a custom event from anywhere
139
+ ```
140
+
141
+ Route changes are tracked automatically. `api` is where the server from Recipes 1 to 6 lives (use a same-origin path when you can).
142
+
143
+ ### Recipe 8: other languages (HTTP)
144
+
145
+ Send hits with `POST {base}/collect`, JSON body `{ "url": "https://site/page", "name": "Signup", "props": { "plan": "pro" }, "value": 49 }` (omit `name` for a pageview). **Forward the visitor's real `User-Agent` and `X-Forwarded-For` headers**, otherwise every visitor looks like your server. The server must run with `TALLYMARK_TRUST_PROXY=true` (or `trustProxy: true`) to read `X-Forwarded-For`. Read with `GET {base}/api/...` and `Authorization: Bearer <apiKey>`. `202` means recorded or deliberately ignored. Complete, tested programs: `examples/http/` (curl, Python, Go, PHP, Ruby, Java).
146
+
147
+ ### Recipe 9: library only
148
+
149
+ ```ts
150
+ import { createTallymark } from 'tallymark'
151
+ const tm = createTallymark({ secret: process.env.SECRET })
152
+ await tm.track({ url: 'https://app.example/start', ip, userAgent }) // pageview
153
+ await tm.summary('7d')
154
+ ```
155
+
156
+ ## Custom events
157
+
158
+ Pageviews, sources, devices, location, time on page and scroll depth are automatic. Add an event only for something that matters to the business. Name events in PascalCase and keep the set small and stable (`Signup`, `Purchase`, `Search`).
159
+
160
+ ```html
161
+ <button data-tally="Signup" data-tally-plan="pro">Start</button> <!-- attribute, no JS; data-tally-<name> becomes a property -->
162
+ <button onclick="tallymark.track('Purchase', { sku: 'A1' }, 49)">Buy</button> <!-- name, properties, value to sum (revenue) -->
163
+ ```
164
+
165
+ ```ts
166
+ await tm.trackRequest(request, { name: 'Subscribe', props: { plan: 'free' }, value: 5 }) // from a server route
167
+ await tm.track({ url, name: 'Purchase', props: { sku: 'A1' }, value: 49 }) // no request available (a webhook)
168
+ ```
169
+
170
+ Properties are flat (strings, numbers, booleans), at most 20. Links to other sites and file downloads become `outbound` and `download` events when the script tag has `data-outbound="true"` or `data-downloads="true"`.
171
+
172
+ ## Reading the numbers
173
+
174
+ Over HTTP (needs the API key): `GET /api/summary`, `/api/compare`, `/api/timeseries`, `/api/top?by=<dimension>`, `/api/funnel?steps=/pricing,event:Signup`, `/api/sessions`, `/api/journeys`, `/api/realtime`, `/api/events`, `/api/export.csv`, `/api/export.ndjson`. Add `?range=1h|24h|7d|30d|90d|365d` and filters such as `&country=DE&device=mobile&prop:plan=pro`.
175
+
176
+ In code: `tm.summary(range, filters)`, `tm.compare`, `tm.timeseries`, `tm.top(dimension, range, filters, limit)`, `tm.funnel(steps, range)`, `tm.sessions`, `tm.journeys`, `tm.realtime`.
177
+
178
+ Dimensions: `path entry_page exit_page hostname referrer source channel utm_source utm_medium utm_campaign utm_term utm_content country continent region city timezone language browser browser_version os os_version device screen event weekday hour` and `prop:<name>` for any custom property. `top('event')` and `top('prop:plan')` count events and add up their `value`. Never call the read API from browser code: the API key is a secret.
179
+
180
+ ## Rules
181
+
182
+ 1. **Secrets.** Generate `secret` and `apiKey` with `openssl rand -hex 32`. Read them from environment variables. Never commit them and never put them in client code. Without `apiKey` the read API is off, which is correct for a write-only deployment.
183
+ 2. **One script tag.** Add exactly one `<script defer src=".../script.js">`. Do not also call `tallymark.pageview()` unless `data-auto="false"`.
184
+ 3. **`basePath` must equal the mount path** the handler is served under (for example `/api/analytics`). A mismatch makes every route a 404.
185
+ 4. **Persistent storage on serverless.** Vercel and Cloudflare instances do not share memory or disk. Use Postgres, Upstash, Turso or D1 there. `memoryStore` is for tests and demos only.
186
+ 5. **`trustProxy`.** Leave it on only when Cloudflare, Vercel or a proxy you control sets the client IP headers. If the server is exposed directly, set it to `false`, otherwise visitors can forge their IP.
187
+ 6. **No personal data** (emails, names, user ids) in event names or properties.
188
+ 7. **No cookies, no consent banner code, no fingerprinting.** Tallymark is designed not to need them. Do not add them.
189
+ 8. **Serve the script first-party** (same origin or a path on the site's own domain, such as `/analytics/script.js`) to avoid blocklists.
190
+ 9. **ESM only.** Use `import`, not `require`.
191
+ 10. **Restrict writes** with `allowedHosts: ['example.com']` and `strictOrigin: true` so other sites cannot add to the numbers.
192
+ 11. **Connect `onError`** to the app's logger; failures are otherwise swallowed on purpose so analytics never breaks a request.
193
+
194
+ ## Verify
195
+
196
+ ```bash
197
+ # 1. The server is up
198
+ curl -fsS $BASE/health # {"ok":true}
199
+ # 2. Send a hit. Use a browser-like User-Agent: curl's default is treated as a bot and ignored.
200
+ curl -fsS -X POST $BASE/collect -H 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/130.0.0.0 Safari/537.36' -d '{"url":"https://example.com/"}'
201
+ # 3. Read it back
202
+ curl -fsS -H "Authorization: Bearer $KEY" "$BASE/api/summary?range=1h" # "pageviews":1
203
+ # 4. In a real browser: open the site, then check /api/top?by=path and /api/top?by=device
204
+ ```
205
+
206
+ ## Troubleshooting
207
+
208
+ | Symptom | Cause and fix |
209
+ |---|---|
210
+ | `/collect` answers 202 but nothing is stored | The hit was deliberately ignored: a bot-like User-Agent (curl, scripts), `DNT`/`Sec-GPC`, an excluded IP, a host not in `allowedHosts`, or referrer spam. Test with a browser-like User-Agent. In code, `track()` returns `{ ok: false, reason }`. |
211
+ | The script sends nothing on localhost | Intended for `localhost`, `127.0.0.1` and `::1` only. Add `data-localhost="true"` while developing. Other hostnames, including `localhost.com`, are recorded. |
212
+ | Nothing is sent from an automated browser | Intended. The script ignores `navigator.webdriver`. |
213
+ | Every route is 404 | `basePath` does not match the mount path, or the catch-all route file is missing. |
214
+ | `/api/*` answers 401 | No `apiKey` configured, or the `Authorization: Bearer <key>` header is missing or wrong. |
215
+ | Country, city and timezone are empty | The host provides no location headers (only Cloudflare and Vercel do). Pass `country` and friends yourself, or accept empty fields. Tallymark never calls a geolocation service. |
216
+ | All visitors count as one | No IP is available. Behind a proxy set `trustProxy: true`; from another language forward `X-Forwarded-For`; on Bun/Deno pass `{ ip }` to `handle()`. |
217
+ | Visitors are counted twice or inflated | `trustProxy` is on while the server is exposed directly (IPs can be forged), or two instances share traffic with different `secret` values. |
218
+ | Data vanishes after a restart or deploy | `memoryStore` (the default) or a file on an ephemeral disk. Use a persistent store. |
219
+ | Browser console shows a CORS error | `allowedOrigins` excludes the site. The default `'*'` allows all. Send the hit as `text/plain` (the script does) to avoid a preflight. |
220
+ | `track()` returns `reason: 'storage'` | The database is unreachable or misconfigured. The error is passed to `onError`. |
221
+
222
+ ## Documentation
223
+
224
+ - [How it works](https://unpkg.com/tallymark@latest/docs/HOW_IT_WORKS.md): event model, visitor hash, sessions, attribution, time on page, privacy, limits.
225
+ - [Usage reference](https://unpkg.com/tallymark@latest/docs/USAGE.md): every option, method, dimension, endpoint, tracker setting and CLI variable.
226
+ - [Deployment](https://unpkg.com/tallymark@latest/docs/DEPLOYMENT.md): Cloudflare, Vercel, Docker, reverse proxies, retention and backups.
227
+ - [Examples index](https://unpkg.com/tallymark@latest/examples/README.md): runnable, commented, each marked with how it is verified.
228
+ - [README](https://unpkg.com/tallymark@latest/README.md): overview.
229
+
230
+ ## Optional
231
+
232
+ - [Custom events, every way](https://unpkg.com/tallymark@latest/examples/events/server.ts): attributes, JavaScript, server-side, automatic, read back.
233
+ - [Every report](https://unpkg.com/tallymark@latest/examples/library/reports.ts): each question the library can answer.
234
+ - [Every store](https://unpkg.com/tallymark@latest/examples/library/stores.ts): memory, SQLite, Postgres, Upstash, mirror.
235
+ - [Security policy](https://unpkg.com/tallymark@latest/SECURITY.md): threat model and deployment checklist.
package/package.json CHANGED
@@ -1,6 +1,118 @@
1
1
  {
2
2
  "name": "tallymark",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Privacy-first, cookieless web analytics. A tiny typed library, a drop-in HTTP API and a browser script. Runs on Bun, Node, Cloudflare Workers, Vercel and any Fetch runtime.",
5
+ "license": "AGPL-3.0-only",
6
+ "author": "tallymark contributors",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/whoisjayd/tallymark.git"
10
+ },
11
+ "homepage": "https://github.com/whoisjayd/tallymark#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/whoisjayd/tallymark/issues"
14
+ },
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "keywords": [
18
+ "analytics",
19
+ "web-analytics",
20
+ "privacy",
21
+ "cookieless",
22
+ "gdpr",
23
+ "self-hosted",
24
+ "cloudflare-workers",
25
+ "bun",
26
+ "plausible-alternative",
27
+ "postgres",
28
+ "upstash"
29
+ ],
30
+ "files": [
31
+ "dist",
32
+ "docs",
33
+ "examples",
34
+ "llms.txt",
35
+ "LICENSE",
36
+ "README.md",
37
+ "SECURITY.md"
38
+ ],
39
+ "bin": {
40
+ "tallymark": "./dist/cli.js"
41
+ },
42
+ "main": "./dist/index.js",
43
+ "types": "./dist/index.d.ts",
44
+ "exports": {
45
+ ".": {
46
+ "types": "./dist/index.d.ts",
47
+ "import": "./dist/index.js"
48
+ },
49
+ "./stores": {
50
+ "types": "./dist/stores.d.ts",
51
+ "import": "./dist/stores.js"
52
+ },
53
+ "./react": {
54
+ "types": "./dist/react.d.ts",
55
+ "import": "./dist/react.js"
56
+ },
57
+ "./cloudflare": {
58
+ "types": "./dist/cloudflare.d.ts",
59
+ "import": "./dist/cloudflare.js"
60
+ },
61
+ "./node": {
62
+ "types": "./dist/node.d.ts",
63
+ "import": "./dist/node.js"
64
+ },
65
+ "./package.json": "./package.json",
66
+ "./vercel": {
67
+ "types": "./dist/vercel.d.ts",
68
+ "import": "./dist/vercel.js"
69
+ }
70
+ },
71
+ "scripts": {
72
+ "dev": "bun --watch src/cli.ts",
73
+ "start": "bun src/cli.ts",
74
+ "test": "bun test",
75
+ "typecheck": "tsc --noEmit",
76
+ "format": "biome check --write .",
77
+ "lint": "biome ci .",
78
+ "check": "biome ci . && bun run typecheck && bun test",
79
+ "prepare": "bun scripts/install-hooks.ts",
80
+ "build": "rm -rf dist && tsc -p tsconfig.build.json",
81
+ "smoke": "bun scripts/smoke.ts",
82
+ "validate": "publint --strict && attw --pack . --profile esm-only",
83
+ "services": "docker compose up -d --wait",
84
+ "test:services": "TM_PG_URL=postgres://postgres:pw@127.0.0.1:55432/stats TM_UPSTASH_URL=http://127.0.0.1:58079 TM_UPSTASH_TOKEN=tok bun test test/stores.test.ts",
85
+ "prepublishOnly": "bun run check && bun run build && bun run smoke && bun run validate"
86
+ },
87
+ "devDependencies": {
88
+ "@arethetypeswrong/cli": "^0.18.5",
89
+ "@biomejs/biome": "^2.6.8",
90
+ "@electric-sql/pglite": "^0.5.17",
91
+ "@types/bun": "latest",
92
+ "@types/express": "^5.0.6",
93
+ "@types/pg": "^8.23.1",
94
+ "@types/react": "19",
95
+ "@types/react-dom": "^19.3.0",
96
+ "@upstash/redis": "^1.41.0",
97
+ "express": "^5.3.0",
98
+ "hono": "^4.13.19",
99
+ "lefthook": "^2.2.2",
100
+ "pg": "^8.23.1",
101
+ "publint": "^0.3.25",
102
+ "react": "19",
103
+ "react-dom": "^19.3.1",
104
+ "typescript": "^5.6.0"
105
+ },
106
+ "publishConfig": {
107
+ "access": "public",
108
+ "provenance": true
109
+ },
110
+ "peerDependencies": {
111
+ "react": ">=18"
112
+ },
113
+ "peerDependenciesMeta": {
114
+ "react": {
115
+ "optional": true
116
+ }
117
+ }
118
+ }