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
package/dist/hit.js ADDED
@@ -0,0 +1,301 @@
1
+ // `(?<!cu)` keeps phone brands such as Cubot. `bot` still matches Googlebot and bingbot.
2
+ const BOT = /(?<!cu)bot|crawl|spider|slurp|headless|lighthouse|pagespeed|preview|facebookexternalhit|embedly|curl\/|wget|python-|httpclient|okhttp|monitor|uptime|pingdom|axios|node-fetch|undici|go-http|java\/|libwww|scrapy|phantomjs|selenium|puppeteer|playwright/i;
3
+ const BROWSERS = [
4
+ ['Edge', /Edg(?:e|A|iOS)?\/(\d+)/],
5
+ ['Opera', /OPR\/(\d+)/],
6
+ ['Samsung Internet', /SamsungBrowser\/(\d+)/],
7
+ ['Firefox', /(?:Firefox|FxiOS)\/(\d+)/],
8
+ ['Chrome', /(?:Chrome|CriOS)\/(\d+)/],
9
+ ['Safari', /Version\/(\d+).*Safari/],
10
+ ];
11
+ /** Tiny, dependency-free UA parser. Browser family + major version, OS, and device class. */
12
+ export function parseUserAgent(ua) {
13
+ const none = {
14
+ browser: null,
15
+ browserVersion: null,
16
+ os: null,
17
+ osVersion: null,
18
+ device: 'unknown',
19
+ bot: true,
20
+ };
21
+ if (!ua || ua.length < 8 || BOT.test(ua))
22
+ return none;
23
+ let browser = null;
24
+ let browserVersion = null;
25
+ for (const [name, pattern] of BROWSERS) {
26
+ const m = ua.match(pattern);
27
+ if (m) {
28
+ browser = name;
29
+ browserVersion = m[1] ?? null;
30
+ break;
31
+ }
32
+ }
33
+ // Windows and macOS versions are not recoverable (frozen or shared by several
34
+ // releases), so a version is reported only where the user agent is honest.
35
+ let os = null;
36
+ let osVersion = null;
37
+ if (/Windows/i.test(ua))
38
+ os = 'Windows';
39
+ else if (/iPhone|iPad|iPod/i.test(ua)) {
40
+ os = 'iOS';
41
+ osVersion = ua.match(/OS (\d+)[_\d]*/)?.[1] ?? null;
42
+ }
43
+ else if (/Android/i.test(ua)) {
44
+ os = 'Android';
45
+ osVersion = ua.match(/Android (\d+)/)?.[1] ?? null;
46
+ }
47
+ else if (/CrOS/i.test(ua))
48
+ os = 'ChromeOS';
49
+ else if (/Mac OS X|Macintosh/i.test(ua))
50
+ os = 'macOS';
51
+ else if (/Linux|X11/i.test(ua))
52
+ os = 'Linux';
53
+ let device = 'desktop';
54
+ if (/iPad|Tablet/i.test(ua) || (/Android/i.test(ua) && !/Mobile/i.test(ua)))
55
+ device = 'tablet';
56
+ else if (/Mobi|iPhone|iPod|Android/i.test(ua))
57
+ device = 'mobile';
58
+ return { browser, browserVersion, os, osVersion, device, bot: false };
59
+ }
60
+ const stripWww = (h) => h.replace(/^www\./, '').toLowerCase();
61
+ const clean = (v, max = 120) => {
62
+ if (!v)
63
+ return null;
64
+ const t = v.trim().slice(0, max);
65
+ return t === '' ? null : t;
66
+ };
67
+ /**
68
+ * Accepts an absolute URL or a bare path. Keeps only hostname, path and campaign
69
+ * parameters. Every other query parameter is dropped: they often carry tokens or
70
+ * personal data.
71
+ */
72
+ export function parseUrl(input) {
73
+ if (typeof input !== 'string' || input.length === 0 || input.length > 2048)
74
+ return null;
75
+ // Only absolute http(s) URLs or rooted paths. A bare word is not a page.
76
+ if (!/^https?:\/\//i.test(input) && !input.startsWith('/'))
77
+ return null;
78
+ let url;
79
+ try {
80
+ url = new URL(input, 'http://localhost');
81
+ }
82
+ catch {
83
+ return null;
84
+ }
85
+ if (url.protocol !== 'http:' && url.protocol !== 'https:')
86
+ return null;
87
+ const q = url.searchParams;
88
+ let path = url.pathname.replace(/\/{2,}/g, '/');
89
+ if (path.length > 1 && path.endsWith('/'))
90
+ path = path.slice(0, -1);
91
+ return {
92
+ hostname: /^https?:\/\//i.test(input) ? stripWww(url.hostname) : '',
93
+ path: path.slice(0, 300) || '/',
94
+ utm: {
95
+ source: clean(q.get('utm_source') ?? q.get('ref') ?? q.get('source')),
96
+ medium: clean(q.get('utm_medium')),
97
+ campaign: clean(q.get('utm_campaign')),
98
+ term: clean(q.get('utm_term')),
99
+ content: clean(q.get('utm_content')),
100
+ },
101
+ };
102
+ }
103
+ /** Returns `{ url, host }` for an external referrer, or nulls for internal/invalid. */
104
+ export function parseReferrer(referrer, hostname) {
105
+ if (!referrer)
106
+ return { referrer: null, host: null };
107
+ try {
108
+ const r = new URL(referrer);
109
+ if (r.protocol !== 'http:' && r.protocol !== 'https:')
110
+ return { referrer: null, host: null };
111
+ const host = stripWww(r.hostname);
112
+ if (host === hostname)
113
+ return { referrer: null, host: null };
114
+ return { referrer: `${host}${r.pathname === '/' ? '' : r.pathname}`.slice(0, 200), host };
115
+ }
116
+ catch {
117
+ return { referrer: null, host: null };
118
+ }
119
+ }
120
+ const val = (v, max = 80) => {
121
+ if (!v)
122
+ return null;
123
+ let s = v;
124
+ try {
125
+ s = decodeURIComponent(v);
126
+ }
127
+ catch {
128
+ /* keep raw */
129
+ }
130
+ s = s.trim().slice(0, max);
131
+ return s === '' ? null : s;
132
+ };
133
+ /**
134
+ * Location and client IP from headers the hosting platform already sets. Free,
135
+ * instant, and no third-party lookup: Cloudflare, Vercel, and generic proxies.
136
+ *
137
+ * Only trust these when the request really passed through that platform.
138
+ */
139
+ /** An IANA timezone such as `Europe/Berlin`, or null. Anything else is dropped. */
140
+ export function timezone(v) {
141
+ return v && /^[A-Za-z_]+(\/[A-Za-z0-9_+-]+){0,2}$/.test(v) && v.length <= 40 ? v : null;
142
+ }
143
+ export function geoFromHeaders(h) {
144
+ // Cloudflare. `XX` = unknown, `T1` = Tor.
145
+ const cf = val(h.get('cf-ipcountry'), 8);
146
+ const vercel = val(h.get('x-vercel-ip-country'), 8);
147
+ const raw = (cf ?? vercel ?? val(h.get('x-country-code'), 8))?.toUpperCase() ?? null;
148
+ const country = raw && /^[A-Z]{2}$/.test(raw) && raw !== 'XX' && raw !== 'T1' ? raw : null;
149
+ return {
150
+ country,
151
+ region: val(h.get('cf-region') ?? h.get('x-vercel-ip-country-region')),
152
+ city: val(h.get('cf-ipcity') ?? h.get('x-vercel-ip-city')),
153
+ timezone: timezone(h.get('cf-timezone') ?? h.get('x-vercel-ip-timezone')),
154
+ };
155
+ }
156
+ export function clientIp(h) {
157
+ const direct = h.get('cf-connecting-ip') ?? h.get('x-real-ip');
158
+ const raw = direct ?? h.get('x-forwarded-for')?.split(',')[0];
159
+ if (!raw)
160
+ return null;
161
+ const ip = raw.trim();
162
+ // A forwarded header is attacker-controlled when the proxy did not overwrite it.
163
+ // Anything longer than an IP is not one, and must not become a rate-limit key.
164
+ return ip.length > 0 && ip.length <= 128 ? ip : null;
165
+ }
166
+ // ── Referrer spam ─────────────────────────────────────────────────────────────
167
+ /**
168
+ * Well-known referrer spam: bots that fake a Referer so their domain shows up in
169
+ * your reports. Suffix-matched, so `x.semalt.com` is caught too. Extend with the
170
+ * `blockedReferrers` option.
171
+ */
172
+ const SPAM = [
173
+ 'semalt.com',
174
+ 'buttons-for-website.com',
175
+ 'darodar.com',
176
+ 'floating-share-buttons.com',
177
+ 'free-share-buttons.com',
178
+ 'simple-share-buttons.com',
179
+ 'best-seo-offer.com',
180
+ 'best-seo-solution.com',
181
+ 'ranksonic.com',
182
+ 'savetubevideo.com',
183
+ 'kambasoft.com',
184
+ 'hulfingtonpost.com',
185
+ 'trafficmonetize.org',
186
+ 'trafficmonetizer.org',
187
+ 'webmonetizer.net',
188
+ 'event-tracking.com',
189
+ 'get-free-traffic-now.com',
190
+ 'sexyali.com',
191
+ 'o00o.ooo',
192
+ ];
193
+ export function isSpamReferrer(host, extra = []) {
194
+ if (!host)
195
+ return false;
196
+ const h = host.toLowerCase();
197
+ return [...SPAM, ...extra].some((s) => {
198
+ const d = s.toLowerCase().replace(/^www\./, '');
199
+ return h === d || h.endsWith(`.${d}`);
200
+ });
201
+ }
202
+ // ── Visitor id ────────────────────────────────────────────────────────────────
203
+ const enc = new TextEncoder();
204
+ async function sha256Hex(input, bytes = 16) {
205
+ const buf = await crypto.subtle.digest('SHA-256', enc.encode(input));
206
+ return Array.from(new Uint8Array(buf).slice(0, bytes), (b) => b.toString(16).padStart(2, '0')).join('');
207
+ }
208
+ /** UTC day number, so the salt flips at 00:00 UTC for everyone. */
209
+ const dayOf = (ts) => Math.floor(ts / 86_400_000);
210
+ /**
211
+ * Anonymous, cookieless visitor id:
212
+ *
213
+ * sha256(secret : utcDay : hostname : ip : userAgent)
214
+ *
215
+ * The raw IP and User-Agent only exist inside this call. Because the day is part
216
+ * of the input, the same person gets a different id tomorrow and cannot be
217
+ * followed across days. Different sites get different ids for the same person.
218
+ */
219
+ export function visitorId(secret, ts, hostname, ip, userAgent) {
220
+ return sha256Hex(`${secret}:${dayOf(ts)}:${hostname}:${ip ?? ''}:${userAgent ?? ''}`);
221
+ }
222
+ export function randomId() {
223
+ const b = crypto.getRandomValues(new Uint8Array(10));
224
+ return Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
225
+ }
226
+ export function randomSecret() {
227
+ return randomId() + randomId();
228
+ }
229
+ // ── Input cleaning ──────────────────────────────────────────────────────────
230
+ const MAX_PROPS = 20;
231
+ const MAX_PROP_KEY = 40;
232
+ const MAX_PROP_VALUE = 200;
233
+ /** Keep props flat, small, and primitive. Anything else is dropped, not thrown. */
234
+ export function sanitizeProps(input) {
235
+ const out = {};
236
+ if (!input || typeof input !== 'object' || Array.isArray(input))
237
+ return out;
238
+ let n = 0;
239
+ for (const [k, v] of Object.entries(input)) {
240
+ if (n >= MAX_PROPS)
241
+ break;
242
+ if (k.length === 0 || k.length > MAX_PROP_KEY)
243
+ continue;
244
+ if (typeof v === 'string')
245
+ out[k] = v.slice(0, MAX_PROP_VALUE);
246
+ else if (typeof v === 'number' && Number.isFinite(v))
247
+ out[k] = v;
248
+ else if (typeof v === 'boolean')
249
+ out[k] = v;
250
+ else
251
+ continue;
252
+ n++;
253
+ }
254
+ return out;
255
+ }
256
+ /** `en-US,en;q=0.9` -> `en-US`. Only the primary tag; never the whole header. */
257
+ export function primaryLanguage(header) {
258
+ const tag = header?.split(',')[0]?.split(';')[0]?.trim();
259
+ return tag && /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$/.test(tag) ? tag : null;
260
+ }
261
+ // ── Screen size and continents ──────────────────────────────────────────────
262
+ /** Plausible-style viewport classes. Bucketed server-side so raw widths are never stored. */
263
+ export function screenClass(width) {
264
+ if (typeof width !== 'number' || !Number.isFinite(width) || width <= 0)
265
+ return null;
266
+ return width < 768 ? 'mobile' : width < 1024 ? 'tablet' : width < 1440 ? 'laptop' : 'desktop';
267
+ }
268
+ const CONTINENTS = {
269
+ Africa: 'DZ AO BJ BW BF BI CV CM CF TD KM CG CD CI DJ EG GQ ER SZ ET GA GM GH GN GW KE LS LR LY MG MW ML MR MU YT MA MZ NA NE NG RE RW SH ST SN SC SL SO ZA SS SD TZ TG TN UG EH ZM ZW',
270
+ Antarctica: 'AQ BV GS HM TF',
271
+ Asia: 'AF AM AZ BH BD BT BN KH CN CY GE HK IN ID IR IQ IL JP JO KZ KW KG LA LB MO MY MV MN MM NP KP OM PK PS PH QA SA SG KR LK SY TW TJ TH TL TR TM AE UZ VN YE',
272
+ Europe: 'AX AL AD AT BY BE BA BG HR CZ DK EE FO FI FR DE GI GR GG VA HU IS IE IM IT JE XK LV LI LT LU MT MD MC ME NL MK NO PL PT RO RU SM RS SK SI ES SJ SE CH UA GB',
273
+ 'North America': 'AI AG AW BS BB BZ BM BQ VG CA KY CR CU CW DM DO SV GL GD GP GT HT HN JM MQ MX MS NI PA PR BL KN LC MF PM VC SX TT TC US VI UM',
274
+ Oceania: 'AS AU CK FJ PF GU KI MH FM NR NC NZ NU NF MP PW PG PN WS SB TK TO TV VU WF',
275
+ 'South America': 'AR BO BR CL CO EC FK GF GY PY PE SR UY VE',
276
+ };
277
+ const CONTINENT_OF = new Map(Object.entries(CONTINENTS).flatMap(([name, codes]) => codes.split(' ').map((c) => [c, name])));
278
+ /** Continent name for an ISO 3166-1 alpha-2 country code, or null. */
279
+ export function continentOf(country) {
280
+ return country ? (CONTINENT_OF.get(country) ?? null) : null;
281
+ }
282
+ /**
283
+ * Read the visitor's IP, User-Agent, language and location from a request. The one
284
+ * place this happens, so the browser endpoint and server-side tracking agree.
285
+ * `info` (the socket address, Cloudflare's `request.cf`) wins over headers.
286
+ */
287
+ export function describeRequest(req, info, trustProxy) {
288
+ const h = req.headers;
289
+ const fromHeaders = trustProxy
290
+ ? geoFromHeaders(h)
291
+ : { country: null, region: null, city: null, timezone: null };
292
+ return {
293
+ ip: info.ip ?? (trustProxy ? clientIp(h) : null),
294
+ userAgent: h.get('user-agent'),
295
+ language: primaryLanguage(h.get('accept-language')),
296
+ country: info.geo?.country ?? fromHeaders.country,
297
+ region: info.geo?.region ?? fromHeaders.region,
298
+ city: info.geo?.city ?? fromHeaders.city,
299
+ timezone: info.geo?.timezone ?? fromHeaders.timezone,
300
+ };
301
+ }
package/dist/http.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ import type { Tallymark } from './tallymark.js';
2
+ import type { ConnInfo } from './types.js';
3
+ /**
4
+ * Sliding-window limiter held in memory. Best-effort by design: on serverless
5
+ * each isolate has its own window, which is still enough to blunt a naive flood.
6
+ * Put Cloudflare / Vercel rate limiting in front for hard guarantees.
7
+ */
8
+ export declare class RateLimiter {
9
+ private max;
10
+ private windowMs;
11
+ private buckets;
12
+ constructor(max: number, windowMs: number);
13
+ /** Returns `true` if the hit is over the limit. */
14
+ hit(key: string, now: number): boolean;
15
+ }
16
+ export declare function timingSafeEqual(a: string, b: string): boolean;
17
+ /**
18
+ * Routes (relative to `basePath`):
19
+ *
20
+ * POST /collect public record a pageview / event
21
+ * GET /script.js public the browser tracker
22
+ * GET /health public liveness
23
+ * GET /api/summary API key totals, bounce rate, session length
24
+ * GET /api/timeseries API key visitors / pageviews over time
25
+ * GET /api/top?by=path API key top pages, referrers, countries, ...
26
+ * GET /api/compare API key this period vs. the previous one
27
+ * GET /api/funnel API key ordered funnel (?steps=/pricing,event:Signup)
28
+ * GET /api/sessions API key recent sessions with the pages and events in order
29
+ * GET /api/journeys API key the most common routes through the site
30
+ * GET /api/realtime API key visitors in the last 5 minutes
31
+ * GET /api/events API key raw events
32
+ * GET /api/export.csv API key CSV download
33
+ * GET /api/export.ndjson API key full-fidelity backup
34
+ * POST /api/import API key restore a backup (NDJSON body)
35
+ */
36
+ export declare function createHandler(engine: Tallymark, now: () => number, onError: (error: unknown) => void): (req: Request, info?: ConnInfo) => Promise<Response>;