@nagoorkani/session-capture-expo 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 +25 -0
- package/README.md +112 -0
- package/dist/device.d.ts +23 -0
- package/dist/index.d.ts +105 -0
- package/dist/index.js +1824 -0
- package/dist/index.mjs +1801 -0
- package/dist/lifecycle.d.ts +20 -0
- package/dist/store-expo.d.ts +35 -0
- package/package.json +60 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
PROPRIETARY SOFTWARE LICENSE
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nagoorkani2393. All rights reserved.
|
|
4
|
+
|
|
5
|
+
This software, its source code, and its accompanying documentation (the
|
|
6
|
+
"Software") are the proprietary and confidential property of the copyright
|
|
7
|
+
holder.
|
|
8
|
+
|
|
9
|
+
NO LICENSE IS GRANTED. No person or entity is permitted to use, copy, modify,
|
|
10
|
+
merge, publish, distribute, sublicense, reverse engineer, create derivative
|
|
11
|
+
works from, or sell the Software, in whole or in part, by any means, except
|
|
12
|
+
under a separate written agreement signed by the copyright holder.
|
|
13
|
+
|
|
14
|
+
Availability of the Software through a public package registry, source
|
|
15
|
+
repository, or any other distribution channel is for the convenience of
|
|
16
|
+
authorized licensees only. It does not grant any license, right, or permission
|
|
17
|
+
to the general public, and no such license may be implied from that
|
|
18
|
+
availability. Unauthorized use, reproduction, or distribution is prohibited.
|
|
19
|
+
|
|
20
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
21
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
22
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
23
|
+
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
24
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
25
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# @nagoorkani/session-capture-expo
|
|
2
|
+
|
|
3
|
+
Session capture and observability for Expo / React Native. Sessions, screens,
|
|
4
|
+
errors, breadcrumbs, network capture, performance marks and a durable offline
|
|
5
|
+
queue, in under 50 KB minified.
|
|
6
|
+
|
|
7
|
+
The capture itself is [`@nagoorkani/session-capture-core`](../core/README.md), shared with
|
|
8
|
+
the Vue SDK and bundled in here; this package is the React Native of it —
|
|
9
|
+
`expo-file-system` for the queue, `AppState` for foreground and background, and
|
|
10
|
+
`Platform` for what the device is.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npx expo install @nagoorkani/session-capture-expo
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Setup
|
|
19
|
+
|
|
20
|
+
Create a project in the dashboard to get its ID and an ingestion key. The key
|
|
21
|
+
is shown once, at creation — only its hash is stored, so a lost key is rotated
|
|
22
|
+
rather than recovered.
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { init } from '@nagoorkani/session-capture-expo'
|
|
26
|
+
|
|
27
|
+
init({
|
|
28
|
+
apiKey: 'pk_live_...',
|
|
29
|
+
projectId: 'project_...',
|
|
30
|
+
endpoint: 'https://ingest.example.com',
|
|
31
|
+
appVersion: '1.4.0',
|
|
32
|
+
})
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
That is the whole required setup. A session opens immediately,
|
|
36
|
+
foreground/background transitions are tracked, and errors — including unhandled
|
|
37
|
+
rejections — are captured without further wiring. Uncaught errors still reach
|
|
38
|
+
your own handlers: the SDK chains rather than replaces them.
|
|
39
|
+
|
|
40
|
+
## Capturing
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { track, screen, identify } from '@nagoorkani/session-capture-expo'
|
|
44
|
+
|
|
45
|
+
screen('Checkout')
|
|
46
|
+
track('checkout_started', { cartValue: 4200 })
|
|
47
|
+
identify('user_123', { plan: 'pro' })
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import { captureException, breadcrumb, startMeasure, endMeasure } from '@nagoorkani/session-capture-expo'
|
|
52
|
+
|
|
53
|
+
breadcrumb('user tapped checkout', { cartValue: 4200 })
|
|
54
|
+
|
|
55
|
+
startMeasure('payment_submit')
|
|
56
|
+
await submitPayment()
|
|
57
|
+
endMeasure('payment_submit')
|
|
58
|
+
|
|
59
|
+
try { await risky() } catch (err) { captureException(err, { screen: 'Checkout' }) }
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Every error carries the last 20 breadcrumbs, so the error view is readable
|
|
63
|
+
without reassembling the whole session first.
|
|
64
|
+
|
|
65
|
+
`fetch` is instrumented automatically. Pass `captureNetwork: false` to `init`
|
|
66
|
+
to opt out. Query strings are stripped and credential headers redacted before
|
|
67
|
+
anything is buffered, and requests to the ingestion endpoint are never
|
|
68
|
+
captured.
|
|
69
|
+
|
|
70
|
+
## Consent
|
|
71
|
+
|
|
72
|
+
For jurisdictions where capture must wait:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { init, setEnabled } from '@nagoorkani/session-capture-expo'
|
|
76
|
+
|
|
77
|
+
init({ apiKey: 'pk_live_...', projectId: 'project_...', endpoint: '...', enabled: false })
|
|
78
|
+
// ...once the user consents
|
|
79
|
+
setEnabled(true)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Nothing is captured *or* buffered while disabled.
|
|
83
|
+
|
|
84
|
+
## The contract
|
|
85
|
+
|
|
86
|
+
- The API key is **not a secret**. It may only submit events, never read them,
|
|
87
|
+
and it is assumed to be extractable from any shipped binary.
|
|
88
|
+
- Auth headers, cookies, and anything matching `token|key|secret|password|auth`
|
|
89
|
+
are redacted on-device before buffering. Request and response bodies are not
|
|
90
|
+
captured by default.
|
|
91
|
+
- Sampling is decided once per session, so a timeline is whole or absent —
|
|
92
|
+
never half-captured. Errors and crashes are always sent.
|
|
93
|
+
- Sample rate, batching, redaction rules and a kill switch arrive by remote
|
|
94
|
+
config, fetched on init and refreshed on foreground. `enabled: false` stops a
|
|
95
|
+
running SDK mid-session without an app release. Config is cached to disk, so
|
|
96
|
+
a cold start begins from the last known values rather than compiled defaults;
|
|
97
|
+
a failed fetch keeps what is already in force rather than reverting.
|
|
98
|
+
- **It must never throw into your app.** Every public entry point and listener
|
|
99
|
+
is wrapped; repeated internal failures self-disable the SDK rather than
|
|
100
|
+
surfacing.
|
|
101
|
+
|
|
102
|
+
## Visual replay
|
|
103
|
+
|
|
104
|
+
[`@nagoorkani/session-capture-expo-replay`](../expo-replay/README.md) is a separate,
|
|
105
|
+
optional package. It carries native code — installing it changes how your app
|
|
106
|
+
is built, which this package never does.
|
|
107
|
+
|
|
108
|
+
## License
|
|
109
|
+
|
|
110
|
+
Proprietary — all rights reserved. See [LICENSE](./LICENSE). No use, copying,
|
|
111
|
+
modification or distribution is permitted without a written agreement with the
|
|
112
|
+
copyright holder.
|
package/dist/device.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Device context, attached to `session_start`.
|
|
3
|
+
*
|
|
4
|
+
* ponytail: no `expo-device`. React Native's own `Platform` is already a peer
|
|
5
|
+
* dependency and covers OS and version for free. `deviceModel` is the only
|
|
6
|
+
* field it cannot provide, and one field is not worth a native module against
|
|
7
|
+
* the 50 KB budget (section 26).
|
|
8
|
+
*
|
|
9
|
+
* `react-native` is imported statically, and that matters. An earlier version
|
|
10
|
+
* reached for `globalThis.require` to stay loadable in Node — but Metro does
|
|
11
|
+
* not expose `require` as a global, so on a real device the lookup silently
|
|
12
|
+
* returned nothing and every session arrived with a null platform. The tests
|
|
13
|
+
* passed the whole time, because Node takes exactly the same empty path.
|
|
14
|
+
*
|
|
15
|
+
* This module is therefore device-only. Nothing importable by tests may import
|
|
16
|
+
* it: `core.ts` receives the context through a provider instead.
|
|
17
|
+
*/
|
|
18
|
+
export interface DeviceContext {
|
|
19
|
+
platform?: 'ios' | 'android';
|
|
20
|
+
osVersion?: string;
|
|
21
|
+
appVersion?: string;
|
|
22
|
+
}
|
|
23
|
+
export declare function readDeviceContext(appVersion?: string): DeviceContext;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @nagoorkani/session-capture-expo
|
|
3
|
+
*
|
|
4
|
+
* Public surface and wiring. Everything the SDK does to the host app —
|
|
5
|
+
* patching `fetch`, installing error handlers, subscribing to app state — is
|
|
6
|
+
* installed here and unwound by `shutdown()`.
|
|
7
|
+
*/
|
|
8
|
+
import { type InitOptions, type RemoteConfig } from '@nagoorkani/session-capture-core';
|
|
9
|
+
export type { CaptureEvent, EventBatch, EventType, InitOptions, RemoteConfig, } from '@nagoorkani/session-capture-core';
|
|
10
|
+
export { SCHEMA_VERSION, DEFAULT_CONFIG } from '@nagoorkani/session-capture-core';
|
|
11
|
+
export { isSelfDisabled, safe, safeAsync } from '@nagoorkani/session-capture-core';
|
|
12
|
+
/**
|
|
13
|
+
* Durable storage, for the replay package's own queue.
|
|
14
|
+
*
|
|
15
|
+
* Exported rather than reimplemented: this already handles the
|
|
16
|
+
* `expo-file-system` API generations and falls back to memory where
|
|
17
|
+
* persistence is unavailable. Callers must pass their own directory — never
|
|
18
|
+
* `QUEUE_DIR` — because `SendQueue.peek()` deletes every file it cannot parse
|
|
19
|
+
* as an event batch.
|
|
20
|
+
*/
|
|
21
|
+
export { MemoryStore, type FileStore } from '@nagoorkani/session-capture-core';
|
|
22
|
+
/**
|
|
23
|
+
* Session sampling, for the replay package's own rate.
|
|
24
|
+
*
|
|
25
|
+
* Shared rather than reimplemented, and deliberately the same hash: with a
|
|
26
|
+
* replay rate below the event rate, the sessions that get recorded are a
|
|
27
|
+
* subset of the sessions that have events. A replay with no timeline beside
|
|
28
|
+
* it would be the useless half of the pair.
|
|
29
|
+
*/
|
|
30
|
+
export { isSampled } from '@nagoorkani/session-capture-core';
|
|
31
|
+
export { createPersistentStore } from './store-expo.ts';
|
|
32
|
+
export { SDK_VERSION } from '@nagoorkani/session-capture-core';
|
|
33
|
+
export type { Breadcrumb } from '@nagoorkani/session-capture-core';
|
|
34
|
+
export type { CapturedError } from '@nagoorkani/session-capture-core';
|
|
35
|
+
export type { NetworkEvent } from '@nagoorkani/session-capture-core';
|
|
36
|
+
/**
|
|
37
|
+
* Start the SDK.
|
|
38
|
+
*
|
|
39
|
+
* Pass `enabled: false` to initialize without capturing, then `setEnabled(true)`
|
|
40
|
+
* once the user consents. Nothing is captured *or* buffered while disabled.
|
|
41
|
+
*/
|
|
42
|
+
export declare const init: (options: InitOptions) => void | undefined;
|
|
43
|
+
/** Enable or disable capture at runtime. The consent gate. */
|
|
44
|
+
export declare const setEnabled: (enabled: boolean) => void | undefined;
|
|
45
|
+
/** Whether the SDK is currently capturing. */
|
|
46
|
+
export declare const isEnabled: () => boolean;
|
|
47
|
+
/** Record a custom event. */
|
|
48
|
+
export declare const track: (name: string, properties?: Record<string, unknown> | undefined) => void | undefined;
|
|
49
|
+
/** Record a screen view and set the current screen. */
|
|
50
|
+
export declare const screen: (name: string) => void | undefined;
|
|
51
|
+
/** Associate the session with an end user. */
|
|
52
|
+
export declare const identify: (userId: string, traits?: Record<string, unknown> | undefined) => void | undefined;
|
|
53
|
+
/** Send anything buffered immediately, then drain the durable queue. */
|
|
54
|
+
export declare const flush: () => Promise<void | undefined>;
|
|
55
|
+
/** Queued batches awaiting delivery. Useful in development. */
|
|
56
|
+
export declare const pendingBatches: () => Promise<number>;
|
|
57
|
+
/**
|
|
58
|
+
* Subscribe to captured errors.
|
|
59
|
+
*
|
|
60
|
+
* Exists for the optional replay package (section 23), which uploads the
|
|
61
|
+
* frames leading up to an error. Returns an unsubscribe; a no-op before
|
|
62
|
+
* `init`.
|
|
63
|
+
*/
|
|
64
|
+
/**
|
|
65
|
+
* The configuration in force right now.
|
|
66
|
+
*
|
|
67
|
+
* Remote config can change it mid-session, so this is a read, not a snapshot
|
|
68
|
+
* taken at init. The replay package reads its own fields from here rather than
|
|
69
|
+
* importing core internals.
|
|
70
|
+
*/
|
|
71
|
+
export declare const currentConfig: () => RemoteConfig;
|
|
72
|
+
/**
|
|
73
|
+
* Keep the current session alive, and rotate it if it has run its course.
|
|
74
|
+
*
|
|
75
|
+
* For the replay package: recording is activity, but it emits no events, so
|
|
76
|
+
* without this a foreground app with an idle user holds one session forever
|
|
77
|
+
* while frames keep accumulating against it. A no-op before `init`, and while
|
|
78
|
+
* capture is disabled.
|
|
79
|
+
*/
|
|
80
|
+
export declare const keepSessionAlive: () => void | undefined;
|
|
81
|
+
/**
|
|
82
|
+
* Subscribe to session starts.
|
|
83
|
+
*
|
|
84
|
+
* Fires as each session begins, and once immediately if one is already open —
|
|
85
|
+
* a subscriber that arrives a tick after `init()` would otherwise wait for the
|
|
86
|
+
* next rotation, which may be half an hour away.
|
|
87
|
+
*
|
|
88
|
+
* Exists for the optional replay package (section 23), which records
|
|
89
|
+
* continuously and so needs the session id at every flush rather than only
|
|
90
|
+
* when an error fires. Returns an unsubscribe; a no-op before `init`.
|
|
91
|
+
*/
|
|
92
|
+
export declare const onSession: (listener: (sessionId: string) => void) => () => void;
|
|
93
|
+
export declare const onError: (listener: (sessionId: string) => void) => () => void;
|
|
94
|
+
/** Report an error explicitly. */
|
|
95
|
+
export declare const captureException: (error: unknown, extra?: Record<string, unknown> | undefined) => void | undefined;
|
|
96
|
+
/** Record a manual breadcrumb. */
|
|
97
|
+
export declare const breadcrumb: (message: string, data?: Record<string, unknown> | undefined) => void | undefined;
|
|
98
|
+
/** Start a named timing measurement. */
|
|
99
|
+
export declare const startMeasure: (name: string) => void | undefined;
|
|
100
|
+
/** Finish a named timing measurement and record it. */
|
|
101
|
+
export declare const endMeasure: (name: string) => void | undefined;
|
|
102
|
+
/** Record time from SDK load until the app became interactive. */
|
|
103
|
+
export declare const markAppReady: () => void | undefined;
|
|
104
|
+
/** Stop the SDK and release listeners. */
|
|
105
|
+
export declare const shutdown: () => void | undefined;
|