@daybook/analytics 0.0.0-stage → 0.2.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/CHANGELOG.md +33 -0
- package/LICENSE +21 -0
- package/README.md +439 -3
- package/dist/browser.d.ts +1 -0
- package/dist/browser.js +30 -0
- package/dist/client.d.ts +123 -0
- package/dist/client.js +448 -0
- package/dist/context.d.ts +40 -0
- package/dist/context.js +133 -0
- package/dist/daybook.js +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +28 -0
- package/dist/log.d.ts +11 -0
- package/dist/log.js +20 -0
- package/dist/react.d.ts +27 -0
- package/dist/react.js +36 -0
- package/dist/storage.d.ts +44 -0
- package/dist/storage.js +102 -0
- package/dist/transport.d.ts +118 -0
- package/dist/transport.js +255 -0
- package/dist/types.d.ts +87 -0
- package/dist/types.js +1 -0
- package/dist/uuid.d.ts +5 -0
- package/dist/uuid.js +19 -0
- package/dist/version.d.ts +11 -0
- package/dist/version.js +11 -0
- package/dist/vue.d.ts +37 -0
- package/dist/vue.js +47 -0
- package/package.json +80 -6
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { DaybookAnalytics } from './client.js';
|
|
2
|
+
import type { AnalyticsOptions } from './types.js';
|
|
3
|
+
export { DaybookAnalytics, DEFAULT_API_URL } from './client.js';
|
|
4
|
+
export { SDK_VERSION } from './version.js';
|
|
5
|
+
export type { AnalyticsEvent, AnalyticsOptions, EventContext, Persistence, Properties, PropertyValue, } from './types.js';
|
|
6
|
+
/**
|
|
7
|
+
* Starts analytics for this site, once:
|
|
8
|
+
*
|
|
9
|
+
* import { init } from '@daybook/analytics'
|
|
10
|
+
*
|
|
11
|
+
* const analytics = init({ key: 'dak_…' })
|
|
12
|
+
* analytics.track('signed_up', { plan: 'pro' })
|
|
13
|
+
*
|
|
14
|
+
* A second call returns the same instance, so a component that re-renders, a hot reload or a provider
|
|
15
|
+
* mounted twice cannot start a second one that sends every page view again.
|
|
16
|
+
*/
|
|
17
|
+
export declare function init(options: AnalyticsOptions): DaybookAnalytics;
|
|
18
|
+
/** The instance `init` started, or null before it. */
|
|
19
|
+
export declare function getAnalytics(): DaybookAnalytics | null;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { DaybookAnalytics } from './client.js';
|
|
2
|
+
export { DaybookAnalytics, DEFAULT_API_URL } from './client.js';
|
|
3
|
+
export { SDK_VERSION } from './version.js';
|
|
4
|
+
let shared = null;
|
|
5
|
+
/**
|
|
6
|
+
* Starts analytics for this site, once:
|
|
7
|
+
*
|
|
8
|
+
* import { init } from '@daybook/analytics'
|
|
9
|
+
*
|
|
10
|
+
* const analytics = init({ key: 'dak_…' })
|
|
11
|
+
* analytics.track('signed_up', { plan: 'pro' })
|
|
12
|
+
*
|
|
13
|
+
* A second call returns the same instance, so a component that re-renders, a hot reload or a provider
|
|
14
|
+
* mounted twice cannot start a second one that sends every page view again.
|
|
15
|
+
*/
|
|
16
|
+
export function init(options) {
|
|
17
|
+
if (shared) {
|
|
18
|
+
if (options?.key && options.key.trim() !== shared.options.key.trim())
|
|
19
|
+
console.warn('[daybook] init was called again with another key; the first instance is kept. Use new DaybookAnalytics() for a second project.');
|
|
20
|
+
return shared;
|
|
21
|
+
}
|
|
22
|
+
shared = new DaybookAnalytics(options);
|
|
23
|
+
return shared;
|
|
24
|
+
}
|
|
25
|
+
/** The instance `init` started, or null before it. */
|
|
26
|
+
export function getAnalytics() {
|
|
27
|
+
return shared;
|
|
28
|
+
}
|
package/dist/log.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The SDK's console. Warnings always show, because each one is a tracking mistake a developer can fix
|
|
3
|
+
* — a refused event, a wrong key — and is said once per page; the rest shows only with `debug`.
|
|
4
|
+
*/
|
|
5
|
+
export declare class Log {
|
|
6
|
+
enabled: boolean;
|
|
7
|
+
private readonly said;
|
|
8
|
+
constructor(enabled: boolean);
|
|
9
|
+
debug(message: string, ...details: unknown[]): void;
|
|
10
|
+
warn(message: string): void;
|
|
11
|
+
}
|
package/dist/log.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The SDK's console. Warnings always show, because each one is a tracking mistake a developer can fix
|
|
3
|
+
* — a refused event, a wrong key — and is said once per page; the rest shows only with `debug`.
|
|
4
|
+
*/
|
|
5
|
+
export class Log {
|
|
6
|
+
constructor(enabled) {
|
|
7
|
+
this.enabled = enabled;
|
|
8
|
+
this.said = new Set();
|
|
9
|
+
}
|
|
10
|
+
debug(message, ...details) {
|
|
11
|
+
if (this.enabled)
|
|
12
|
+
console.log(`[daybook] ${message}`, ...details);
|
|
13
|
+
}
|
|
14
|
+
warn(message) {
|
|
15
|
+
if (this.said.has(message))
|
|
16
|
+
return;
|
|
17
|
+
this.said.add(message);
|
|
18
|
+
console.warn(`[daybook] ${message}`);
|
|
19
|
+
}
|
|
20
|
+
}
|
package/dist/react.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { type ReactNode } from 'react';
|
|
2
|
+
import { DaybookAnalytics } from './index.js';
|
|
3
|
+
import type { AnalyticsOptions } from './types.js';
|
|
4
|
+
export { DaybookAnalytics } from './index.js';
|
|
5
|
+
export type { AnalyticsEvent, AnalyticsOptions, Properties } from './index.js';
|
|
6
|
+
export interface DaybookProviderProps {
|
|
7
|
+
/** Options for the site's instance, started once with `init`. */
|
|
8
|
+
options?: AnalyticsOptions;
|
|
9
|
+
/** Or an instance you started yourself. */
|
|
10
|
+
client?: DaybookAnalytics;
|
|
11
|
+
children?: ReactNode;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Analytics for a React app (PM-R-0062 criterion 6):
|
|
15
|
+
*
|
|
16
|
+
* <DaybookProvider options={{ key: 'dak_…' }}>
|
|
17
|
+
* <App />
|
|
18
|
+
* </DaybookProvider>
|
|
19
|
+
*
|
|
20
|
+
* Started once, while rendering, so the first page view is not a render late. `init` returns the same
|
|
21
|
+
* instance every time, which keeps StrictMode's double render and a remounted provider from starting
|
|
22
|
+
* a second one. Marked 'use client', so Next.js's App Router renders it as a client component; on the
|
|
23
|
+
* server the instance does nothing.
|
|
24
|
+
*/
|
|
25
|
+
export declare function DaybookProvider({ options, client, children }: DaybookProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<DaybookAnalytics | null>>;
|
|
26
|
+
/** The site's analytics, inside a `DaybookProvider`: `const analytics = useAnalytics(); analytics.track('…')`. */
|
|
27
|
+
export declare function useAnalytics(): DaybookAnalytics;
|
package/dist/react.js
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
import { createContext, createElement, useContext, useRef } from 'react';
|
|
3
|
+
import { DaybookAnalytics, init } from './index.js';
|
|
4
|
+
export { DaybookAnalytics } from './index.js';
|
|
5
|
+
const AnalyticsContext = createContext(null);
|
|
6
|
+
/**
|
|
7
|
+
* Analytics for a React app (PM-R-0062 criterion 6):
|
|
8
|
+
*
|
|
9
|
+
* <DaybookProvider options={{ key: 'dak_…' }}>
|
|
10
|
+
* <App />
|
|
11
|
+
* </DaybookProvider>
|
|
12
|
+
*
|
|
13
|
+
* Started once, while rendering, so the first page view is not a render late. `init` returns the same
|
|
14
|
+
* instance every time, which keeps StrictMode's double render and a remounted provider from starting
|
|
15
|
+
* a second one. Marked 'use client', so Next.js's App Router renders it as a client component; on the
|
|
16
|
+
* server the instance does nothing.
|
|
17
|
+
*/
|
|
18
|
+
export function DaybookProvider({ options, client, children }) {
|
|
19
|
+
const instance = useRef(null);
|
|
20
|
+
if (instance.current === null) {
|
|
21
|
+
if (client)
|
|
22
|
+
instance.current = client;
|
|
23
|
+
else if (options)
|
|
24
|
+
instance.current = init(options);
|
|
25
|
+
else
|
|
26
|
+
throw new Error('@daybook/analytics/react: DaybookProvider needs `options` (with your key) or a `client`.');
|
|
27
|
+
}
|
|
28
|
+
return createElement(AnalyticsContext.Provider, { value: instance.current }, children);
|
|
29
|
+
}
|
|
30
|
+
/** The site's analytics, inside a `DaybookProvider`: `const analytics = useAnalytics(); analytics.track('…')`. */
|
|
31
|
+
export function useAnalytics() {
|
|
32
|
+
const instance = useContext(AnalyticsContext);
|
|
33
|
+
if (!instance)
|
|
34
|
+
throw new Error('@daybook/analytics/react: useAnalytics is used outside a DaybookProvider.');
|
|
35
|
+
return instance;
|
|
36
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { Persistence } from './types.js';
|
|
2
|
+
/** A place to keep a string by name. Every method swallows the browser's refusals: storage is a nicety, never a reason to lose an event. */
|
|
3
|
+
export interface Store {
|
|
4
|
+
get(name: string): string | null;
|
|
5
|
+
set(name: string, value: string): void;
|
|
6
|
+
remove(name: string): void;
|
|
7
|
+
}
|
|
8
|
+
/** What the SDK remembers about this browser between page loads. */
|
|
9
|
+
export interface State {
|
|
10
|
+
/** The anonymous id: the event's `distinct_id`. */
|
|
11
|
+
anon: string;
|
|
12
|
+
/** The signed-in user, after `identify()`. */
|
|
13
|
+
user?: string;
|
|
14
|
+
/** Registered properties, sent with every event. */
|
|
15
|
+
props: Record<string, unknown>;
|
|
16
|
+
/** Where this browser first came from: `$initial_referrer`, `$initial_utm_source` and the rest. */
|
|
17
|
+
initial?: Record<string, string>;
|
|
18
|
+
/** Whether `initial` has gone to this anonymous id's person as set_once properties (PM-T-0540). */
|
|
19
|
+
initialSent?: boolean;
|
|
20
|
+
/** The current session: when it started and when it last saw an event (ms). */
|
|
21
|
+
session?: {
|
|
22
|
+
id: string;
|
|
23
|
+
start?: number;
|
|
24
|
+
last: number;
|
|
25
|
+
};
|
|
26
|
+
/** The visitor's choice, once they have made one. */
|
|
27
|
+
consent?: 'in' | 'out';
|
|
28
|
+
}
|
|
29
|
+
export declare function memoryStore(): Store;
|
|
30
|
+
/**
|
|
31
|
+
* localStorage or sessionStorage, if the browser lets this page use it. Safari's private mode, a
|
|
32
|
+
* sandboxed iframe and a storage-blocking setting all throw on access rather than saying no, so the
|
|
33
|
+
* only reliable test is to try.
|
|
34
|
+
*/
|
|
35
|
+
export declare function webStore(kind: 'localStorage' | 'sessionStorage'): Store | null;
|
|
36
|
+
/**
|
|
37
|
+
* A first-party cookie, so one visitor on `www.example.com` and `app.example.com` is one anonymous id
|
|
38
|
+
* when `domain` is `.example.com`. Never sent to Daybook: the SDK's requests carry no credentials.
|
|
39
|
+
*/
|
|
40
|
+
export declare function cookieStore(domain?: string): Store | null;
|
|
41
|
+
/** The store a persistence choice gets, falling back to memory where the browser refuses it. */
|
|
42
|
+
export declare function storeFor(persistence: Persistence, cookieDomain?: string): Store;
|
|
43
|
+
/** A stored state, or null when there is none or it is not one. */
|
|
44
|
+
export declare function readState(store: Store, name: string): Partial<State> | null;
|
package/dist/storage.js
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
export function memoryStore() {
|
|
2
|
+
const values = new Map();
|
|
3
|
+
return {
|
|
4
|
+
get: (name) => values.get(name) ?? null,
|
|
5
|
+
set: (name, value) => void values.set(name, value),
|
|
6
|
+
remove: (name) => void values.delete(name),
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* localStorage or sessionStorage, if the browser lets this page use it. Safari's private mode, a
|
|
11
|
+
* sandboxed iframe and a storage-blocking setting all throw on access rather than saying no, so the
|
|
12
|
+
* only reliable test is to try.
|
|
13
|
+
*/
|
|
14
|
+
export function webStore(kind) {
|
|
15
|
+
let storage;
|
|
16
|
+
try {
|
|
17
|
+
storage = globalThis[kind];
|
|
18
|
+
const probe = '__daybook_probe__';
|
|
19
|
+
storage.setItem(probe, '1');
|
|
20
|
+
storage.removeItem(probe);
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
return null;
|
|
24
|
+
}
|
|
25
|
+
return {
|
|
26
|
+
get: (name) => {
|
|
27
|
+
try {
|
|
28
|
+
return storage.getItem(name);
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
set: (name, value) => {
|
|
35
|
+
try {
|
|
36
|
+
storage.setItem(name, value);
|
|
37
|
+
}
|
|
38
|
+
catch { /* full or blocked */ }
|
|
39
|
+
},
|
|
40
|
+
remove: (name) => {
|
|
41
|
+
try {
|
|
42
|
+
storage.removeItem(name);
|
|
43
|
+
}
|
|
44
|
+
catch { /* blocked */ }
|
|
45
|
+
},
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* A first-party cookie, so one visitor on `www.example.com` and `app.example.com` is one anonymous id
|
|
50
|
+
* when `domain` is `.example.com`. Never sent to Daybook: the SDK's requests carry no credentials.
|
|
51
|
+
*/
|
|
52
|
+
export function cookieStore(domain) {
|
|
53
|
+
if (typeof document === 'undefined')
|
|
54
|
+
return null;
|
|
55
|
+
const secure = globalThis.location?.protocol === 'https:' ? '; Secure' : '';
|
|
56
|
+
const scope = `; path=/${domain ? `; domain=${domain}` : ''}; SameSite=Lax${secure}`;
|
|
57
|
+
return {
|
|
58
|
+
get: (name) => {
|
|
59
|
+
try {
|
|
60
|
+
const prefix = `${name}=`;
|
|
61
|
+
const found = document.cookie.split('; ').find((c) => c.startsWith(prefix));
|
|
62
|
+
return found ? decodeURIComponent(found.slice(prefix.length)) : null;
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
},
|
|
68
|
+
set: (name, value) => {
|
|
69
|
+
try {
|
|
70
|
+
document.cookie = `${name}=${encodeURIComponent(value)}; max-age=31536000${scope}`;
|
|
71
|
+
}
|
|
72
|
+
catch { /* blocked */ }
|
|
73
|
+
},
|
|
74
|
+
remove: (name) => {
|
|
75
|
+
try {
|
|
76
|
+
document.cookie = `${name}=; max-age=0${scope}`;
|
|
77
|
+
}
|
|
78
|
+
catch { /* blocked */ }
|
|
79
|
+
},
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
/** The store a persistence choice gets, falling back to memory where the browser refuses it. */
|
|
83
|
+
export function storeFor(persistence, cookieDomain) {
|
|
84
|
+
if (persistence === 'memory')
|
|
85
|
+
return memoryStore();
|
|
86
|
+
if (persistence === 'cookie' || cookieDomain)
|
|
87
|
+
return cookieStore(cookieDomain) ?? memoryStore();
|
|
88
|
+
return webStore('localStorage') ?? memoryStore();
|
|
89
|
+
}
|
|
90
|
+
/** A stored state, or null when there is none or it is not one. */
|
|
91
|
+
export function readState(store, name) {
|
|
92
|
+
const text = store.get(name);
|
|
93
|
+
if (!text)
|
|
94
|
+
return null;
|
|
95
|
+
try {
|
|
96
|
+
const value = JSON.parse(text);
|
|
97
|
+
return value && typeof value === 'object' ? value : null;
|
|
98
|
+
}
|
|
99
|
+
catch {
|
|
100
|
+
return null;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import type { AnalyticsEvent } from './types.js';
|
|
2
|
+
import type { Log } from './log.js';
|
|
3
|
+
import type { Store } from './storage.js';
|
|
4
|
+
export interface IdentifyBody {
|
|
5
|
+
distinct_id: string;
|
|
6
|
+
user_id: string;
|
|
7
|
+
properties?: Record<string, unknown>;
|
|
8
|
+
}
|
|
9
|
+
export interface PeopleBody {
|
|
10
|
+
distinct_id?: string;
|
|
11
|
+
user_id?: string;
|
|
12
|
+
set?: Record<string, unknown>;
|
|
13
|
+
/** Written only where the person has no value yet, under any of their ids. */
|
|
14
|
+
set_once?: Record<string, unknown>;
|
|
15
|
+
unset?: string[];
|
|
16
|
+
}
|
|
17
|
+
/** One thing waiting to be sent: an event (sent in batches), an identify, or a person's properties. */
|
|
18
|
+
export type Job = {
|
|
19
|
+
t: 'e';
|
|
20
|
+
e: AnalyticsEvent;
|
|
21
|
+
} | {
|
|
22
|
+
t: 'i';
|
|
23
|
+
b: IdentifyBody;
|
|
24
|
+
} | {
|
|
25
|
+
t: 'p';
|
|
26
|
+
b: PeopleBody;
|
|
27
|
+
};
|
|
28
|
+
type Outcome = {
|
|
29
|
+
kind: 'ok';
|
|
30
|
+
body: unknown;
|
|
31
|
+
} | {
|
|
32
|
+
kind: 'retry';
|
|
33
|
+
afterMs?: number;
|
|
34
|
+
} | {
|
|
35
|
+
kind: 'too_large';
|
|
36
|
+
} | {
|
|
37
|
+
kind: 'drop';
|
|
38
|
+
status: number;
|
|
39
|
+
detail: string;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* Talks to `/analytics/v1` the way a page can (PM-T-0528): the key and the SDK's name in the query
|
|
43
|
+
* string and the body as `text/plain`, so every request is CORS-simple — no preflight — and the one
|
|
44
|
+
* sent while the page is going away can be a beacon, which cannot set headers at all.
|
|
45
|
+
*/
|
|
46
|
+
export declare class Transport {
|
|
47
|
+
private readonly apiUrl;
|
|
48
|
+
private readonly key;
|
|
49
|
+
constructor(apiUrl: string, key: string);
|
|
50
|
+
url(path: string): string;
|
|
51
|
+
post(path: string, text: string): Promise<Outcome>;
|
|
52
|
+
/** True when the browser took it; it sends it after the page is gone, and no answer ever comes back. */
|
|
53
|
+
beacon(path: string, text: string): boolean;
|
|
54
|
+
}
|
|
55
|
+
export interface OutboxOptions {
|
|
56
|
+
batchSize: number;
|
|
57
|
+
flushIntervalMs: number;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Everything waiting to be sent, in order, and the sending of it (PM-R-0062 criterion 4).
|
|
61
|
+
*
|
|
62
|
+
* <p>
|
|
63
|
+
* Kept in sessionStorage, which outlives a reload and a crash of the page but is one tab's own. A
|
|
64
|
+
* queue in localStorage would be every tab's, and two tabs would each send the other's events; with
|
|
65
|
+
* this one a closed tab loses what it could not send while offline, which is the smaller harm.
|
|
66
|
+
* </p>
|
|
67
|
+
*
|
|
68
|
+
* <p>
|
|
69
|
+
* A batch that fails is sent again exactly as it was — the same events, not the same events plus
|
|
70
|
+
* whatever arrived since — so the API's deduplication token, made from the batch's event ids,
|
|
71
|
+
* recognises it and stores it once.
|
|
72
|
+
* </p>
|
|
73
|
+
*
|
|
74
|
+
* <p>
|
|
75
|
+
* Every batch says when it left, as <code>sent_at</code> by this device's clock (PM-R-0068). The API
|
|
76
|
+
* moves each event by the gap between that and when the batch arrived, so a clock that is wrong, or an
|
|
77
|
+
* event that waited offline for hours, still lands at the time it happened. It is stamped as the
|
|
78
|
+
* request is made — each retry and each beacon anew — never when the events were queued.
|
|
79
|
+
* </p>
|
|
80
|
+
*/
|
|
81
|
+
export declare class Outbox {
|
|
82
|
+
private readonly transport;
|
|
83
|
+
private readonly store;
|
|
84
|
+
private readonly name;
|
|
85
|
+
private readonly options;
|
|
86
|
+
private readonly log;
|
|
87
|
+
private jobs;
|
|
88
|
+
private timer;
|
|
89
|
+
private sending;
|
|
90
|
+
private failures;
|
|
91
|
+
private retrySize;
|
|
92
|
+
private inFlight;
|
|
93
|
+
private stopped;
|
|
94
|
+
constructor(transport: Transport, store: Store | null, name: string, options: OutboxOptions, log: Log);
|
|
95
|
+
get size(): number;
|
|
96
|
+
push(job: Job): void;
|
|
97
|
+
/** Sends everything now, and resolves when the queue is empty or the API cannot be reached. */
|
|
98
|
+
flush(): Promise<void>;
|
|
99
|
+
/**
|
|
100
|
+
* The page is going away: hand everything to the browser as beacons, which it sends after the page
|
|
101
|
+
* is gone. A batch already on its way was sent with keepalive and stays queued until it is answered.
|
|
102
|
+
*/
|
|
103
|
+
beaconAll(): void;
|
|
104
|
+
clear(): void;
|
|
105
|
+
stop(): void;
|
|
106
|
+
/** Online again: whatever is waiting goes now rather than at the end of its backoff. */
|
|
107
|
+
resume(): void;
|
|
108
|
+
private schedule;
|
|
109
|
+
private drain;
|
|
110
|
+
/** The next request from `from` on: one identify or person update, or as many events in a row as fit. */
|
|
111
|
+
private next;
|
|
112
|
+
/** The API stores the good events of a batch and says which it refused and why. */
|
|
113
|
+
private report;
|
|
114
|
+
private refused;
|
|
115
|
+
private load;
|
|
116
|
+
private save;
|
|
117
|
+
}
|
|
118
|
+
export {};
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
import { SDK_NAME } from './version.js';
|
|
2
|
+
/** The API takes 1 MB a batch; staying well under it leaves room for what JSON adds. */
|
|
3
|
+
const MAX_BATCH_BYTES = 512 * 1024;
|
|
4
|
+
/** What a browser lets a beacon or a keepalive request carry, all of them together. */
|
|
5
|
+
const MAX_BEACON_BYTES = 60 * 1024;
|
|
6
|
+
const MAX_QUEUE = 1000;
|
|
7
|
+
/**
|
|
8
|
+
* Talks to `/analytics/v1` the way a page can (PM-T-0528): the key and the SDK's name in the query
|
|
9
|
+
* string and the body as `text/plain`, so every request is CORS-simple — no preflight — and the one
|
|
10
|
+
* sent while the page is going away can be a beacon, which cannot set headers at all.
|
|
11
|
+
*/
|
|
12
|
+
export class Transport {
|
|
13
|
+
constructor(apiUrl, key) {
|
|
14
|
+
this.apiUrl = apiUrl;
|
|
15
|
+
this.key = key;
|
|
16
|
+
}
|
|
17
|
+
url(path) {
|
|
18
|
+
return `${this.apiUrl.replace(/\/+$/, '')}/analytics/v1/${path}?key=${encodeURIComponent(this.key)}&sdk=${SDK_NAME}`;
|
|
19
|
+
}
|
|
20
|
+
async post(path, text) {
|
|
21
|
+
let response;
|
|
22
|
+
try {
|
|
23
|
+
response = await fetch(this.url(path), {
|
|
24
|
+
method: 'POST',
|
|
25
|
+
body: text,
|
|
26
|
+
headers: { 'Content-Type': 'text/plain' },
|
|
27
|
+
credentials: 'omit',
|
|
28
|
+
keepalive: text.length < MAX_BEACON_BYTES,
|
|
29
|
+
});
|
|
30
|
+
}
|
|
31
|
+
catch {
|
|
32
|
+
return { kind: 'retry' };
|
|
33
|
+
}
|
|
34
|
+
if (response.ok)
|
|
35
|
+
return { kind: 'ok', body: await response.json().catch(() => null) };
|
|
36
|
+
if (response.status === 413)
|
|
37
|
+
return { kind: 'too_large' };
|
|
38
|
+
if (response.status === 408 || response.status === 429 || response.status >= 500) {
|
|
39
|
+
const seconds = Number(response.headers.get('Retry-After'));
|
|
40
|
+
return { kind: 'retry', afterMs: Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined };
|
|
41
|
+
}
|
|
42
|
+
const body = (await response.json().catch(() => null));
|
|
43
|
+
return { kind: 'drop', status: response.status, detail: body?.message ?? body?.code ?? '' };
|
|
44
|
+
}
|
|
45
|
+
/** True when the browser took it; it sends it after the page is gone, and no answer ever comes back. */
|
|
46
|
+
beacon(path, text) {
|
|
47
|
+
const url = this.url(path);
|
|
48
|
+
try {
|
|
49
|
+
if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function')
|
|
50
|
+
return navigator.sendBeacon(url, new Blob([text], { type: 'text/plain' }));
|
|
51
|
+
void fetch(url, { method: 'POST', body: text, headers: { 'Content-Type': 'text/plain' }, credentials: 'omit', keepalive: true })
|
|
52
|
+
.catch(() => undefined);
|
|
53
|
+
return true;
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
return false;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Everything waiting to be sent, in order, and the sending of it (PM-R-0062 criterion 4).
|
|
62
|
+
*
|
|
63
|
+
* <p>
|
|
64
|
+
* Kept in sessionStorage, which outlives a reload and a crash of the page but is one tab's own. A
|
|
65
|
+
* queue in localStorage would be every tab's, and two tabs would each send the other's events; with
|
|
66
|
+
* this one a closed tab loses what it could not send while offline, which is the smaller harm.
|
|
67
|
+
* </p>
|
|
68
|
+
*
|
|
69
|
+
* <p>
|
|
70
|
+
* A batch that fails is sent again exactly as it was — the same events, not the same events plus
|
|
71
|
+
* whatever arrived since — so the API's deduplication token, made from the batch's event ids,
|
|
72
|
+
* recognises it and stores it once.
|
|
73
|
+
* </p>
|
|
74
|
+
*
|
|
75
|
+
* <p>
|
|
76
|
+
* Every batch says when it left, as <code>sent_at</code> by this device's clock (PM-R-0068). The API
|
|
77
|
+
* moves each event by the gap between that and when the batch arrived, so a clock that is wrong, or an
|
|
78
|
+
* event that waited offline for hours, still lands at the time it happened. It is stamped as the
|
|
79
|
+
* request is made — each retry and each beacon anew — never when the events were queued.
|
|
80
|
+
* </p>
|
|
81
|
+
*/
|
|
82
|
+
export class Outbox {
|
|
83
|
+
constructor(transport, store, name, options, log) {
|
|
84
|
+
this.transport = transport;
|
|
85
|
+
this.store = store;
|
|
86
|
+
this.name = name;
|
|
87
|
+
this.options = options;
|
|
88
|
+
this.log = log;
|
|
89
|
+
this.timer = null;
|
|
90
|
+
this.sending = null;
|
|
91
|
+
this.failures = 0;
|
|
92
|
+
this.retrySize = null;
|
|
93
|
+
this.inFlight = 0;
|
|
94
|
+
this.stopped = false;
|
|
95
|
+
this.jobs = this.load();
|
|
96
|
+
if (this.jobs.length > 0)
|
|
97
|
+
this.schedule(0);
|
|
98
|
+
}
|
|
99
|
+
get size() {
|
|
100
|
+
return this.jobs.length;
|
|
101
|
+
}
|
|
102
|
+
push(job) {
|
|
103
|
+
this.jobs.push(job);
|
|
104
|
+
// A page that cannot reach the API for hours must not grow without end; the oldest go first.
|
|
105
|
+
if (this.jobs.length > MAX_QUEUE) {
|
|
106
|
+
this.jobs.splice(0, this.jobs.length - MAX_QUEUE);
|
|
107
|
+
this.log.warn(`more than ${MAX_QUEUE} events are waiting to be sent; the oldest were dropped`);
|
|
108
|
+
}
|
|
109
|
+
this.save();
|
|
110
|
+
this.schedule(this.options.flushIntervalMs);
|
|
111
|
+
}
|
|
112
|
+
/** Sends everything now, and resolves when the queue is empty or the API cannot be reached. */
|
|
113
|
+
flush() {
|
|
114
|
+
if (this.timer !== null) {
|
|
115
|
+
clearTimeout(this.timer);
|
|
116
|
+
this.timer = null;
|
|
117
|
+
}
|
|
118
|
+
this.sending ?? (this.sending = this.drain().finally(() => { this.sending = null; }));
|
|
119
|
+
return this.sending;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* The page is going away: hand everything to the browser as beacons, which it sends after the page
|
|
123
|
+
* is gone. A batch already on its way was sent with keepalive and stays queued until it is answered.
|
|
124
|
+
*/
|
|
125
|
+
beaconAll() {
|
|
126
|
+
while (this.jobs.length > this.inFlight) {
|
|
127
|
+
const { path, text, count } = this.next(MAX_BEACON_BYTES, this.inFlight);
|
|
128
|
+
if (!this.transport.beacon(path, text))
|
|
129
|
+
break;
|
|
130
|
+
this.jobs.splice(this.inFlight, count);
|
|
131
|
+
}
|
|
132
|
+
if (this.inFlight === 0)
|
|
133
|
+
this.retrySize = null;
|
|
134
|
+
this.save();
|
|
135
|
+
}
|
|
136
|
+
clear() {
|
|
137
|
+
this.jobs = [];
|
|
138
|
+
this.retrySize = null;
|
|
139
|
+
this.save();
|
|
140
|
+
}
|
|
141
|
+
stop() {
|
|
142
|
+
this.stopped = true;
|
|
143
|
+
if (this.timer !== null)
|
|
144
|
+
clearTimeout(this.timer);
|
|
145
|
+
this.timer = null;
|
|
146
|
+
}
|
|
147
|
+
/** Online again: whatever is waiting goes now rather than at the end of its backoff. */
|
|
148
|
+
resume() {
|
|
149
|
+
if (this.jobs.length > 0 && !this.sending)
|
|
150
|
+
void this.flush();
|
|
151
|
+
}
|
|
152
|
+
schedule(delayMs) {
|
|
153
|
+
if (this.stopped || this.timer !== null)
|
|
154
|
+
return;
|
|
155
|
+
this.timer = setTimeout(() => {
|
|
156
|
+
this.timer = null;
|
|
157
|
+
void this.flush();
|
|
158
|
+
}, delayMs);
|
|
159
|
+
}
|
|
160
|
+
async drain() {
|
|
161
|
+
while (this.jobs.length > 0 && !this.stopped) {
|
|
162
|
+
const { path, text, count, events } = this.next(MAX_BATCH_BYTES);
|
|
163
|
+
this.inFlight = count;
|
|
164
|
+
const outcome = await this.transport.post(path, text).finally(() => { this.inFlight = 0; });
|
|
165
|
+
if (outcome.kind === 'retry') {
|
|
166
|
+
this.retrySize = count;
|
|
167
|
+
this.failures++;
|
|
168
|
+
// 1 s, 2 s, 4 s … up to five minutes, with jitter so a fleet of pages does not return at once.
|
|
169
|
+
const backoff = Math.min(300000, 1000 * 2 ** Math.min(this.failures - 1, 9)) * (0.75 + Math.random() / 2);
|
|
170
|
+
this.log.debug(`could not reach the API; trying again in ${Math.round((outcome.afterMs ?? backoff) / 1000)} s`);
|
|
171
|
+
this.schedule(outcome.afterMs ?? backoff);
|
|
172
|
+
return;
|
|
173
|
+
}
|
|
174
|
+
if (outcome.kind === 'too_large' && count > 1) {
|
|
175
|
+
this.retrySize = Math.ceil(count / 2);
|
|
176
|
+
continue;
|
|
177
|
+
}
|
|
178
|
+
this.jobs.splice(0, count);
|
|
179
|
+
this.retrySize = null;
|
|
180
|
+
this.failures = 0;
|
|
181
|
+
this.save();
|
|
182
|
+
if (outcome.kind === 'ok')
|
|
183
|
+
this.report(path, outcome.body, events, count);
|
|
184
|
+
else if (outcome.kind === 'too_large')
|
|
185
|
+
this.log.warn('an event was too large for the API and was dropped');
|
|
186
|
+
else
|
|
187
|
+
this.refused(outcome.status, outcome.detail, path, count);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
/** The next request from `from` on: one identify or person update, or as many events in a row as fit. */
|
|
191
|
+
next(maxBytes, from = 0) {
|
|
192
|
+
const first = this.jobs[from];
|
|
193
|
+
if (first.t === 'i')
|
|
194
|
+
return { path: 'identify', text: JSON.stringify(first.b), count: 1, events: [] };
|
|
195
|
+
if (first.t === 'p')
|
|
196
|
+
return { path: 'people', text: JSON.stringify(first.b), count: 1, events: [] };
|
|
197
|
+
const limit = from === 0 && this.retrySize !== null ? this.retrySize : this.options.batchSize;
|
|
198
|
+
const events = [];
|
|
199
|
+
let bytes = 16;
|
|
200
|
+
for (const job of this.jobs.slice(from)) {
|
|
201
|
+
if (job.t !== 'e' || events.length >= limit)
|
|
202
|
+
break;
|
|
203
|
+
const size = JSON.stringify(job.e).length + 1;
|
|
204
|
+
if (events.length > 0 && bytes + size > maxBytes)
|
|
205
|
+
break;
|
|
206
|
+
events.push(job.e);
|
|
207
|
+
bytes += size;
|
|
208
|
+
}
|
|
209
|
+
return { path: 'batch', text: JSON.stringify({ sent_at: new Date().toISOString(), events }), count: events.length, events };
|
|
210
|
+
}
|
|
211
|
+
/** The API stores the good events of a batch and says which it refused and why. */
|
|
212
|
+
report(path, body, events, count) {
|
|
213
|
+
if (path !== 'batch') {
|
|
214
|
+
this.log.debug(`${path} sent`);
|
|
215
|
+
return;
|
|
216
|
+
}
|
|
217
|
+
const refused = body?.refused ?? [];
|
|
218
|
+
this.log.debug(`${count - refused.length} of ${count} events stored`);
|
|
219
|
+
for (const r of refused)
|
|
220
|
+
this.log.warn(`"${events[r.index]?.event ?? '?'}" was refused (${r.reason}): ${r.message ?? ''}`);
|
|
221
|
+
}
|
|
222
|
+
refused(status, detail, path, count) {
|
|
223
|
+
if (status === 401) {
|
|
224
|
+
this.log.warn('the ingest key was refused; check the key in Analytics → Settings. Nothing more is sent from this page.');
|
|
225
|
+
this.clear();
|
|
226
|
+
this.stop();
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
if (status === 409 && path === 'identify') {
|
|
230
|
+
this.log.warn(`identify was refused: ${detail}`);
|
|
231
|
+
return;
|
|
232
|
+
}
|
|
233
|
+
this.log.warn(`${count} ${path === 'batch' ? 'events were' : path + ' request was'} refused (${status}): ${detail}`);
|
|
234
|
+
}
|
|
235
|
+
load() {
|
|
236
|
+
const text = this.store?.get(this.name);
|
|
237
|
+
if (!text)
|
|
238
|
+
return [];
|
|
239
|
+
try {
|
|
240
|
+
const jobs = JSON.parse(text);
|
|
241
|
+
return Array.isArray(jobs) ? jobs.filter((j) => j && (j.t === 'e' || j.t === 'i' || j.t === 'p')) : [];
|
|
242
|
+
}
|
|
243
|
+
catch {
|
|
244
|
+
return [];
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
save() {
|
|
248
|
+
if (!this.store)
|
|
249
|
+
return;
|
|
250
|
+
if (this.jobs.length === 0)
|
|
251
|
+
this.store.remove(this.name);
|
|
252
|
+
else
|
|
253
|
+
this.store.set(this.name, JSON.stringify(this.jobs));
|
|
254
|
+
}
|
|
255
|
+
}
|