@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 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).
@@ -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;
@@ -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;