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
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
import { describeRequest, isSpamReferrer, parseReferrer, parseUrl, parseUserAgent, randomId, randomSecret, sanitizeProps, screenClass, visitorId, } from './hit.js';
|
|
2
|
+
import { createHandler } from './http.js';
|
|
3
|
+
import * as q from './query.js';
|
|
4
|
+
import { memoryStore } from './stores.js';
|
|
5
|
+
const RANGE_MS = {
|
|
6
|
+
'1h': 3_600_000,
|
|
7
|
+
'24h': 86_400_000,
|
|
8
|
+
'7d': 7 * 86_400_000,
|
|
9
|
+
'30d': 30 * 86_400_000,
|
|
10
|
+
'90d': 90 * 86_400_000,
|
|
11
|
+
'365d': 365 * 86_400_000,
|
|
12
|
+
};
|
|
13
|
+
/** Structural check for imported data: never trust a backup file blindly. */
|
|
14
|
+
export function isTallymarkEvent(v) {
|
|
15
|
+
if (!v || typeof v !== 'object')
|
|
16
|
+
return false;
|
|
17
|
+
const e = v;
|
|
18
|
+
const str = (x) => typeof x === 'string';
|
|
19
|
+
const nstr = (x) => x === null || typeof x === 'string';
|
|
20
|
+
const u = e.utm;
|
|
21
|
+
return (str(e.id) &&
|
|
22
|
+
e.id.length > 0 &&
|
|
23
|
+
e.id.length <= 64 &&
|
|
24
|
+
(e.type === 'pageview' || e.type === 'event' || e.type === 'engagement') &&
|
|
25
|
+
str(e.name) &&
|
|
26
|
+
typeof e.ts === 'number' &&
|
|
27
|
+
Number.isFinite(e.ts) &&
|
|
28
|
+
str(e.visitor) &&
|
|
29
|
+
str(e.hostname) &&
|
|
30
|
+
str(e.path) &&
|
|
31
|
+
nstr(e.referrer) &&
|
|
32
|
+
nstr(e.referrerHost) &&
|
|
33
|
+
!!u &&
|
|
34
|
+
typeof u === 'object' &&
|
|
35
|
+
['source', 'medium', 'campaign', 'term', 'content'].every((k) => nstr(u[k])) &&
|
|
36
|
+
nstr(e.browser) &&
|
|
37
|
+
nstr(e.os) &&
|
|
38
|
+
nstr(e.country) &&
|
|
39
|
+
nstr(e.region) &&
|
|
40
|
+
nstr(e.city) &&
|
|
41
|
+
nstr(e.language) &&
|
|
42
|
+
nstr(e.browserVersion) &&
|
|
43
|
+
nstr(e.osVersion) &&
|
|
44
|
+
nstr(e.timezone) &&
|
|
45
|
+
(e.screen === null || ['mobile', 'tablet', 'laptop', 'desktop'].includes(e.screen)) &&
|
|
46
|
+
(e.duration === null || (typeof e.duration === 'number' && Number.isFinite(e.duration))) &&
|
|
47
|
+
(e.scroll === null || (typeof e.scroll === 'number' && Number.isFinite(e.scroll))) &&
|
|
48
|
+
['desktop', 'mobile', 'tablet', 'unknown'].includes(e.device) &&
|
|
49
|
+
!!e.props &&
|
|
50
|
+
typeof e.props === 'object' &&
|
|
51
|
+
!Array.isArray(e.props) &&
|
|
52
|
+
(e.value === null || (typeof e.value === 'number' && Number.isFinite(e.value))));
|
|
53
|
+
}
|
|
54
|
+
export function createTallymark(options = {}) {
|
|
55
|
+
const now = options.now ?? Date.now;
|
|
56
|
+
const store = options.store ?? memoryStore();
|
|
57
|
+
const secret = options.secret ?? randomSecret();
|
|
58
|
+
const sessionMinutes = options.sessionMinutes ?? 30;
|
|
59
|
+
const respectDnt = options.respectDnt ?? true;
|
|
60
|
+
const allowedHosts = options.allowedHosts?.map((h) => h.toLowerCase().replace(/^www\./, ''));
|
|
61
|
+
const excludeIps = new Set(options.excludeIps ?? []);
|
|
62
|
+
const report = (error, where) => {
|
|
63
|
+
try {
|
|
64
|
+
options.onError?.(error, { where });
|
|
65
|
+
}
|
|
66
|
+
catch {
|
|
67
|
+
/* a broken logger must never break analytics */
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
const resolve = (r = '7d') => {
|
|
71
|
+
if (typeof r !== 'string')
|
|
72
|
+
return r;
|
|
73
|
+
const to = now() + 1;
|
|
74
|
+
return { from: to - (RANGE_MS[r] ?? RANGE_MS['7d']), to };
|
|
75
|
+
};
|
|
76
|
+
const load = async (r, filters = {}, limit) => {
|
|
77
|
+
const range = resolve(r);
|
|
78
|
+
const cap = typeof limit === 'number' && Number.isFinite(limit) && limit > 0
|
|
79
|
+
? Math.floor(limit)
|
|
80
|
+
: undefined;
|
|
81
|
+
// A filter has to see the whole range. Limiting first keeps the newest rows,
|
|
82
|
+
// then drops the ones that do not match, and the caller gets nothing.
|
|
83
|
+
const filtering = Object.values(filters).some((v) => v !== undefined && v !== '');
|
|
84
|
+
const events = q.applyFilters(q.inheritAttribution(await store.list({ ...range, limit: filtering ? undefined : cap }), sessionMinutes * 60_000), filters);
|
|
85
|
+
return { range, events: cap !== undefined ? events.slice(-cap) : events };
|
|
86
|
+
};
|
|
87
|
+
const engine = {
|
|
88
|
+
store,
|
|
89
|
+
options,
|
|
90
|
+
async track(input, info) {
|
|
91
|
+
const parsed = parseUrl(input.url);
|
|
92
|
+
if (!parsed)
|
|
93
|
+
return { ok: false, reason: 'invalid' };
|
|
94
|
+
const hostname = parsed.hostname;
|
|
95
|
+
if (allowedHosts && !allowedHosts.includes(hostname))
|
|
96
|
+
return { ok: false, reason: 'host' };
|
|
97
|
+
if (input.ip && excludeIps.has(input.ip))
|
|
98
|
+
return { ok: false, reason: 'excluded' };
|
|
99
|
+
const ua = parseUserAgent(input.userAgent);
|
|
100
|
+
if (ua.bot)
|
|
101
|
+
return { ok: false, reason: 'bot' };
|
|
102
|
+
const name = (input.name ?? 'pageview').trim().slice(0, 80);
|
|
103
|
+
if (name === '')
|
|
104
|
+
return { ok: false, reason: 'invalid' };
|
|
105
|
+
const type = name === 'pageview' ? 'pageview' : name === 'engagement' ? 'engagement' : 'event';
|
|
106
|
+
// An engagement beacon reports time on a page; without a duration it means nothing.
|
|
107
|
+
if (type === 'engagement' &&
|
|
108
|
+
!(typeof input.duration === 'number' && Number.isFinite(input.duration))) {
|
|
109
|
+
return { ok: false, reason: 'invalid' };
|
|
110
|
+
}
|
|
111
|
+
const ref = parseReferrer(input.referrer, hostname);
|
|
112
|
+
if (isSpamReferrer(ref.host, options.blockedReferrers))
|
|
113
|
+
return { ok: false, reason: 'spam' };
|
|
114
|
+
const ts = input.ts ?? now();
|
|
115
|
+
const value = typeof input.value === 'number' && Number.isFinite(input.value) ? input.value : null;
|
|
116
|
+
const event = {
|
|
117
|
+
id: randomId(),
|
|
118
|
+
type,
|
|
119
|
+
name,
|
|
120
|
+
ts,
|
|
121
|
+
visitor: await visitorId(secret, ts, hostname, input.ip ?? null, input.userAgent ?? null),
|
|
122
|
+
hostname,
|
|
123
|
+
path: parsed.path,
|
|
124
|
+
referrer: ref.referrer,
|
|
125
|
+
referrerHost: ref.host,
|
|
126
|
+
utm: parsed.utm,
|
|
127
|
+
browser: ua.browser,
|
|
128
|
+
browserVersion: ua.browserVersion,
|
|
129
|
+
os: ua.os,
|
|
130
|
+
osVersion: ua.osVersion,
|
|
131
|
+
device: ua.device,
|
|
132
|
+
country: input.country ?? null,
|
|
133
|
+
region: input.region ?? null,
|
|
134
|
+
city: input.city ?? null,
|
|
135
|
+
timezone: input.timezone ?? null,
|
|
136
|
+
language: input.language ?? null,
|
|
137
|
+
screen: screenClass(input.screenWidth),
|
|
138
|
+
props: type === 'engagement' ? {} : sanitizeProps(input.props),
|
|
139
|
+
value: type === 'engagement' ? null : value,
|
|
140
|
+
// Capped at 4 hours: a tab left open overnight is not four hundred minutes of reading.
|
|
141
|
+
duration: type === 'engagement'
|
|
142
|
+
? Math.min(14_400_000, Math.max(0, Math.round(input.duration)))
|
|
143
|
+
: null,
|
|
144
|
+
scroll: type === 'engagement' && typeof input.scroll === 'number' && Number.isFinite(input.scroll)
|
|
145
|
+
? Math.min(100, Math.max(0, Math.round(input.scroll)))
|
|
146
|
+
: null,
|
|
147
|
+
};
|
|
148
|
+
// A failing database must not crash the caller; report it as a typed result.
|
|
149
|
+
try {
|
|
150
|
+
await store.insert(event);
|
|
151
|
+
}
|
|
152
|
+
catch (error) {
|
|
153
|
+
report(error, 'track');
|
|
154
|
+
return { ok: false, reason: 'storage' };
|
|
155
|
+
}
|
|
156
|
+
if (options.forward) {
|
|
157
|
+
const forward = options.forward;
|
|
158
|
+
const job = Promise.resolve()
|
|
159
|
+
.then(() => forward(event))
|
|
160
|
+
.catch((error) => report(error, 'track'));
|
|
161
|
+
if (info?.waitUntil)
|
|
162
|
+
info.waitUntil(job);
|
|
163
|
+
else
|
|
164
|
+
await job;
|
|
165
|
+
}
|
|
166
|
+
return { ok: true, event };
|
|
167
|
+
},
|
|
168
|
+
async trackRequest(request, event = {}, info = {}) {
|
|
169
|
+
if (respectDnt &&
|
|
170
|
+
(request.headers.get('dnt') === '1' || request.headers.get('sec-gpc') === '1')) {
|
|
171
|
+
return { ok: false, reason: 'dnt' };
|
|
172
|
+
}
|
|
173
|
+
const { name, url, props, value } = event;
|
|
174
|
+
return engine.track({
|
|
175
|
+
name,
|
|
176
|
+
props,
|
|
177
|
+
value,
|
|
178
|
+
url: url ?? request.url,
|
|
179
|
+
referrer: request.headers.get('referer'),
|
|
180
|
+
...describeRequest(request, info, options.trustProxy ?? true),
|
|
181
|
+
}, info);
|
|
182
|
+
},
|
|
183
|
+
async summary(range, filters) {
|
|
184
|
+
const { range: r, events } = await load(range, filters);
|
|
185
|
+
return q.summary(events, r, sessionMinutes);
|
|
186
|
+
},
|
|
187
|
+
async compare(range, filters) {
|
|
188
|
+
const current = resolve(range);
|
|
189
|
+
const previous = { from: current.from - (current.to - current.from), to: current.from };
|
|
190
|
+
const [a, b] = await Promise.all([load(current, filters), load(previous, filters)]);
|
|
191
|
+
return q.compare(q.summary(a.events, a.range, sessionMinutes), q.summary(b.events, b.range, sessionMinutes));
|
|
192
|
+
},
|
|
193
|
+
async timeseries(range, filters, interval) {
|
|
194
|
+
const { range: r, events } = await load(range, filters);
|
|
195
|
+
return q.timeseries(events, r, interval);
|
|
196
|
+
},
|
|
197
|
+
async top(by, range, filters, limit) {
|
|
198
|
+
const { events } = await load(range, filters);
|
|
199
|
+
return q.top(events, by, limit, sessionMinutes);
|
|
200
|
+
},
|
|
201
|
+
async funnel(steps, range, filters) {
|
|
202
|
+
const { events } = await load(range, filters);
|
|
203
|
+
return q.funnel(events, steps);
|
|
204
|
+
},
|
|
205
|
+
async sessions(range, filters, limit) {
|
|
206
|
+
const { events } = await load(range, filters);
|
|
207
|
+
return q.sessionTraces(events, sessionMinutes, limit);
|
|
208
|
+
},
|
|
209
|
+
async journeys(range, filters, options = {}) {
|
|
210
|
+
const { events } = await load(range, filters);
|
|
211
|
+
return q.journeys(events, sessionMinutes, options.depth, options.limit);
|
|
212
|
+
},
|
|
213
|
+
async realtime(windowMinutes = 5) {
|
|
214
|
+
const t = now();
|
|
215
|
+
const events = await store.list({ from: t - windowMinutes * 60_000, to: t + 1 });
|
|
216
|
+
return q.realtime(events, t, windowMinutes);
|
|
217
|
+
},
|
|
218
|
+
async events(range, filters, limit = 1000) {
|
|
219
|
+
const max = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 1000;
|
|
220
|
+
return (await load(range, filters, max)).events;
|
|
221
|
+
},
|
|
222
|
+
async export(range, filters) {
|
|
223
|
+
const { events } = await load(range, filters, 1_000_000);
|
|
224
|
+
return events.map((e) => JSON.stringify(e)).join('\n') + (events.length ? '\n' : '');
|
|
225
|
+
},
|
|
226
|
+
async import(ndjson) {
|
|
227
|
+
let imported = 0;
|
|
228
|
+
let skipped = 0;
|
|
229
|
+
for (const line of ndjson.split('\n')) {
|
|
230
|
+
if (line.trim() === '')
|
|
231
|
+
continue;
|
|
232
|
+
let e;
|
|
233
|
+
try {
|
|
234
|
+
e = JSON.parse(line);
|
|
235
|
+
}
|
|
236
|
+
catch {
|
|
237
|
+
skipped++;
|
|
238
|
+
continue;
|
|
239
|
+
}
|
|
240
|
+
if (!isTallymarkEvent(e)) {
|
|
241
|
+
skipped++;
|
|
242
|
+
continue;
|
|
243
|
+
}
|
|
244
|
+
await store.insert(e);
|
|
245
|
+
imported++;
|
|
246
|
+
}
|
|
247
|
+
return { imported, skipped };
|
|
248
|
+
},
|
|
249
|
+
async prune() {
|
|
250
|
+
const days = options.retentionDays ?? 0;
|
|
251
|
+
if (days <= 0 || !store.prune)
|
|
252
|
+
return 0;
|
|
253
|
+
try {
|
|
254
|
+
return await store.prune(now() - days * 86_400_000);
|
|
255
|
+
}
|
|
256
|
+
catch (error) {
|
|
257
|
+
report(error, 'prune');
|
|
258
|
+
throw error;
|
|
259
|
+
}
|
|
260
|
+
},
|
|
261
|
+
handle: undefined,
|
|
262
|
+
};
|
|
263
|
+
engine.handle = createHandler(engine, now, (e) => report(e, 'handle'));
|
|
264
|
+
return engine;
|
|
265
|
+
}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
/** Custom event properties. Flat on purpose: easy to store, easy to filter. */
|
|
2
|
+
export type Props = Record<string, string | number | boolean>;
|
|
3
|
+
export type Device = 'desktop' | 'mobile' | 'tablet' | 'unknown';
|
|
4
|
+
export interface Utm {
|
|
5
|
+
source: string | null;
|
|
6
|
+
medium: string | null;
|
|
7
|
+
campaign: string | null;
|
|
8
|
+
term: string | null;
|
|
9
|
+
content: string | null;
|
|
10
|
+
}
|
|
11
|
+
/** One stored record. Contains no IP address and no raw User-Agent. */
|
|
12
|
+
export interface TallymarkEvent {
|
|
13
|
+
id: string;
|
|
14
|
+
/** `pageview` is automatic; `event` is a named custom event. */
|
|
15
|
+
type: 'pageview' | 'event' | 'engagement';
|
|
16
|
+
/** `pageview` or `engagement` for those types, otherwise the custom event name. */
|
|
17
|
+
name: string;
|
|
18
|
+
/** Unix epoch, milliseconds. */
|
|
19
|
+
ts: number;
|
|
20
|
+
/** Daily-rotating anonymous visitor id. Cannot be linked across days. */
|
|
21
|
+
visitor: string;
|
|
22
|
+
hostname: string;
|
|
23
|
+
path: string;
|
|
24
|
+
referrer: string | null;
|
|
25
|
+
referrerHost: string | null;
|
|
26
|
+
utm: Utm;
|
|
27
|
+
/** Browser family, e.g. `Chrome`. */
|
|
28
|
+
browser: string | null;
|
|
29
|
+
/** Major version, e.g. `130`. */
|
|
30
|
+
browserVersion: string | null;
|
|
31
|
+
os: string | null;
|
|
32
|
+
/** Major version. Only for Android and iOS: other user agents are frozen or ambiguous. */
|
|
33
|
+
osVersion: string | null;
|
|
34
|
+
device: Device;
|
|
35
|
+
country: string | null;
|
|
36
|
+
region: string | null;
|
|
37
|
+
city: string | null;
|
|
38
|
+
/** IANA timezone when the platform provides it, e.g. `Europe/Berlin`. */
|
|
39
|
+
timezone: string | null;
|
|
40
|
+
/** Primary language tag from Accept-Language, e.g. `en-US`. */
|
|
41
|
+
language: string | null;
|
|
42
|
+
/** Viewport class reported by the tracker. */
|
|
43
|
+
screen: ScreenClass | null;
|
|
44
|
+
props: Props;
|
|
45
|
+
/** Optional numeric value, e.g. revenue. */
|
|
46
|
+
value: number | null;
|
|
47
|
+
/** Engaged milliseconds on the page (tab visible). Only on `engagement` events. */
|
|
48
|
+
duration: number | null;
|
|
49
|
+
/** Deepest scroll position reached, 0 to 100. Only on `engagement` events. */
|
|
50
|
+
scroll: number | null;
|
|
51
|
+
}
|
|
52
|
+
/** Viewport width class: mobile < 768, tablet < 1024, laptop < 1440, desktop beyond. */
|
|
53
|
+
export type ScreenClass = 'mobile' | 'tablet' | 'laptop' | 'desktop';
|
|
54
|
+
export interface ListQuery {
|
|
55
|
+
from: number;
|
|
56
|
+
to: number;
|
|
57
|
+
/** Hard cap on returned rows. */
|
|
58
|
+
limit?: number;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* The only thing tallymark needs from a database. Three methods.
|
|
62
|
+
* Implement it for anything; the built-ins cover memory, D1, SQLite and libSQL.
|
|
63
|
+
*/
|
|
64
|
+
export interface EventStore {
|
|
65
|
+
insert(event: TallymarkEvent): Promise<void>;
|
|
66
|
+
/** Events with `from <= ts < to`, oldest first. */
|
|
67
|
+
list(query: ListQuery): Promise<TallymarkEvent[]>;
|
|
68
|
+
/** Delete events older than `before`. Returns the number removed. */
|
|
69
|
+
prune?(before: number): Promise<number>;
|
|
70
|
+
}
|
|
71
|
+
/** Why an incoming hit was not recorded. */
|
|
72
|
+
export type IgnoreReason = 'bot' | 'dnt' | 'invalid' | 'rate_limited' | 'origin' | 'too_large' | 'host' | 'excluded' | 'dnt' | 'spam' | 'prefetch' | 'storage';
|
|
73
|
+
export type TrackResult = {
|
|
74
|
+
ok: true;
|
|
75
|
+
event: TallymarkEvent;
|
|
76
|
+
} | {
|
|
77
|
+
ok: false;
|
|
78
|
+
reason: IgnoreReason;
|
|
79
|
+
};
|
|
80
|
+
/** Everything a hit needs, independent of HTTP. Use it for server-side tracking. */
|
|
81
|
+
export interface TrackInput {
|
|
82
|
+
/** Event name. Omit (or `pageview`) for a pageview. */
|
|
83
|
+
name?: string;
|
|
84
|
+
/** Absolute URL or a path. Query strings are dropped except campaign params. */
|
|
85
|
+
url: string;
|
|
86
|
+
referrer?: string | null;
|
|
87
|
+
props?: Props;
|
|
88
|
+
value?: number;
|
|
89
|
+
ip?: string | null;
|
|
90
|
+
userAgent?: string | null;
|
|
91
|
+
country?: string | null;
|
|
92
|
+
region?: string | null;
|
|
93
|
+
city?: string | null;
|
|
94
|
+
language?: string | null;
|
|
95
|
+
timezone?: string | null;
|
|
96
|
+
/** Viewport width in CSS pixels; bucketed into a screen class. */
|
|
97
|
+
screenWidth?: number;
|
|
98
|
+
/** With `name: 'engagement'`: engaged milliseconds on the page. */
|
|
99
|
+
duration?: number;
|
|
100
|
+
/** With `name: 'engagement'`: deepest scroll position, 0 to 100. */
|
|
101
|
+
scroll?: number;
|
|
102
|
+
/** Defaults to now. */
|
|
103
|
+
ts?: number;
|
|
104
|
+
}
|
|
105
|
+
/** Per-request connection facts the platform knows and headers cannot be trusted for. */
|
|
106
|
+
export interface ConnInfo {
|
|
107
|
+
/** Authoritative client IP, e.g. from Bun's `server.requestIP()`. Wins over proxy headers. */
|
|
108
|
+
ip?: string | null;
|
|
109
|
+
/**
|
|
110
|
+
* Run background work (forwarding) without blocking the response. Pass
|
|
111
|
+
* `ctx.waitUntil` on Cloudflare / Vercel; without it, forwarding is awaited.
|
|
112
|
+
*/
|
|
113
|
+
waitUntil?: (promise: Promise<unknown>) => void;
|
|
114
|
+
/**
|
|
115
|
+
* Authoritative location from the platform (e.g. Cloudflare's `request.cf`).
|
|
116
|
+
* Wins over headers and is applied even when `trustProxy` is false.
|
|
117
|
+
*/
|
|
118
|
+
geo?: {
|
|
119
|
+
country?: string | null;
|
|
120
|
+
region?: string | null;
|
|
121
|
+
city?: string | null;
|
|
122
|
+
timezone?: string | null;
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
export interface TallymarkOptions {
|
|
126
|
+
/**
|
|
127
|
+
* Secret mixed into visitor hashes. Set a long random string in production.
|
|
128
|
+
* Rotate it to invalidate every visitor id at once. Falls back to a random
|
|
129
|
+
* per-process value, which means ids change on every restart.
|
|
130
|
+
*/
|
|
131
|
+
secret?: string;
|
|
132
|
+
/** Where events go. Defaults to a bounded in-memory store: no database needed. */
|
|
133
|
+
store?: EventStore;
|
|
134
|
+
/** Bearer token for the read API. Unset = the read API is disabled. */
|
|
135
|
+
apiKey?: string;
|
|
136
|
+
/** Origins allowed to POST /collect from a browser. `*` allows any. Default `*`. */
|
|
137
|
+
allowedOrigins?: string[] | '*';
|
|
138
|
+
/** Only record hits for these hostnames. Default: any. */
|
|
139
|
+
allowedHosts?: string[];
|
|
140
|
+
/** Honour Do-Not-Track and Global Privacy Control. Default `true`. */
|
|
141
|
+
respectDnt?: boolean;
|
|
142
|
+
/** Per-IP limit on /collect. `false` disables. Default 120 hits / minute. */
|
|
143
|
+
rateLimit?: {
|
|
144
|
+
max: number;
|
|
145
|
+
windowMs: number;
|
|
146
|
+
} | false;
|
|
147
|
+
/** Read client IP / geo from proxy headers (Cloudflare, Vercel, nginx). Default `true`. */
|
|
148
|
+
trustProxy?: boolean;
|
|
149
|
+
/** URL prefix the handler is mounted at, e.g. `/api/analytics`. Default `''`. */
|
|
150
|
+
basePath?: string;
|
|
151
|
+
/** Delete events older than this many days when `prune()` runs. Default 0 = keep. */
|
|
152
|
+
retentionDays?: number;
|
|
153
|
+
/** Inactivity gap that starts a new session, in minutes. Default 30. */
|
|
154
|
+
sessionMinutes?: number;
|
|
155
|
+
/** Drop hits from these IPs (your own, health checks). Exact match. */
|
|
156
|
+
excludeIps?: string[];
|
|
157
|
+
/** Extra referrer hosts to treat as spam, on top of the built-in list. Suffix match. */
|
|
158
|
+
blockedReferrers?: string[];
|
|
159
|
+
/**
|
|
160
|
+
* Require the browser's Origin (or Referer) host to be one of `allowedHosts`.
|
|
161
|
+
* Stops other websites from injecting hits via a visitor's browser. Needs `allowedHosts`.
|
|
162
|
+
*/
|
|
163
|
+
strictOrigin?: boolean;
|
|
164
|
+
/**
|
|
165
|
+
* Send every recorded event to a third party as well (webhook, queue, another
|
|
166
|
+
* analytics tool). Runs after the event is stored; failures go to `onError`
|
|
167
|
+
* and never fail the hit. See `webhookSink()`.
|
|
168
|
+
*/
|
|
169
|
+
forward?: (event: TallymarkEvent) => void | Promise<void>;
|
|
170
|
+
/** Called on swallowed failures (storage errors, handler exceptions). Wire it to your logger. */
|
|
171
|
+
onError?: (error: unknown, context: {
|
|
172
|
+
where: 'track' | 'handle' | 'prune';
|
|
173
|
+
}) => void;
|
|
174
|
+
/** Clock override, for tests. */
|
|
175
|
+
now?: () => number;
|
|
176
|
+
}
|
|
177
|
+
/** Every built-in dimension. Pass to `top()`, or use as a filter. */
|
|
178
|
+
export type StaticDimension = 'path' | 'referrer' | 'source' | 'channel' | 'country' | 'continent' | 'region' | 'city' | 'timezone' | 'language' | 'browser' | 'browser_version' | 'os' | 'os_version' | 'device' | 'screen' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'utm_term' | 'utm_content' | 'event' | 'hostname' | 'weekday' | 'hour';
|
|
179
|
+
/** A built-in dimension, or `prop:<name>` for any custom event property, e.g. `prop:plan`. */
|
|
180
|
+
export type Dimension = StaticDimension | `prop:${string}`;
|
|
181
|
+
/** Dimensions `top()` can group by. Entry/exit pages are derived from sessions. */
|
|
182
|
+
export type TopDimension = Dimension | 'entry_page' | 'exit_page';
|
|
183
|
+
export type Filters = Partial<Record<Dimension, string>>;
|
|
184
|
+
export interface Range {
|
|
185
|
+
from: number;
|
|
186
|
+
to: number;
|
|
187
|
+
}
|
|
188
|
+
export type RangeInput = Range | '1h' | '24h' | '7d' | '30d' | '90d' | '365d';
|
|
189
|
+
export interface Summary {
|
|
190
|
+
range: Range;
|
|
191
|
+
pageviews: number;
|
|
192
|
+
visitors: number;
|
|
193
|
+
sessions: number;
|
|
194
|
+
events: number;
|
|
195
|
+
/** Sum of the `value` of custom events (revenue). */
|
|
196
|
+
revenue: number;
|
|
197
|
+
/** 0..1. Sessions with exactly one pageview and no custom events. */
|
|
198
|
+
bounceRate: number;
|
|
199
|
+
/** Average session length in seconds, including time on the last page when the tracker reports it. */
|
|
200
|
+
avgSessionSeconds: number;
|
|
201
|
+
/** Average time on page in seconds (engaged time when reported, else time to the next hit). */
|
|
202
|
+
avgTimeOnPageSeconds: number;
|
|
203
|
+
viewsPerSession: number;
|
|
204
|
+
}
|
|
205
|
+
export type Interval = 'hour' | 'day' | 'week' | 'month';
|
|
206
|
+
export interface TimePoint {
|
|
207
|
+
/** Bucket start, epoch ms (UTC). */
|
|
208
|
+
t: number;
|
|
209
|
+
pageviews: number;
|
|
210
|
+
visitors: number;
|
|
211
|
+
events: number;
|
|
212
|
+
}
|
|
213
|
+
export interface TopRow {
|
|
214
|
+
key: string;
|
|
215
|
+
visitors: number;
|
|
216
|
+
/** Pageviews, or event count when `by = 'event'`. */
|
|
217
|
+
count: number;
|
|
218
|
+
/** Sum of `value`, only present when `by = 'event'`. */
|
|
219
|
+
value?: number;
|
|
220
|
+
/** Average time on page in seconds. Only for `by = 'path'`. */
|
|
221
|
+
seconds?: number;
|
|
222
|
+
/** Average deepest scroll position, 0 to 100. Only for `by = 'path'`, when reported. */
|
|
223
|
+
scroll?: number;
|
|
224
|
+
}
|
|
225
|
+
export interface Realtime {
|
|
226
|
+
windowMinutes: number;
|
|
227
|
+
visitors: number;
|
|
228
|
+
pageviews: number;
|
|
229
|
+
topPaths: TopRow[];
|
|
230
|
+
}
|
|
231
|
+
export interface Delta {
|
|
232
|
+
current: number;
|
|
233
|
+
previous: number;
|
|
234
|
+
/** Relative change vs. previous, or null when the previous value was 0. */
|
|
235
|
+
change: number | null;
|
|
236
|
+
}
|
|
237
|
+
export interface Comparison {
|
|
238
|
+
current: Summary;
|
|
239
|
+
previous: Summary;
|
|
240
|
+
delta: {
|
|
241
|
+
pageviews: Delta;
|
|
242
|
+
visitors: Delta;
|
|
243
|
+
sessions: Delta;
|
|
244
|
+
events: Delta;
|
|
245
|
+
revenue: Delta;
|
|
246
|
+
bounceRate: Delta;
|
|
247
|
+
avgSessionSeconds: Delta;
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
/** One funnel step: a page path, or a custom event name. */
|
|
251
|
+
export type FunnelStep = {
|
|
252
|
+
path: string;
|
|
253
|
+
} | {
|
|
254
|
+
event: string;
|
|
255
|
+
};
|
|
256
|
+
export interface FunnelRow {
|
|
257
|
+
step: number;
|
|
258
|
+
label: string;
|
|
259
|
+
/** Visitors who completed this step after completing every earlier one, in order. */
|
|
260
|
+
visitors: number;
|
|
261
|
+
/** Share of the first step, 0..1. */
|
|
262
|
+
rate: number;
|
|
263
|
+
/** Share lost since the previous step, 0..1. */
|
|
264
|
+
dropoff: number;
|
|
265
|
+
}
|
|
266
|
+
/** One step of a session, in order: a page viewed or a custom event fired. */
|
|
267
|
+
export interface SessionStep {
|
|
268
|
+
t: number;
|
|
269
|
+
type: 'pageview' | 'event';
|
|
270
|
+
path: string;
|
|
271
|
+
/** Custom events only. */
|
|
272
|
+
name?: string;
|
|
273
|
+
value?: number;
|
|
274
|
+
/** Pageviews only: seconds on the page, if known. */
|
|
275
|
+
seconds?: number;
|
|
276
|
+
/** Pageviews only: deepest scroll position, if reported. */
|
|
277
|
+
scroll?: number;
|
|
278
|
+
}
|
|
279
|
+
/** A visitor's journey through the site, rebuilt from their hits. Anonymous, one day at most. */
|
|
280
|
+
export interface SessionTrace {
|
|
281
|
+
id: string;
|
|
282
|
+
start: number;
|
|
283
|
+
/** Last known activity. */
|
|
284
|
+
end: number;
|
|
285
|
+
seconds: number;
|
|
286
|
+
pages: number;
|
|
287
|
+
entry: string | null;
|
|
288
|
+
exit: string | null;
|
|
289
|
+
source: string;
|
|
290
|
+
channel: string;
|
|
291
|
+
country: string | null;
|
|
292
|
+
device: Device;
|
|
293
|
+
browser: string | null;
|
|
294
|
+
os: string | null;
|
|
295
|
+
language: string | null;
|
|
296
|
+
screen: ScreenClass | null;
|
|
297
|
+
revenue: number;
|
|
298
|
+
steps: SessionStep[];
|
|
299
|
+
}
|
|
300
|
+
/** A common route through the site: the first pages of a session, in order. */
|
|
301
|
+
export interface Journey {
|
|
302
|
+
steps: string[];
|
|
303
|
+
sessions: number;
|
|
304
|
+
/** Share of sessions with at least one pageview, 0..1. */
|
|
305
|
+
share: number;
|
|
306
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/vercel.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Tallymark } from './tallymark.js';
|
|
2
|
+
/**
|
|
3
|
+
* Vercel Functions and Next.js route handlers (anything that takes a Web `Request`).
|
|
4
|
+
* Vercel sets `x-real-ip` and `x-vercel-ip-*` headers, which Tallymark reads for the
|
|
5
|
+
* visitor's IP, country, region, city and timezone.
|
|
6
|
+
*
|
|
7
|
+
* // app/api/analytics/[...route]/route.ts
|
|
8
|
+
* import { waitUntil } from '@vercel/functions'
|
|
9
|
+
* export const { GET, POST, OPTIONS } = vercel(analytics, { waitUntil })
|
|
10
|
+
*
|
|
11
|
+
* Set `basePath: '/api/analytics'` on the instance so routes resolve under that path.
|
|
12
|
+
* `waitUntil` is optional: with it, `forward` and `mirrorStore` work after the response is sent.
|
|
13
|
+
*/
|
|
14
|
+
export declare function vercel(tm: Tallymark, options?: {
|
|
15
|
+
waitUntil?: (promise: Promise<unknown>) => void;
|
|
16
|
+
}): {
|
|
17
|
+
GET: (request: Request) => Promise<Response>;
|
|
18
|
+
POST: (request: Request) => Promise<Response>;
|
|
19
|
+
OPTIONS: (request: Request) => Promise<Response>;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* Retention sweep for a Vercel Cron Job. Vercel sends `Authorization: Bearer $CRON_SECRET`;
|
|
23
|
+
* without a secret configured, the handler refuses every call.
|
|
24
|
+
*
|
|
25
|
+
* // app/api/analytics-cron/route.ts
|
|
26
|
+
* export const GET = vercelCron(analytics, { secret: process.env.CRON_SECRET })
|
|
27
|
+
*
|
|
28
|
+
* // vercel.json
|
|
29
|
+
* { "crons": [{ "path": "/api/analytics-cron", "schedule": "0 3 * * *" }] }
|
|
30
|
+
*/
|
|
31
|
+
export declare function vercelCron(tm: Tallymark, options: {
|
|
32
|
+
secret: string | undefined;
|
|
33
|
+
}): (request: Request) => Promise<Response>;
|
package/dist/vercel.js
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { timingSafeEqual } from './http.js';
|
|
2
|
+
/**
|
|
3
|
+
* Vercel Functions and Next.js route handlers (anything that takes a Web `Request`).
|
|
4
|
+
* Vercel sets `x-real-ip` and `x-vercel-ip-*` headers, which Tallymark reads for the
|
|
5
|
+
* visitor's IP, country, region, city and timezone.
|
|
6
|
+
*
|
|
7
|
+
* // app/api/analytics/[...route]/route.ts
|
|
8
|
+
* import { waitUntil } from '@vercel/functions'
|
|
9
|
+
* export const { GET, POST, OPTIONS } = vercel(analytics, { waitUntil })
|
|
10
|
+
*
|
|
11
|
+
* Set `basePath: '/api/analytics'` on the instance so routes resolve under that path.
|
|
12
|
+
* `waitUntil` is optional: with it, `forward` and `mirrorStore` work after the response is sent.
|
|
13
|
+
*/
|
|
14
|
+
export function vercel(tm, options = {}) {
|
|
15
|
+
const handler = (request) => tm.handle(request, { waitUntil: options.waitUntil });
|
|
16
|
+
return { GET: handler, POST: handler, OPTIONS: handler };
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Retention sweep for a Vercel Cron Job. Vercel sends `Authorization: Bearer $CRON_SECRET`;
|
|
20
|
+
* without a secret configured, the handler refuses every call.
|
|
21
|
+
*
|
|
22
|
+
* // app/api/analytics-cron/route.ts
|
|
23
|
+
* export const GET = vercelCron(analytics, { secret: process.env.CRON_SECRET })
|
|
24
|
+
*
|
|
25
|
+
* // vercel.json
|
|
26
|
+
* { "crons": [{ "path": "/api/analytics-cron", "schedule": "0 3 * * *" }] }
|
|
27
|
+
*/
|
|
28
|
+
export function vercelCron(tm, options) {
|
|
29
|
+
return async (request) => {
|
|
30
|
+
const token = (request.headers.get('authorization') ?? '').replace(/^bearer /i, '');
|
|
31
|
+
if (!options.secret || !timingSafeEqual(token, options.secret)) {
|
|
32
|
+
return Response.json({ ok: false, error: 'unauthorized' }, { status: 401 });
|
|
33
|
+
}
|
|
34
|
+
return Response.json({ ok: true, pruned: await tm.prune() });
|
|
35
|
+
};
|
|
36
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { TallymarkEvent } from './types.js';
|
|
2
|
+
export interface WebhookOptions {
|
|
3
|
+
url: string;
|
|
4
|
+
/**
|
|
5
|
+
* If set, each request carries `x-tallymark-signature: sha256=<hex>`, an
|
|
6
|
+
* HMAC-SHA256 of the raw body. Verify it before trusting a delivery.
|
|
7
|
+
*/
|
|
8
|
+
secret?: string;
|
|
9
|
+
headers?: Record<string, string>;
|
|
10
|
+
/** Per-attempt timeout. Default 5000 ms. */
|
|
11
|
+
timeoutMs?: number;
|
|
12
|
+
/** Extra attempts after the first on network errors / 5xx. Default 1. */
|
|
13
|
+
retries?: number;
|
|
14
|
+
fetch?: typeof fetch;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Third-party fan-out: POST every event as JSON to any URL (Zapier, n8n, Slack
|
|
18
|
+
* relay, your own queue). Use as `forward`:
|
|
19
|
+
*
|
|
20
|
+
* createTallymark({ forward: webhookSink({ url, secret }) })
|
|
21
|
+
*
|
|
22
|
+
* Throws on final failure, which the engine routes to `onError`; it never fails
|
|
23
|
+
* the visitor's hit.
|
|
24
|
+
*/
|
|
25
|
+
export declare function webhookSink(options: WebhookOptions): (event: TallymarkEvent) => Promise<void>;
|
|
26
|
+
/** Verify a delivery on the receiving end. Constant-time. */
|
|
27
|
+
export declare function verifyWebhookSignature(secret: string, rawBody: string, header: string | null): Promise<boolean>;
|