@flashlog/tracker-sdk 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# @flashlog/tracker-sdk
+
+The official browser-side SDK for **Flashlog** — a powerful bug tracking, real-time error reporting, and session replay platform.
+
+Easily capture JavaScript exceptions, network failures, and WebSocket errors, while correlating frontend errors to backend logs with trace propagation. Include session replay recordings for debugging user journeys with high-fidelity visual playback.
+
+---
+
+## Key Features
+
+*   **Error Monitoring**: Automatically captures unhandled runtime errors, promise rejections, and console errors.
+*   **Network & Socket Tracking**: Records HTTP (fetch/XHR) failures, response statuses, and WebSocket connection errors/abnormal closures.
+*   **Session Replay (rrweb)**: Records high-fidelity user sessions with custom flushing, masking, and chunking options.
+*   **Trace Propagation**: Correlates frontend network requests with backend logs by injecting trace headers (e.g., `traceparent`, `x-flashlog-trace-id`).
+*   **Privacy-First Sanitization**: Automatically redacts sensitive fields like passwords, tokens, API keys, and cookies from request/response payloads and replays.
+
+---
+
+## Installation
+
+Install the tracker package in your application:
+
+```bash
+npm install @flashlog/tracker-sdk
+# or
+yarn add @flashlog/tracker-sdk
+```
+
+Initialize the tracker in your application bootstrap code (e.g., `index.js` or `main.ts`):
+
+```typescript
+import tracker from '@flashlog/tracker-sdk';
+
+tracker.init('YOUR_PRODUCT_OR_BRAND_ID', {
+  apiKey: 'YOUR_PUBLIC_API_KEY',
+  apiUrl: 'https://api.flashlog.app/api', // optional override
+  enableSessionReplay: true,
+});
+```
+
+---
+
+## Configuration Options
+
+When calling `tracker.init(brandId, config)`, you can customize behavior using the following options:
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `apiKey` | `string` | `""` | **Required.** Your Flashlog public API key. |
+| `apiUrl` | `string` | `"https://api.flashlog.app/api"` | Base API endpoint for reporting. (Overridden by `VITE_FLASHLOG_API_URL` at build time if set). |
+| `debug` | `boolean` | `false` | Enables verbose logging to the browser console. |
+| `autoCapture` | `boolean` | `true` | Automatically configures standard global handlers for errors and rejections. |
+| `captureJsErrors` | `boolean` | `true` | Captures unhandled runtime exceptions and promise rejections. |
+| `captureNetworkErrors` | `boolean` | `true` | Captures failed Fetch/XHR requests (status codes $\ge 400$, network dropouts). |
+| `captureSocketErrors` | `boolean` | `true` | Captures abnormal close events and connection errors on `WebSocket` connections. |
+| `captureRequestBody` | `boolean` | `true` | Includes HTTP request bodies in reported network logs (redacted for privacy). |
+| `captureResponseBody` | `boolean` | `true` | Includes HTTP response bodies in reported network logs (redacted for privacy). |
+| `redactKeys` | `string[]` | *See defaults below* | Payload object keys to redact (replace with `[REDACTED]`). |
+| `redactUrlParams` | `string[]` | *See defaults below* | Query parameters in URLs to redact (replace with `[REDACTED]`). |
+| `propagateTraceHeaders` | `boolean` | `false` | Generates trace contexts and injects tracking headers into fetch/XHR requests. |
+| `traceOrigins` | `string[]` | `[]` | List of allowed backend origin URL prefixes for trace header propagation. |
+| `traceHeaderName` | `string` | `"x-flashlog-trace-id"` | Header name used for custom trace correlation. |
+| `enableSessionReplay` | `boolean` | `true` | Enables rrweb-based video playback of user sessions. |
+| `replayFlushIntervalMs`| `number` | `10000` (10s) | The time frequency in milliseconds at which recording events are flushed to storage. |
+| `replayMaxSegmentBytes`| `number` | `524288` (512KB) | Maximum payload size in bytes before splitting replay segments. |
+| `replayMaxSegmentEvents`| `number` | `400` | Maximum recording events count before splitting replay segments. |
+| `replayMaskAllInputs` | `boolean` | `true` | Mask all text inputs/forms during session recording for user privacy. |
+| `ignoredStatusCodes` | `number[]` | `[401, 403]` | HTTP response status codes that should not trigger network errors. |
+| `ignoredUrls` | `string[]` | *Third-party list* | URL strings or regex patterns to ignore from error tracking (e.g. analytics). |
+
+---
+
+## Detailed Usage Guides
+
+### Distributing Tracing (Frontend $\rightarrow$ Backend Correlation)
+
+To correlate frontend issues with backend execution logs:
+1. Set `propagateTraceHeaders: true` in your config.
+2. Specify your backend endpoints in `traceOrigins` (headers are blocked on external domains for security).
+3. The SDK will inject `traceparent` (W3C standard) and `x-flashlog-trace-id` (custom) headers.
+
+```javascript
+tracker.init('YOUR_PRODUCT_ID', {
+  apiKey: 'YOUR_PUBLIC_API_KEY',
+  propagateTraceHeaders: true,
+  traceOrigins: ['https://api.myapp.com', 'https://staging.api.myapp.com'],
+  traceHeaderName: 'x-custom-trace-id' // Optional custom header override
+});
+```
+
+To fetch active trace headers for manual injection (e.g. within customized Apollo, Axios, or GraphQL clients):
+
+```javascript
+const headers = window.FlashlogBugTracker.getTraceHeaders();
+// Returns: { "traceparent": "...", "x-flashlog-trace-id": "..." }
+```
+
+### Identity Across Devices
+
+You can tie browser sessions, device metadata, and recorded bugs to authenticated users:
+
+```javascript
+// Call after login
+window.FlashlogBugTracker.identify("user_db_id_987", {
+  email: "user@domain.com",
+  plan: "enterprise",
+  name: "John Doe"
+});
+
+// Call after logout to clear
+window.FlashlogBugTracker.clearIdentity();
+```
+
+---
+
+## Privacy & Redaction
+
+The SDK automatically sanitizes request payloads, response bodies, and URLs to ensure PII (Personally Identifiable Information) and credentials never leave the client's browser.
+
+### Redacted Keys by Default:
+*   Credentials: `password`, `passwd`, `authorization`, `credentials`, `cookie`, `session`, `sessionToken`, `sessionCookie`, `sessionSecret`
+*   Security: `token`, `jwt`, `csrf`, `passcode`, `otp`, `apiKey`, `accessToken`, `refreshToken`, `clientSecret`, `privateKey`, `authCode`, `verificationCode`
+
+To add custom keys for redaction:
+
+```javascript
+tracker.init('YOUR_PRODUCT_ID', {
+  apiKey: 'YOUR_PUBLIC_API_KEY',
+  redactKeys: ['ssn', 'creditCardNumber', 'internalAccountNumber'],
+  redactUrlParams: ['token', 'inviteCode']
+});
+```
+
+---
+
+## API Reference
+
+The SDK exports the tracker instance as both the `default` export and a named export `flashlogTracker`.
+
+```typescript
+import flashlogTracker, { flashlogTracker as namedTracker } from '@flashlog/tracker-sdk';
+```
+
+When loaded in the browser, the instance is also attached to `window.FlashlogBugTracker` and `window.Tracker` (if the global name is not already occupied).
+
+### Public Methods
+
+*   **`init(brandId: string | number, config?: Partial<TrackerConfig>): Promise<void>`**  
+    Initializes the tracking agent with your brand/product ID and optional configuration overrides.
+*   **`track(eventName: string, data?: Record<string, unknown>): Promise<boolean>`**  
+    Dispatches a custom event payload to the collector backend.
+*   **`reportError(error: Error | string, context?: Record<string, unknown>): Promise<boolean>`**  
+    Manually reports a handled exception/error with optional context metadata.
+*   **`addUserAction(action: string, details?: Record<string, unknown>): void`**  
+    Adds a custom user action (breadcrumb) to the current session action buffer.
+*   **`identify(accountId: string, traits?: Record<string, unknown>): void`**  
+    Associates the current session and subsequent reports with a specific user account.
+*   **`clearIdentity(): void`**  
+    Dissociates the user identity from the tracking session.
+*   **`getTraceHeaders(): Record<string, string>`**  
+    Generates and returns the active tracing headers (`traceparent` and `x-flashlog-trace-id`) for the current transaction.
+*   **`getSessionId(): string | null`**  
+    Retrieves the active browser session ID.
+*   **`getDeviceId(): string | null`**  
+    Retrieves the persistent device identifier.
+*   **`flushReplay(reason?: string): Promise<ReplayFlushResult | null>`**  
+    Manually flushes the current recording event queue to the backend.
+*   **`finalizeReplay(reason?: string): Promise<ReplayFinalizeResult | null>`**  
+    Manually finalizes the session recording and prepares it for replay playback.
+*   **`reset(): void`**  
+    Resets the tracker instance, cleans local storage states, and removes global error/rejection handlers.
+
+---
+
+## License
+
+MIT © [Eastplayers](https://github.com/Eastplayers)

package/dist/action-buffer.d.ts

@@ -0,0 +1,12 @@
+import { UserAction } from "./types";
+export declare class ActionBuffer {
+    private readonly maxSize;
+    private actions;
+    private detachHandlers;
+    constructor(maxSize: number);
+    start(): void;
+    stop(): void;
+    add(action: string, details?: Record<string, unknown>): void;
+    getAll(): UserAction[];
+    clear(): void;
+}

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+import { TrackerConfig } from "./types";
+export declare const ERROR_EVENT_NAMES: Set<string>;
+export declare const DEFAULT_REDACT_KEYS: string[];
+export declare const DEFAULT_REDACT_URL_PARAMS: string[];
+export declare const DEFAULT_CONFIG: TrackerConfig;
+export declare const STORAGE_KEYS: {
+    sessionId: string;
+    sessionSeenAt: string;
+    deviceId: string;
+    accountId: string;
+    accountTraits: string;
+};

package/dist/device.d.ts

@@ -0,0 +1,3 @@
+import { DeviceInfo, NetworkStatus } from "./types";
+export declare const getDeviceInfo: (deviceId: string) => DeviceInfo;
+export declare const getNetworkStatus: () => NetworkStatus;

package/dist/error-capture.d.ts

@@ -0,0 +1,33 @@
+import { TrackerConfig } from "./types";
+export interface ErrorCaptureHooks {
+    onNetworkActivity(data: Record<string, unknown>): void;
+    onNetworkError(data: Record<string, unknown>): void;
+    onSocketError(data: Record<string, unknown>): void;
+    onJsError(data: Record<string, unknown>): void;
+    onUnhandledRejection(data: Record<string, unknown>): void;
+    debug: boolean;
+}
+export declare class ErrorCapture {
+    private readonly config;
+    private readonly hooks;
+    private originalFetch?;
+    private originalXhrOpen?;
+    private originalXhrSend?;
+    private originalWebSocket?;
+    private readonly socketMeta;
+    private initialized;
+    constructor(config: TrackerConfig, hooks: ErrorCaptureHooks);
+    start(): void;
+    stop(): void;
+    private shouldIgnoreUrl;
+    private shouldIgnoreStatus;
+    private truncate;
+    private getBodyType;
+    private safeBodyPreview;
+    private attachTraceHeadersToFetchRequest;
+    private interceptFetch;
+    private interceptXhr;
+    private interceptWebSocket;
+    private handleWindowError;
+    private handleUnhandledRejection;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { DEFAULT_CONFIG } from "./constants";
+import { TrackerPublicApi } from "./types";
+declare global {
+    interface Window {
+        FlashlogBugTracker?: TrackerPublicApi;
+        Tracker?: TrackerPublicApi;
+    }
+}
+declare const tracker: TrackerPublicApi;
+export declare const flashlogTracker: TrackerPublicApi;
+export { DEFAULT_CONFIG };
+export { createTracker, FlashlogTrackerLite } from "./tracker";
+export type { DeviceInfo, NetworkStatus, ReplayFinalizeResult, ReplayFlushResult, TrackerConfig, TrackerPayload, TrackerPublicApi, TrackerTraceContext, UserAction, } from "./types";
+export default tracker;

package/dist/installation-ping.d.ts

@@ -0,0 +1,10 @@
+interface InstallationPingPayload {
+    apiKey: string;
+    apiUrl?: string;
+    brandId: number | string;
+    debug: boolean;
+    source?: "package" | "script";
+    scriptUrl?: string;
+}
+export declare const pingTrackerInstallation: (payload: InstallationPingPayload) => Promise<void>;
+export {};

package/dist/privacy.d.ts

@@ -0,0 +1,6 @@
+import { TrackerConfig, TrackerPayload } from "./types";
+export declare const REDACTED_VALUE = "[redacted]";
+export declare const normalizeKeySegments: (key: string) => string[];
+export declare const matchesConfiguredKey: (key: string, configuredKeys: string[]) => boolean;
+export declare const redactSecretLikeText: (value: string) => string;
+export declare const sanitizePayload: (payload: TrackerPayload, config: TrackerConfig) => TrackerPayload;

package/dist/replay-recorder.d.ts

@@ -0,0 +1,64 @@
+export interface ReplayRecorderConfig {
+    apiKey: string;
+    apiUrl: string;
+    brandId: number;
+    debug: boolean;
+    deviceId: string | null;
+    maskAllInputs: boolean;
+    maxSegmentBytes: number;
+    maxSegmentEvents: number;
+    flushIntervalMs: number;
+    sessionId: string;
+}
+export interface ReplayFlushResult {
+    content_type: string;
+    object_key: string;
+    replay_session_id: string | null;
+    segment_id: string;
+    sequence_number: number;
+    session_id: string;
+    size_bytes: number;
+    storage_driver: string;
+}
+export interface ReplayFinalizeResult {
+    finalized_at: string;
+    id: string;
+    segment_count: number;
+    session_id: string;
+    status: string;
+    total_size_bytes: number;
+}
+export declare class ReplayRecorder {
+    private config;
+    private currentBytes;
+    private currentEvents;
+    private detachListeners;
+    private finalized;
+    private flushInFlight;
+    private flushTimer;
+    private replaySessionId;
+    private segmentSequence;
+    private stopRecording;
+    start(config: ReplayRecorderConfig): Promise<void>;
+    flush(reason?: string, options?: {
+        keepalive?: boolean;
+    }): Promise<ReplayFlushResult | null>;
+    finalize(reason?: string, options?: {
+        keepalive?: boolean;
+    }): Promise<ReplayFinalizeResult | null>;
+    dispose(options?: {
+        finalize?: boolean;
+        keepalive?: boolean;
+        reason?: string;
+    }): Promise<void>;
+    addCustomEvent<T>(tag: string, payload: T): void;
+    private bindLifecycleListeners;
+    private debug;
+    private pushEvent;
+    private estimateEventSize;
+    private nextSegmentId;
+    private restorePendingSegment;
+    private stopCapture;
+    private takePendingSegment;
+    private uploadSegment;
+}

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+export declare const getOrCreateDeviceId: () => string;
+export declare const getOrCreateSessionId: (sessionTimeoutMs: number) => string;
+export declare const touchSession: () => void;
+export declare const getSessionId: () => string | null;
+export declare const getDeviceId: () => string | null;
+export declare const setAccountIdentity: (accountId: string, traits?: Record<string, unknown>) => void;
+export declare const getAccountId: () => string | null;
+export declare const getAccountTraits: () => Record<string, unknown> | null;
+export declare const clearAccountIdentity: () => void;
+export declare const clearTrackerStorage: () => void;

package/dist/trace.d.ts

@@ -0,0 +1,5 @@
+import { TrackerConfig, TrackerTraceContext } from "./types";
+export declare const createTraceContext: () => TrackerTraceContext;
+export declare const resolveTraceContext: (data?: Record<string, unknown>) => TrackerTraceContext;
+export declare const buildTraceHeaders: (traceContext: TrackerTraceContext, traceHeaderName: string) => Record<string, string>;
+export declare const shouldPropagateTraceHeaders: (url: string, config: Pick<TrackerConfig, "propagateTraceHeaders" | "traceOrigins">) => boolean;

package/dist/tracker.d.ts

@@ -0,0 +1,45 @@
+import { ReplayFinalizeResult, ReplayFlushResult, TrackerConfig, TrackerPublicApi } from "./types";
+export declare class FlashlogTrackerLite implements TrackerPublicApi {
+    private config;
+    private brandId;
+    private sessionId;
+    private deviceId;
+    private accountId;
+    private accountTraits;
+    private readonly actionBuffer;
+    private errorCapture;
+    private readonly replayRecorder;
+    private initialized;
+    private performanceObservers;
+    private performanceSampleTimer;
+    private pendingLongTaskMs;
+    private resourceObserver;
+    private readonly replayResourceKeys;
+    private nextPerformanceSampleAt;
+    constructor();
+    init(brandId: string | number, config?: Partial<TrackerConfig>): Promise<void>;
+    track(eventName: string, data?: Record<string, unknown>): Promise<boolean>;
+    reportError(error: Error | string, context?: Record<string, unknown>): Promise<boolean>;
+    addUserAction(action: string, details?: Record<string, unknown>): void;
+    identify(accountId: string, traits?: Record<string, unknown>): void;
+    clearIdentity(): void;
+    getTraceHeaders(): Record<string, string>;
+    getSessionId(): string | null;
+    getDeviceId(): string | null;
+    flushReplay(reason?: string): Promise<ReplayFlushResult | null>;
+    finalizeReplay(reason?: string): Promise<ReplayFinalizeResult | null>;
+    reset(): void;
+    private buildPayload;
+    private trackInternal;
+    private recordReplaySessionContext;
+    private stopReplayResourceCapture;
+    private stopReplayPerformanceCapture;
+    private startReplayResourceCapture;
+    private startReplayPerformanceCapture;
+    private scheduleReplayPerformanceSample;
+    private captureReplayPerformanceSample;
+    private observeReplayLongTasks;
+    private observeReplayLayoutShifts;
+    private captureReplayResourceEntries;
+}
+export declare const createTracker: () => TrackerPublicApi;