@lib-acr/browser 0.0.0-stage → 0.0.1

package/dist/types/control/ui.d.ts

@@ -0,0 +1,50 @@
+import type { ControlState } from '@lib-acr/core';
+/** Which built-in screens the SDK renders. Turn one off to render your own from the control state. */
+export interface ControlUiOptions {
+    /** Full-page maintenance screen. Default true. */
+    maintenance?: boolean;
+    /** Announcement banner at the top of the page. Default true. */
+    announcement?: boolean;
+    /** "New version available" prompt (release checks and `reload` commands in prompt mode). Default true. */
+    release?: boolean;
+}
+export type ResolvedUiOptions = Required<ControlUiOptions>;
+export declare function resolveUiOptions(ui: boolean | ControlUiOptions | undefined): ResolvedUiOptions;
+export interface ControlUiActions {
+    dismissAnnouncement(id: string): void;
+    reload(): void;
+    refresh(): void;
+}
+/** Tag of the element that hosts the shadow root. */
+export declare const UI_HOST_TAG = "acr-ui";
+/**
+ * The default remote-control UI: maintenance screen, announcement banner and "new version available" prompt. It lives
+ * in the shadow root of one `<acr-ui>` element, so the page's CSS cannot reach it and its CSS cannot leak out. Server
+ * text is always inserted as text, never as HTML. The element is added only while something is shown.
+ */
+export declare class ControlUI {
+    private readonly options;
+    private readonly actions;
+    private host;
+    private wrap;
+    private readonly keys;
+    private readonly elements;
+    private dismissedToast;
+    private lastState;
+    private restoreFocus;
+    private savedOverflow;
+    private waitingForBody;
+    constructor(options: ResolvedUiOptions, actions: ControlUiActions);
+    render(state: ControlState): void;
+    /** Removes the element and everything it shows. */
+    destroy(): void;
+    private mount;
+    private unmount;
+    /** Replaces a section only when its content changes, so focus and animations are not disturbed. */
+    private update;
+    private buildMaintenance;
+    private onMaintenanceShown;
+    private onMaintenanceHidden;
+    private buildBanner;
+    private buildToast;
+}

package/dist/types/device.d.ts

@@ -0,0 +1,24 @@
+export interface DeviceInfo {
+    browser: string;
+    os: string;
+    deviceType: 'desktop' | 'mobile' | 'tablet' | 'unknown';
+    language: string | null;
+    timezone: string | null;
+    screen: string | null;
+    viewport: string | null;
+}
+/** Coarse browser, OS and device class from a user agent string. No version numbers are kept for the OS. */
+export declare function parseUserAgent(ua: string): Pick<DeviceInfo, 'browser' | 'os' | 'deviceType'>;
+/** Device and locale facts for session_start. Reads only what the browser exposes without a permission prompt. */
+export declare function getDeviceInfo(env?: {
+    userAgent?: string;
+    language?: string;
+    screen?: {
+        width: number;
+        height: number;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}): DeviceInfo;

package/dist/types/fetch-tracker.d.ts

@@ -0,0 +1,15 @@
+import type { AcrClient } from '@lib-acr/core';
+export interface FetchTrackerOptions {
+    /** Requests whose URL starts with one of these prefixes are not recorded (for example the ACR endpoint). */
+    ignoreUrlPrefixes: string[];
+    base: string;
+}
+type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Wraps fetch to record duration and outcome per request. Request and response bodies and headers are never read.
+ * URLs are reduced to origin and a normalized path. Network failures are also reported as frontend errors, and then
+ * rethrown so the application behaves as before. A rethrown failure is marked as captured, so it is not reported a
+ * second time as an unhandled rejection.
+ */
+export declare function wrapFetch(original: FetchFn, client: AcrClient, options: FetchTrackerOptions): FetchFn;
+export {};

package/dist/types/identity.d.ts

@@ -0,0 +1,48 @@
+/** The subset of Web Storage used here. Storage can be blocked, so every access is guarded. */
+export interface KeyValueStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
+}
+export declare const ANONYMOUS_KEY = "acr.anonymousId";
+export declare const SESSION_KEY = "acr.session";
+/** ISO time this browser first ran the SDK. Commands issued before it are skipped (nothing stale to clear). */
+export declare const FIRST_SEEN_KEY = "acr.firstSeen";
+export declare function randomId(): string;
+/** Stable id for one browser profile. Kept in localStorage when available, in memory otherwise. */
+export declare function getOrCreateAnonymousId(store: KeyValueStore | null, memory: {
+    id?: string;
+}): string;
+/**
+ * Returns `acr.firstSeen`, writing the current time when it is missing (a new visitor, or a visitor whose anonymous id
+ * predates this key). It is never changed afterwards, not even by reset(). With storage blocked the value lives in
+ * memory for this page only.
+ */
+export declare function ensureFirstSeen(store: KeyValueStore | null, memory: {
+    firstSeen?: string;
+}, now?: () => number): string;
+/** Replaces the anonymous id with a new one (for example on logout) and returns it. */
+export declare function resetAnonymousId(store: KeyValueStore | null, memory: {
+    id?: string;
+}): string;
+export interface SessionState {
+    id: string;
+    isNew: boolean;
+}
+/**
+ * Browser session: a new id after `timeoutMs` without activity, or when the tab is new. The state lives in
+ * sessionStorage, so it survives reloads of the same tab but not a new tab.
+ */
+export declare class SessionTracker {
+    private readonly store;
+    private readonly timeoutMs;
+    private readonly now;
+    private memory;
+    constructor(store: KeyValueStore | null, timeoutMs: number, now?: () => number);
+    /** Returns the current session and marks it active. */
+    touch(): SessionState;
+    /** Ends the current session and starts a new one now. */
+    reset(): SessionState;
+    private read;
+    private write;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+export { BrowserACR, BROWSER_SDK, DISMISSED_KEY, FORCE_RELOAD_KEY, QUEUE_KEY, assertPublishableOptions } from './browser-acr.js';
+export type { BrowserAcrOptions, Teardown } from './browser-acr.js';
+export { normalizePath, describeUrl } from './url.js';
+export { getDeviceInfo, parseUserAgent } from './device.js';
+export type { DeviceInfo } from './device.js';
+export { ANONYMOUS_KEY, FIRST_SEEN_KEY, SessionTracker, ensureFirstSeen, getOrCreateAnonymousId, resetAnonymousId } from './identity.js';
+export { CommandRunner, clearCaches, COMMANDS_KEY, COMMAND_APPLIED_EVENT, RELOAD_GUARD_KEY, RESERVED_PREFIX } from './control/command-runner.js';
+export type { CacheCategory, CategoryResult, CommandOutcome, CommandResult, CommandRunnerDeps } from './control/command-runner.js';
+export { ControlUI, UI_HOST_TAG, resolveUiOptions } from './control/ui.js';
+export type { ControlUiActions, ControlUiOptions, ResolvedUiOptions } from './control/ui.js';
+export type { KeyValueStore, SessionState } from './identity.js';
+export { VitalsCollector } from './web-vitals.js';
+export type { VitalsSnapshot } from './web-vitals.js';
+export { wrapFetch } from './fetch-tracker.js';
+export { markCaptured, wasCaptured } from './captured.js';
+export { AcrError, CORE_SDK, REDACTED, REDACTED_EMAIL, SCHEMA_VERSION, EMPTY_CONTROL_STATE, clearCacheParams, compareSemver, describeError, evaluateFlag, fnv1a32, formatTraceparent, generateId, generateSpanId, generateTraceId, inRollout, isSensitiveKey, parseSemver, parseSnapshot, parseTraceparent, planCommands, redactAttributes, redactString, reloadParams, rolloutBucket, sessionSampled, typedFlagValue, } from '@lib-acr/core';
+export type { AcrOptions, Announcement, AnnouncementSeverity, AnnouncementState, Attributes, AttributeValue, ClearCacheParams, ClientStats, CommandDecision, CommandSkipReason, ControlCommand, ControlListener, ControlSnapshot, ControlState, FlagDefinition, FlagOptions, FlagType, MaintenanceControl, MaintenanceState, ReleaseControl, ReleaseMode, ReleaseState, ReloadParams, SdkControl, ErrorDescription, ErrorOptions, FetchLike, FetchResponseLike, HeartbeatOptions, ItemOptions, LogLevel, QueuedItem, SdkInfo, TelemetryKind, TraceContext, } from '@lib-acr/core';

package/dist/types/sdk-info.d.ts

@@ -0,0 +1,4 @@
+export declare const SDK_INFO: {
+    readonly name: "@lib-acr/browser";
+    readonly version: "0.0.1";
+};

package/dist/types/url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Path for telemetry: no query string, no fragment, and ids replaced with :id so that /orders/42 and /orders/43 group
+ * together. Query strings often carry tokens or personal data, so they are never sent.
+ */
+export declare function normalizePath(pathname: string): string;
+/** Absolute URL to origin + normalized path, for api_request events. */
+export declare function describeUrl(input: string, base: string): {
+    host: string;
+    path: string;
+} | null;

package/dist/types/web-vitals.d.ts

@@ -0,0 +1,50 @@
+export interface VitalsSnapshot {
+    /** First Contentful Paint, ms. */
+    fcp: number | null;
+    /** Largest Contentful Paint, ms. */
+    lcp: number | null;
+    /** Cumulative Layout Shift (session windows), unitless. */
+    cls: number | null;
+    /** Time to First Byte, ms. */
+    ttfb: number | null;
+    /**
+     * Longest interaction duration seen, ms. This approximates INP: it is the maximum, not the 98th percentile
+     * that the official metric uses.
+     */
+    inpMaxMs: number | null;
+    /** Load event end, ms. */
+    pageLoadMs: number | null;
+}
+type Listener = (snapshot: VitalsSnapshot) => void;
+/**
+ * Collects Core Web Vitals with PerformanceObserver. It degrades silently where an entry type is unsupported, which is
+ * the case in older browsers and in jsdom.
+ */
+export declare class VitalsCollector {
+    private state;
+    /** Stable reference, replaced only when a value changes, so useSyncExternalStore does not loop. */
+    private current;
+    private observers;
+    private readonly listeners;
+    private clsWindow;
+    private clsMax;
+    private loadListener;
+    private loadTimer;
+    start(): void;
+    stop(): void;
+    snapshot(): VitalsSnapshot;
+    subscribe(listener: Listener): () => void;
+    private observeEntries;
+    /**
+     * `loadEventEnd` is only known once the load event has finished. When start() runs earlier (the usual case for an
+     * SDK loaded in the page head), read the navigation entry again just after `load`.
+     */
+    private watchLoad;
+    private observe;
+    /** Session windows: a window ends after 1 s of quiet or 5 s in total; CLS is the largest window. */
+    private addLayoutShift;
+    private readNavigation;
+    private update;
+    private publish;
+}
+export {};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lib-acr/browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "ACR SDK for browsers: JavaScript errors, page views, fetch timing, web vitals and sessions. Uses publishable keys only.",
+  "license": "MIT",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@lib-acr/core": "0.0.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/application-control-room/application.git",
+    "directory": "packages/browser"
+  },
+  "homepage": "https://github.com/application-control-room/application/tree/main/packages/browser#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}