@hanzo/event 0.3.1 → 0.3.3
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/README.md +81 -17
- package/dist/core-B1XEdWLd.d.cts +296 -0
- package/dist/core-B1XEdWLd.d.ts +296 -0
- package/dist/index.cjs +590 -63
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +177 -6
- package/dist/index.d.ts +177 -6
- package/dist/index.mjs +581 -64
- package/dist/index.mjs.map +1 -1
- package/dist/react.cjs +413 -25
- package/dist/react.cjs.map +1 -1
- package/dist/react.d.cts +1 -1
- package/dist/react.d.ts +1 -1
- package/dist/react.mjs +413 -25
- package/dist/react.mjs.map +1 -1
- package/package.json +2 -2
- package/src/core.test.ts +258 -5
- package/src/core.ts +237 -45
- package/src/events.ts +30 -1
- package/src/funnels.test.ts +92 -0
- package/src/funnels.ts +154 -0
- package/src/goals.ts +25 -11
- package/src/index.ts +10 -0
- package/src/scrub.test.ts +96 -0
- package/src/scrub.ts +117 -0
- package/src/sentry.test.ts +312 -0
- package/src/sentry.ts +309 -0
- package/src/types.ts +117 -15
- package/src/version.ts +4 -0
- package/dist/core-CrbiAQhN.d.cts +0 -186
- package/dist/core-CrbiAQhN.d.ts +0 -186
package/src/types.ts
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
// Public types for the Hanzo Event client.
|
|
2
2
|
|
|
3
|
-
/** The event kinds — the closed set the server understands.
|
|
4
|
-
*
|
|
5
|
-
*
|
|
3
|
+
/** The event kinds — the closed set the server understands. `error` marks the
|
|
4
|
+
* breadcrumb an exception leaves on the event stream (Cloud stamps
|
|
5
|
+
* event_type='error' for the warehouse, GET /v1/errors). It does NOT reach the
|
|
6
|
+
* Sentry dashboard — the envelope on the error plane does that. */
|
|
6
7
|
export type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error'
|
|
7
8
|
|
|
8
|
-
/** A captured exception
|
|
9
|
-
*
|
|
10
|
-
* error
|
|
9
|
+
/** A captured exception as it rides the EVENT STREAM — Cloud folds it into
|
|
10
|
+
* properties.$exception for the warehouse. The richer copy (parsed stack frames,
|
|
11
|
+
* grouping, release) travels on the error plane as a Sentry envelope; see
|
|
12
|
+
* AnalyticsConfig.dsn. */
|
|
11
13
|
export interface Exception {
|
|
12
14
|
/** Constructor/class name, e.g. "TypeError". */
|
|
13
15
|
type?: string
|
|
@@ -70,7 +72,8 @@ export interface WireEvent {
|
|
|
70
72
|
revenue?: number
|
|
71
73
|
currency?: string
|
|
72
74
|
/** Set on `type:'error'` events — the captured exception. Cloud lifts it into
|
|
73
|
-
* properties.$exception (foldException) for the
|
|
75
|
+
* properties.$exception (foldException) for the event warehouse. Not a Sentry
|
|
76
|
+
* path: the envelope on the error plane is what feeds the dashboard. */
|
|
74
77
|
error?: Exception
|
|
75
78
|
properties?: Record<string, unknown>
|
|
76
79
|
library?: string
|
|
@@ -82,8 +85,21 @@ export interface WireEvent {
|
|
|
82
85
|
* Authorization on fetch; on a headerless beacon a publishable key rides the
|
|
83
86
|
* ?ingest_key query. */
|
|
84
87
|
export interface Transport {
|
|
85
|
-
/** Durable POST usable during page unload (fetch keepalive / sendBeacon).
|
|
86
|
-
|
|
88
|
+
/** Durable POST usable during page unload (fetch keepalive / sendBeacon).
|
|
89
|
+
* `contentType` defaults to application/json; the error plane overrides it with
|
|
90
|
+
* application/x-sentry-envelope. */
|
|
91
|
+
send(
|
|
92
|
+
url: string,
|
|
93
|
+
body: string,
|
|
94
|
+
opts: {
|
|
95
|
+
beacon: boolean
|
|
96
|
+
token?: string
|
|
97
|
+
ingestKey?: string
|
|
98
|
+
contentType?: string
|
|
99
|
+
/** Surface non-OK / failed ingest on the console. Never on by default. */
|
|
100
|
+
debug?: boolean
|
|
101
|
+
},
|
|
102
|
+
): void
|
|
87
103
|
}
|
|
88
104
|
|
|
89
105
|
export interface AnalyticsConfig {
|
|
@@ -99,10 +115,11 @@ export interface AnalyticsConfig {
|
|
|
99
115
|
/** Publishable ingest key (pk_…). When set, the client authenticates to the ONE
|
|
100
116
|
* front door `/v1/event` with this key instead of a bearer/cookie: it rides
|
|
101
117
|
* Authorization: Bearer pk_… on fetch and ?ingest_key=pk_… on a headerless
|
|
102
|
-
* page-unload beacon, so
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
118
|
+
* page-unload beacon, so anonymous traffic is accepted and unload beacons work
|
|
119
|
+
* without a bearer. The key is write-only (cannot read) and safe to ship in a
|
|
120
|
+
* bundle; mint one per org via POST /v1/ingest/keys. This authenticates the
|
|
121
|
+
* EVENT STREAM only — the error plane authenticates independently with `dsn`,
|
|
122
|
+
* and one does not stand in for the other. */
|
|
106
123
|
ingestKey?: string
|
|
107
124
|
/** Max events buffered before an automatic flush. */
|
|
108
125
|
batchSize?: number
|
|
@@ -111,11 +128,96 @@ export interface AnalyticsConfig {
|
|
|
111
128
|
/** Turn the client off entirely (e.g. opt-out / DNT). Defaults to enabled. */
|
|
112
129
|
enabled?: boolean
|
|
113
130
|
/** Auto-capture unhandled errors + promise rejections (window.onerror,
|
|
114
|
-
* unhandledrejection)
|
|
115
|
-
* this is what makes the client a drop-in @sentry replacement
|
|
131
|
+
* unhandledrejection). Browser-only, defaults to enabled. Together with `dsn`
|
|
132
|
+
* this is what makes the client a drop-in @sentry replacement — without a
|
|
133
|
+
* `dsn` the captures never reach the Sentry dashboard. */
|
|
116
134
|
captureErrors?: boolean
|
|
117
135
|
/** Override the transport (tests). */
|
|
118
136
|
transport?: Transport
|
|
119
137
|
/** Debug logging. */
|
|
120
138
|
debug?: boolean
|
|
139
|
+
|
|
140
|
+
// ── error plane (Sentry envelope -> sentry.hanzo.ai) ──────────────────────
|
|
141
|
+
|
|
142
|
+
/** Hanzo-minted Sentry DSN: "https://<version>:<hmac>@<host>/v1/sentry/<projectId>".
|
|
143
|
+
* Publishable — the key authorizes writes to ONE project and can read nothing,
|
|
144
|
+
* so it is safe in a browser bundle (same trust class as `ingestKey`). When
|
|
145
|
+
* absent the client reads NEXT_PUBLIC_HANZO_EVENT_DSN; when neither is set the
|
|
146
|
+
* error plane is inert (fail-safe: nothing sent, nothing thrown, analytics
|
|
147
|
+
* unaffected). Mint one per property: POST /v1/sentry/projects. */
|
|
148
|
+
dsn?: string
|
|
149
|
+
/** Release stamped on error events (a git SHA / app version). */
|
|
150
|
+
release?: string
|
|
151
|
+
/** Deployment environment for error events (production | staging | …). */
|
|
152
|
+
environment?: string
|
|
153
|
+
/** Retain end-user PII (emails/IPs) in error text. Default false = scrub
|
|
154
|
+
* client-side before anything leaves the device (the server scrubs again). */
|
|
155
|
+
capturePII?: boolean
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// ── Sentry envelope wire types (a from-scratch model of the PUBLIC, documented
|
|
159
|
+
// Sentry ingest protocol — develop.sentry.dev; no upstream code) ───────────
|
|
160
|
+
|
|
161
|
+
export type SentryLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug'
|
|
162
|
+
|
|
163
|
+
export interface SentryFrame {
|
|
164
|
+
filename?: string
|
|
165
|
+
function?: string
|
|
166
|
+
module?: string
|
|
167
|
+
abs_path?: string
|
|
168
|
+
lineno?: number
|
|
169
|
+
colno?: number
|
|
170
|
+
in_app?: boolean
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export interface SentryExceptionValue {
|
|
174
|
+
type?: string
|
|
175
|
+
value?: string
|
|
176
|
+
module?: string
|
|
177
|
+
stacktrace?: { frames: SentryFrame[] }
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
export interface SentryUser {
|
|
181
|
+
/** Stable subject id (OIDC sub / anon id). NEVER email/username/ip. */
|
|
182
|
+
id?: string
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export interface SentryEvent {
|
|
186
|
+
event_id: string
|
|
187
|
+
timestamp: number
|
|
188
|
+
platform: 'javascript'
|
|
189
|
+
level: SentryLevel
|
|
190
|
+
logger?: string
|
|
191
|
+
environment?: string
|
|
192
|
+
release?: string
|
|
193
|
+
transaction?: string
|
|
194
|
+
fingerprint?: string[]
|
|
195
|
+
message?: string
|
|
196
|
+
exception?: { values: SentryExceptionValue[] }
|
|
197
|
+
tags?: Record<string, string>
|
|
198
|
+
user?: SentryUser
|
|
199
|
+
contexts?: Record<string, Record<string, unknown>>
|
|
200
|
+
sdk?: { name: string; version: string }
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** Parsed DSN — the public key + the derived ingest URL. */
|
|
204
|
+
export interface Dsn {
|
|
205
|
+
/** "<version>:<hmac>" public key presented via ?sentry_key= (beacon-safe). */
|
|
206
|
+
publicKey: string
|
|
207
|
+
/** Ingest origin, e.g. "https://sentry.hanzo.ai". */
|
|
208
|
+
origin: string
|
|
209
|
+
/** Project id segment. */
|
|
210
|
+
projectId: string
|
|
211
|
+
/** Fully-derived envelope ingest URL incl. ?sentry_key=. */
|
|
212
|
+
ingestUrl: string
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** Options for Analytics.captureError. */
|
|
216
|
+
export interface CaptureErrorOptions {
|
|
217
|
+
/** false => uncaught (window.onerror / unhandledrejection / render crash). */
|
|
218
|
+
handled?: boolean
|
|
219
|
+
/** Severity + free-form context; merged into the event's tags. */
|
|
220
|
+
properties?: Record<string, unknown>
|
|
221
|
+
/** Override the event level (default: error, or fatal when handled === false). */
|
|
222
|
+
level?: SentryLevel
|
|
121
223
|
}
|
package/src/version.ts
ADDED
package/dist/core-CrbiAQhN.d.cts
DELETED
|
@@ -1,186 +0,0 @@
|
|
|
1
|
-
/** The event kinds — the closed set the server understands. An error is just
|
|
2
|
-
* another event on the one stream (Cloud stamps type:'error' → event_type='error',
|
|
3
|
-
* the key the error-tracking lens filters on). */
|
|
4
|
-
type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error';
|
|
5
|
-
/** A captured exception. Carried on a `type:'error'` event's top-level `error`
|
|
6
|
-
* field; Cloud folds it into properties.$exception and lenses the event into the
|
|
7
|
-
* error-tracking view (sentry.hanzo.ai). */
|
|
8
|
-
interface Exception {
|
|
9
|
-
/** Constructor/class name, e.g. "TypeError". */
|
|
10
|
-
type?: string;
|
|
11
|
-
/** The error message. */
|
|
12
|
-
message: string;
|
|
13
|
-
/** Stack trace when available. */
|
|
14
|
-
stack?: string;
|
|
15
|
-
/** false = an unhandled/global error (window.onerror, unhandledrejection);
|
|
16
|
-
* true = a caught error the app chose to report. Defaults true. */
|
|
17
|
-
handled?: boolean;
|
|
18
|
-
}
|
|
19
|
-
/** First-touch marketing attribution, parsed once and persisted. */
|
|
20
|
-
interface Attribution {
|
|
21
|
-
utm: {
|
|
22
|
-
source?: string;
|
|
23
|
-
medium?: string;
|
|
24
|
-
campaign?: string;
|
|
25
|
-
term?: string;
|
|
26
|
-
content?: string;
|
|
27
|
-
};
|
|
28
|
-
referrer?: string;
|
|
29
|
-
refCode?: string;
|
|
30
|
-
/** Derived acquisition channel: direct | organic | paid | social | referral. */
|
|
31
|
-
channel?: string;
|
|
32
|
-
}
|
|
33
|
-
/** Cohort dimensions carried on every event once known (see goals.ts COHORTS). */
|
|
34
|
-
interface Cohort {
|
|
35
|
-
/** ISO week the person first signed up, e.g. "2026-W28". */
|
|
36
|
-
signupWeek?: string;
|
|
37
|
-
channel?: string;
|
|
38
|
-
refCode?: string;
|
|
39
|
-
}
|
|
40
|
-
/** One event as sent on the wire — the canonical Hanzo Cloud event. Maps 1:1 to
|
|
41
|
-
* the cloud `CaptureEvent` (camelCase JSON keys); a batch of these is POSTed to
|
|
42
|
-
* the ONE front door `/v1/event` as `{ batch: [WireEvent, …] }`. tenant/org is
|
|
43
|
-
* NEVER a field here — the server stamps it from the validated session/key. */
|
|
44
|
-
interface WireEvent {
|
|
45
|
-
messageId: string;
|
|
46
|
-
type: EventKind;
|
|
47
|
-
event?: string;
|
|
48
|
-
timestamp: string;
|
|
49
|
-
distinctId?: string;
|
|
50
|
-
anonymousId?: string;
|
|
51
|
-
personId?: string;
|
|
52
|
-
sessionId?: string;
|
|
53
|
-
product?: string;
|
|
54
|
-
url?: string;
|
|
55
|
-
path?: string;
|
|
56
|
-
referrer?: string;
|
|
57
|
-
utm?: Attribution['utm'];
|
|
58
|
-
refCode?: string;
|
|
59
|
-
channel?: string;
|
|
60
|
-
groupId?: string;
|
|
61
|
-
signupWeek?: string;
|
|
62
|
-
productId?: string;
|
|
63
|
-
quantity?: number;
|
|
64
|
-
revenue?: number;
|
|
65
|
-
currency?: string;
|
|
66
|
-
/** Set on `type:'error'` events — the captured exception. Cloud lifts it into
|
|
67
|
-
* properties.$exception (foldException) for the error-tracking lens. */
|
|
68
|
-
error?: Exception;
|
|
69
|
-
properties?: Record<string, unknown>;
|
|
70
|
-
library?: string;
|
|
71
|
-
libraryVersion?: string;
|
|
72
|
-
}
|
|
73
|
-
/** Injectable transports — overridden in tests; the default in core.ts uses fetch
|
|
74
|
-
* (keepalive) and sendBeacon. A bearer JWT or a publishable pk_ key rides
|
|
75
|
-
* Authorization on fetch; on a headerless beacon a publishable key rides the
|
|
76
|
-
* ?ingest_key query. */
|
|
77
|
-
interface Transport {
|
|
78
|
-
/** Durable POST usable during page unload (fetch keepalive / sendBeacon). */
|
|
79
|
-
send(url: string, body: string, opts: {
|
|
80
|
-
beacon: boolean;
|
|
81
|
-
token?: string;
|
|
82
|
-
ingestKey?: string;
|
|
83
|
-
}): void;
|
|
84
|
-
}
|
|
85
|
-
interface AnalyticsConfig {
|
|
86
|
-
/** Cloud base URL. Defaults to "https://api.hanzo.ai" (the one edge). Set to
|
|
87
|
-
* same-origin ("") for cookie-auth apps served behind the same edge
|
|
88
|
-
* (console/admin/chat), so the browser rides the session cookie. */
|
|
89
|
-
host?: string;
|
|
90
|
-
/** Emitting surface: console | chat | app | site | admin. */
|
|
91
|
-
product: string;
|
|
92
|
-
/** Bearer token provider for token-auth apps. Omit for cookie/session apps
|
|
93
|
-
* (the client then relies on same-origin credentials). */
|
|
94
|
-
getToken?: () => string | undefined | null;
|
|
95
|
-
/** Publishable ingest key (pk_…). When set, the client authenticates to the ONE
|
|
96
|
-
* front door `/v1/event` with this key instead of a bearer/cookie: it rides
|
|
97
|
-
* Authorization: Bearer pk_… on fetch and ?ingest_key=pk_… on a headerless
|
|
98
|
-
* page-unload beacon, so ALL THREE lenses (web + product + error) light up with
|
|
99
|
-
* no bearer and unload beacons work anonymously. The key is write-only (cannot
|
|
100
|
-
* read) and safe to ship in a bundle; mint one per org via POST /v1/ingest/keys.
|
|
101
|
-
* Recommended for marketing/public pages and the full sentry-subsuming setup. */
|
|
102
|
-
ingestKey?: string;
|
|
103
|
-
/** Max events buffered before an automatic flush. */
|
|
104
|
-
batchSize?: number;
|
|
105
|
-
/** Auto-flush cadence in ms. */
|
|
106
|
-
flushIntervalMs?: number;
|
|
107
|
-
/** Turn the client off entirely (e.g. opt-out / DNT). Defaults to enabled. */
|
|
108
|
-
enabled?: boolean;
|
|
109
|
-
/** Auto-capture unhandled errors + promise rejections (window.onerror,
|
|
110
|
-
* unhandledrejection) as error events. Browser-only. Defaults to enabled —
|
|
111
|
-
* this is what makes the client a drop-in @sentry replacement. */
|
|
112
|
-
captureErrors?: boolean;
|
|
113
|
-
/** Override the transport (tests). */
|
|
114
|
-
transport?: Transport;
|
|
115
|
-
/** Debug logging. */
|
|
116
|
-
debug?: boolean;
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
declare const VERSION = "0.3.0";
|
|
120
|
-
declare class Analytics {
|
|
121
|
-
private cfg;
|
|
122
|
-
private transport;
|
|
123
|
-
private queue;
|
|
124
|
-
private timer;
|
|
125
|
-
private personId?;
|
|
126
|
-
private attribution;
|
|
127
|
-
private cohort;
|
|
128
|
-
private started;
|
|
129
|
-
constructor(config: AnalyticsConfig);
|
|
130
|
-
/** init is idempotent and browser-only for its side effects: capture first-touch
|
|
131
|
-
* attribution, hydrate cohort, register the unload flush, and (unless opted out)
|
|
132
|
-
* auto-capture unhandled errors. Safe to call from a React effect on every
|
|
133
|
-
* render. */
|
|
134
|
-
init(): void;
|
|
135
|
-
/** identify binds the current visitor to a stable person id (post-login). */
|
|
136
|
-
identify(personId: string, traits?: Record<string, unknown>): void;
|
|
137
|
-
/** group associates the visitor with an org/team (analytics grouping, not the
|
|
138
|
-
* server tenant — the server still derives tenant from the session). */
|
|
139
|
-
group(groupId: string, traits?: Record<string, unknown>): void;
|
|
140
|
-
/** pageview records a $pageview for the current (or given) location. */
|
|
141
|
-
pageview(path?: string, properties?: Record<string, unknown>): void;
|
|
142
|
-
/** capture records a named product event with optional properties. Commerce
|
|
143
|
-
* fields (productId/quantity/revenue/currency) may be passed for order events. */
|
|
144
|
-
capture(event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, 'productId' | 'quantity' | 'revenue' | 'currency'>): void;
|
|
145
|
-
/** track is an alias of capture (Segment familiarity). */
|
|
146
|
-
track: (event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, "productId" | "quantity" | "revenue" | "currency">) => void;
|
|
147
|
-
/** captureError records an exception as a first-class error event — the ONE
|
|
148
|
-
* error path (subsumes @sentry). A caught error, an unhandled rejection, a
|
|
149
|
-
* React render error, or a manual report all become a type:'error' event on the
|
|
150
|
-
* same stream; Cloud folds the exception into properties.$exception and stamps
|
|
151
|
-
* event_type='error', so it surfaces in the error-tracking lens. Never throws
|
|
152
|
-
* back into the app; errors are higher-signal than pageviews, so it flushes
|
|
153
|
-
* promptly (a crash may unload the page moments later). */
|
|
154
|
-
captureError(err: unknown, context?: {
|
|
155
|
-
handled?: boolean;
|
|
156
|
-
properties?: Record<string, unknown>;
|
|
157
|
-
}): void;
|
|
158
|
-
/** captureException — @sentry-familiar alias of captureError. */
|
|
159
|
-
captureException: (err: unknown, context?: {
|
|
160
|
-
handled?: boolean;
|
|
161
|
-
properties?: Record<string, unknown>;
|
|
162
|
-
}) => void;
|
|
163
|
-
/** setCohort persists cohort dimensions (e.g. signupWeek at signup) so they ride
|
|
164
|
-
* every subsequent event. */
|
|
165
|
-
setCohort(patch: Cohort): void;
|
|
166
|
-
/** flush drains the buffer to the server as ONE batch through the ONE ingest
|
|
167
|
-
* front door POST /v1/event, body { batch: [Event…] }. beacon=true selects the
|
|
168
|
-
* unload-safe transport. Auth is orthogonal to the wire:
|
|
169
|
-
*
|
|
170
|
-
* • publishable key set → rides Authorization: Bearer pk_… (fetch) or
|
|
171
|
-
* ?ingest_key=pk_… (beacon), so unload beacons work anonymously.
|
|
172
|
-
* • else a bearer JWT rides Authorization (fetch only — sendBeacon cannot
|
|
173
|
-
* carry a header, so token apps fall back to keepalive fetch on unload).
|
|
174
|
-
* • else a cookie app rides same-origin credentials (beacon carries the
|
|
175
|
-
* cookie fine).
|
|
176
|
-
*/
|
|
177
|
-
flush(beacon?: boolean): void;
|
|
178
|
-
private enqueue;
|
|
179
|
-
private build;
|
|
180
|
-
private schedule;
|
|
181
|
-
private clearTimer;
|
|
182
|
-
}
|
|
183
|
-
/** createAnalytics builds a client instance. Most apps use one shared instance. */
|
|
184
|
-
declare function createAnalytics(config: AnalyticsConfig): Analytics;
|
|
185
|
-
|
|
186
|
-
export { type Attribution as A, type Cohort as C, type EventKind as E, type Transport as T, VERSION as V, type WireEvent as W, Analytics as a, type AnalyticsConfig as b, type Exception as c, createAnalytics as d };
|
package/dist/core-CrbiAQhN.d.ts
DELETED
|
@@ -1,186 +0,0 @@
|
|
|
1
|
-
/** The event kinds — the closed set the server understands. An error is just
|
|
2
|
-
* another event on the one stream (Cloud stamps type:'error' → event_type='error',
|
|
3
|
-
* the key the error-tracking lens filters on). */
|
|
4
|
-
type EventKind = 'pageview' | 'event' | 'identify' | 'group' | 'error';
|
|
5
|
-
/** A captured exception. Carried on a `type:'error'` event's top-level `error`
|
|
6
|
-
* field; Cloud folds it into properties.$exception and lenses the event into the
|
|
7
|
-
* error-tracking view (sentry.hanzo.ai). */
|
|
8
|
-
interface Exception {
|
|
9
|
-
/** Constructor/class name, e.g. "TypeError". */
|
|
10
|
-
type?: string;
|
|
11
|
-
/** The error message. */
|
|
12
|
-
message: string;
|
|
13
|
-
/** Stack trace when available. */
|
|
14
|
-
stack?: string;
|
|
15
|
-
/** false = an unhandled/global error (window.onerror, unhandledrejection);
|
|
16
|
-
* true = a caught error the app chose to report. Defaults true. */
|
|
17
|
-
handled?: boolean;
|
|
18
|
-
}
|
|
19
|
-
/** First-touch marketing attribution, parsed once and persisted. */
|
|
20
|
-
interface Attribution {
|
|
21
|
-
utm: {
|
|
22
|
-
source?: string;
|
|
23
|
-
medium?: string;
|
|
24
|
-
campaign?: string;
|
|
25
|
-
term?: string;
|
|
26
|
-
content?: string;
|
|
27
|
-
};
|
|
28
|
-
referrer?: string;
|
|
29
|
-
refCode?: string;
|
|
30
|
-
/** Derived acquisition channel: direct | organic | paid | social | referral. */
|
|
31
|
-
channel?: string;
|
|
32
|
-
}
|
|
33
|
-
/** Cohort dimensions carried on every event once known (see goals.ts COHORTS). */
|
|
34
|
-
interface Cohort {
|
|
35
|
-
/** ISO week the person first signed up, e.g. "2026-W28". */
|
|
36
|
-
signupWeek?: string;
|
|
37
|
-
channel?: string;
|
|
38
|
-
refCode?: string;
|
|
39
|
-
}
|
|
40
|
-
/** One event as sent on the wire — the canonical Hanzo Cloud event. Maps 1:1 to
|
|
41
|
-
* the cloud `CaptureEvent` (camelCase JSON keys); a batch of these is POSTed to
|
|
42
|
-
* the ONE front door `/v1/event` as `{ batch: [WireEvent, …] }`. tenant/org is
|
|
43
|
-
* NEVER a field here — the server stamps it from the validated session/key. */
|
|
44
|
-
interface WireEvent {
|
|
45
|
-
messageId: string;
|
|
46
|
-
type: EventKind;
|
|
47
|
-
event?: string;
|
|
48
|
-
timestamp: string;
|
|
49
|
-
distinctId?: string;
|
|
50
|
-
anonymousId?: string;
|
|
51
|
-
personId?: string;
|
|
52
|
-
sessionId?: string;
|
|
53
|
-
product?: string;
|
|
54
|
-
url?: string;
|
|
55
|
-
path?: string;
|
|
56
|
-
referrer?: string;
|
|
57
|
-
utm?: Attribution['utm'];
|
|
58
|
-
refCode?: string;
|
|
59
|
-
channel?: string;
|
|
60
|
-
groupId?: string;
|
|
61
|
-
signupWeek?: string;
|
|
62
|
-
productId?: string;
|
|
63
|
-
quantity?: number;
|
|
64
|
-
revenue?: number;
|
|
65
|
-
currency?: string;
|
|
66
|
-
/** Set on `type:'error'` events — the captured exception. Cloud lifts it into
|
|
67
|
-
* properties.$exception (foldException) for the error-tracking lens. */
|
|
68
|
-
error?: Exception;
|
|
69
|
-
properties?: Record<string, unknown>;
|
|
70
|
-
library?: string;
|
|
71
|
-
libraryVersion?: string;
|
|
72
|
-
}
|
|
73
|
-
/** Injectable transports — overridden in tests; the default in core.ts uses fetch
|
|
74
|
-
* (keepalive) and sendBeacon. A bearer JWT or a publishable pk_ key rides
|
|
75
|
-
* Authorization on fetch; on a headerless beacon a publishable key rides the
|
|
76
|
-
* ?ingest_key query. */
|
|
77
|
-
interface Transport {
|
|
78
|
-
/** Durable POST usable during page unload (fetch keepalive / sendBeacon). */
|
|
79
|
-
send(url: string, body: string, opts: {
|
|
80
|
-
beacon: boolean;
|
|
81
|
-
token?: string;
|
|
82
|
-
ingestKey?: string;
|
|
83
|
-
}): void;
|
|
84
|
-
}
|
|
85
|
-
interface AnalyticsConfig {
|
|
86
|
-
/** Cloud base URL. Defaults to "https://api.hanzo.ai" (the one edge). Set to
|
|
87
|
-
* same-origin ("") for cookie-auth apps served behind the same edge
|
|
88
|
-
* (console/admin/chat), so the browser rides the session cookie. */
|
|
89
|
-
host?: string;
|
|
90
|
-
/** Emitting surface: console | chat | app | site | admin. */
|
|
91
|
-
product: string;
|
|
92
|
-
/** Bearer token provider for token-auth apps. Omit for cookie/session apps
|
|
93
|
-
* (the client then relies on same-origin credentials). */
|
|
94
|
-
getToken?: () => string | undefined | null;
|
|
95
|
-
/** Publishable ingest key (pk_…). When set, the client authenticates to the ONE
|
|
96
|
-
* front door `/v1/event` with this key instead of a bearer/cookie: it rides
|
|
97
|
-
* Authorization: Bearer pk_… on fetch and ?ingest_key=pk_… on a headerless
|
|
98
|
-
* page-unload beacon, so ALL THREE lenses (web + product + error) light up with
|
|
99
|
-
* no bearer and unload beacons work anonymously. The key is write-only (cannot
|
|
100
|
-
* read) and safe to ship in a bundle; mint one per org via POST /v1/ingest/keys.
|
|
101
|
-
* Recommended for marketing/public pages and the full sentry-subsuming setup. */
|
|
102
|
-
ingestKey?: string;
|
|
103
|
-
/** Max events buffered before an automatic flush. */
|
|
104
|
-
batchSize?: number;
|
|
105
|
-
/** Auto-flush cadence in ms. */
|
|
106
|
-
flushIntervalMs?: number;
|
|
107
|
-
/** Turn the client off entirely (e.g. opt-out / DNT). Defaults to enabled. */
|
|
108
|
-
enabled?: boolean;
|
|
109
|
-
/** Auto-capture unhandled errors + promise rejections (window.onerror,
|
|
110
|
-
* unhandledrejection) as error events. Browser-only. Defaults to enabled —
|
|
111
|
-
* this is what makes the client a drop-in @sentry replacement. */
|
|
112
|
-
captureErrors?: boolean;
|
|
113
|
-
/** Override the transport (tests). */
|
|
114
|
-
transport?: Transport;
|
|
115
|
-
/** Debug logging. */
|
|
116
|
-
debug?: boolean;
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
declare const VERSION = "0.3.0";
|
|
120
|
-
declare class Analytics {
|
|
121
|
-
private cfg;
|
|
122
|
-
private transport;
|
|
123
|
-
private queue;
|
|
124
|
-
private timer;
|
|
125
|
-
private personId?;
|
|
126
|
-
private attribution;
|
|
127
|
-
private cohort;
|
|
128
|
-
private started;
|
|
129
|
-
constructor(config: AnalyticsConfig);
|
|
130
|
-
/** init is idempotent and browser-only for its side effects: capture first-touch
|
|
131
|
-
* attribution, hydrate cohort, register the unload flush, and (unless opted out)
|
|
132
|
-
* auto-capture unhandled errors. Safe to call from a React effect on every
|
|
133
|
-
* render. */
|
|
134
|
-
init(): void;
|
|
135
|
-
/** identify binds the current visitor to a stable person id (post-login). */
|
|
136
|
-
identify(personId: string, traits?: Record<string, unknown>): void;
|
|
137
|
-
/** group associates the visitor with an org/team (analytics grouping, not the
|
|
138
|
-
* server tenant — the server still derives tenant from the session). */
|
|
139
|
-
group(groupId: string, traits?: Record<string, unknown>): void;
|
|
140
|
-
/** pageview records a $pageview for the current (or given) location. */
|
|
141
|
-
pageview(path?: string, properties?: Record<string, unknown>): void;
|
|
142
|
-
/** capture records a named product event with optional properties. Commerce
|
|
143
|
-
* fields (productId/quantity/revenue/currency) may be passed for order events. */
|
|
144
|
-
capture(event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, 'productId' | 'quantity' | 'revenue' | 'currency'>): void;
|
|
145
|
-
/** track is an alias of capture (Segment familiarity). */
|
|
146
|
-
track: (event: string, properties?: Record<string, unknown>, commerce?: Pick<WireEvent, "productId" | "quantity" | "revenue" | "currency">) => void;
|
|
147
|
-
/** captureError records an exception as a first-class error event — the ONE
|
|
148
|
-
* error path (subsumes @sentry). A caught error, an unhandled rejection, a
|
|
149
|
-
* React render error, or a manual report all become a type:'error' event on the
|
|
150
|
-
* same stream; Cloud folds the exception into properties.$exception and stamps
|
|
151
|
-
* event_type='error', so it surfaces in the error-tracking lens. Never throws
|
|
152
|
-
* back into the app; errors are higher-signal than pageviews, so it flushes
|
|
153
|
-
* promptly (a crash may unload the page moments later). */
|
|
154
|
-
captureError(err: unknown, context?: {
|
|
155
|
-
handled?: boolean;
|
|
156
|
-
properties?: Record<string, unknown>;
|
|
157
|
-
}): void;
|
|
158
|
-
/** captureException — @sentry-familiar alias of captureError. */
|
|
159
|
-
captureException: (err: unknown, context?: {
|
|
160
|
-
handled?: boolean;
|
|
161
|
-
properties?: Record<string, unknown>;
|
|
162
|
-
}) => void;
|
|
163
|
-
/** setCohort persists cohort dimensions (e.g. signupWeek at signup) so they ride
|
|
164
|
-
* every subsequent event. */
|
|
165
|
-
setCohort(patch: Cohort): void;
|
|
166
|
-
/** flush drains the buffer to the server as ONE batch through the ONE ingest
|
|
167
|
-
* front door POST /v1/event, body { batch: [Event…] }. beacon=true selects the
|
|
168
|
-
* unload-safe transport. Auth is orthogonal to the wire:
|
|
169
|
-
*
|
|
170
|
-
* • publishable key set → rides Authorization: Bearer pk_… (fetch) or
|
|
171
|
-
* ?ingest_key=pk_… (beacon), so unload beacons work anonymously.
|
|
172
|
-
* • else a bearer JWT rides Authorization (fetch only — sendBeacon cannot
|
|
173
|
-
* carry a header, so token apps fall back to keepalive fetch on unload).
|
|
174
|
-
* • else a cookie app rides same-origin credentials (beacon carries the
|
|
175
|
-
* cookie fine).
|
|
176
|
-
*/
|
|
177
|
-
flush(beacon?: boolean): void;
|
|
178
|
-
private enqueue;
|
|
179
|
-
private build;
|
|
180
|
-
private schedule;
|
|
181
|
-
private clearTimer;
|
|
182
|
-
}
|
|
183
|
-
/** createAnalytics builds a client instance. Most apps use one shared instance. */
|
|
184
|
-
declare function createAnalytics(config: AnalyticsConfig): Analytics;
|
|
185
|
-
|
|
186
|
-
export { type Attribution as A, type Cohort as C, type EventKind as E, type Transport as T, VERSION as V, type WireEvent as W, Analytics as a, type AnalyticsConfig as b, type Exception as c, createAnalytics as d };
|