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.
- package/LICENSE +661 -0
- package/README.md +234 -2
- package/SECURITY.md +37 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +124 -0
- package/dist/cloudflare.d.ts +9 -0
- package/dist/cloudflare.js +53 -0
- package/dist/hit.d.ts +83 -0
- package/dist/hit.js +301 -0
- package/dist/http.d.ts +36 -0
- package/dist/http.js +393 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +4 -0
- package/dist/node.d.ts +40 -0
- package/dist/node.js +66 -0
- package/dist/query.d.ts +31 -0
- package/dist/query.js +699 -0
- package/dist/react.d.ts +27 -0
- package/dist/react.js +34 -0
- package/dist/script.d.ts +17 -0
- package/dist/script.js +147 -0
- package/dist/stores.d.ts +129 -0
- package/dist/stores.js +393 -0
- package/dist/tallymark.d.ts +49 -0
- package/dist/tallymark.js +265 -0
- package/dist/types.d.ts +306 -0
- package/dist/types.js +1 -0
- package/dist/vercel.d.ts +33 -0
- package/dist/vercel.js +36 -0
- package/dist/webhook.d.ts +27 -0
- package/dist/webhook.js +61 -0
- package/docs/DEPLOYMENT.md +155 -0
- package/docs/HOW_IT_WORKS.md +106 -0
- package/docs/USAGE.md +237 -0
- package/examples/README.md +39 -0
- package/examples/browser/index.html +32 -0
- package/examples/browser/server.ts +34 -0
- package/examples/events/index.html +89 -0
- package/examples/events/server.ts +101 -0
- package/examples/frameworks/astro/[...path].ts +21 -0
- package/examples/frameworks/bun.ts +23 -0
- package/examples/frameworks/cloudflare.ts +37 -0
- package/examples/frameworks/deno.ts +26 -0
- package/examples/frameworks/express.ts +57 -0
- package/examples/frameworks/hono.ts +38 -0
- package/examples/frameworks/nextjs/app/api/analytics/[...route]/route.ts +7 -0
- package/examples/frameworks/nextjs/app/api/analytics-cron/route.ts +6 -0
- package/examples/frameworks/nextjs/app/layout.tsx +15 -0
- package/examples/frameworks/nextjs/app/page.tsx +21 -0
- package/examples/frameworks/nextjs/lib/analytics.ts +14 -0
- package/examples/frameworks/nextjs/vercel.json +3 -0
- package/examples/frameworks/react/main.tsx +32 -0
- package/examples/frameworks/sveltekit/+server.ts +26 -0
- package/examples/frameworks/vercel/api/analytics-cron.ts +9 -0
- package/examples/frameworks/vercel/api/analytics.ts +22 -0
- package/examples/frameworks/vercel/vercel.json +4 -0
- package/examples/http/Java.java +74 -0
- package/examples/http/curl.sh +46 -0
- package/examples/http/go.go +93 -0
- package/examples/http/php.php +74 -0
- package/examples/http/python.py +62 -0
- package/examples/http/ruby.rb +60 -0
- package/examples/library/basic.ts +95 -0
- package/examples/library/reports.ts +136 -0
- package/examples/library/stores.ts +57 -0
- package/examples/library/webhook-receiver.ts +30 -0
- package/llms.txt +235 -0
- package/package.json +116 -4
package/dist/http.js
ADDED
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
import { describeRequest } from './hit.js';
|
|
2
|
+
import { isDimension, TOP_DIMENSIONS, toCsv } from './query.js';
|
|
3
|
+
import { TRACKER } from './script.js';
|
|
4
|
+
// ── Rate limiter ──────────────────────────────────────────────────────────────
|
|
5
|
+
/**
|
|
6
|
+
* Sliding-window limiter held in memory. Best-effort by design: on serverless
|
|
7
|
+
* each isolate has its own window, which is still enough to blunt a naive flood.
|
|
8
|
+
* Put Cloudflare / Vercel rate limiting in front for hard guarantees.
|
|
9
|
+
*/
|
|
10
|
+
export class RateLimiter {
|
|
11
|
+
max;
|
|
12
|
+
windowMs;
|
|
13
|
+
buckets = new Map();
|
|
14
|
+
constructor(max, windowMs) {
|
|
15
|
+
this.max = max;
|
|
16
|
+
this.windowMs = windowMs;
|
|
17
|
+
}
|
|
18
|
+
/** Returns `true` if the hit is over the limit. */
|
|
19
|
+
hit(key, now) {
|
|
20
|
+
const hits = (this.buckets.get(key) ?? []).filter((t) => now - t < this.windowMs);
|
|
21
|
+
if (hits.length >= this.max) {
|
|
22
|
+
this.buckets.set(key, hits);
|
|
23
|
+
return true;
|
|
24
|
+
}
|
|
25
|
+
hits.push(now);
|
|
26
|
+
this.buckets.set(key, hits);
|
|
27
|
+
if (this.buckets.size > 5000) {
|
|
28
|
+
for (const [k, v] of this.buckets) {
|
|
29
|
+
if (!v.some((t) => now - t < this.windowMs))
|
|
30
|
+
this.buckets.delete(k);
|
|
31
|
+
}
|
|
32
|
+
// Distinct keys, including spoofed forwarded IPs, must not grow without bound.
|
|
33
|
+
while (this.buckets.size > 5000) {
|
|
34
|
+
const oldest = this.buckets.keys().next().value;
|
|
35
|
+
if (oldest === undefined)
|
|
36
|
+
break;
|
|
37
|
+
this.buckets.delete(oldest);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
return false;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
// ── Request handler ───────────────────────────────────────────────────────────
|
|
44
|
+
const MAX_BODY = 8 * 1024;
|
|
45
|
+
const MAX_IMPORT = 32 * 1024 * 1024;
|
|
46
|
+
const RANGES = new Set(['1h', '24h', '7d', '30d', '90d', '365d']);
|
|
47
|
+
/** Read at most `max` bytes. Returns null if the body is larger, without buffering it all. */
|
|
48
|
+
async function readBounded(req, max) {
|
|
49
|
+
if (!req.body)
|
|
50
|
+
return '';
|
|
51
|
+
const reader = req.body.getReader();
|
|
52
|
+
const chunks = [];
|
|
53
|
+
let size = 0;
|
|
54
|
+
for (;;) {
|
|
55
|
+
const { done, value } = await reader.read();
|
|
56
|
+
if (done)
|
|
57
|
+
break;
|
|
58
|
+
size += value.byteLength;
|
|
59
|
+
if (size > max) {
|
|
60
|
+
await reader.cancel().catch(() => { });
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
chunks.push(value);
|
|
64
|
+
}
|
|
65
|
+
const all = new Uint8Array(size);
|
|
66
|
+
let off = 0;
|
|
67
|
+
for (const c of chunks) {
|
|
68
|
+
all.set(c, off);
|
|
69
|
+
off += c.byteLength;
|
|
70
|
+
}
|
|
71
|
+
return new TextDecoder().decode(all);
|
|
72
|
+
}
|
|
73
|
+
export function timingSafeEqual(a, b) {
|
|
74
|
+
const ea = new TextEncoder().encode(a);
|
|
75
|
+
const eb = new TextEncoder().encode(b);
|
|
76
|
+
let diff = ea.length ^ eb.length;
|
|
77
|
+
for (let i = 0; i < Math.max(ea.length, eb.length); i++)
|
|
78
|
+
diff |= (ea[i] ?? 0) ^ (eb[i] ?? 0);
|
|
79
|
+
return diff === 0;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Routes (relative to `basePath`):
|
|
83
|
+
*
|
|
84
|
+
* POST /collect public record a pageview / event
|
|
85
|
+
* GET /script.js public the browser tracker
|
|
86
|
+
* GET /health public liveness
|
|
87
|
+
* GET /api/summary API key totals, bounce rate, session length
|
|
88
|
+
* GET /api/timeseries API key visitors / pageviews over time
|
|
89
|
+
* GET /api/top?by=path API key top pages, referrers, countries, ...
|
|
90
|
+
* GET /api/compare API key this period vs. the previous one
|
|
91
|
+
* GET /api/funnel API key ordered funnel (?steps=/pricing,event:Signup)
|
|
92
|
+
* GET /api/sessions API key recent sessions with the pages and events in order
|
|
93
|
+
* GET /api/journeys API key the most common routes through the site
|
|
94
|
+
* GET /api/realtime API key visitors in the last 5 minutes
|
|
95
|
+
* GET /api/events API key raw events
|
|
96
|
+
* GET /api/export.csv API key CSV download
|
|
97
|
+
* GET /api/export.ndjson API key full-fidelity backup
|
|
98
|
+
* POST /api/import API key restore a backup (NDJSON body)
|
|
99
|
+
*/
|
|
100
|
+
export function createHandler(engine, now, onError) {
|
|
101
|
+
const o = engine.options;
|
|
102
|
+
const base = (o.basePath ?? '').replace(/\/$/, '');
|
|
103
|
+
const respectDnt = o.respectDnt ?? true;
|
|
104
|
+
const origins = o.allowedOrigins ?? '*';
|
|
105
|
+
const limiter = o.rateLimit === false
|
|
106
|
+
? null
|
|
107
|
+
: new RateLimiter(o.rateLimit?.max ?? 120, o.rateLimit?.windowMs ?? 60_000);
|
|
108
|
+
const corsFor = (req) => {
|
|
109
|
+
const origin = req.headers.get('origin');
|
|
110
|
+
if (origins === '*')
|
|
111
|
+
return { 'access-control-allow-origin': '*' };
|
|
112
|
+
if (origin && origins.includes(origin)) {
|
|
113
|
+
return { 'access-control-allow-origin': origin, vary: 'Origin' };
|
|
114
|
+
}
|
|
115
|
+
return {};
|
|
116
|
+
};
|
|
117
|
+
const json = (body, status = 200, extra = {}) => new Response(JSON.stringify(body), {
|
|
118
|
+
status,
|
|
119
|
+
headers: {
|
|
120
|
+
'content-type': 'application/json; charset=utf-8',
|
|
121
|
+
'cache-control': 'no-store',
|
|
122
|
+
...extra,
|
|
123
|
+
},
|
|
124
|
+
});
|
|
125
|
+
async function collect(req, info) {
|
|
126
|
+
const cors = corsFor(req);
|
|
127
|
+
const origin = req.headers.get('origin');
|
|
128
|
+
if (origins !== '*' && origin && !origins.includes(origin)) {
|
|
129
|
+
return json({ ok: false, error: 'origin' }, 403);
|
|
130
|
+
}
|
|
131
|
+
if (o.strictOrigin && o.allowedHosts) {
|
|
132
|
+
const src = req.headers.get('origin') ?? req.headers.get('referer');
|
|
133
|
+
let host = '';
|
|
134
|
+
try {
|
|
135
|
+
host = src ? new URL(src).hostname.replace(/^www\./, '').toLowerCase() : '';
|
|
136
|
+
}
|
|
137
|
+
catch {
|
|
138
|
+
/* unparseable = rejected below */
|
|
139
|
+
}
|
|
140
|
+
const allowed = o.allowedHosts.map((h) => h.toLowerCase().replace(/^www\./, ''));
|
|
141
|
+
if (!allowed.includes(host))
|
|
142
|
+
return json({ ok: false, error: 'origin' }, 403);
|
|
143
|
+
}
|
|
144
|
+
// Ignored hits return 202, not an error: don't teach bots what tripped them,
|
|
145
|
+
// and don't spam the visitor's console.
|
|
146
|
+
const ignored = (reason) => json({ ok: true, ignored: reason }, 202, cors);
|
|
147
|
+
if (respectDnt && (req.headers.get('dnt') === '1' || req.headers.get('sec-gpc') === '1')) {
|
|
148
|
+
return ignored('dnt');
|
|
149
|
+
}
|
|
150
|
+
// Browsers speculatively load pages the user may never see.
|
|
151
|
+
const purpose = (req.headers.get('sec-purpose') ??
|
|
152
|
+
req.headers.get('purpose') ??
|
|
153
|
+
'').toLowerCase();
|
|
154
|
+
if (purpose.includes('prefetch') || purpose.includes('prerender'))
|
|
155
|
+
return ignored('prefetch');
|
|
156
|
+
const trust = o.trustProxy ?? true;
|
|
157
|
+
const facts = describeRequest(req, info, trust);
|
|
158
|
+
const ip = facts.ip;
|
|
159
|
+
// No IP means no honest bucket key. A shared bucket would let one client
|
|
160
|
+
// throttle everyone, so limit only when we can tell clients apart.
|
|
161
|
+
if (limiter && ip && limiter.hit(ip, now())) {
|
|
162
|
+
return json({ ok: false, error: 'rate_limited' }, 429, { ...cors, 'retry-after': '60' });
|
|
163
|
+
}
|
|
164
|
+
const declared = Number(req.headers.get('content-length') ?? 0);
|
|
165
|
+
if (declared > MAX_BODY)
|
|
166
|
+
return json({ ok: false, error: 'too_large' }, 413, cors);
|
|
167
|
+
const text = await readBounded(req, MAX_BODY);
|
|
168
|
+
if (text === null)
|
|
169
|
+
return json({ ok: false, error: 'too_large' }, 413, cors);
|
|
170
|
+
let body;
|
|
171
|
+
try {
|
|
172
|
+
body = JSON.parse(text);
|
|
173
|
+
if (!body || typeof body !== 'object')
|
|
174
|
+
throw new Error();
|
|
175
|
+
}
|
|
176
|
+
catch {
|
|
177
|
+
return json({ ok: false, error: 'bad_json' }, 400, cors);
|
|
178
|
+
}
|
|
179
|
+
const result = await engine.track({
|
|
180
|
+
name: typeof body.name === 'string' ? body.name : undefined,
|
|
181
|
+
url: typeof body.url === 'string' ? body.url : '',
|
|
182
|
+
referrer: typeof body.referrer === 'string' ? body.referrer : null,
|
|
183
|
+
props: body.props,
|
|
184
|
+
value: typeof body.value === 'number' ? body.value : undefined,
|
|
185
|
+
// Short keys from the tracker: w = viewport width, d = engaged ms, s = scroll depth.
|
|
186
|
+
screenWidth: typeof body.w === 'number' ? body.w : undefined,
|
|
187
|
+
duration: typeof body.d === 'number' ? body.d : undefined,
|
|
188
|
+
scroll: typeof body.s === 'number' ? body.s : undefined,
|
|
189
|
+
...facts,
|
|
190
|
+
}, info);
|
|
191
|
+
if (!result.ok) {
|
|
192
|
+
if (result.reason === 'invalid')
|
|
193
|
+
return json({ ok: false, error: 'invalid' }, 422, cors);
|
|
194
|
+
if (result.reason === 'storage')
|
|
195
|
+
return json({ ok: false, error: 'storage' }, 503, { ...cors, 'retry-after': '30' });
|
|
196
|
+
return ignored(result.reason);
|
|
197
|
+
}
|
|
198
|
+
return json({ ok: true }, 202, cors);
|
|
199
|
+
}
|
|
200
|
+
function authorised(req) {
|
|
201
|
+
if (!o.apiKey)
|
|
202
|
+
return false;
|
|
203
|
+
const header = req.headers.get('authorization') ?? '';
|
|
204
|
+
// RFC 7235: the auth scheme is case-insensitive.
|
|
205
|
+
const token = /^bearer /i.test(header) ? header.slice(7) : '';
|
|
206
|
+
return timingSafeEqual(token, o.apiKey);
|
|
207
|
+
}
|
|
208
|
+
function parseRange(p) {
|
|
209
|
+
const from = p.get('from');
|
|
210
|
+
const to = p.get('to');
|
|
211
|
+
if (from || to) {
|
|
212
|
+
const f = toMs(from);
|
|
213
|
+
const t = toMs(to) ?? now() + 1;
|
|
214
|
+
if (f === null || t === null || f >= t)
|
|
215
|
+
return { error: 'bad_range' };
|
|
216
|
+
return { from: f, to: t };
|
|
217
|
+
}
|
|
218
|
+
const r = p.get('range') ?? '7d';
|
|
219
|
+
return RANGES.has(r) ? r : { error: 'bad_range' };
|
|
220
|
+
}
|
|
221
|
+
function parseFilters(p) {
|
|
222
|
+
const f = {};
|
|
223
|
+
// Any dimension, including `prop:<name>`, can be used as a filter.
|
|
224
|
+
for (const [k, v] of p) {
|
|
225
|
+
if (v && isDimension(k))
|
|
226
|
+
f[k] = v;
|
|
227
|
+
}
|
|
228
|
+
return f;
|
|
229
|
+
}
|
|
230
|
+
async function api(req, route, p) {
|
|
231
|
+
if (!authorised(req)) {
|
|
232
|
+
return json({ ok: false, error: 'unauthorized' }, 401, { 'www-authenticate': 'Bearer' });
|
|
233
|
+
}
|
|
234
|
+
const range = parseRange(p);
|
|
235
|
+
if (typeof range === 'object' && 'error' in range)
|
|
236
|
+
return json({ ok: false, error: range.error }, 400);
|
|
237
|
+
const filters = parseFilters(p);
|
|
238
|
+
switch (route) {
|
|
239
|
+
case '/api/summary':
|
|
240
|
+
return json({ ok: true, data: await engine.summary(range, filters) });
|
|
241
|
+
case '/api/timeseries': {
|
|
242
|
+
const i = p.get('interval');
|
|
243
|
+
const interval = i === 'hour' || i === 'day' || i === 'week' || i === 'month' ? i : undefined;
|
|
244
|
+
return json({ ok: true, data: await engine.timeseries(range, filters, interval) });
|
|
245
|
+
}
|
|
246
|
+
case '/api/top': {
|
|
247
|
+
const by = p.get('by');
|
|
248
|
+
if (!by || !(TOP_DIMENSIONS.includes(by) || isDimension(by))) {
|
|
249
|
+
return json({ ok: false, error: 'bad_dimension', allowed: TOP_DIMENSIONS }, 400);
|
|
250
|
+
}
|
|
251
|
+
// A dimension can't also be its own filter, or the answer is one row.
|
|
252
|
+
if (by !== 'entry_page' && by !== 'exit_page')
|
|
253
|
+
delete filters[by];
|
|
254
|
+
const limit = Number(p.get('limit') ?? 10);
|
|
255
|
+
return json({
|
|
256
|
+
ok: true,
|
|
257
|
+
data: await engine.top(by, range, filters, Number.isFinite(limit) ? limit : 10),
|
|
258
|
+
});
|
|
259
|
+
}
|
|
260
|
+
case '/api/compare':
|
|
261
|
+
return json({ ok: true, data: await engine.compare(range, filters) });
|
|
262
|
+
case '/api/funnel': {
|
|
263
|
+
const steps = parseSteps(p.get('steps'));
|
|
264
|
+
if (!steps)
|
|
265
|
+
return json({ ok: false, error: 'bad_steps', hint: 'steps=/pricing,event:Signup (2-10 steps)' }, 400);
|
|
266
|
+
return json({ ok: true, data: await engine.funnel(steps, range, filters) });
|
|
267
|
+
}
|
|
268
|
+
case '/api/export.ndjson':
|
|
269
|
+
return new Response(await engine.export(range, filters), {
|
|
270
|
+
headers: {
|
|
271
|
+
'content-type': 'application/x-ndjson; charset=utf-8',
|
|
272
|
+
'content-disposition': 'attachment; filename="tallymark.ndjson"',
|
|
273
|
+
'cache-control': 'no-store',
|
|
274
|
+
},
|
|
275
|
+
});
|
|
276
|
+
case '/api/sessions': {
|
|
277
|
+
const limit = Number(p.get('limit') ?? 50);
|
|
278
|
+
return json({
|
|
279
|
+
ok: true,
|
|
280
|
+
data: await engine.sessions(range, filters, Number.isFinite(limit) ? limit : 50),
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
case '/api/journeys': {
|
|
284
|
+
const depth = Number(p.get('depth') ?? 3);
|
|
285
|
+
const limit = Number(p.get('limit') ?? 10);
|
|
286
|
+
return json({
|
|
287
|
+
ok: true,
|
|
288
|
+
data: await engine.journeys(range, filters, {
|
|
289
|
+
depth: Number.isFinite(depth) ? depth : 3,
|
|
290
|
+
limit: Number.isFinite(limit) ? limit : 10,
|
|
291
|
+
}),
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
case '/api/realtime':
|
|
295
|
+
return json({ ok: true, data: await engine.realtime() });
|
|
296
|
+
case '/api/events': {
|
|
297
|
+
const raw = Number(p.get('limit') ?? 100);
|
|
298
|
+
// `-1` is truthy, so `n || fallback` would pass it through. Postgres then
|
|
299
|
+
// rejects LIMIT -1 and the handler answers 500.
|
|
300
|
+
const limit = Number.isFinite(raw) ? Math.min(5000, Math.max(1, Math.floor(raw))) : 100;
|
|
301
|
+
return json({ ok: true, data: await engine.events(range, filters, limit) });
|
|
302
|
+
}
|
|
303
|
+
case '/api/export.csv': {
|
|
304
|
+
const csv = toCsv(await engine.events(range, filters, 100_000));
|
|
305
|
+
return new Response(csv, {
|
|
306
|
+
headers: {
|
|
307
|
+
'content-type': 'text/csv; charset=utf-8',
|
|
308
|
+
'content-disposition': 'attachment; filename="tallymark.csv"',
|
|
309
|
+
'cache-control': 'no-store',
|
|
310
|
+
},
|
|
311
|
+
});
|
|
312
|
+
}
|
|
313
|
+
default:
|
|
314
|
+
return json({ ok: false, error: 'not_found' }, 404);
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
return async function handle(req, info = {}) {
|
|
318
|
+
try {
|
|
319
|
+
const url = new URL(req.url);
|
|
320
|
+
let route = url.pathname;
|
|
321
|
+
if (base && route.startsWith(base))
|
|
322
|
+
route = route.slice(base.length) || '/';
|
|
323
|
+
route = route.replace(/\/$/, '') || '/';
|
|
324
|
+
if (req.method === 'OPTIONS') {
|
|
325
|
+
return new Response(null, {
|
|
326
|
+
status: 204,
|
|
327
|
+
headers: {
|
|
328
|
+
...corsFor(req),
|
|
329
|
+
'access-control-allow-methods': 'GET, POST, OPTIONS',
|
|
330
|
+
'access-control-allow-headers': 'content-type, authorization',
|
|
331
|
+
'access-control-max-age': '86400',
|
|
332
|
+
},
|
|
333
|
+
});
|
|
334
|
+
}
|
|
335
|
+
if (route === '/collect') {
|
|
336
|
+
return req.method === 'POST'
|
|
337
|
+
? await collect(req, info)
|
|
338
|
+
: json({ ok: false }, 405, { allow: 'POST, OPTIONS' });
|
|
339
|
+
}
|
|
340
|
+
if (route === '/script.js' && req.method === 'GET') {
|
|
341
|
+
return new Response(TRACKER, {
|
|
342
|
+
headers: {
|
|
343
|
+
'content-type': 'application/javascript; charset=utf-8',
|
|
344
|
+
'cache-control': 'public, max-age=86400',
|
|
345
|
+
'access-control-allow-origin': '*',
|
|
346
|
+
},
|
|
347
|
+
});
|
|
348
|
+
}
|
|
349
|
+
if (route === '/health')
|
|
350
|
+
return json({ ok: true });
|
|
351
|
+
if (route === '/api/import') {
|
|
352
|
+
if (req.method !== 'POST')
|
|
353
|
+
return json({ ok: false }, 405, { allow: 'POST' });
|
|
354
|
+
if (!authorised(req))
|
|
355
|
+
return json({ ok: false, error: 'unauthorized' }, 401, { 'www-authenticate': 'Bearer' });
|
|
356
|
+
const text = await readBounded(req, MAX_IMPORT);
|
|
357
|
+
if (text === null)
|
|
358
|
+
return json({ ok: false, error: 'too_large' }, 413);
|
|
359
|
+
return json({ ok: true, data: await engine.import(text) });
|
|
360
|
+
}
|
|
361
|
+
if (route.startsWith('/api/') && req.method === 'GET')
|
|
362
|
+
return await api(req, route, url.searchParams);
|
|
363
|
+
return json({ ok: false, error: 'not_found' }, 404);
|
|
364
|
+
}
|
|
365
|
+
catch (error) {
|
|
366
|
+
onError(error);
|
|
367
|
+
// Analytics must never take a host app down, and must never leak internals.
|
|
368
|
+
return json({ ok: false, error: 'internal' }, 500);
|
|
369
|
+
}
|
|
370
|
+
};
|
|
371
|
+
}
|
|
372
|
+
function toMs(v) {
|
|
373
|
+
if (!v)
|
|
374
|
+
return null;
|
|
375
|
+
const n = /^\d+$/.test(v) ? Number(v) : Date.parse(v);
|
|
376
|
+
return Number.isFinite(n) ? n : null;
|
|
377
|
+
}
|
|
378
|
+
/** `steps=/pricing,/docs/*,event:Signup` -> steps. 2 to 10 steps. */
|
|
379
|
+
function parseSteps(v) {
|
|
380
|
+
if (!v)
|
|
381
|
+
return null;
|
|
382
|
+
const steps = v.split(',').map((s) => {
|
|
383
|
+
const t = s.trim();
|
|
384
|
+
if (t.startsWith('event:') && t.length > 6)
|
|
385
|
+
return { event: t.slice(6) };
|
|
386
|
+
if (t.startsWith('/'))
|
|
387
|
+
return { path: t };
|
|
388
|
+
return null;
|
|
389
|
+
});
|
|
390
|
+
if (steps.length < 2 || steps.length > 10 || steps.some((s) => s === null))
|
|
391
|
+
return null;
|
|
392
|
+
return steps;
|
|
393
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export { DIMENSIONS, isDimension, TOP_DIMENSIONS } from './query.js';
|
|
2
|
+
export { memoryStore, mirrorStore } from './stores.js';
|
|
3
|
+
export type { Tallymark } from './tallymark.js';
|
|
4
|
+
export { createTallymark, isTallymarkEvent } from './tallymark.js';
|
|
5
|
+
export type * from './types.js';
|
|
6
|
+
export type { WebhookOptions } from './webhook.js';
|
|
7
|
+
export { verifyWebhookSignature, webhookSink } from './webhook.js';
|
package/dist/index.js
ADDED
package/dist/node.d.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { Tallymark } from './tallymark.js';
|
|
2
|
+
import type { ConnInfo } from './types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Node.js `http` / Express / Fastify / Connect. Structural types only, so this
|
|
5
|
+
* file imports nothing from Node and stays runtime-neutral.
|
|
6
|
+
*
|
|
7
|
+
* import express from 'express'
|
|
8
|
+
* app.use('/analytics', nodeHandler(analytics)) // express
|
|
9
|
+
* http.createServer(nodeHandler(analytics)).listen(3000) // plain node
|
|
10
|
+
*
|
|
11
|
+
* Mount under a prefix and set `basePath` to match, e.g. `basePath: '/analytics'`.
|
|
12
|
+
*/
|
|
13
|
+
export interface NodeRequestLike extends AsyncIterable<Uint8Array | string> {
|
|
14
|
+
method?: string;
|
|
15
|
+
url?: string;
|
|
16
|
+
originalUrl?: string;
|
|
17
|
+
headers: Record<string, string | string[] | undefined>;
|
|
18
|
+
socket?: {
|
|
19
|
+
remoteAddress?: string;
|
|
20
|
+
encrypted?: boolean;
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
export interface NodeResponseLike {
|
|
24
|
+
statusCode: number;
|
|
25
|
+
setHeader(name: string, value: string | string[]): unknown;
|
|
26
|
+
end(chunk?: Uint8Array | string): unknown;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* A Fetch `Request` built from a Node request. Pass a body only when you need one:
|
|
30
|
+
* without it the body stream is never touched, so this is safe after `express.json()`.
|
|
31
|
+
* Use it with `tm.trackRequest(nodeRequest(req), ...)` to record server-side events.
|
|
32
|
+
*/
|
|
33
|
+
export declare function nodeRequest(req: NodeRequestLike, body?: Uint8Array): Request;
|
|
34
|
+
/** The socket address is the truth unless a proxy you control sits in front. */
|
|
35
|
+
export declare function nodeConn(req: NodeRequestLike, options?: {
|
|
36
|
+
trustProxy?: boolean;
|
|
37
|
+
}): ConnInfo;
|
|
38
|
+
export declare function nodeHandler(engine: Tallymark, options?: {
|
|
39
|
+
trustProxy?: boolean;
|
|
40
|
+
}): (req: NodeRequestLike, res: NodeResponseLike) => Promise<void>;
|
package/dist/node.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A Fetch `Request` built from a Node request. Pass a body only when you need one:
|
|
3
|
+
* without it the body stream is never touched, so this is safe after `express.json()`.
|
|
4
|
+
* Use it with `tm.trackRequest(nodeRequest(req), ...)` to record server-side events.
|
|
5
|
+
*/
|
|
6
|
+
export function nodeRequest(req, body) {
|
|
7
|
+
const headers = new Headers();
|
|
8
|
+
for (const [k, v] of Object.entries(req.headers)) {
|
|
9
|
+
if (v === undefined)
|
|
10
|
+
continue;
|
|
11
|
+
if (Array.isArray(v))
|
|
12
|
+
for (const x of v)
|
|
13
|
+
headers.append(k, x);
|
|
14
|
+
else
|
|
15
|
+
headers.set(k, v);
|
|
16
|
+
}
|
|
17
|
+
const host = headers.get('host') ?? 'localhost';
|
|
18
|
+
const proto = req.socket?.encrypted || headers.get('x-forwarded-proto') === 'https' ? 'https' : 'http';
|
|
19
|
+
// Express strips the mount prefix from `url`; `originalUrl` keeps it.
|
|
20
|
+
const url = new URL(req.originalUrl ?? req.url ?? '/', `${proto}://${host}`);
|
|
21
|
+
return new Request(url, {
|
|
22
|
+
method: (req.method ?? 'GET').toUpperCase(),
|
|
23
|
+
headers,
|
|
24
|
+
body: body,
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
/** The socket address is the truth unless a proxy you control sits in front. */
|
|
28
|
+
export function nodeConn(req, options = {}) {
|
|
29
|
+
return { ip: options.trustProxy ? undefined : req.socket?.remoteAddress };
|
|
30
|
+
}
|
|
31
|
+
// Same ceiling as the import endpoint. Stop reading once it is passed.
|
|
32
|
+
const MAX_NODE_BODY = 32 * 1024 * 1024;
|
|
33
|
+
export function nodeHandler(engine, options = {}) {
|
|
34
|
+
return async (req, res) => {
|
|
35
|
+
const method = (req.method ?? 'GET').toUpperCase();
|
|
36
|
+
let body;
|
|
37
|
+
if (method !== 'GET' && method !== 'HEAD') {
|
|
38
|
+
const parts = [];
|
|
39
|
+
let size = 0;
|
|
40
|
+
for await (const chunk of req) {
|
|
41
|
+
const bytes = typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk;
|
|
42
|
+
size += bytes.byteLength;
|
|
43
|
+
if (size > MAX_NODE_BODY) {
|
|
44
|
+
res.statusCode = 413;
|
|
45
|
+
res.setHeader('content-type', 'application/json; charset=utf-8');
|
|
46
|
+
res.setHeader('cache-control', 'no-store');
|
|
47
|
+
res.end(JSON.stringify({ ok: false, error: 'too_large' }));
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
50
|
+
parts.push(bytes);
|
|
51
|
+
}
|
|
52
|
+
body = new Uint8Array(size);
|
|
53
|
+
let off = 0;
|
|
54
|
+
for (const p of parts) {
|
|
55
|
+
body.set(p, off);
|
|
56
|
+
off += p.byteLength;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
const response = await engine.handle(nodeRequest(req, body), nodeConn(req, options));
|
|
60
|
+
res.statusCode = response.status;
|
|
61
|
+
response.headers.forEach((value, key) => {
|
|
62
|
+
res.setHeader(key, value);
|
|
63
|
+
});
|
|
64
|
+
res.end(new Uint8Array(await response.arrayBuffer()));
|
|
65
|
+
};
|
|
66
|
+
}
|
package/dist/query.d.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Comparison, Dimension, Filters, FunnelRow, FunnelStep, Interval, Journey, Range, Realtime, SessionTrace, StaticDimension, Summary, TallymarkEvent, TimePoint, TopDimension, TopRow } from './types.js';
|
|
2
|
+
export declare const DIMENSIONS: readonly StaticDimension[];
|
|
3
|
+
/** Everything `top()` accepts: the dimensions, plus entry/exit pages derived from sessions. */
|
|
4
|
+
export declare const TOP_DIMENSIONS: readonly TopDimension[];
|
|
5
|
+
/** A built-in dimension or a `prop:<name>` custom property. */
|
|
6
|
+
export declare const isDimension: (d: string) => d is Dimension;
|
|
7
|
+
export declare function applyFilters(events: TallymarkEvent[], filters: Filters): TallymarkEvent[];
|
|
8
|
+
/**
|
|
9
|
+
* Only a session's entry pageview carries a referrer or campaign. Let every later hit
|
|
10
|
+
* (pages, custom events, engagement beacons) inherit it, so a visitor who arrived from
|
|
11
|
+
* Google counts as Google for the whole visit, and "revenue by source" works.
|
|
12
|
+
* A hit that brings its own source (a new campaign landing) replaces the inherited one,
|
|
13
|
+
* and a new session starts after `gapMs` of inactivity.
|
|
14
|
+
*/
|
|
15
|
+
export declare function inheritAttribution(events: TallymarkEvent[], gapMs?: number): TallymarkEvent[];
|
|
16
|
+
export declare function summary(events: TallymarkEvent[], range: Range, sessionMinutes?: number): Summary;
|
|
17
|
+
export declare const autoInterval: (r: Range) => Interval;
|
|
18
|
+
export declare function timeseries(events: TallymarkEvent[], range: Range, interval?: Interval): TimePoint[];
|
|
19
|
+
export declare function top(events: TallymarkEvent[], by: TopDimension, limit?: number, sessionMinutes?: number): TopRow[];
|
|
20
|
+
/** Recent sessions, newest first, each with the ordered steps the visitor took. */
|
|
21
|
+
export declare function sessionTraces(events: TallymarkEvent[], sessionMinutes?: number, limit?: number): SessionTrace[];
|
|
22
|
+
/** The most common routes through the site: each session's first `depth` pages, in order. */
|
|
23
|
+
export declare function journeys(events: TallymarkEvent[], sessionMinutes?: number, depth?: number, limit?: number): Journey[];
|
|
24
|
+
export declare function compare(current: Summary, previous: Summary): Comparison;
|
|
25
|
+
/**
|
|
26
|
+
* Ordered funnel. A visitor counts for step N only if they hit steps 1..N in
|
|
27
|
+
* order. Visitor ids rotate daily by design, so a funnel measures within-day journeys.
|
|
28
|
+
*/
|
|
29
|
+
export declare function funnel(events: TallymarkEvent[], steps: FunnelStep[]): FunnelRow[];
|
|
30
|
+
export declare function realtime(events: TallymarkEvent[], now: number, windowMinutes?: number): Realtime;
|
|
31
|
+
export declare function toCsv(events: TallymarkEvent[]): string;
|