@prism-analytics/browser 0.0.1

package/README.md

@@ -0,0 +1,40 @@
+# @prism-analytics/browser
+
+Browser SDK for [Prism](https://prism-analytics.vercel.app) — page views, custom events, error tracking, and privacy-first collection. Built on `@prism-analytics/core`.
+
+[![npm](https://img.shields.io/npm/v/@prism-analytics/browser)](https://www.npmjs.com/package/@prism-analytics/browser)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+## Install
+
+```sh
+npm install @prism-analytics/browser
+# yarn add @prism-analytics/browser
+# pnpm add @prism-analytics/browser
+```
+
+## Quick start
+
+```ts
+import { createBrowserClient } from "@prism-analytics/browser";
+
+export const prism = await createBrowserClient({
+  sourceKey: "psk_…", // from Prism dashboard -> Sources -> Web
+  endpoint: "https://prism-api.orekud.workers.dev",
+  collection: { initialState: "granted" }, // or "denied" for consent gate
+  pageViews: { mode: "history" }, // or "manual" with usePrismPageView
+});
+
+prism.track("checkout_started", { value: 42 });
+```
+
+## Docs
+
+- [Quickstart](https://prism-analytics.vercel.app/docs/start/javascript-sdk)
+- [Capturing events](https://prism-analytics.vercel.app/docs/features/capturing-events)
+- [Page analytics](https://prism-analytics.vercel.app/docs/features/page-analytics)
+- [Error tracking](https://prism-analytics.vercel.app/docs/features/error-tracking)
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,170 @@
+import { CaptureResult, ErrorCaptureResult, PrismErrorReporter, ErrorReportInput, PrismDiagnostic, PrismDiagnosticHandle, ErrorReporterShare, ErrorBeforeSend, ErrorReporterOptions, CollectionState, AnonymousPersistence, PrismQueueOptions, SanitizeOptions, BrowserPageViewOptions, PrismClient } from '@prism-analytics/core';
+export { BrowserPageViewOptions, ErrorBeforeSend, ErrorReporterShare, framesFromStack } from '@prism-analytics/core';
+
+/**
+ * Sanitized page identity for explicit tracking (§11): the PATH ONLY —
+ * query strings and hashes are excluded — and the referrer ORIGIN only
+ * (never a full URL with query parameters). Returned as plain data so
+ * callers decide where to attach it; automatic route tracking is a later
+ * task.
+ */
+declare function capturePageContext(): {
+    path: string;
+    referrer: string | null;
+};
+
+interface BrowserPageViewController {
+    readonly mode: "history" | "manual";
+    /** Manual-mode capture; history mode rejects manual calls. Synchronous,
+     * track()-style result semantics. */
+    capture(input?: {
+        path?: string;
+        title?: string;
+    }): CaptureResult;
+    /** Test/diagnostic surface: forces a fresh Web session on next capture. */
+    resetForTests(): void;
+}
+
+/**
+ * Browser error adapter (task-15 slice 3b) — `createBrowserErrorReporter`.
+ *
+ * Translates browser failure primitives (Error, ErrorEvent,
+ * PromiseRejectionEvent, strings, arbitrary rejection reasons) into the
+ * core's `ErrorReportInput` shape and drives the runtime-neutral
+ * `createPrismErrorReporter` lane from `@prism-analytics/core`.
+ *
+ * Global error handlers are OPT-IN (never installed by the factory
+ * unless `captureGlobalErrors` is set), idempotently installable/
+ * uninstallable, and always `handled: false`. A bounded dedupe window
+ * coalesces same-fingerprint bursts. "Script error." (the opaque
+ * cross-origin message) is captured HONESTLY — its own fingerprintable
+ * type, no fabricated frames — so it groups separately instead of being
+ * thrown away or faked.
+ *
+ * Like its analytics sibling, this package only translates browser
+ * primitives; the core owns queueing, batching, retries, consent, and
+ * sanitization, and unload flushes are the runtime's authenticated
+ * keepalive.
+ */
+/** Result of `captureException` — core's plus a coarsened `deduped` state. */
+type BrowserCaptureResult = ErrorCaptureResult | {
+    readonly status: "deduped";
+    readonly id: string;
+};
+interface ErrorCaptureOptions {
+    /** Default `false` for global-handler captures; direct calls default `true`. */
+    handled?: boolean;
+    level?: ErrorReportInput["level"];
+    release?: string;
+    environment?: string;
+    context?: ErrorReportInput["context"];
+    breadcrumbs?: ErrorReportInput["breadcrumbs"];
+}
+interface BrowserErrorReporterOptions {
+    /** Project source key (ingestion auth; server derives project/source). */
+    sourceKey: string;
+    /** Ingestion origin chosen at runtime — REQUIRED, never compiled in. */
+    endpoint: string;
+    /** Safe identity/consent sharing source (wire the analytics client's). */
+    share: ErrorReporterShare;
+    /** Optional dev-side boundary (immutable in; drop/redact/throw-safe). */
+    beforeSend?: ErrorBeforeSend;
+    /** Queue/delivery tuning passthrough to the core reporter. */
+    queue?: ErrorReporterOptions["queue"];
+    /** Optional release + environment stamped on every report. */
+    release?: string;
+    environment?: string;
+    /** Opt-in: install window onerror + unhandledrejection handlers. */
+    captureGlobalErrors?: boolean;
+    /** Coalescing window in ms for same-fingerprint bursts. Default 1000. */
+    dedupeMs?: number;
+    /** Diagnostic subscription made BEFORE the reporter starts. */
+    onDiagnostic?: (diagnostic: PrismDiagnostic) => void;
+}
+interface BrowserErrorReporter {
+    /** The underlying runtime-neutral reporter (flush/shutdown/diagnostics). */
+    readonly reporter: PrismErrorReporter;
+    readonly installed: boolean;
+    /** Number of queued, undelivered error reports. */
+    readonly pendingCount: number;
+    /**
+     * Normalize ANY thrown/collected value into an error report and enqueue
+     * it. Invalid callers passing a malformed ErrorReportInput still THROW
+     * (same contract as core). Consent/shutdown/queue-capacity return
+     * `dropped`; a same-fingerprint duplicate within the dedupe window
+     * returns `deduped`.
+     */
+    captureException(value: unknown, options?: ErrorCaptureOptions): BrowserCaptureResult;
+    /** Idempotent: install window error handlers (no-op when installed). */
+    install(): void;
+    /** Idempotent: remove window error handlers (no-op when not installed). */
+    uninstall(): void;
+    /** Attempt delivery of all queued batches. */
+    flush(): Promise<void>;
+    /** Idempotent shutdown: stop handlers, timers, bounded final flush. */
+    shutdown(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Subscribe to diagnostics; returns an idempotent remove handle. */
+    onDiagnostic(listener: (d: PrismDiagnostic) => void): PrismDiagnosticHandle;
+}
+/**
+ * Normalize ANY collected value into an ErrorReportInput: Error instances
+ * (frames from stack), ErrorEvent, PromiseRejectionEvent, strings, plain
+ * objects that already match the report shape (passthrough), and opaque
+ * rejection reasons (summarized, never thrown).
+ */
+declare function normalizeErrorValue(value: unknown): ErrorReportInput;
+declare function createBrowserErrorReporter(options: BrowserErrorReporterOptions): Promise<BrowserErrorReporter>;
+
+interface BrowserClientOptions {
+    /** Source ingestion key (publishable, write-only). */
+    sourceKey: string;
+    /**
+     * Ingestion origin chosen at runtime (hosted or self-hosted) — REQUIRED,
+     * never compiled into the package (task-9 §11).
+     */
+    endpoint: string;
+    /** Privacy/collection configuration (explicit consent, like the core). */
+    collection: {
+        initialState: CollectionState;
+        anonymousPersistence?: AnonymousPersistence;
+    };
+    queue?: PrismQueueOptions;
+    sanitize?: SanitizeOptions;
+    /**
+     * Task 17: explicit Web page-view tracking. Omitted (or undefined) means
+     * the client captures NO page views and exposes `pageViews: null`.
+     */
+    pageViews?: BrowserPageViewOptions;
+}
+/**
+ * The Browser client surface: everything PrismClient promises plus a
+ * stable page controller when (and only when) pageViews is configured.
+ */
+type BrowserPrismClient = PrismClient & {
+    readonly pageViews: {
+        readonly mode: "history" | "manual";
+        capture(input?: {
+            path?: string;
+            title?: string;
+        }): CaptureResult;
+    } | null;
+};
+/**
+ * Create the minimal browser client (task-9 §11): a thin runtime adapter
+ * over the @prism-analytics/core engine. The core owns ALL queueing, consent,
+ * sanitization, session, authentication, and retry semantics — this
+ * package only translates browser primitives (fetch transport, local
+ * storage, timers, lifecycle events) into the runtime seam.
+ *
+ * - Fails loudly outside a browser (no half-working Node import).
+ * - Requires an explicit runtime `endpoint`.
+ * - Storage denial (privacy modes) degrades to the core's in-memory
+ *   queue — never a crash.
+ * - Unload flushes use an AUTHENTICATED fetch keepalive — never an
+ *   unauthenticated sendBeacon fallback.
+ */
+declare function createBrowserClient(options: BrowserClientOptions): Promise<BrowserPrismClient>;
+
+export { type BrowserCaptureResult, type BrowserClientOptions, type BrowserErrorReporter, type BrowserErrorReporterOptions, type BrowserPageViewController, type BrowserPrismClient, type ErrorCaptureOptions, capturePageContext, createBrowserClient, createBrowserErrorReporter, normalizeErrorValue };

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { CaptureResult, ErrorCaptureResult, PrismErrorReporter, ErrorReportInput, PrismDiagnostic, PrismDiagnosticHandle, ErrorReporterShare, ErrorBeforeSend, ErrorReporterOptions, CollectionState, AnonymousPersistence, PrismQueueOptions, SanitizeOptions, BrowserPageViewOptions, PrismClient } from '@prism-analytics/core';
+export { BrowserPageViewOptions, ErrorBeforeSend, ErrorReporterShare, framesFromStack } from '@prism-analytics/core';
+
+/**
+ * Sanitized page identity for explicit tracking (§11): the PATH ONLY —
+ * query strings and hashes are excluded — and the referrer ORIGIN only
+ * (never a full URL with query parameters). Returned as plain data so
+ * callers decide where to attach it; automatic route tracking is a later
+ * task.
+ */
+declare function capturePageContext(): {
+    path: string;
+    referrer: string | null;
+};
+
+interface BrowserPageViewController {
+    readonly mode: "history" | "manual";
+    /** Manual-mode capture; history mode rejects manual calls. Synchronous,
+     * track()-style result semantics. */
+    capture(input?: {
+        path?: string;
+        title?: string;
+    }): CaptureResult;
+    /** Test/diagnostic surface: forces a fresh Web session on next capture. */
+    resetForTests(): void;
+}
+
+/**
+ * Browser error adapter (task-15 slice 3b) — `createBrowserErrorReporter`.
+ *
+ * Translates browser failure primitives (Error, ErrorEvent,
+ * PromiseRejectionEvent, strings, arbitrary rejection reasons) into the
+ * core's `ErrorReportInput` shape and drives the runtime-neutral
+ * `createPrismErrorReporter` lane from `@prism-analytics/core`.
+ *
+ * Global error handlers are OPT-IN (never installed by the factory
+ * unless `captureGlobalErrors` is set), idempotently installable/
+ * uninstallable, and always `handled: false`. A bounded dedupe window
+ * coalesces same-fingerprint bursts. "Script error." (the opaque
+ * cross-origin message) is captured HONESTLY — its own fingerprintable
+ * type, no fabricated frames — so it groups separately instead of being
+ * thrown away or faked.
+ *
+ * Like its analytics sibling, this package only translates browser
+ * primitives; the core owns queueing, batching, retries, consent, and
+ * sanitization, and unload flushes are the runtime's authenticated
+ * keepalive.
+ */
+/** Result of `captureException` — core's plus a coarsened `deduped` state. */
+type BrowserCaptureResult = ErrorCaptureResult | {
+    readonly status: "deduped";
+    readonly id: string;
+};
+interface ErrorCaptureOptions {
+    /** Default `false` for global-handler captures; direct calls default `true`. */
+    handled?: boolean;
+    level?: ErrorReportInput["level"];
+    release?: string;
+    environment?: string;
+    context?: ErrorReportInput["context"];
+    breadcrumbs?: ErrorReportInput["breadcrumbs"];
+}
+interface BrowserErrorReporterOptions {
+    /** Project source key (ingestion auth; server derives project/source). */
+    sourceKey: string;
+    /** Ingestion origin chosen at runtime — REQUIRED, never compiled in. */
+    endpoint: string;
+    /** Safe identity/consent sharing source (wire the analytics client's). */
+    share: ErrorReporterShare;
+    /** Optional dev-side boundary (immutable in; drop/redact/throw-safe). */
+    beforeSend?: ErrorBeforeSend;
+    /** Queue/delivery tuning passthrough to the core reporter. */
+    queue?: ErrorReporterOptions["queue"];
+    /** Optional release + environment stamped on every report. */
+    release?: string;
+    environment?: string;
+    /** Opt-in: install window onerror + unhandledrejection handlers. */
+    captureGlobalErrors?: boolean;
+    /** Coalescing window in ms for same-fingerprint bursts. Default 1000. */
+    dedupeMs?: number;
+    /** Diagnostic subscription made BEFORE the reporter starts. */
+    onDiagnostic?: (diagnostic: PrismDiagnostic) => void;
+}
+interface BrowserErrorReporter {
+    /** The underlying runtime-neutral reporter (flush/shutdown/diagnostics). */
+    readonly reporter: PrismErrorReporter;
+    readonly installed: boolean;
+    /** Number of queued, undelivered error reports. */
+    readonly pendingCount: number;
+    /**
+     * Normalize ANY thrown/collected value into an error report and enqueue
+     * it. Invalid callers passing a malformed ErrorReportInput still THROW
+     * (same contract as core). Consent/shutdown/queue-capacity return
+     * `dropped`; a same-fingerprint duplicate within the dedupe window
+     * returns `deduped`.
+     */
+    captureException(value: unknown, options?: ErrorCaptureOptions): BrowserCaptureResult;
+    /** Idempotent: install window error handlers (no-op when installed). */
+    install(): void;
+    /** Idempotent: remove window error handlers (no-op when not installed). */
+    uninstall(): void;
+    /** Attempt delivery of all queued batches. */
+    flush(): Promise<void>;
+    /** Idempotent shutdown: stop handlers, timers, bounded final flush. */
+    shutdown(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** Subscribe to diagnostics; returns an idempotent remove handle. */
+    onDiagnostic(listener: (d: PrismDiagnostic) => void): PrismDiagnosticHandle;
+}
+/**
+ * Normalize ANY collected value into an ErrorReportInput: Error instances
+ * (frames from stack), ErrorEvent, PromiseRejectionEvent, strings, plain
+ * objects that already match the report shape (passthrough), and opaque
+ * rejection reasons (summarized, never thrown).
+ */
+declare function normalizeErrorValue(value: unknown): ErrorReportInput;
+declare function createBrowserErrorReporter(options: BrowserErrorReporterOptions): Promise<BrowserErrorReporter>;
+
+interface BrowserClientOptions {
+    /** Source ingestion key (publishable, write-only). */
+    sourceKey: string;
+    /**
+     * Ingestion origin chosen at runtime (hosted or self-hosted) — REQUIRED,
+     * never compiled into the package (task-9 §11).
+     */
+    endpoint: string;
+    /** Privacy/collection configuration (explicit consent, like the core). */
+    collection: {
+        initialState: CollectionState;
+        anonymousPersistence?: AnonymousPersistence;
+    };
+    queue?: PrismQueueOptions;
+    sanitize?: SanitizeOptions;
+    /**
+     * Task 17: explicit Web page-view tracking. Omitted (or undefined) means
+     * the client captures NO page views and exposes `pageViews: null`.
+     */
+    pageViews?: BrowserPageViewOptions;
+}
+/**
+ * The Browser client surface: everything PrismClient promises plus a
+ * stable page controller when (and only when) pageViews is configured.
+ */
+type BrowserPrismClient = PrismClient & {
+    readonly pageViews: {
+        readonly mode: "history" | "manual";
+        capture(input?: {
+            path?: string;
+            title?: string;
+        }): CaptureResult;
+    } | null;
+};
+/**
+ * Create the minimal browser client (task-9 §11): a thin runtime adapter
+ * over the @prism-analytics/core engine. The core owns ALL queueing, consent,
+ * sanitization, session, authentication, and retry semantics — this
+ * package only translates browser primitives (fetch transport, local
+ * storage, timers, lifecycle events) into the runtime seam.
+ *
+ * - Fails loudly outside a browser (no half-working Node import).
+ * - Requires an explicit runtime `endpoint`.
+ * - Storage denial (privacy modes) degrades to the core's in-memory
+ *   queue — never a crash.
+ * - Unload flushes use an AUTHENTICATED fetch keepalive — never an
+ *   unauthenticated sendBeacon fallback.
+ */
+declare function createBrowserClient(options: BrowserClientOptions): Promise<BrowserPrismClient>;
+
+export { type BrowserCaptureResult, type BrowserClientOptions, type BrowserErrorReporter, type BrowserErrorReporterOptions, type BrowserPageViewController, type BrowserPrismClient, type ErrorCaptureOptions, capturePageContext, createBrowserClient, createBrowserErrorReporter, normalizeErrorValue };