@inkronik/browser-sdk 1.0.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 +21 -0
- package/README.md +105 -0
- package/dist/client.d.ts +44 -0
- package/dist/constants.d.ts +26 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +753 -0
- package/dist/index.js.map +18 -0
- package/dist/instrumentation.d.ts +2 -0
- package/dist/protocol/types.d.ts +44 -0
- package/dist/sanitizer.d.ts +6 -0
- package/dist/session.d.ts +3 -0
- package/dist/trace-context.d.ts +4 -0
- package/dist/transport.d.ts +2 -0
- package/dist/types.d.ts +183 -0
- package/dist/utils.d.ts +15 -0
- package/package.json +66 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Inkronik
|
|
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
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# `@inkronik/browser-sdk`
|
|
2
|
+
|
|
3
|
+
Privacy-first browser RUM, distributed tracing, and product-event collection for Inkronik.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
bun add @inkronik/browser-sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The package ships compiled, tree-shakeable ESM and TypeScript declarations. It has no runtime dependencies and is safe to import during server-side
|
|
12
|
+
rendering; browser instrumentation starts only when a client is constructed in a browser environment.
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
Create the client only after your application's consent policy permits telemetry:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { createInkronikBrowser } from '@inkronik/browser-sdk'
|
|
20
|
+
|
|
21
|
+
const inkronik = createInkronikBrowser({
|
|
22
|
+
publicKey: 'ik_pub_...',
|
|
23
|
+
collectorUrl: 'https://collector.inkronik.codemask.dev',
|
|
24
|
+
tracePropagationOrigins: ['https://api.example.com'],
|
|
25
|
+
user: {
|
|
26
|
+
id: currentUser.uuid,
|
|
27
|
+
attributes: { role: currentUser.role, tenant_id: currentUser.tenantId },
|
|
28
|
+
},
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
inkronik.capture({ name: 'checkout_started', attributes: { plan: 'pro' } })
|
|
32
|
+
|
|
33
|
+
// Authentication state can change after initialization.
|
|
34
|
+
inkronik.setUser({ id: currentUser.uuid, attributes: { role: currentUser.role } })
|
|
35
|
+
inkronik.clearUser()
|
|
36
|
+
|
|
37
|
+
// Flush queued telemetry and remove instrumentation during application teardown.
|
|
38
|
+
await inkronik.shutdown()
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The public key is a revocable source identifier, not a secret. It can send only browser RUM, constrained browser spans, and custom events.
|
|
42
|
+
|
|
43
|
+
## Identity and privacy
|
|
44
|
+
|
|
45
|
+
Use one stable, opaque user ID across the browser and backend, ideally the authentication `sub` or UUID. Matching identifiers let RUM, product
|
|
46
|
+
events, request captures, logs, and traces be queried for the same user. Do not use an email address, name, phone number, or raw token as the ID.
|
|
47
|
+
User attributes are stored as `user.*`; sensitive keys and values are redacted in both the SDK and Collector.
|
|
48
|
+
|
|
49
|
+
The SDK:
|
|
50
|
+
|
|
51
|
+
- never reads form values, DOM text, request bodies, cookies, clipboard data, or arbitrary storage contents;
|
|
52
|
+
- strips URL credentials, query strings, fragments, and identifier-like route segments before transport;
|
|
53
|
+
- keeps its bounded telemetry queue in memory;
|
|
54
|
+
- persists only an anonymous session UUID and activity timestamps in `localStorage`, and falls back to an in-memory session when storage is
|
|
55
|
+
unavailable;
|
|
56
|
+
- accepts only primitive custom attribute values and sanitizes them before transport.
|
|
57
|
+
|
|
58
|
+
## Distributed tracing
|
|
59
|
+
|
|
60
|
+
The SDK creates one trace per browser view and instruments `fetch`. Same-origin requests are traced by default. Cross-origin propagation happens
|
|
61
|
+
only for exact origins listed in `tracePropagationOrigins`:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
const inkronik = createInkronikBrowser({
|
|
65
|
+
publicKey: 'ik_pub_...',
|
|
66
|
+
collectorUrl: 'https://collector.inkronik.codemask.dev',
|
|
67
|
+
tracePropagationOrigins: ['https://api.example.com'],
|
|
68
|
+
})
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The injected W3C `traceparent` lets an instrumented backend continue the browser trace through server, database, messaging, and external-service
|
|
72
|
+
spans. Collector requests are always excluded from fetch instrumentation.
|
|
73
|
+
|
|
74
|
+
Adding `traceparent` to a cross-origin request requires the target API's CORS policy to allow that request header. Send trace context only to
|
|
75
|
+
services you trust; configured targets are normalized to exact origins.
|
|
76
|
+
|
|
77
|
+
Set `enableFetchTracing: false` if another library must exclusively own global fetch instrumentation.
|
|
78
|
+
|
|
79
|
+
## Manual flushing
|
|
80
|
+
|
|
81
|
+
The SDK flushes automatically by interval and batch size. You can also request delivery explicitly:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
await inkronik.flush()
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`shutdown()` removes installed browser hooks, stops the timer, and attempts a final delivery using `sendBeacon` when available.
|
|
88
|
+
|
|
89
|
+
## Development
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
bun install --frozen-lockfile
|
|
93
|
+
bun test
|
|
94
|
+
bun run typecheck
|
|
95
|
+
bun run check:lint
|
|
96
|
+
bun run check:format
|
|
97
|
+
bun run build
|
|
98
|
+
npm pack --dry-run
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
See [RELEASING.md](./RELEASING.md) for the release process and [SECURITY.md](./SECURITY.md) for vulnerability reporting.
|
|
102
|
+
|
|
103
|
+
## License
|
|
104
|
+
|
|
105
|
+
MIT License. See [LICENSE](./LICENSE).
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { CaptureEventInput, CreateInkronikBrowserOptions, SetUserInput } from './types.js';
|
|
2
|
+
export declare class InkronikBrowserClient {
|
|
3
|
+
private readonly publicKey;
|
|
4
|
+
private readonly collectorUrl;
|
|
5
|
+
private readonly sampleRate;
|
|
6
|
+
private readonly defaultAttributes;
|
|
7
|
+
private readonly maxBatchSize;
|
|
8
|
+
private readonly maxQueueSize;
|
|
9
|
+
private readonly maxRetries;
|
|
10
|
+
private readonly fetchImpl;
|
|
11
|
+
private readonly onError;
|
|
12
|
+
private readonly getRoute;
|
|
13
|
+
private readonly sanitizeUrl;
|
|
14
|
+
private readonly enableFetchTracing;
|
|
15
|
+
private readonly tracePropagationOrigins;
|
|
16
|
+
private readonly environment;
|
|
17
|
+
private readonly session;
|
|
18
|
+
private readonly flushTimer;
|
|
19
|
+
private readonly cleanupInstrumentation;
|
|
20
|
+
private readonly cleanupLifecycle;
|
|
21
|
+
private readonly sampled;
|
|
22
|
+
private queue;
|
|
23
|
+
private flushing;
|
|
24
|
+
private viewContext;
|
|
25
|
+
private userId;
|
|
26
|
+
private userAttributes;
|
|
27
|
+
private closed;
|
|
28
|
+
constructor(options: CreateInkronikBrowserOptions);
|
|
29
|
+
capture(input: CaptureEventInput): void;
|
|
30
|
+
setUser(input: SetUserInput): void;
|
|
31
|
+
clearUser(): void;
|
|
32
|
+
flush(): Promise<void>;
|
|
33
|
+
shutdown(): Promise<void>;
|
|
34
|
+
private beginView;
|
|
35
|
+
private startView;
|
|
36
|
+
private enqueue;
|
|
37
|
+
private enqueueSpan;
|
|
38
|
+
private enqueueItem;
|
|
39
|
+
private flushBatch;
|
|
40
|
+
private installInstrumentation;
|
|
41
|
+
private readonly traceFetch;
|
|
42
|
+
private completeFetchSpan;
|
|
43
|
+
private installLifecycle;
|
|
44
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export declare const DEFAULT_BATCH_SIZE = 20;
|
|
2
|
+
export declare const DEFAULT_MAX_QUEUE_SIZE = 200;
|
|
3
|
+
export declare const DEFAULT_FLUSH_INTERVAL_MS = 5000;
|
|
4
|
+
export declare const DEFAULT_MAX_RETRIES = 2;
|
|
5
|
+
export declare const DEFAULT_RETRY_BASE_MS = 250;
|
|
6
|
+
export declare const DEFAULT_SAMPLE_RATE = 1;
|
|
7
|
+
export declare const SDK_NAME = "@inkronik/browser-sdk";
|
|
8
|
+
export declare const SDK_VERSION = "1.0.0";
|
|
9
|
+
export declare const DEFAULT_SESSION_INACTIVITY_MS: number;
|
|
10
|
+
export declare const DEFAULT_SESSION_MAX_DURATION_MS: number;
|
|
11
|
+
export declare const BROWSER_SESSION_STORAGE_KEY = "inkronik.browser.session";
|
|
12
|
+
export declare const REDACTED_VALUE = "[REDACTED]";
|
|
13
|
+
export declare const MAX_ATTRIBUTES = 32;
|
|
14
|
+
export declare const MAX_ATTRIBUTE_KEY_LENGTH = 64;
|
|
15
|
+
export declare const MAX_ATTRIBUTE_VALUE_LENGTH = 512;
|
|
16
|
+
export declare const MAX_ERROR_VALUE_LENGTH = 4096;
|
|
17
|
+
export declare const INKRONIK_ORIGINAL_BROWSER_FETCH: unique symbol;
|
|
18
|
+
export declare const SENSITIVE_KEY_FRAGMENTS: readonly ["password", "passwd", "secret", "token", "authorization", "cookie", "api_key", "apikey", "credential", "session", "card", "cvv", "cvc", "email", "phone", "ssn", "input", "value"];
|
|
19
|
+
export declare const EMAIL_PATTERN: RegExp;
|
|
20
|
+
export declare const PHONE_PATTERN: RegExp;
|
|
21
|
+
export declare const CARD_PATTERN: RegExp;
|
|
22
|
+
export declare const TOKEN_PATTERN: RegExp;
|
|
23
|
+
export declare const ROUTE_UUID_SEGMENT_PATTERN: RegExp;
|
|
24
|
+
export declare const ROUTE_ULID_SEGMENT_PATTERN: RegExp;
|
|
25
|
+
export declare const ROUTE_OBJECT_ID_SEGMENT_PATTERN: RegExp;
|
|
26
|
+
export declare const ROUTE_NUMERIC_SEGMENT_PATTERN: RegExp;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { InkronikBrowserClient } from './client.js';
|
|
2
|
+
export { sanitizeBrowserAttributes, sanitizeBrowserUrl } from './sanitizer.js';
|
|
3
|
+
export type * from './types.js';
|
|
4
|
+
import { InkronikBrowserClient } from './client.js';
|
|
5
|
+
import type { CreateInkronikBrowserOptions } from './types.js';
|
|
6
|
+
export declare const createInkronikBrowser: (options: CreateInkronikBrowserOptions) => InkronikBrowserClient;
|