@usesequential/browser 0.0.0-stage → 1.0.1

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 ADDED
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ ## 1.0.1
4
+
5
+ - README only: where the key comes from when there is no account yet (a trial that a coding agent creates with one call). No code change.
6
+
7
+ ## 1.0.0
8
+
9
+ - First release: `init(options)` and `VERSION`. The SDK code is `sequential.js`, the file the script tag loads, with
10
+ the same behaviour: autocapture, session replay, identify, accounts, opt-out (no id or session value stored before
11
+ opt-in or while opted out) and the context cookie `__sq_ctx`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sequential
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,98 @@
1
- # Temporary Holding Version
1
+ # @usesequential/browser
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The [Sequential](https://www.usesequential.com) browser SDK as an npm package: product analytics and session replay
4
+ from one call. The code is `sequential.js`, the file that the Sequential script tag loads, with the same behaviour.
5
+
6
+ - Page views, clicks, form submits, rage clicks and dead clicks, recorded automatically.
7
+ - Session replay, when replay is on for your project. The SDK loads the recorder from your ingest host.
8
+ - `identify`, `account`, custom events and errors.
9
+ - Consent: start opted out, and nothing is stored on the device until `optIn()`.
10
+ - No dependencies. ES modules and CommonJS. Types included. Safe to import in server-rendered apps.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ npm install @usesequential/browser
16
+ ```
17
+
18
+ You need the project's **sequential** key (`sq_sequential_…`) and the API host, `https://api.usesequential.com`:
19
+
20
+ - **You have a Sequential project:** copy them from **Setup** in Sequential.
21
+ - **No account yet (for example, a coding agent installing this for someone):** create a trial with one call. No
22
+ account is needed. The answer's `ingest_key` is the key; the person claims the trial from an email within 72 hours.
23
+ Until then, the trial accepts events only from `localhost`.
24
+
25
+ ```bash
26
+ curl -X POST https://api.usesequential.com/api/agent/provision \
27
+ -H 'content-type: application/json' \
28
+ -d '{"owner_email": "person@example.com", "platform": "web"}'
29
+ ```
30
+
31
+ Details: [Let your agent set up a trial](https://www.usesequential.com/docs/agent-trial).
32
+
33
+ ## Start it
34
+
35
+ Call `init()` once, in the browser, as early as you can:
36
+
37
+ ```ts
38
+ import { init } from '@usesequential/browser';
39
+
40
+ const sequential = init({
41
+ key: 'sq_sequential_…',
42
+ api: 'https://api.usesequential.com',
43
+ release: 'web@2.14.1', // optional: your app's build, on every event
44
+ });
45
+
46
+ sequential.identify(user.id, { email: user.email });
47
+ sequential.capture('checkout_started', { plan: 'pro' });
48
+ ```
49
+
50
+ `init()` also sets `window.sequential`, the same object, so code written for the script tag works.
51
+
52
+ - **Server rendering.** Importing the package does nothing. Without a window, `init()` returns an object whose
53
+ methods do nothing. Call it from client code: in SvelteKit in `onMount` or a `+layout.svelte` browser block, in
54
+ Next.js in a client component's `useEffect`.
55
+ - **Call it once.** A second `init()` returns the running SDK and writes a warning to the console.
56
+ - **Not with the script tag.** Use the package or the tag, not both. If the tag already loaded the SDK, `init()`
57
+ returns that SDK and does not read its options. If the tag's install snippet ran first, `init()` sends the calls
58
+ that it queued.
59
+
60
+ ## Options
61
+
62
+ | Option | Same as the tag's | |
63
+ |---|---|---|
64
+ | `key` | `data-key` | Required. |
65
+ | `api` | `data-api` | Required. |
66
+ | `release` | `data-release` | 1 to 64 printable ASCII characters. |
67
+ | `optOut: true` | `data-opt-out` | Start opted out. |
68
+ | `autocapture: false` | `data-autocapture="false"` | No automatic page views, clicks or form submits. |
69
+ | `identityText: false` | `data-identity-text="off"` | No check for the signed-in person's name and email in click text. |
70
+ | `contextCookieDomain` | `data-context-cookie-domain` | `Domain=` for the context cookie `__sq_ctx`. |
71
+
72
+ Without `key` and `api`, `init()` writes one error to the console and sends nothing.
73
+
74
+ ## Consent
75
+
76
+ For a site that waits for consent, start opted out and call `optIn()` when the visitor agrees:
77
+
78
+ ```ts
79
+ const sequential = init({ key: 'sq_sequential_…', api: 'https://api.usesequential.com', optOut: true });
80
+ consentBanner.onAccept(() => sequential.optIn());
81
+ ```
82
+
83
+ Before opt-in, and while a visitor is opted out, the SDK stores no id, no session value and no cookie on the device.
84
+ With `optOut: true`, it stores nothing at all. `optOut()` deletes the ids that the SDK stored and keeps one key,
85
+ `__sq_opt`, that holds only the visitor's choice, so the opt-out stays in force on the next pages. `optIn()` deletes
86
+ it.
87
+
88
+ ## Methods
89
+
90
+ `capture(name, props)`, `identify(userId, props)`, `account(id, traits)`, `register(props)`, `unregister(name)`,
91
+ `reset()`, `optOut()`, `optIn()`, `captureException(error, props)` and `flush()`. Names that start with `$` are
92
+ reserved, and `capture()` throws on them.
93
+
94
+ Full documentation: https://www.usesequential.com/docs/browser-npm and https://www.usesequential.com/docs/sequential.
95
+
96
+ ## Licence
97
+
98
+ MIT