@inferevents/sdk 0.1.3 → 0.1.4
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 +140 -0
- package/package.json +4 -3
package/README.md
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# @inferevents/sdk
|
|
2
|
+
|
|
3
|
+
Event collection SDK for [Infer](https://infer.events) — analytics designed for AI agents, not dashboards.
|
|
4
|
+
|
|
5
|
+
3KB. Zero dependencies. Auto-tracks page views, clicks, sessions, and errors out of the box.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @inferevents/sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { init, track, identify } from "@inferevents/sdk";
|
|
17
|
+
|
|
18
|
+
init({
|
|
19
|
+
projectId: "pk_write_...", // your write key (safe to embed in client JS)
|
|
20
|
+
autoTrack: true, // auto-tracks page views, clicks, sessions, errors
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
// Track custom events
|
|
24
|
+
track("signup_completed", { plan: "pro" });
|
|
25
|
+
|
|
26
|
+
// Identify a user (links anonymous activity to a known user)
|
|
27
|
+
identify("user_123", { email: "alice@example.com" });
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## API
|
|
31
|
+
|
|
32
|
+
### `init(config)`
|
|
33
|
+
|
|
34
|
+
Initialize the SDK. Must be called before other methods (events queued before init are replayed automatically).
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
init({
|
|
38
|
+
projectId: string; // Required. Your write key (pk_write_...)
|
|
39
|
+
endpoint?: string; // API endpoint (default: https://api.infer.events)
|
|
40
|
+
autoTrack?: boolean; // Enable auto-tracking (default: false)
|
|
41
|
+
batchSize?: number; // Events per batch (default: 20)
|
|
42
|
+
flushInterval?: number; // Flush interval in ms (default: 10000)
|
|
43
|
+
debug?: boolean; // Console logging (default: false)
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### `track(eventName, properties?)`
|
|
48
|
+
|
|
49
|
+
Track a custom event.
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
track("purchase", { amount: 49.99, currency: "USD" });
|
|
53
|
+
track("feature_used", { feature: "export" });
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### `identify(userId, traits?)`
|
|
57
|
+
|
|
58
|
+
Link the current anonymous user to a known user ID. All past and future events are associated with this identity.
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
identify("user_123", { name: "Alice", plan: "pro" });
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### `page(name?)`
|
|
65
|
+
|
|
66
|
+
Track a page view. Called automatically if `autoTrack: true`.
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
page("Pricing");
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### `screen(name)`
|
|
73
|
+
|
|
74
|
+
Track a screen view (React Native / mobile).
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
screen("Settings");
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### `flush()`
|
|
81
|
+
|
|
82
|
+
Manually flush the event queue. Events are batched and sent automatically, but you can force a flush.
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
await flush();
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### `reset()`
|
|
89
|
+
|
|
90
|
+
Clear the current user identity. Use on logout to start a new anonymous session.
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
reset();
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### `destroy()`
|
|
97
|
+
|
|
98
|
+
Tear down the SDK, clear timers and listeners.
|
|
99
|
+
|
|
100
|
+
## Auto-tracking
|
|
101
|
+
|
|
102
|
+
When `autoTrack: true`, the SDK automatically captures:
|
|
103
|
+
|
|
104
|
+
| Event | Trigger |
|
|
105
|
+
|-------|---------|
|
|
106
|
+
| `page_view` | Page navigation (History API) |
|
|
107
|
+
| `session_start` | New browser session |
|
|
108
|
+
| `click` | Clicks on interactive elements (buttons, links) |
|
|
109
|
+
| `form_submit` | Form submissions |
|
|
110
|
+
| `error` | Uncaught JavaScript errors |
|
|
111
|
+
|
|
112
|
+
## Context
|
|
113
|
+
|
|
114
|
+
Every event includes auto-collected context:
|
|
115
|
+
|
|
116
|
+
| Field | Source |
|
|
117
|
+
|-------|--------|
|
|
118
|
+
| `browser` | User agent |
|
|
119
|
+
| `os` | Parsed from UA (macOS, Windows, iOS, Android, Linux) |
|
|
120
|
+
| `device_type` | Mobile, Tablet, or Desktop |
|
|
121
|
+
| `page_url` | `window.location.href` |
|
|
122
|
+
| `pathname` | `window.location.pathname` |
|
|
123
|
+
| `referrer` | `document.referrer` |
|
|
124
|
+
| `locale` | `navigator.language` |
|
|
125
|
+
| `timezone` | `Intl.DateTimeFormat` timezone |
|
|
126
|
+
| `screen_width` / `screen_height` | Screen dimensions |
|
|
127
|
+
|
|
128
|
+
Server-side geo enrichment (country, city, region) is added at ingestion time.
|
|
129
|
+
|
|
130
|
+
## How it works
|
|
131
|
+
|
|
132
|
+
- Events are queued in memory and flushed every 10 seconds (or when batch size is reached)
|
|
133
|
+
- On page unload, queued events are sent via `fetch` with `keepalive: true`
|
|
134
|
+
- Unflushed events are persisted to `localStorage` and restored on next page load
|
|
135
|
+
- Failed sends are retried with exponential backoff
|
|
136
|
+
- Each event gets a UUID for deduplication (server-side `ON CONFLICT DO NOTHING`)
|
|
137
|
+
|
|
138
|
+
## License
|
|
139
|
+
|
|
140
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@inferevents/sdk",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.4",
|
|
4
|
+
"description": "Event collection SDK for Infer — analytics designed for AI agents, not dashboards",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
7
7
|
"module": "./dist/index.js",
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
}
|
|
20
20
|
},
|
|
21
21
|
"files": [
|
|
22
|
-
"dist"
|
|
22
|
+
"dist",
|
|
23
|
+
"README.md"
|
|
23
24
|
],
|
|
24
25
|
"scripts": {
|
|
25
26
|
"build": "tsup",
|