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/stores.js
ADDED
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
// ── Memory ────────────────────────────────────────────────────────────────────
|
|
2
|
+
/**
|
|
3
|
+
* Zero-dependency store. Events live in process memory and vanish on restart,
|
|
4
|
+
* which is exactly what you want for tests, demos, and "just give me numbers".
|
|
5
|
+
* Bounded, so it can never grow without limit. Keyed by id, like every other store.
|
|
6
|
+
*/
|
|
7
|
+
export function memoryStore(options = {}) {
|
|
8
|
+
const max = Math.max(1, options.maxEvents ?? 100_000);
|
|
9
|
+
// A Map keeps insertion order, so the first key is always the oldest insert.
|
|
10
|
+
const events = new Map();
|
|
11
|
+
return {
|
|
12
|
+
async insert(event) {
|
|
13
|
+
if (events.has(event.id))
|
|
14
|
+
return;
|
|
15
|
+
events.set(event.id, event);
|
|
16
|
+
if (events.size > max)
|
|
17
|
+
events.delete(events.keys().next().value);
|
|
18
|
+
},
|
|
19
|
+
async list({ from, to, limit }) {
|
|
20
|
+
const out = [...events.values()]
|
|
21
|
+
.filter((e) => e.ts >= from && e.ts < to)
|
|
22
|
+
.sort((a, b) => a.ts - b.ts);
|
|
23
|
+
return limit ? out.slice(-limit) : out;
|
|
24
|
+
},
|
|
25
|
+
async prune(before) {
|
|
26
|
+
let n = 0;
|
|
27
|
+
for (const [id, e] of events) {
|
|
28
|
+
if (e.ts < before) {
|
|
29
|
+
events.delete(id);
|
|
30
|
+
n++;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
return n;
|
|
34
|
+
},
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
const COLUMNS = `
|
|
38
|
+
id TEXT PRIMARY KEY,
|
|
39
|
+
ts @INT NOT NULL,
|
|
40
|
+
type TEXT NOT NULL,
|
|
41
|
+
name TEXT NOT NULL,
|
|
42
|
+
visitor TEXT NOT NULL,
|
|
43
|
+
hostname TEXT NOT NULL,
|
|
44
|
+
path TEXT NOT NULL,
|
|
45
|
+
referrer TEXT,
|
|
46
|
+
referrer_host TEXT,
|
|
47
|
+
utm_source TEXT, utm_medium TEXT, utm_campaign TEXT, utm_term TEXT, utm_content TEXT,
|
|
48
|
+
browser TEXT, browser_version TEXT, os TEXT, os_version TEXT, device TEXT, screen TEXT,
|
|
49
|
+
country TEXT, region TEXT, city TEXT, timezone TEXT, language TEXT,
|
|
50
|
+
props TEXT,
|
|
51
|
+
value @REAL,
|
|
52
|
+
duration @INT,
|
|
53
|
+
scroll @INT`;
|
|
54
|
+
const schema = (d) => [
|
|
55
|
+
`CREATE TABLE IF NOT EXISTS tallymark_events (${COLUMNS}
|
|
56
|
+
)`
|
|
57
|
+
.replaceAll('@INT', d === 'postgres' ? 'BIGINT' : 'INTEGER')
|
|
58
|
+
.replace('@REAL', d === 'postgres' ? 'DOUBLE PRECISION' : 'REAL'),
|
|
59
|
+
'CREATE INDEX IF NOT EXISTS tallymark_events_ts ON tallymark_events (ts)',
|
|
60
|
+
];
|
|
61
|
+
function fromRow(r) {
|
|
62
|
+
let props = {};
|
|
63
|
+
if (r.props) {
|
|
64
|
+
try {
|
|
65
|
+
props = JSON.parse(r.props);
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
/* corrupt props never break a query */
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return {
|
|
72
|
+
id: r.id,
|
|
73
|
+
// Postgres returns BIGINT as a string; normalise.
|
|
74
|
+
ts: Number(r.ts),
|
|
75
|
+
type: r.type,
|
|
76
|
+
name: r.name,
|
|
77
|
+
visitor: r.visitor,
|
|
78
|
+
hostname: r.hostname,
|
|
79
|
+
path: r.path,
|
|
80
|
+
referrer: r.referrer,
|
|
81
|
+
referrerHost: r.referrer_host,
|
|
82
|
+
utm: {
|
|
83
|
+
source: r.utm_source,
|
|
84
|
+
medium: r.utm_medium,
|
|
85
|
+
campaign: r.utm_campaign,
|
|
86
|
+
term: r.utm_term,
|
|
87
|
+
content: r.utm_content,
|
|
88
|
+
},
|
|
89
|
+
browser: r.browser,
|
|
90
|
+
browserVersion: r.browser_version ?? null,
|
|
91
|
+
os: r.os,
|
|
92
|
+
osVersion: r.os_version ?? null,
|
|
93
|
+
device: r.device ?? 'unknown',
|
|
94
|
+
screen: r.screen ?? null,
|
|
95
|
+
timezone: r.timezone ?? null,
|
|
96
|
+
duration: r.duration === null || r.duration === undefined ? null : Number(r.duration),
|
|
97
|
+
scroll: r.scroll === null || r.scroll === undefined ? null : Number(r.scroll),
|
|
98
|
+
country: r.country,
|
|
99
|
+
region: r.region,
|
|
100
|
+
city: r.city,
|
|
101
|
+
language: r.language ?? null,
|
|
102
|
+
props,
|
|
103
|
+
value: r.value === null || r.value === undefined ? null : Number(r.value),
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
// Order matters: it must match the parameter list in insert().
|
|
107
|
+
const COLS = [
|
|
108
|
+
'id',
|
|
109
|
+
'ts',
|
|
110
|
+
'type',
|
|
111
|
+
'name',
|
|
112
|
+
'visitor',
|
|
113
|
+
'hostname',
|
|
114
|
+
'path',
|
|
115
|
+
'referrer',
|
|
116
|
+
'referrer_host',
|
|
117
|
+
'utm_source',
|
|
118
|
+
'utm_medium',
|
|
119
|
+
'utm_campaign',
|
|
120
|
+
'utm_term',
|
|
121
|
+
'utm_content',
|
|
122
|
+
'browser',
|
|
123
|
+
'browser_version',
|
|
124
|
+
'os',
|
|
125
|
+
'os_version',
|
|
126
|
+
'device',
|
|
127
|
+
'screen',
|
|
128
|
+
'country',
|
|
129
|
+
'region',
|
|
130
|
+
'city',
|
|
131
|
+
'timezone',
|
|
132
|
+
'language',
|
|
133
|
+
'props',
|
|
134
|
+
'value',
|
|
135
|
+
'duration',
|
|
136
|
+
'scroll',
|
|
137
|
+
];
|
|
138
|
+
const INSERT_COLS = `(${COLS.join(', ')}) VALUES (${COLS.map(() => '?').join(',')})`;
|
|
139
|
+
export function sqlStore(driver) {
|
|
140
|
+
const dialect = driver.dialect ?? 'sqlite';
|
|
141
|
+
const pg = dialect === 'postgres';
|
|
142
|
+
// `?` -> `$n` for Postgres. None of our SQL contains a literal question mark.
|
|
143
|
+
const sql = (text) => {
|
|
144
|
+
if (!pg)
|
|
145
|
+
return text;
|
|
146
|
+
let i = 0;
|
|
147
|
+
return text.replace(/\?/g, () => `$${++i}`);
|
|
148
|
+
};
|
|
149
|
+
const run = (text, params = []) => driver.run(sql(text), params);
|
|
150
|
+
const all = (text, params = []) => driver.all(sql(text), params);
|
|
151
|
+
// Memoised in-flight promise collapses a cold-start stampede into one DDL run.
|
|
152
|
+
// A failure clears it so one blip is not a permanent outage.
|
|
153
|
+
let ready = null;
|
|
154
|
+
const ensure = () => {
|
|
155
|
+
ready ??= (async () => {
|
|
156
|
+
try {
|
|
157
|
+
for (const stmt of schema(dialect))
|
|
158
|
+
await run(stmt);
|
|
159
|
+
}
|
|
160
|
+
catch (error) {
|
|
161
|
+
// Concurrent isolates can race `CREATE TABLE IF NOT EXISTS` on Postgres and
|
|
162
|
+
// lose with a duplicate-key error. If the table is usable, that is fine.
|
|
163
|
+
try {
|
|
164
|
+
await all('SELECT 1 FROM tallymark_events LIMIT 1');
|
|
165
|
+
}
|
|
166
|
+
catch {
|
|
167
|
+
throw error;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
})().catch((e) => {
|
|
171
|
+
ready = null;
|
|
172
|
+
throw e;
|
|
173
|
+
});
|
|
174
|
+
return ready;
|
|
175
|
+
};
|
|
176
|
+
return {
|
|
177
|
+
async insert(e) {
|
|
178
|
+
await ensure();
|
|
179
|
+
const head = pg ? 'INSERT INTO tallymark_events' : 'INSERT OR IGNORE INTO tallymark_events';
|
|
180
|
+
const tail = pg ? ' ON CONFLICT (id) DO NOTHING' : '';
|
|
181
|
+
await run(`${head} ${INSERT_COLS}${tail}`, [
|
|
182
|
+
e.id,
|
|
183
|
+
e.ts,
|
|
184
|
+
e.type,
|
|
185
|
+
e.name,
|
|
186
|
+
e.visitor,
|
|
187
|
+
e.hostname,
|
|
188
|
+
e.path,
|
|
189
|
+
e.referrer,
|
|
190
|
+
e.referrerHost,
|
|
191
|
+
e.utm.source,
|
|
192
|
+
e.utm.medium,
|
|
193
|
+
e.utm.campaign,
|
|
194
|
+
e.utm.term,
|
|
195
|
+
e.utm.content,
|
|
196
|
+
e.browser,
|
|
197
|
+
e.browserVersion,
|
|
198
|
+
e.os,
|
|
199
|
+
e.osVersion,
|
|
200
|
+
e.device,
|
|
201
|
+
e.screen,
|
|
202
|
+
e.country,
|
|
203
|
+
e.region,
|
|
204
|
+
e.city,
|
|
205
|
+
e.timezone,
|
|
206
|
+
e.language,
|
|
207
|
+
Object.keys(e.props).length ? JSON.stringify(e.props) : null,
|
|
208
|
+
e.value,
|
|
209
|
+
e.duration,
|
|
210
|
+
e.scroll,
|
|
211
|
+
]);
|
|
212
|
+
},
|
|
213
|
+
async list({ from, to, limit }) {
|
|
214
|
+
await ensure();
|
|
215
|
+
// Newest-first with LIMIT keeps the most recent rows, then we restore order.
|
|
216
|
+
const rows = await all('SELECT * FROM tallymark_events WHERE ts >= ? AND ts < ? ORDER BY ts DESC LIMIT ?', [from, to, limit ?? 500_000]);
|
|
217
|
+
return rows.reverse().map(fromRow);
|
|
218
|
+
},
|
|
219
|
+
async prune(before) {
|
|
220
|
+
await ensure();
|
|
221
|
+
if (!pg)
|
|
222
|
+
return run('DELETE FROM tallymark_events WHERE ts < ?', [before]);
|
|
223
|
+
// Row counts differ across Postgres clients; counting via RETURNING works on all.
|
|
224
|
+
const rows = await all('WITH d AS (DELETE FROM tallymark_events WHERE ts < ? RETURNING 1) SELECT COUNT(*) AS n FROM d', [before]);
|
|
225
|
+
return Number(rows[0]?.n ?? 0);
|
|
226
|
+
},
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
export function d1Store(db) {
|
|
230
|
+
const driver = {
|
|
231
|
+
async run(sql, params) {
|
|
232
|
+
const r = await db
|
|
233
|
+
.prepare(sql)
|
|
234
|
+
.bind(...params)
|
|
235
|
+
.run();
|
|
236
|
+
return r.meta?.changes ?? 0;
|
|
237
|
+
},
|
|
238
|
+
async all(sql, params) {
|
|
239
|
+
const r = await db
|
|
240
|
+
.prepare(sql)
|
|
241
|
+
.bind(...params)
|
|
242
|
+
.all();
|
|
243
|
+
return (r.results ?? []);
|
|
244
|
+
},
|
|
245
|
+
};
|
|
246
|
+
return sqlStore(driver);
|
|
247
|
+
}
|
|
248
|
+
export function bunSqliteStore(db) {
|
|
249
|
+
return sqlStore({
|
|
250
|
+
async run(sql, params) {
|
|
251
|
+
return db.prepare(sql).run(...params).changes;
|
|
252
|
+
},
|
|
253
|
+
async all(sql, params) {
|
|
254
|
+
return db.prepare(sql).all(...params);
|
|
255
|
+
},
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
export function libsqlStore(client) {
|
|
259
|
+
return sqlStore({
|
|
260
|
+
async run(sql, params) {
|
|
261
|
+
return (await client.execute({ sql, args: params })).rowsAffected;
|
|
262
|
+
},
|
|
263
|
+
async all(sql, params) {
|
|
264
|
+
return (await client.execute({ sql, args: params })).rows;
|
|
265
|
+
},
|
|
266
|
+
});
|
|
267
|
+
}
|
|
268
|
+
/** `pg` returns `{ rows, rowCount }`; Neon's HTTP driver returns the rows array. */
|
|
269
|
+
const pgRows = (r) => (Array.isArray(r) ? r : (r?.rows ?? []));
|
|
270
|
+
export function pgStore(client) {
|
|
271
|
+
return sqlStore({
|
|
272
|
+
dialect: 'postgres',
|
|
273
|
+
async run(sql, params) {
|
|
274
|
+
const r = await client.query(sql, params);
|
|
275
|
+
return Number(r?.rowCount ?? r?.affectedRows ?? 0);
|
|
276
|
+
},
|
|
277
|
+
async all(sql, params) {
|
|
278
|
+
return pgRows(await client.query(sql, params));
|
|
279
|
+
},
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
export function postgresJsStore(sql) {
|
|
283
|
+
return sqlStore({
|
|
284
|
+
dialect: 'postgres',
|
|
285
|
+
async run(text, params) {
|
|
286
|
+
const r = await sql.unsafe(text, params);
|
|
287
|
+
return Number(r?.count ?? 0);
|
|
288
|
+
},
|
|
289
|
+
async all(text, params) {
|
|
290
|
+
return Array.from(await sql.unsafe(text, params));
|
|
291
|
+
},
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
export function redisStore(redis, options = {}) {
|
|
295
|
+
const key = options.key ?? 'tallymark:events';
|
|
296
|
+
return {
|
|
297
|
+
async insert(e) {
|
|
298
|
+
await redis.zadd(key, e.ts, JSON.stringify(e));
|
|
299
|
+
},
|
|
300
|
+
async list({ from, to, limit }) {
|
|
301
|
+
const raw = await redis.zrangeByScoreRev(key, from, to, limit ?? 500_000);
|
|
302
|
+
const out = [];
|
|
303
|
+
for (const m of raw) {
|
|
304
|
+
// Some clients (Upstash) auto-parse JSON members; others return strings.
|
|
305
|
+
const e = typeof m === 'string' ? safeParse(m) : m;
|
|
306
|
+
if (e && typeof e === 'object' && typeof e.ts === 'number')
|
|
307
|
+
out.push(e);
|
|
308
|
+
}
|
|
309
|
+
return out.reverse();
|
|
310
|
+
},
|
|
311
|
+
prune: (before) => redis.zremBelow(key, before),
|
|
312
|
+
};
|
|
313
|
+
}
|
|
314
|
+
function safeParse(s) {
|
|
315
|
+
try {
|
|
316
|
+
return JSON.parse(s);
|
|
317
|
+
}
|
|
318
|
+
catch {
|
|
319
|
+
return null;
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
export function upstashStore(client, options) {
|
|
323
|
+
return redisStore({
|
|
324
|
+
zadd: (key, score, member) => client.zadd(key, { score, member }),
|
|
325
|
+
// With `rev`, Upstash takes (max, min). "(" makes the upper bound exclusive.
|
|
326
|
+
zrangeByScoreRev: async (key, min, max, count) => (await client.zrange(key, `(${max}`, min, {
|
|
327
|
+
byScore: true,
|
|
328
|
+
rev: true,
|
|
329
|
+
offset: 0,
|
|
330
|
+
count,
|
|
331
|
+
})) ?? [],
|
|
332
|
+
zremBelow: async (key, before) => Number(await client.zremrangebyscore(key, '-inf', `(${before}`)),
|
|
333
|
+
}, options);
|
|
334
|
+
}
|
|
335
|
+
/**
|
|
336
|
+
* Upstash over plain `fetch`: no SDK, works on any edge runtime.
|
|
337
|
+
* upstashRestStore({ url: env.UPSTASH_REDIS_REST_URL, token: env.UPSTASH_REDIS_REST_TOKEN })
|
|
338
|
+
*/
|
|
339
|
+
export function upstashRestStore(config) {
|
|
340
|
+
const f = config.fetch ?? fetch;
|
|
341
|
+
const cmd = async (...args) => {
|
|
342
|
+
const res = await f(config.url, {
|
|
343
|
+
method: 'POST',
|
|
344
|
+
headers: { authorization: `Bearer ${config.token}`, 'content-type': 'application/json' },
|
|
345
|
+
body: JSON.stringify(args),
|
|
346
|
+
});
|
|
347
|
+
const body = (await res.json().catch(() => ({})));
|
|
348
|
+
if (!res.ok || body.error)
|
|
349
|
+
throw new Error(`upstash: ${body.error ?? res.status}`);
|
|
350
|
+
return body.result;
|
|
351
|
+
};
|
|
352
|
+
return redisStore({
|
|
353
|
+
zadd: (key, score, member) => cmd('ZADD', key, score, member),
|
|
354
|
+
zrangeByScoreRev: async (key, min, max, count) => (await cmd('ZRANGE', key, `(${max}`, min, 'BYSCORE', 'REV', 'LIMIT', 0, count)) ?? [],
|
|
355
|
+
zremBelow: async (key, before) => Number(await cmd('ZREMRANGEBYSCORE', key, '-inf', `(${before}`)),
|
|
356
|
+
}, { key: config.key });
|
|
357
|
+
}
|
|
358
|
+
// ── Mirror (live backup) ──────────────────────────────────────────────────────
|
|
359
|
+
/**
|
|
360
|
+
* Live backup / migration helper: every event is written to the primary store,
|
|
361
|
+
* then copied to each mirror. Reads come from the primary.
|
|
362
|
+
*
|
|
363
|
+
* mirrorStore(d1Store(env.DB), upstashRestStore({ ... })) // D1 primary, Redis backup
|
|
364
|
+
*
|
|
365
|
+
* The primary decides success: if it fails, the insert fails. A mirror failure
|
|
366
|
+
* never fails the hit; it is reported through `onError` so you can alert on it.
|
|
367
|
+
* Restore from a mirror with `engine.export()` / `engine.import()`.
|
|
368
|
+
*/
|
|
369
|
+
export function mirrorStore(primary, mirrors, options = {}) {
|
|
370
|
+
const copies = Array.isArray(mirrors) ? mirrors : [mirrors];
|
|
371
|
+
return {
|
|
372
|
+
async insert(event) {
|
|
373
|
+
await primary.insert(event);
|
|
374
|
+
const results = await Promise.allSettled(copies.map((m) => m.insert(event)));
|
|
375
|
+
results.forEach((r, i) => {
|
|
376
|
+
if (r.status === 'rejected') {
|
|
377
|
+
try {
|
|
378
|
+
options.onError?.(r.reason, i);
|
|
379
|
+
}
|
|
380
|
+
catch {
|
|
381
|
+
/* a broken logger must not break the hit */
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
});
|
|
385
|
+
},
|
|
386
|
+
list: (q) => primary.list(q),
|
|
387
|
+
async prune(before) {
|
|
388
|
+
const n = (await primary.prune?.(before)) ?? 0;
|
|
389
|
+
await Promise.allSettled(copies.map((m) => m.prune?.(before)));
|
|
390
|
+
return n;
|
|
391
|
+
},
|
|
392
|
+
};
|
|
393
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { Comparison, ConnInfo, EventStore, Filters, FunnelRow, FunnelStep, Interval, Journey, Props, RangeInput, Realtime, SessionTrace, Summary, TallymarkEvent, TallymarkOptions, TimePoint, TopDimension, TopRow, TrackInput, TrackResult } from './types.js';
|
|
2
|
+
export interface Tallymark {
|
|
3
|
+
/** Record one hit. Returns a typed result; never throws. */
|
|
4
|
+
track(input: TrackInput, info?: ConnInfo): Promise<TrackResult>;
|
|
5
|
+
/**
|
|
6
|
+
* Record a hit from a `Request` you are already handling (a route, a server action, a webhook).
|
|
7
|
+
* The visitor's IP, browser, language, location and referrer are read from the request for you.
|
|
8
|
+
* Omit `name` for a pageview; pass `name` (and `props`, `value`) for a custom event.
|
|
9
|
+
*/
|
|
10
|
+
trackRequest(request: Request, event?: {
|
|
11
|
+
name?: string;
|
|
12
|
+
url?: string;
|
|
13
|
+
props?: Props;
|
|
14
|
+
value?: number;
|
|
15
|
+
}, info?: ConnInfo): Promise<TrackResult>;
|
|
16
|
+
summary(range?: RangeInput, filters?: Filters): Promise<Summary>;
|
|
17
|
+
/** Current period vs. the equally long period right before it. */
|
|
18
|
+
compare(range?: RangeInput, filters?: Filters): Promise<Comparison>;
|
|
19
|
+
timeseries(range?: RangeInput, filters?: Filters, interval?: Interval): Promise<TimePoint[]>;
|
|
20
|
+
top(by: TopDimension, range?: RangeInput, filters?: Filters, limit?: number): Promise<TopRow[]>;
|
|
21
|
+
/** Ordered conversion funnel over pages and/or custom events. */
|
|
22
|
+
funnel(steps: FunnelStep[], range?: RangeInput, filters?: Filters): Promise<FunnelRow[]>;
|
|
23
|
+
/** Recent sessions, each with the ordered pages and events the visitor went through. */
|
|
24
|
+
sessions(range?: RangeInput, filters?: Filters, limit?: number): Promise<SessionTrace[]>;
|
|
25
|
+
/** The most common routes through the site (first `depth` pages of each session). */
|
|
26
|
+
journeys(range?: RangeInput, filters?: Filters, options?: {
|
|
27
|
+
depth?: number;
|
|
28
|
+
limit?: number;
|
|
29
|
+
}): Promise<Journey[]>;
|
|
30
|
+
realtime(windowMinutes?: number): Promise<Realtime>;
|
|
31
|
+
/** Raw events, newest last. */
|
|
32
|
+
events(range?: RangeInput, filters?: Filters, limit?: number): Promise<TallymarkEvent[]>;
|
|
33
|
+
/** Backup: newline-delimited JSON, one event per line. */
|
|
34
|
+
export(range?: RangeInput, filters?: Filters): Promise<string>;
|
|
35
|
+
/** Restore from `export()` output. Invalid lines are skipped; duplicates are ignored by id. */
|
|
36
|
+
import(ndjson: string): Promise<{
|
|
37
|
+
imported: number;
|
|
38
|
+
skipped: number;
|
|
39
|
+
}>;
|
|
40
|
+
/** Delete events past `retentionDays`. Wire to a cron. Returns rows removed. */
|
|
41
|
+
prune(): Promise<number>;
|
|
42
|
+
/** Fetch-standard handler: `(Request) => Response`. Mount it anywhere. */
|
|
43
|
+
handle(request: Request, info?: ConnInfo): Promise<Response>;
|
|
44
|
+
readonly store: EventStore;
|
|
45
|
+
readonly options: Readonly<TallymarkOptions>;
|
|
46
|
+
}
|
|
47
|
+
/** Structural check for imported data: never trust a backup file blindly. */
|
|
48
|
+
export declare function isTallymarkEvent(v: unknown): v is TallymarkEvent;
|
|
49
|
+
export declare function createTallymark(options?: TallymarkOptions): Tallymark;
|