@allstak/react 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import * as React from 'react';
 
 /**
- * Minimal HTTP transport for React Native. Uses the global `fetch` (always
- * present in RN >= 0.60) with a 3s timeout. Failed sends fall into a small
- * in-memory ring buffer that we retry on the next successful flush.
+ * Fail-open HTTP transport for browser/React. Telemetry sends are best-effort:
+ * they use a short timeout, never reject into the host app, and fall into a
+ * bounded in-memory ring buffer with circuit-breaker backoff when AllStak is
+ * unavailable.
  *
  * No window, no AbortController fallback shims — RN exposes both natively.
  */
@@ -12,10 +13,17 @@ declare class HttpTransport {
     private apiKey;
     private buffer;
     private flushing;
+    private consecutiveFailures;
+    private circuitOpenUntil;
     constructor(baseUrl: string, apiKey: string);
     send(path: string, payload: unknown): Promise<void>;
+    private enqueueOrDispatch;
+    private dispatch;
     private doFetch;
+    private push;
+    private scheduleFlush;
     private flushBuffer;
+    private recordFailure;
     getBufferSize(): number;
     /**
      * Wait for the in-flight retry-buffer to drain. Resolves `true` if the
@@ -303,9 +311,44 @@ interface HttpTrackingOptions {
     maxBodyBytes?: number;
 }
 
+/**
+ * Idempotent instrumentation of `globalThis.fetch` and `console.warn/error`
+ * to feed breadcrumbs into the AllStak client. Safe to call once at init.
+ *
+ * - `instrumentFetch`: wraps fetch and records a breadcrumb per request
+ *   (success and failure). Skips requests targeting the SDK's own ingest
+ *   host so the wrap never recurses. Preserves the original return type
+ *   and rethrows fetch errors after the breadcrumb is recorded.
+ * - `instrumentConsole`: wraps `console.warn` and `console.error` to
+ *   record `log`-type breadcrumbs at the corresponding level.
+ *
+ * Both patches use a flag on the wrapper function so a second call is a
+ * no-op — important because hot-module-reload in dev would otherwise
+ * stack patches and double-fire breadcrumbs.
+ */
+type AddBreadcrumbFn$1 = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
+declare function instrumentFetch(addBreadcrumb: AddBreadcrumbFn$1, ownBaseUrl?: string): void;
+/**
+ * Per-console-method capture flags. Defaults: warn + error captured,
+ * log + info NOT captured (typical React apps emit thousands of debug
+ * lines per session — flooding the dashboard with them creates pure
+ * noise, so they're opt-in).
+ *
+ *   <AllStakProvider captureConsole={{ log: true, info: true }} />
+ */
+interface ConsoleCaptureOptions {
+    log?: boolean;
+    info?: boolean;
+    warn?: boolean;
+    error?: boolean;
+}
+declare function instrumentConsole(addBreadcrumb: AddBreadcrumbFn$1, options?: ConsoleCaptureOptions): void;
+/** @internal — for tests. Resets the wrap-once flag. */
+declare function __resetConsoleInstrumentationFlagForTest(): void;
+
 declare const INGEST_HOST = "https://api.allstak.sa";
 declare const SDK_NAME = "allstak-react";
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.3.3";
 
 interface AllStakConfig {
     /** Project API key (`ask_live_…`). Required. */
@@ -342,8 +385,22 @@ interface AllStakConfig {
     autoCaptureBrowserErrors?: boolean;
     /** Wrap `globalThis.fetch` to record HTTP breadcrumbs. Default: true */
     autoBreadcrumbsFetch?: boolean;
-    /** Wrap `console.warn` and `console.error` to record log breadcrumbs. Default: true */
+    /** Wrap `console.*` methods to record log breadcrumbs. Default: true.
+     * Per-method capture is controlled by `captureConsole` (warn + error
+     * default on, log + info default off). */
     autoBreadcrumbsConsole?: boolean;
+    /**
+     * Per-console-method capture flags. Defaults: warn + error captured,
+     * log + info NOT captured (to avoid breadcrumb spam from typical app
+     * logging). Set `{ log: true, info: true }` to opt-in.
+     */
+    captureConsole?: ConsoleCaptureOptions;
+    /**
+     * Auto-capture Web Vitals (CLS, LCP, INP, FCP, TTFB) via the browser's
+     * PerformanceObserver. Default: true. Each metric ships as a
+     * `web_vitals` log on the next backend flush.
+     */
+    autoWebVitals?: boolean;
     /** Wrap `history.pushState`/`replaceState` and listen to `popstate` for SPA navigation breadcrumbs. Default: true */
     autoBreadcrumbsNavigation?: boolean;
     /**
@@ -440,6 +497,7 @@ declare class AllStakClient {
     private _instrumentAxios;
     private onErrorHandler;
     private onRejectionHandler;
+    private webVitals;
     constructor(config: AllStakConfig);
     /** Manually instrument an axios instance. No-op when HTTP tracking is off. */
     instrumentAxios<T = any>(axios: T): T;
@@ -576,6 +634,80 @@ declare const AllStak: {
     /** @internal */ _getInstance(): AllStakClient | null;
 };
 
+interface AllStakProviderProps {
+    children: React.ReactNode;
+    apiKey: string;
+    environment?: string;
+    release?: string;
+    host?: string;
+    user?: {
+        id?: string;
+        email?: string;
+    };
+    tags?: Record<string, string>;
+    debug?: boolean;
+    enableHttpTracking?: boolean;
+    httpTracking?: AllStakConfig['httpTracking'];
+    /**
+     * Per-console-method capture flags. Defaults: warn + error captured,
+     * log + info NOT captured (to avoid breadcrumb spam from typical app
+     * logging). Set `{ log: true, info: true }` to opt-in.
+     */
+    captureConsole?: AllStakConfig['captureConsole'];
+    sampleRate?: number;
+    beforeSend?: AllStakConfig['beforeSend'];
+    replay?: AllStakConfig['replay'];
+    tracesSampleRate?: number;
+    service?: string;
+    dist?: string;
+    /** Default true. Capture window error + unhandledrejection. */
+    autoCaptureBrowserErrors?: boolean;
+    /** Default true. Wrap fetch for breadcrumbs. */
+    autoBreadcrumbsFetch?: boolean;
+    /** Default true. Wrap console for breadcrumbs (per-method via captureConsole). */
+    autoBreadcrumbsConsole?: boolean;
+    /** Default true. Patch history.pushState/replaceState + popstate listener. */
+    autoBreadcrumbsNavigation?: boolean;
+    /** Default true. Collect Web Vitals via PerformanceObserver. */
+    autoWebVitals?: boolean;
+    /**
+     * Tear down the SDK when the provider unmounts. Default `false`.
+     *
+     * Most apps mount `AllStakProvider` once at the root and never unmount
+     * it. Setting this to `true` risks disabling telemetry if the provider
+     * re-mounts (Fast Refresh in dev, route key changes, React 18 Strict
+     * Mode double-mount, etc.) — there is a brief window between unmount
+     * and remount where captures throw.
+     *
+     * Leave at the default unless you genuinely need to dispose the SDK.
+     */
+    destroyOnUnmount?: boolean;
+    fallback?: React.ReactNode | ((props: {
+        error: Error;
+        resetError: () => void;
+    }) => React.ReactNode);
+    onError?: (error: Error, componentStack?: string) => void;
+}
+declare function AllStakProvider({ children, apiKey, environment, release, host, user, tags, debug, enableHttpTracking, httpTracking, captureConsole, sampleRate, beforeSend, replay, tracesSampleRate, service, dist, autoCaptureBrowserErrors, autoBreadcrumbsFetch, autoBreadcrumbsConsole, autoBreadcrumbsNavigation, autoWebVitals, destroyOnUnmount, fallback, onError, }: AllStakProviderProps): React.ReactElement;
+/**
+ * Convenience hook — exposes the most common capture/context APIs with
+ * a stable identity so components don't have to import the namespace.
+ */
+declare function useAllStak(): {
+    captureException: (error: Error, ctx?: Record<string, unknown>) => void;
+    captureMessage: (msg: string, level?: "fatal" | "error" | "warning" | "info") => void;
+    setUser: (user: {
+        id?: string;
+        email?: string;
+    }) => void;
+    setTag: (key: string, value: string) => void;
+    setContext: (name: string, ctx: Record<string, unknown> | null) => void;
+    addBreadcrumb: (type: string, message: string, level?: string, data?: Record<string, unknown>) => void;
+    flush: (timeoutMs?: number) => Promise<boolean>;
+};
+/** @internal — for tests. Resets the module-level remount-guard. */
+declare function __resetProviderInstanceForTest(): void;
+
 /**
  * Browser navigation breadcrumbs — minimal fallback that doesn't depend on
  * any specific router library. Wraps `history.pushState`/`replaceState` and
@@ -588,41 +720,77 @@ declare const AllStak: {
  * For framework-specific instrumentation (React Router's `useNavigate`,
  * Next's `router.events`), bind manually with `AllStak.addBreadcrumb`.
  */
-type AddBreadcrumbFn$1 = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
-declare function instrumentBrowserNavigation(addBreadcrumb: AddBreadcrumbFn$1): void;
+type AddBreadcrumbFn = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
+declare function instrumentBrowserNavigation(addBreadcrumb: AddBreadcrumbFn): void;
 declare function instrumentReactRouter(location: {
     pathname: string;
     search?: string;
-}, addBreadcrumb?: AddBreadcrumbFn$1): void;
-declare function instrumentNextRouter(url: string, addBreadcrumb?: AddBreadcrumbFn$1): void;
+}, addBreadcrumb?: AddBreadcrumbFn): void;
+declare function instrumentNextRouter(url: string, addBreadcrumb?: AddBreadcrumbFn): void;
 
 /**
- * Idempotent instrumentation of `globalThis.fetch` and `console.warn/error`
- * to feed breadcrumbs into the AllStak client. Safe to call once at init.
+ * Lightweight Web Vitals collection via the browser's PerformanceObserver.
  *
- * - `instrumentFetch`: wraps fetch and records a breadcrumb per request
- *   (success and failure). Skips requests targeting the SDK's own ingest
- *   host so the wrap never recurses. Preserves the original return type
- *   and rethrows fetch errors after the breadcrumb is recorded.
- * - `instrumentConsole`: wraps `console.warn` and `console.error` to
- *   record `log`-type breadcrumbs at the corresponding level.
+ * Captures CLS, LCP, INP, FCP, TTFB without pulling in the `web-vitals`
+ * package as a runtime dependency. Each metric is shipped as a single
+ * `web_vital` log on the SDK's `/ingest/v1/logs` channel — so the
+ * dashboard can chart them alongside other logs.
  *
- * Both patches use a flag on the wrapper function so a second call is a
- * no-op — important because hot-module-reload in dev would otherwise
- * stack patches and double-fire breadcrumbs.
+ * Privacy: only numeric values + the metric name are sent. No URLs,
+ * referrers, or user-identifiable data.
+ *
+ * Browser compatibility: PerformanceObserver is available in every
+ * evergreen browser (Chrome 51+, Safari 11+, Firefox 57+, Edge 79+).
+ * Older browsers silently no-op via the `typeof PerformanceObserver`
+ * guard.
+ *
+ *   - **CLS** (Cumulative Layout Shift) — layout-shift entries with
+ *     `hadRecentInput=false`, summed for the session
+ *   - **LCP** (Largest Contentful Paint) — biggest paint entry's startTime
+ *   - **INP** (Interaction to Next Paint) — longest event-timing duration
+ *   - **FCP** (First Contentful Paint) — first paint named `first-contentful-paint`
+ *   - **TTFB** (Time to First Byte) — `responseStart - requestStart` from the
+ *     navigation timing entry
  */
-type AddBreadcrumbFn = (type: string, msg: string, level?: string, data?: Record<string, unknown>) => void;
-declare function instrumentFetch(addBreadcrumb: AddBreadcrumbFn, ownBaseUrl?: string): void;
-declare function instrumentConsole(addBreadcrumb: AddBreadcrumbFn): void;
+type VitalsReporter = (metric: {
+    name: string;
+    value: number;
+    id?: string;
+}) => void;
+interface WebVitalsHandle {
+    /** Disconnects all observers. Idempotent. */
+    destroy(): void;
+}
+/**
+ * Start collecting Web Vitals. Returns a handle whose `destroy()` cleans
+ * up all PerformanceObservers. Safe no-op on non-browser runtimes.
+ */
+declare function startWebVitals(report: VitalsReporter): WebVitalsHandle;
+/** @internal — reset the started flag so tests can re-init. */
+declare function __resetWebVitalsFlagForTest(): void;
 
 /**
  * @allstak/react — standalone React SDK.
  *
  * Self-contained: no @allstak/js or @allstak-io/* dependencies. Ships its own
  * AllStak client (init/capture/breadcrumbs/transport) plus React-specific
- * helpers (ErrorBoundary, useAllStak hook, withAllStakProfiler HOC).
+ * helpers (Provider, ErrorBoundary, useAllStak hook, withAllStakProfiler HOC).
+ *
+ * Recommended usage (one-liner):
+ *
+ *   import { AllStakProvider } from '@allstak/react';
+ *
+ *   export function App() {
+ *     return (
+ *       <AllStakProvider apiKey="ask_live_..." environment="production" debug>
+ *         <AppRoot />
+ *       </AllStakProvider>
+ *     );
+ *   }
  *
- * Usage:
+ * Advanced / manual usage:
+ *
+ *   import { AllStak } from '@allstak/react';
  *   AllStak.init({ apiKey, environment, release });
  *   <AllStakErrorBoundary>...</AllStakErrorBoundary>
  *   const { captureException } = useAllStak();
@@ -650,23 +818,9 @@ declare class AllStakErrorBoundary extends React.Component<AllStakErrorBoundaryP
     render(): React.ReactNode;
 }
 /**
- * Convenience hook — exposes the most common capture/context APIs with a
- * stable identity so components don't have to import the namespace.
- */
-declare function useAllStak(): {
-    captureException: (error: Error, ctx?: Record<string, unknown>) => void;
-    captureMessage: (msg: string, level?: "fatal" | "error" | "warning" | "info") => void;
-    setUser: (user: {
-        id?: string;
-        email?: string;
-    }) => void;
-    setTag: (key: string, value: string) => void;
-    addBreadcrumb: (type: string, message: string, level?: string, data?: Record<string, unknown>) => void;
-};
-/**
- * HOC: drops a navigation breadcrumb when a component mounts. Useful for
- * marking screen boundaries without a router.
+ * HOC: drops a navigation breadcrumb when a component mounts. Useful
+ * for marking screen boundaries without a router.
  */
 declare function withAllStakProfiler<P extends object>(Component: React.ComponentType<P>, name?: string): React.FC<P>;
 
-export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, type Breadcrumb, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, useAllStak, withAllStakProfiler };
+export { AllStak, AllStakClient, type AllStakConfig, AllStakErrorBoundary, type AllStakErrorBoundaryProps, AllStakProvider, type AllStakProviderProps, type Breadcrumb, type ConsoleCaptureOptions, type HttpRequestEvent, HttpRequestModule, type HttpTrackingOptions, INGEST_HOST, type ReplayOptions, ReplayRecorder, SDK_NAME, SDK_VERSION, Scope, type WebVitalsHandle, __resetConsoleInstrumentationFlagForTest, __resetProviderInstanceForTest, __resetWebVitalsFlagForTest, instrumentBrowserNavigation, instrumentConsole, instrumentFetch, instrumentNextRouter, instrumentReactRouter, startWebVitals, useAllStak, withAllStakProfiler };