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/react.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
type Props = Record<string, string | number | boolean>;
|
|
2
|
+
export interface AnalyticsProps {
|
|
3
|
+
/** Base URL of your tallymark API, e.g. `https://stats.example.com`, or `/api/analytics`. */
|
|
4
|
+
api: string;
|
|
5
|
+
outbound?: boolean;
|
|
6
|
+
downloads?: boolean;
|
|
7
|
+
localhost?: boolean;
|
|
8
|
+
}
|
|
9
|
+
declare global {
|
|
10
|
+
interface Window {
|
|
11
|
+
tallymark?: {
|
|
12
|
+
track(name: string, props?: Props, value?: number): void;
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Loads the tracker script once. Renders nothing. Mount near the root:
|
|
18
|
+
*
|
|
19
|
+
* <Analytics api="https://stats.example.com" outbound />
|
|
20
|
+
*
|
|
21
|
+
* Route changes are picked up automatically (History API), including the
|
|
22
|
+
* Next.js App Router and React Router.
|
|
23
|
+
*/
|
|
24
|
+
export declare function Analytics({ api, outbound, downloads, localhost }: AnalyticsProps): null;
|
|
25
|
+
/** Send a custom event. A no-op on the server and until the script has loaded. */
|
|
26
|
+
export declare function track(name: string, props?: Props, value?: number): void;
|
|
27
|
+
export {};
|
package/dist/react.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { useEffect } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Loads the tracker script once. Renders nothing. Mount near the root:
|
|
4
|
+
*
|
|
5
|
+
* <Analytics api="https://stats.example.com" outbound />
|
|
6
|
+
*
|
|
7
|
+
* Route changes are picked up automatically (History API), including the
|
|
8
|
+
* Next.js App Router and React Router.
|
|
9
|
+
*/
|
|
10
|
+
export function Analytics({ api, outbound, downloads, localhost }) {
|
|
11
|
+
useEffect(() => {
|
|
12
|
+
// StrictMode mounts twice in development; load the script only once.
|
|
13
|
+
if (document.querySelector('script[data-tallymark]'))
|
|
14
|
+
return;
|
|
15
|
+
const s = document.createElement('script');
|
|
16
|
+
s.src = `${api.replace(/\/$/, '')}/script.js`;
|
|
17
|
+
s.async = true;
|
|
18
|
+
s.dataset.tallymark = '';
|
|
19
|
+
s.dataset.api = api;
|
|
20
|
+
if (outbound)
|
|
21
|
+
s.dataset.outbound = 'true';
|
|
22
|
+
if (downloads)
|
|
23
|
+
s.dataset.downloads = 'true';
|
|
24
|
+
if (localhost)
|
|
25
|
+
s.dataset.localhost = 'true';
|
|
26
|
+
document.head.append(s);
|
|
27
|
+
}, [api, outbound, downloads, localhost]);
|
|
28
|
+
return null;
|
|
29
|
+
}
|
|
30
|
+
/** Send a custom event. A no-op on the server and until the script has loaded. */
|
|
31
|
+
export function track(name, props, value) {
|
|
32
|
+
if (typeof window !== 'undefined')
|
|
33
|
+
window.tallymark?.track(name, props, value);
|
|
34
|
+
}
|
package/dist/script.d.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The browser tracker, served at `/script.js`. Plain JavaScript in a string so it
|
|
3
|
+
* needs no build step and cannot drift from what is served.
|
|
4
|
+
*
|
|
5
|
+
* It sets no cookies and writes nothing to storage. Config is read from the
|
|
6
|
+
* <script> tag: data-api, data-auto, data-outbound, data-downloads,
|
|
7
|
+
* data-engagement ("false" turns off time-on-page), data-localhost.
|
|
8
|
+
*
|
|
9
|
+
* Exposes `window.tallymark.track(name, props?, value?)` and `.pageview()`.
|
|
10
|
+
* Elements with `data-tally="Name"` send that event on click; extra props are
|
|
11
|
+
* `data-tally-*` attributes (`data-tally-plan="pro"` sends `{ plan: "pro" }`).
|
|
12
|
+
*
|
|
13
|
+
* Time on page: engaged time (tab visible) and the deepest scroll position are
|
|
14
|
+
* sent as a cumulative `engagement` beacon when the page is hidden, left, or
|
|
15
|
+
* replaced by a single-page-app navigation. The server keeps the largest value.
|
|
16
|
+
*/
|
|
17
|
+
export declare const TRACKER = "(function () {\n var s = document.currentScript\n if (!s) return\n var d = s.dataset\n // Default: wherever this script was served from, so a mounted prefix just works.\n var api = (d.api || s.src.replace(/\\/script\\.js.*$/, '')).replace(/\\/$/, '')\n var endpoint = api + '/collect'\n var last = ''\n var ref = document.referrer\n var cur = ''\n var engaged = 0\n var since = 0\n var sent = 0\n var maxScroll = 0\n\n function skip() {\n // Exact loopback names only: localhost, 127.0.0.1 and ::1. Not localhost.com.\n if (d.localhost !== 'true' && /^(localhost|127(?:\\.\\d{1,3}){3}|::1)$/.test(location.hostname)) return true\n if (navigator.webdriver) return true\n try { return localStorage.getItem('tallymark_ignore') === 'true' } catch (e) { return false }\n }\n\n function send(body) {\n if (skip()) return\n body.w = window.innerWidth\n var payload = JSON.stringify(body)\n // text/plain keeps this a \"simple\" CORS request, so there is no preflight.\n try {\n if (navigator.sendBeacon && navigator.sendBeacon(endpoint, new Blob([payload], { type: 'text/plain' }))) return\n } catch (e) {}\n fetch(endpoint, { method: 'POST', body: payload, headers: { 'content-type': 'text/plain' }, keepalive: true }).catch(function () {})\n }\n\n function visible() { return document.visibilityState !== 'hidden' }\n\n function scrolled() {\n var el = document.documentElement\n var room = el.scrollHeight - window.innerHeight\n var pct = room > 0 ? Math.round(((window.pageYOffset || el.scrollTop || 0) / room) * 100) : 100\n if (pct > maxScroll) maxScroll = Math.min(100, pct)\n }\n\n // Cumulative engaged time for the page being left. Sent again only if it grew.\n // Close the open interval first: a page restored from the back-forward cache\n // must not count the time it spent frozen.\n function report() {\n if (d.engagement === 'false' || !cur) return\n if (since) {\n engaged += Date.now() - since\n since = 0\n }\n if (engaged < 1 || engaged === sent) return\n sent = engaged\n send({ name: 'engagement', url: cur, d: engaged, s: maxScroll })\n }\n\n var t = {\n pageview: () => {\n var path = location.pathname + location.search\n if (path === last) return\n report()\n last = path\n cur = location.href\n engaged = 0\n sent = 0\n maxScroll = 0\n since = visible() ? Date.now() : 0\n scrolled()\n send({ url: cur, referrer: ref || undefined })\n // The next page was reached from this one. Same-site referrers are dropped server-side.\n ref = cur\n },\n track: (name, props, value) => {\n send({ name: name, url: location.href, props: props, value: value })\n }\n }\n window.tallymark = t\n\n document.addEventListener('visibilitychange', function () {\n if (visible()) since = Date.now()\n else report()\n })\n addEventListener('pagehide', report)\n addEventListener('pageshow', function (e) {\n // The first pageshow is the load itself. Only a page restored from the\n // back-forward cache needs the clock started again.\n if (e && e.persisted && visible()) since = Date.now()\n })\n addEventListener('scroll', scrolled, { passive: true })\n\n if (d.auto !== 'false') {\n // Single-page apps change the URL without a page load. replaceState covers\n // routers that update the query string in place.\n var wrap = function (fn) {\n return function () {\n var r = fn.apply(this, arguments)\n setTimeout(t.pageview, 0)\n return r\n }\n }\n if (history.pushState) history.pushState = wrap(history.pushState)\n if (history.replaceState) history.replaceState = wrap(history.replaceState)\n addEventListener('popstate', t.pageview)\n if (document.visibilityState === 'prerender') {\n document.addEventListener('visibilitychange', t.pageview, { once: true })\n } else {\n t.pageview()\n }\n }\n\n document.addEventListener('click', function (e) {\n var el = e.target && e.target.closest && e.target.closest('a,[data-tally]')\n if (!el) return\n var name = el.getAttribute('data-tally')\n if (name) {\n var props = {}\n for (var i = 0; i < el.attributes.length; i++) {\n var a = el.attributes[i]\n if (a.name.indexOf('data-tally-') === 0) props[a.name.slice(11)] = a.value\n }\n return t.track(name, props)\n }\n if (!el.href) return\n if (d.downloads === 'true' && /\\.(pdf|zip|gz|dmg|exe|msi|pkg|csv|xlsx?|docx?|pptx?|mp[34]|mov)$/i.test(el.pathname)) {\n t.track('download', { file: el.pathname })\n } else if (d.outbound === 'true' && el.hostname && el.hostname !== location.hostname) {\n t.track('outbound', { url: el.href.split(/[?#]/)[0] })\n }\n })\n})()\n";
|
package/dist/script.js
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The browser tracker, served at `/script.js`. Plain JavaScript in a string so it
|
|
3
|
+
* needs no build step and cannot drift from what is served.
|
|
4
|
+
*
|
|
5
|
+
* It sets no cookies and writes nothing to storage. Config is read from the
|
|
6
|
+
* <script> tag: data-api, data-auto, data-outbound, data-downloads,
|
|
7
|
+
* data-engagement ("false" turns off time-on-page), data-localhost.
|
|
8
|
+
*
|
|
9
|
+
* Exposes `window.tallymark.track(name, props?, value?)` and `.pageview()`.
|
|
10
|
+
* Elements with `data-tally="Name"` send that event on click; extra props are
|
|
11
|
+
* `data-tally-*` attributes (`data-tally-plan="pro"` sends `{ plan: "pro" }`).
|
|
12
|
+
*
|
|
13
|
+
* Time on page: engaged time (tab visible) and the deepest scroll position are
|
|
14
|
+
* sent as a cumulative `engagement` beacon when the page is hidden, left, or
|
|
15
|
+
* replaced by a single-page-app navigation. The server keeps the largest value.
|
|
16
|
+
*/
|
|
17
|
+
export const TRACKER = `(function () {
|
|
18
|
+
var s = document.currentScript
|
|
19
|
+
if (!s) return
|
|
20
|
+
var d = s.dataset
|
|
21
|
+
// Default: wherever this script was served from, so a mounted prefix just works.
|
|
22
|
+
var api = (d.api || s.src.replace(/\\/script\\.js.*$/, '')).replace(/\\/$/, '')
|
|
23
|
+
var endpoint = api + '/collect'
|
|
24
|
+
var last = ''
|
|
25
|
+
var ref = document.referrer
|
|
26
|
+
var cur = ''
|
|
27
|
+
var engaged = 0
|
|
28
|
+
var since = 0
|
|
29
|
+
var sent = 0
|
|
30
|
+
var maxScroll = 0
|
|
31
|
+
|
|
32
|
+
function skip() {
|
|
33
|
+
// Exact loopback names only: localhost, 127.0.0.1 and ::1. Not localhost.com.
|
|
34
|
+
if (d.localhost !== 'true' && /^(localhost|127(?:\\.\\d{1,3}){3}|::1)$/.test(location.hostname)) return true
|
|
35
|
+
if (navigator.webdriver) return true
|
|
36
|
+
try { return localStorage.getItem('tallymark_ignore') === 'true' } catch (e) { return false }
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function send(body) {
|
|
40
|
+
if (skip()) return
|
|
41
|
+
body.w = window.innerWidth
|
|
42
|
+
var payload = JSON.stringify(body)
|
|
43
|
+
// text/plain keeps this a "simple" CORS request, so there is no preflight.
|
|
44
|
+
try {
|
|
45
|
+
if (navigator.sendBeacon && navigator.sendBeacon(endpoint, new Blob([payload], { type: 'text/plain' }))) return
|
|
46
|
+
} catch (e) {}
|
|
47
|
+
fetch(endpoint, { method: 'POST', body: payload, headers: { 'content-type': 'text/plain' }, keepalive: true }).catch(function () {})
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function visible() { return document.visibilityState !== 'hidden' }
|
|
51
|
+
|
|
52
|
+
function scrolled() {
|
|
53
|
+
var el = document.documentElement
|
|
54
|
+
var room = el.scrollHeight - window.innerHeight
|
|
55
|
+
var pct = room > 0 ? Math.round(((window.pageYOffset || el.scrollTop || 0) / room) * 100) : 100
|
|
56
|
+
if (pct > maxScroll) maxScroll = Math.min(100, pct)
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// Cumulative engaged time for the page being left. Sent again only if it grew.
|
|
60
|
+
// Close the open interval first: a page restored from the back-forward cache
|
|
61
|
+
// must not count the time it spent frozen.
|
|
62
|
+
function report() {
|
|
63
|
+
if (d.engagement === 'false' || !cur) return
|
|
64
|
+
if (since) {
|
|
65
|
+
engaged += Date.now() - since
|
|
66
|
+
since = 0
|
|
67
|
+
}
|
|
68
|
+
if (engaged < 1 || engaged === sent) return
|
|
69
|
+
sent = engaged
|
|
70
|
+
send({ name: 'engagement', url: cur, d: engaged, s: maxScroll })
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
var t = {
|
|
74
|
+
pageview: () => {
|
|
75
|
+
var path = location.pathname + location.search
|
|
76
|
+
if (path === last) return
|
|
77
|
+
report()
|
|
78
|
+
last = path
|
|
79
|
+
cur = location.href
|
|
80
|
+
engaged = 0
|
|
81
|
+
sent = 0
|
|
82
|
+
maxScroll = 0
|
|
83
|
+
since = visible() ? Date.now() : 0
|
|
84
|
+
scrolled()
|
|
85
|
+
send({ url: cur, referrer: ref || undefined })
|
|
86
|
+
// The next page was reached from this one. Same-site referrers are dropped server-side.
|
|
87
|
+
ref = cur
|
|
88
|
+
},
|
|
89
|
+
track: (name, props, value) => {
|
|
90
|
+
send({ name: name, url: location.href, props: props, value: value })
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
window.tallymark = t
|
|
94
|
+
|
|
95
|
+
document.addEventListener('visibilitychange', function () {
|
|
96
|
+
if (visible()) since = Date.now()
|
|
97
|
+
else report()
|
|
98
|
+
})
|
|
99
|
+
addEventListener('pagehide', report)
|
|
100
|
+
addEventListener('pageshow', function (e) {
|
|
101
|
+
// The first pageshow is the load itself. Only a page restored from the
|
|
102
|
+
// back-forward cache needs the clock started again.
|
|
103
|
+
if (e && e.persisted && visible()) since = Date.now()
|
|
104
|
+
})
|
|
105
|
+
addEventListener('scroll', scrolled, { passive: true })
|
|
106
|
+
|
|
107
|
+
if (d.auto !== 'false') {
|
|
108
|
+
// Single-page apps change the URL without a page load. replaceState covers
|
|
109
|
+
// routers that update the query string in place.
|
|
110
|
+
var wrap = function (fn) {
|
|
111
|
+
return function () {
|
|
112
|
+
var r = fn.apply(this, arguments)
|
|
113
|
+
setTimeout(t.pageview, 0)
|
|
114
|
+
return r
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
if (history.pushState) history.pushState = wrap(history.pushState)
|
|
118
|
+
if (history.replaceState) history.replaceState = wrap(history.replaceState)
|
|
119
|
+
addEventListener('popstate', t.pageview)
|
|
120
|
+
if (document.visibilityState === 'prerender') {
|
|
121
|
+
document.addEventListener('visibilitychange', t.pageview, { once: true })
|
|
122
|
+
} else {
|
|
123
|
+
t.pageview()
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
document.addEventListener('click', function (e) {
|
|
128
|
+
var el = e.target && e.target.closest && e.target.closest('a,[data-tally]')
|
|
129
|
+
if (!el) return
|
|
130
|
+
var name = el.getAttribute('data-tally')
|
|
131
|
+
if (name) {
|
|
132
|
+
var props = {}
|
|
133
|
+
for (var i = 0; i < el.attributes.length; i++) {
|
|
134
|
+
var a = el.attributes[i]
|
|
135
|
+
if (a.name.indexOf('data-tally-') === 0) props[a.name.slice(11)] = a.value
|
|
136
|
+
}
|
|
137
|
+
return t.track(name, props)
|
|
138
|
+
}
|
|
139
|
+
if (!el.href) return
|
|
140
|
+
if (d.downloads === 'true' && /\\.(pdf|zip|gz|dmg|exe|msi|pkg|csv|xlsx?|docx?|pptx?|mp[34]|mov)$/i.test(el.pathname)) {
|
|
141
|
+
t.track('download', { file: el.pathname })
|
|
142
|
+
} else if (d.outbound === 'true' && el.hostname && el.hostname !== location.hostname) {
|
|
143
|
+
t.track('outbound', { url: el.href.split(/[?#]/)[0] })
|
|
144
|
+
}
|
|
145
|
+
})
|
|
146
|
+
})()
|
|
147
|
+
`;
|
package/dist/stores.d.ts
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
import type { EventStore } from './types.js';
|
|
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 declare function memoryStore(options?: {
|
|
8
|
+
maxEvents?: number;
|
|
9
|
+
}): EventStore;
|
|
10
|
+
export type Dialect = 'sqlite' | 'postgres';
|
|
11
|
+
/**
|
|
12
|
+
* One SQL store, many databases. Anything that speaks SQLite or PostgreSQL can
|
|
13
|
+
* plug in by providing two functions. Write SQL with `?` placeholders; the
|
|
14
|
+
* store rewrites them to `$1, $2, ...` for Postgres.
|
|
15
|
+
*/
|
|
16
|
+
export interface SqlDriver {
|
|
17
|
+
/** Defaults to `sqlite`. */
|
|
18
|
+
dialect?: Dialect;
|
|
19
|
+
/** Run a write. Return the number of rows changed (0 if unknown). */
|
|
20
|
+
run(sql: string, params: unknown[]): Promise<number>;
|
|
21
|
+
all<T = Record<string, unknown>>(sql: string, params: unknown[]): Promise<T[]>;
|
|
22
|
+
}
|
|
23
|
+
export declare function sqlStore(driver: SqlDriver): EventStore;
|
|
24
|
+
/** Cloudflare D1. `d1Store(env.DB)` */
|
|
25
|
+
export interface D1Like {
|
|
26
|
+
prepare(sql: string): {
|
|
27
|
+
bind(...values: unknown[]): {
|
|
28
|
+
run(): Promise<{
|
|
29
|
+
meta?: {
|
|
30
|
+
changes?: number;
|
|
31
|
+
};
|
|
32
|
+
}>;
|
|
33
|
+
all(): Promise<{
|
|
34
|
+
results?: unknown[];
|
|
35
|
+
}>;
|
|
36
|
+
};
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
export declare function d1Store(db: D1Like): EventStore;
|
|
40
|
+
/** `bun:sqlite`. `bunSqliteStore(new Database('stats.db'))` */
|
|
41
|
+
export interface BunSqliteLike {
|
|
42
|
+
prepare(sql: string): {
|
|
43
|
+
run(...params: any[]): {
|
|
44
|
+
changes: number;
|
|
45
|
+
};
|
|
46
|
+
all(...params: any[]): unknown[];
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
export declare function bunSqliteStore(db: BunSqliteLike): EventStore;
|
|
50
|
+
/** libSQL / Turso. `libsqlStore(createClient({ url, authToken }))` */
|
|
51
|
+
export interface LibsqlLike {
|
|
52
|
+
execute(stmt: {
|
|
53
|
+
sql: string;
|
|
54
|
+
args: any[];
|
|
55
|
+
}): Promise<{
|
|
56
|
+
rows: unknown[];
|
|
57
|
+
rowsAffected: number;
|
|
58
|
+
}>;
|
|
59
|
+
}
|
|
60
|
+
export declare function libsqlStore(client: LibsqlLike): EventStore;
|
|
61
|
+
/**
|
|
62
|
+
* PostgreSQL via anything exposing `query(text, params)`:
|
|
63
|
+
* `pg` (Pool / Client), Neon (`neon(url)`), `@vercel/postgres`, Supabase (via pg),
|
|
64
|
+
* PGlite, and friends.
|
|
65
|
+
*
|
|
66
|
+
* pgStore(new Pool({ connectionString }))
|
|
67
|
+
* pgStore(neon(process.env.DATABASE_URL!)) // serverless HTTP driver
|
|
68
|
+
*/
|
|
69
|
+
export interface PgLike {
|
|
70
|
+
query(text: string, params?: any[]): Promise<any>;
|
|
71
|
+
}
|
|
72
|
+
export declare function pgStore(client: PgLike): EventStore;
|
|
73
|
+
/** postgres.js (`postgres(url)`). */
|
|
74
|
+
export interface PostgresJsLike {
|
|
75
|
+
unsafe(text: string, params?: any[]): PromiseLike<any>;
|
|
76
|
+
}
|
|
77
|
+
export declare function postgresJsStore(sql: PostgresJsLike): EventStore;
|
|
78
|
+
/**
|
|
79
|
+
* Redis-style stores keep events in one sorted set, scored by timestamp. That is
|
|
80
|
+
* exactly the access pattern analytics needs: "everything between A and B".
|
|
81
|
+
*/
|
|
82
|
+
export interface RedisLike {
|
|
83
|
+
/** Add one member with a score. */
|
|
84
|
+
zadd(key: string, score: number, member: string): Promise<unknown>;
|
|
85
|
+
/** Members with `min <= score < max` (exclusive max), newest first, at most `count`. */
|
|
86
|
+
zrangeByScoreRev(key: string, min: number, max: number, count: number): Promise<unknown[]>;
|
|
87
|
+
/** Remove members with `score < before`. Returns the number removed. */
|
|
88
|
+
zremBelow(key: string, before: number): Promise<number>;
|
|
89
|
+
}
|
|
90
|
+
export declare function redisStore(redis: RedisLike, options?: {
|
|
91
|
+
key?: string;
|
|
92
|
+
}): EventStore;
|
|
93
|
+
/**
|
|
94
|
+
* The slice of `@upstash/redis` we use: `upstashStore(Redis.fromEnv())`.
|
|
95
|
+
*
|
|
96
|
+
* Arguments are loose on purpose. The SDK declares many overloads that a narrower
|
|
97
|
+
* structural type cannot match, which would force every user to write a cast.
|
|
98
|
+
*/
|
|
99
|
+
export interface UpstashLike {
|
|
100
|
+
zadd(key: string, ...args: any[]): Promise<unknown>;
|
|
101
|
+
zrange(key: string, ...args: any[]): Promise<unknown>;
|
|
102
|
+
zremrangebyscore(key: string, ...args: any[]): Promise<unknown>;
|
|
103
|
+
}
|
|
104
|
+
export declare function upstashStore(client: UpstashLike, options?: {
|
|
105
|
+
key?: string;
|
|
106
|
+
}): EventStore;
|
|
107
|
+
/**
|
|
108
|
+
* Upstash over plain `fetch`: no SDK, works on any edge runtime.
|
|
109
|
+
* upstashRestStore({ url: env.UPSTASH_REDIS_REST_URL, token: env.UPSTASH_REDIS_REST_TOKEN })
|
|
110
|
+
*/
|
|
111
|
+
export declare function upstashRestStore(config: {
|
|
112
|
+
url: string;
|
|
113
|
+
token: string;
|
|
114
|
+
key?: string;
|
|
115
|
+
fetch?: typeof fetch;
|
|
116
|
+
}): EventStore;
|
|
117
|
+
/**
|
|
118
|
+
* Live backup / migration helper: every event is written to the primary store,
|
|
119
|
+
* then copied to each mirror. Reads come from the primary.
|
|
120
|
+
*
|
|
121
|
+
* mirrorStore(d1Store(env.DB), upstashRestStore({ ... })) // D1 primary, Redis backup
|
|
122
|
+
*
|
|
123
|
+
* The primary decides success: if it fails, the insert fails. A mirror failure
|
|
124
|
+
* never fails the hit; it is reported through `onError` so you can alert on it.
|
|
125
|
+
* Restore from a mirror with `engine.export()` / `engine.import()`.
|
|
126
|
+
*/
|
|
127
|
+
export declare function mirrorStore(primary: EventStore, mirrors: EventStore | EventStore[], options?: {
|
|
128
|
+
onError?: (error: unknown, mirrorIndex: number) => void;
|
|
129
|
+
}): EventStore;
|