@deeptracer/react 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,224 @@
+# @deeptracer/react
+
+[![npm](https://img.shields.io/npm/v/@deeptracer/react?color=blue)](https://www.npmjs.com/package/@deeptracer/react)
+
+DeepTracer React integration — provider, error boundary, and hooks for automatic error capture. Re-exports everything from `@deeptracer/browser`.
+
+## Installation
+
+```bash
+npm install @deeptracer/react
+```
+
+**Peer dependencies:** `react >=18`, `react-dom >=18`
+
+## Quick Start
+
+```tsx
+import { DeepTracerProvider, DeepTracerErrorBoundary, useLogger } from "@deeptracer/react"
+
+function App() {
+  return (
+    <DeepTracerProvider config={{
+      product: "my-app",
+      service: "web",
+      environment: "production",
+      endpoint: "https://deeptracer.example.com",
+      apiKey: "dt_live_xxx",
+    }}>
+      <DeepTracerErrorBoundary fallback={<div>Something went wrong</div>}>
+        <MyApp />
+      </DeepTracerErrorBoundary>
+    </DeepTracerProvider>
+  )
+}
+
+function MyApp() {
+  const logger = useLogger()
+
+  function handleClick() {
+    logger.info("Button clicked", { component: "MyApp" })
+  }
+
+  return <button onClick={handleClick}>Click me</button>
+}
+```
+
+## API Reference
+
+### `DeepTracerProvider`
+
+React context provider that creates and manages a DeepTracer Logger instance. Automatically captures browser global errors (`window.onerror` and `unhandledrejection`).
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `LoggerConfig` | — | Logger configuration. Creates a new Logger internally. |
+| `logger` | `Logger` | — | An existing Logger instance to share. Mutually exclusive with `config`. |
+| `captureErrors` | `boolean` | `true` | Automatically capture unhandled window errors. |
+| `children` | `ReactNode` | — | Child components with access to the logger via `useLogger()`. |
+
+If neither `config` nor `logger` is provided, the provider reads from environment variables automatically:
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `NEXT_PUBLIC_DEEPTRACER_ENDPOINT` | Ingestion endpoint URL (required) |
+| `NEXT_PUBLIC_DEEPTRACER_API_KEY` | API key (required) |
+| `NEXT_PUBLIC_DEEPTRACER_PRODUCT` | Product name (required) |
+| `NEXT_PUBLIC_DEEPTRACER_SERVICE` | Service name (default: `"web"`) |
+| `NEXT_PUBLIC_DEEPTRACER_ENVIRONMENT` | `"production"` or `"staging"` (default: `"production"`) |
+
+```tsx
+// Explicit config
+<DeepTracerProvider config={{
+  product: "my-app",
+  service: "web",
+  environment: "production",
+  endpoint: process.env.NEXT_PUBLIC_DEEPTRACER_ENDPOINT!,
+  apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+}}>
+  {children}
+</DeepTracerProvider>
+
+// Zero-config (reads NEXT_PUBLIC_DEEPTRACER_* env vars)
+<DeepTracerProvider>{children}</DeepTracerProvider>
+
+// Existing logger instance
+<DeepTracerProvider logger={myLogger}>{children}</DeepTracerProvider>
+```
+
+---
+
+### `DeepTracerErrorPage`
+
+Drop-in function component for Next.js `error.tsx` or `global-error.tsx`. Receives `{ error, reset }` from Next.js, calls `captureError()` in `useEffect`, and shows a default fallback UI with a "Try again" button.
+
+**One-line setup:**
+
+```tsx
+// app/global-error.tsx
+"use client"
+export { DeepTracerErrorPage as default } from "@deeptracer/react"
+```
+
+```tsx
+// app/error.tsx
+"use client"
+export { DeepTracerErrorPage as default } from "@deeptracer/react"
+```
+
+Requires a `<DeepTracerProvider>` in the component tree. If no provider is found, the error is displayed but not reported (a `console.warn` is emitted).
+
+---
+
+### `useDeepTracerErrorReporter(error, severity?)`
+
+Hook for custom error pages that still want automatic error reporting. Use when you want your own UI but still want DeepTracer to capture the error.
+
+**Parameters:**
+- `error: Error` — the error to report
+- `severity: "low" | "medium" | "high" | "critical"` — default: `"high"`
+
+```tsx
+// app/error.tsx — custom UI with automatic reporting
+"use client"
+import { useDeepTracerErrorReporter } from "@deeptracer/react"
+
+export default function ErrorPage({ error, reset }: { error: Error; reset: () => void }) {
+  useDeepTracerErrorReporter(error)
+  return (
+    <div>
+      <h2>Oops! {error.message}</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )
+}
+```
+
+---
+
+### `DeepTracerErrorBoundary`
+
+Class-based React error boundary that catches rendering errors in child components and reports them to DeepTracer.
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `fallback` | `ReactNode \| (({ error, resetErrorBoundary }) => ReactNode)` | Content to show on error. |
+| `children` | `ReactNode` | Components to protect. |
+| `onError` | `(error: Error, errorInfo: ErrorInfo) => void` | Called after the error is caught and reported. |
+
+```tsx
+import { DeepTracerErrorBoundary } from "@deeptracer/react"
+
+// Static fallback
+<DeepTracerErrorBoundary fallback={<div>Something went wrong</div>}>
+  <MyComponent />
+</DeepTracerErrorBoundary>
+
+// Render function fallback
+<DeepTracerErrorBoundary
+  fallback={({ error, resetErrorBoundary }) => (
+    <div>
+      <p>Error: {error.message}</p>
+      <button onClick={resetErrorBoundary}>Retry</button>
+    </div>
+  )}
+>
+  <MyComponent />
+</DeepTracerErrorBoundary>
+```
+
+---
+
+### `useLogger()`
+
+Hook that returns the DeepTracer Logger from context. Throws with a clear error message if used outside a `<DeepTracerProvider>`.
+
+```tsx
+import { useLogger } from "@deeptracer/react"
+
+function MyComponent() {
+  const logger = useLogger()
+
+  async function handleSubmit() {
+    try {
+      await submitData()
+      logger.info("Form submitted successfully")
+    } catch (error) {
+      logger.captureError(error, { severity: "high" })
+    }
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+## Re-exported from @deeptracer/browser
+
+All exports from `@deeptracer/browser` and `@deeptracer/core` are available directly from this package. You do not need to install them separately.
+
+## Monorepo
+
+This package is part of the [DeepTracer JavaScript SDK](https://github.com/getdeeptracer/deeptracer-js) monorepo:
+
+| Package | Description |
+|---------|-------------|
+| [`@deeptracer/core`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/core) | Zero-dependency shared core |
+| [`@deeptracer/node`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/node) | Node.js/Bun SDK |
+| [`@deeptracer/ai`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/ai) | AI SDK wrappers |
+| [`@deeptracer/browser`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/browser) | Browser SDK |
+| **`@deeptracer/react`** | React integration (this package) |
+| [`@deeptracer/nextjs`](https://github.com/getdeeptracer/deeptracer-js/tree/main/packages/nextjs) | Next.js integration |
+
+## Links
+
+- [deeptracer.dev](https://deeptracer.dev) — Homepage
+- [Docs](https://deeptracer.dev/docs) — Documentation
+- [GitHub](https://github.com/getdeeptracer/deeptracer-js) — Source code
+
+## License
+
+MIT

package/dist/index.cjs

@@ -1,8 +1,13 @@
+"use client";
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -16,9 +21,202 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  DeepTracerErrorBoundary: () => DeepTracerErrorBoundary,
+  DeepTracerErrorPage: () => DeepTracerErrorPage,
+  DeepTracerProvider: () => DeepTracerProvider,
+  useDeepTracerErrorReporter: () => useDeepTracerErrorReporter,
+  useLogger: () => useLogger
+});
 module.exports = __toCommonJS(index_exports);
 __reExport(index_exports, require("@deeptracer/browser"), module.exports);
+
+// src/context.tsx
+var import_react = require("react");
+var import_browser = require("@deeptracer/browser");
+var import_browser2 = require("@deeptracer/browser");
+var import_jsx_runtime = require("react/jsx-runtime");
+var DeepTracerContext = (0, import_react.createContext)(null);
+function DeepTracerProvider({
+  config,
+  logger: externalLogger,
+  captureErrors = true,
+  children
+}) {
+  const [logger, setLogger] = (0, import_react.useState)(externalLogger ?? null);
+  const ownsLogger = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    if (externalLogger) {
+      setLogger(externalLogger);
+      ownsLogger.current = false;
+      return;
+    }
+    const resolvedConfig = config ?? readConfigFromEnv();
+    if (!resolvedConfig) {
+      console.warn(
+        "[@deeptracer/react] DeepTracerProvider: No config, logger, or NEXT_PUBLIC_DEEPTRACER_* env vars found. Logger is disabled. Pass a config prop or set environment variables."
+      );
+      return;
+    }
+    const newLogger = (0, import_browser.createLogger)(resolvedConfig);
+    setLogger(newLogger);
+    ownsLogger.current = true;
+    if (captureErrors) {
+      (0, import_browser2.captureGlobalErrors)(newLogger);
+    }
+    return () => {
+      newLogger.destroy().catch(() => {
+      });
+    };
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DeepTracerContext.Provider, { value: logger, children });
+}
+function readConfigFromEnv() {
+  const endpoint = typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_ENDPOINT : void 0;
+  const apiKey = typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_API_KEY : void 0;
+  const product = typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_PRODUCT : void 0;
+  if (!endpoint || !apiKey || !product) return null;
+  const service = (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_SERVICE : void 0) ?? "web";
+  const environment = (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_ENVIRONMENT : void 0) ?? "production";
+  return { product, service, environment, endpoint, apiKey };
+}
+
+// src/error-boundary.tsx
+var import_react2 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function DeepTracerErrorPage({
+  error,
+  reset
+}) {
+  const logger = (0, import_react2.useContext)(DeepTracerContext);
+  (0, import_react2.useEffect)(() => {
+    if (logger) {
+      logger.captureError(error, {
+        severity: "high",
+        context: {
+          source: "react-error-page",
+          digest: error.digest
+        }
+      });
+    } else {
+      console.warn(
+        "[@deeptracer/react] DeepTracerErrorPage: No DeepTracerProvider found. Error not reported to DeepTracer. Wrap your app with <DeepTracerProvider>."
+      );
+    }
+  }, [error, logger]);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: { padding: "2rem", fontFamily: "system-ui, sans-serif" }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { style: { marginBottom: "1rem" }, children: "Something went wrong" }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { style: { color: "#666", marginBottom: "1.5rem" }, children: error.message || "An unexpected error occurred." }),
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "button",
+      {
+        onClick: reset,
+        style: {
+          padding: "0.5rem 1rem",
+          borderRadius: "0.375rem",
+          border: "1px solid #ccc",
+          background: "#fff",
+          cursor: "pointer",
+          fontSize: "0.875rem"
+        },
+        children: "Try again"
+      }
+    )
+  ] });
+}
+function useDeepTracerErrorReporter(error, severity = "high") {
+  const logger = (0, import_react2.useContext)(DeepTracerContext);
+  (0, import_react2.useEffect)(() => {
+    if (logger) {
+      logger.captureError(error, {
+        severity,
+        context: { source: "react-error-page" }
+      });
+    }
+  }, [error, logger, severity]);
+}
+var DeepTracerErrorBoundary = class extends import_react2.Component {
+  static contextType = DeepTracerContext;
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+  componentDidCatch(error, errorInfo) {
+    const logger = this.context;
+    if (logger) {
+      logger.captureError(error, {
+        severity: "high",
+        context: {
+          source: "react-error-boundary",
+          componentStack: errorInfo.componentStack ?? void 0
+        }
+      });
+    } else {
+      console.warn(
+        "[@deeptracer/react] DeepTracerErrorBoundary: No DeepTracerProvider found. Error not reported to DeepTracer."
+      );
+    }
+    this.props.onError?.(error, errorInfo);
+  }
+  resetErrorBoundary = () => {
+    this.setState({ hasError: false, error: null });
+  };
+  render() {
+    if (this.state.hasError && this.state.error) {
+      const { fallback } = this.props;
+      if (typeof fallback === "function") {
+        return fallback({
+          error: this.state.error,
+          resetErrorBoundary: this.resetErrorBoundary
+        });
+      }
+      if (fallback) {
+        return fallback;
+      }
+      return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: { padding: "2rem", fontFamily: "system-ui, sans-serif" }, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { style: { marginBottom: "1rem" }, children: "Something went wrong" }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { style: { color: "#666", marginBottom: "1.5rem" }, children: this.state.error.message || "An unexpected error occurred." }),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+          "button",
+          {
+            onClick: this.resetErrorBoundary,
+            style: {
+              padding: "0.5rem 1rem",
+              borderRadius: "0.375rem",
+              border: "1px solid #ccc",
+              background: "#fff",
+              cursor: "pointer",
+              fontSize: "0.875rem"
+            },
+            children: "Try again"
+          }
+        )
+      ] });
+    }
+    return this.props.children;
+  }
+};
+
+// src/hooks.ts
+var import_react3 = require("react");
+function useLogger() {
+  const logger = (0, import_react3.useContext)(DeepTracerContext);
+  if (!logger) {
+    throw new Error(
+      "[@deeptracer/react] useLogger() must be used inside a <DeepTracerProvider>. Wrap your app with <DeepTracerProvider config={{...}}>."
+    );
+  }
+  return logger;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DeepTracerErrorBoundary,
+  DeepTracerErrorPage,
+  DeepTracerProvider,
+  useDeepTracerErrorReporter,
+  useLogger,
   ...require("@deeptracer/browser")
 });

package/dist/index.d.cts

@@ -1 +1,232 @@
+import { LoggerConfig, Logger } from '@deeptracer/browser';
 export * from '@deeptracer/browser';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
+
+/**
+ * Props for the DeepTracerProvider component.
+ *
+ * Pass either a `config` object to create a new Logger, or an existing
+ * `logger` instance. If neither is given, reads from `NEXT_PUBLIC_DEEPTRACER_*`
+ * environment variables automatically (zero-config for Next.js).
+ */
+interface DeepTracerProviderProps {
+    /**
+     * Logger configuration. A new Logger is created internally.
+     * Mutually exclusive with `logger`.
+     *
+     * @example
+     * ```tsx
+     * <DeepTracerProvider config={{
+     *   product: "my-app",
+     *   service: "web",
+     *   environment: "production",
+     *   endpoint: process.env.NEXT_PUBLIC_DEEPTRACER_ENDPOINT!,
+     *   apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+     * }}>
+     * ```
+     */
+    config?: LoggerConfig;
+    /**
+     * An existing Logger instance to share with child components.
+     * Mutually exclusive with `config`.
+     */
+    logger?: Logger;
+    /**
+     * Automatically capture unhandled window errors and promise rejections.
+     * Default: true
+     */
+    captureErrors?: boolean;
+    /** Child components that will have access to the logger via useLogger(). */
+    children: ReactNode;
+}
+/**
+ * Provides a DeepTracer Logger to all child components via React context.
+ *
+ * Automatically captures browser global errors (window.onerror and
+ * unhandledrejection) unless `captureErrors={false}`.
+ *
+ * The Logger is created once on mount and destroyed on unmount.
+ *
+ * @example
+ * With explicit config:
+ * ```tsx
+ * import { DeepTracerProvider } from "@deeptracer/react"
+ *
+ * export default function App({ children }) {
+ *   return (
+ *     <DeepTracerProvider config={{
+ *       product: "my-app",
+ *       service: "web",
+ *       environment: "production",
+ *       endpoint: "https://deeptracer.example.com",
+ *       apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+ *     }}>
+ *       {children}
+ *     </DeepTracerProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Zero-config (reads NEXT_PUBLIC_DEEPTRACER_* env vars):
+ * ```tsx
+ * <DeepTracerProvider>{children}</DeepTracerProvider>
+ * ```
+ */
+declare function DeepTracerProvider({ config, logger: externalLogger, captureErrors, children, }: DeepTracerProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Drop-in error page component for Next.js `error.tsx` or `global-error.tsx`.
+ *
+ * Automatically reports the error to DeepTracer when a `<DeepTracerProvider>`
+ * is present in the component tree. If no provider is found, the error is
+ * still displayed but not reported (a console.warn is emitted).
+ *
+ * @example
+ * One-line setup for `app/global-error.tsx`:
+ * ```tsx
+ * "use client"
+ * export { DeepTracerErrorPage as default } from "@deeptracer/react"
+ * ```
+ *
+ * @example
+ * One-line setup for `app/error.tsx`:
+ * ```tsx
+ * "use client"
+ * export { DeepTracerErrorPage as default } from "@deeptracer/react"
+ * ```
+ */
+declare function DeepTracerErrorPage({ error, reset, }: {
+    error: Error & {
+        digest?: string;
+    };
+    reset: () => void;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook that reports an error to DeepTracer. Use in custom `error.tsx` pages
+ * when you want your own UI but still want automatic error reporting.
+ *
+ * @param error - The error to report
+ * @param severity - Error severity (default: "high")
+ *
+ * @example
+ * ```tsx
+ * // app/error.tsx
+ * "use client"
+ * import { useDeepTracerErrorReporter } from "@deeptracer/react"
+ *
+ * export default function ErrorPage({ error, reset }) {
+ *   useDeepTracerErrorReporter(error)
+ *   return <div>Custom error UI <button onClick={reset}>Retry</button></div>
+ * }
+ * ```
+ */
+declare function useDeepTracerErrorReporter(error: Error, severity?: "low" | "medium" | "high" | "critical"): void;
+/**
+ * Props for the DeepTracerErrorBoundary component.
+ */
+interface ErrorBoundaryProps {
+    /** Content to render when an error occurs. Static ReactNode or render function. */
+    fallback?: ReactNode | ((props: {
+        error: Error;
+        resetErrorBoundary: () => void;
+    }) => ReactNode);
+    /** Child components to protect with the error boundary. */
+    children: ReactNode;
+    /** Called when an error is caught, after reporting to DeepTracer. */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component that catches React rendering errors in child
+ * components and automatically reports them to DeepTracer.
+ *
+ * For Next.js `error.tsx` / `global-error.tsx`, use `DeepTracerErrorPage` instead.
+ * This component is for wrapping arbitrary React trees.
+ *
+ * @example
+ * ```tsx
+ * import { DeepTracerErrorBoundary } from "@deeptracer/react"
+ *
+ * function App() {
+ *   return (
+ *     <DeepTracerErrorBoundary fallback={<div>Something went wrong</div>}>
+ *       <MyComponent />
+ *     </DeepTracerErrorBoundary>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * With render function fallback:
+ * ```tsx
+ * <DeepTracerErrorBoundary
+ *   fallback={({ error, resetErrorBoundary }) => (
+ *     <div>
+ *       <p>Error: {error.message}</p>
+ *       <button onClick={resetErrorBoundary}>Retry</button>
+ *     </div>
+ *   )}
+ * >
+ *   <MyComponent />
+ * </DeepTracerErrorBoundary>
+ * ```
+ */
+declare class DeepTracerErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    static contextType: react.Context<Logger | null>;
+    context: Logger | null;
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    resetErrorBoundary: () => void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+/**
+ * Access the DeepTracer Logger instance from React context.
+ *
+ * Must be used inside a `<DeepTracerProvider>`. Throws with a clear
+ * error message if no provider is found.
+ *
+ * @returns The Logger instance from the nearest DeepTracerProvider
+ * @throws Error if called outside a DeepTracerProvider
+ *
+ * @example
+ * ```tsx
+ * import { useLogger } from "@deeptracer/react"
+ *
+ * function MyComponent() {
+ *   const logger = useLogger()
+ *
+ *   function handleClick() {
+ *     logger.info("Button clicked", { component: "MyComponent" })
+ *   }
+ *
+ *   return <button onClick={handleClick}>Click me</button>
+ * }
+ * ```
+ *
+ * @example
+ * Capture errors manually:
+ * ```tsx
+ * function SubmitForm() {
+ *   const logger = useLogger()
+ *
+ *   async function handleSubmit() {
+ *     try {
+ *       await submitData()
+ *     } catch (error) {
+ *       logger.captureError(error, { severity: "high" })
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function useLogger(): Logger;
+
+export { DeepTracerErrorBoundary, DeepTracerErrorPage, DeepTracerProvider, type DeepTracerProviderProps, useDeepTracerErrorReporter, useLogger };

package/dist/index.d.ts

@@ -1 +1,232 @@
+import { LoggerConfig, Logger } from '@deeptracer/browser';
 export * from '@deeptracer/browser';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
+
+/**
+ * Props for the DeepTracerProvider component.
+ *
+ * Pass either a `config` object to create a new Logger, or an existing
+ * `logger` instance. If neither is given, reads from `NEXT_PUBLIC_DEEPTRACER_*`
+ * environment variables automatically (zero-config for Next.js).
+ */
+interface DeepTracerProviderProps {
+    /**
+     * Logger configuration. A new Logger is created internally.
+     * Mutually exclusive with `logger`.
+     *
+     * @example
+     * ```tsx
+     * <DeepTracerProvider config={{
+     *   product: "my-app",
+     *   service: "web",
+     *   environment: "production",
+     *   endpoint: process.env.NEXT_PUBLIC_DEEPTRACER_ENDPOINT!,
+     *   apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+     * }}>
+     * ```
+     */
+    config?: LoggerConfig;
+    /**
+     * An existing Logger instance to share with child components.
+     * Mutually exclusive with `config`.
+     */
+    logger?: Logger;
+    /**
+     * Automatically capture unhandled window errors and promise rejections.
+     * Default: true
+     */
+    captureErrors?: boolean;
+    /** Child components that will have access to the logger via useLogger(). */
+    children: ReactNode;
+}
+/**
+ * Provides a DeepTracer Logger to all child components via React context.
+ *
+ * Automatically captures browser global errors (window.onerror and
+ * unhandledrejection) unless `captureErrors={false}`.
+ *
+ * The Logger is created once on mount and destroyed on unmount.
+ *
+ * @example
+ * With explicit config:
+ * ```tsx
+ * import { DeepTracerProvider } from "@deeptracer/react"
+ *
+ * export default function App({ children }) {
+ *   return (
+ *     <DeepTracerProvider config={{
+ *       product: "my-app",
+ *       service: "web",
+ *       environment: "production",
+ *       endpoint: "https://deeptracer.example.com",
+ *       apiKey: process.env.NEXT_PUBLIC_DEEPTRACER_API_KEY!,
+ *     }}>
+ *       {children}
+ *     </DeepTracerProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Zero-config (reads NEXT_PUBLIC_DEEPTRACER_* env vars):
+ * ```tsx
+ * <DeepTracerProvider>{children}</DeepTracerProvider>
+ * ```
+ */
+declare function DeepTracerProvider({ config, logger: externalLogger, captureErrors, children, }: DeepTracerProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Drop-in error page component for Next.js `error.tsx` or `global-error.tsx`.
+ *
+ * Automatically reports the error to DeepTracer when a `<DeepTracerProvider>`
+ * is present in the component tree. If no provider is found, the error is
+ * still displayed but not reported (a console.warn is emitted).
+ *
+ * @example
+ * One-line setup for `app/global-error.tsx`:
+ * ```tsx
+ * "use client"
+ * export { DeepTracerErrorPage as default } from "@deeptracer/react"
+ * ```
+ *
+ * @example
+ * One-line setup for `app/error.tsx`:
+ * ```tsx
+ * "use client"
+ * export { DeepTracerErrorPage as default } from "@deeptracer/react"
+ * ```
+ */
+declare function DeepTracerErrorPage({ error, reset, }: {
+    error: Error & {
+        digest?: string;
+    };
+    reset: () => void;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Hook that reports an error to DeepTracer. Use in custom `error.tsx` pages
+ * when you want your own UI but still want automatic error reporting.
+ *
+ * @param error - The error to report
+ * @param severity - Error severity (default: "high")
+ *
+ * @example
+ * ```tsx
+ * // app/error.tsx
+ * "use client"
+ * import { useDeepTracerErrorReporter } from "@deeptracer/react"
+ *
+ * export default function ErrorPage({ error, reset }) {
+ *   useDeepTracerErrorReporter(error)
+ *   return <div>Custom error UI <button onClick={reset}>Retry</button></div>
+ * }
+ * ```
+ */
+declare function useDeepTracerErrorReporter(error: Error, severity?: "low" | "medium" | "high" | "critical"): void;
+/**
+ * Props for the DeepTracerErrorBoundary component.
+ */
+interface ErrorBoundaryProps {
+    /** Content to render when an error occurs. Static ReactNode or render function. */
+    fallback?: ReactNode | ((props: {
+        error: Error;
+        resetErrorBoundary: () => void;
+    }) => ReactNode);
+    /** Child components to protect with the error boundary. */
+    children: ReactNode;
+    /** Called when an error is caught, after reporting to DeepTracer. */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component that catches React rendering errors in child
+ * components and automatically reports them to DeepTracer.
+ *
+ * For Next.js `error.tsx` / `global-error.tsx`, use `DeepTracerErrorPage` instead.
+ * This component is for wrapping arbitrary React trees.
+ *
+ * @example
+ * ```tsx
+ * import { DeepTracerErrorBoundary } from "@deeptracer/react"
+ *
+ * function App() {
+ *   return (
+ *     <DeepTracerErrorBoundary fallback={<div>Something went wrong</div>}>
+ *       <MyComponent />
+ *     </DeepTracerErrorBoundary>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * With render function fallback:
+ * ```tsx
+ * <DeepTracerErrorBoundary
+ *   fallback={({ error, resetErrorBoundary }) => (
+ *     <div>
+ *       <p>Error: {error.message}</p>
+ *       <button onClick={resetErrorBoundary}>Retry</button>
+ *     </div>
+ *   )}
+ * >
+ *   <MyComponent />
+ * </DeepTracerErrorBoundary>
+ * ```
+ */
+declare class DeepTracerErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    static contextType: react.Context<Logger | null>;
+    context: Logger | null;
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    resetErrorBoundary: () => void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+/**
+ * Access the DeepTracer Logger instance from React context.
+ *
+ * Must be used inside a `<DeepTracerProvider>`. Throws with a clear
+ * error message if no provider is found.
+ *
+ * @returns The Logger instance from the nearest DeepTracerProvider
+ * @throws Error if called outside a DeepTracerProvider
+ *
+ * @example
+ * ```tsx
+ * import { useLogger } from "@deeptracer/react"
+ *
+ * function MyComponent() {
+ *   const logger = useLogger()
+ *
+ *   function handleClick() {
+ *     logger.info("Button clicked", { component: "MyComponent" })
+ *   }
+ *
+ *   return <button onClick={handleClick}>Click me</button>
+ * }
+ * ```
+ *
+ * @example
+ * Capture errors manually:
+ * ```tsx
+ * function SubmitForm() {
+ *   const logger = useLogger()
+ *
+ *   async function handleSubmit() {
+ *     try {
+ *       await submitData()
+ *     } catch (error) {
+ *       logger.captureError(error, { severity: "high" })
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function useLogger(): Logger;
+
+export { DeepTracerErrorBoundary, DeepTracerErrorPage, DeepTracerProvider, type DeepTracerProviderProps, useDeepTracerErrorReporter, useLogger };

package/dist/index.js

@@ -1,2 +1,192 @@
+"use client";
+
 // src/index.ts
 export * from "@deeptracer/browser";
+
+// src/context.tsx
+import { createContext, useEffect, useRef, useState } from "react";
+import { createLogger } from "@deeptracer/browser";
+import { captureGlobalErrors } from "@deeptracer/browser";
+import { jsx } from "react/jsx-runtime";
+var DeepTracerContext = createContext(null);
+function DeepTracerProvider({
+  config,
+  logger: externalLogger,
+  captureErrors = true,
+  children
+}) {
+  const [logger, setLogger] = useState(externalLogger ?? null);
+  const ownsLogger = useRef(false);
+  useEffect(() => {
+    if (externalLogger) {
+      setLogger(externalLogger);
+      ownsLogger.current = false;
+      return;
+    }
+    const resolvedConfig = config ?? readConfigFromEnv();
+    if (!resolvedConfig) {
+      console.warn(
+        "[@deeptracer/react] DeepTracerProvider: No config, logger, or NEXT_PUBLIC_DEEPTRACER_* env vars found. Logger is disabled. Pass a config prop or set environment variables."
+      );
+      return;
+    }
+    const newLogger = createLogger(resolvedConfig);
+    setLogger(newLogger);
+    ownsLogger.current = true;
+    if (captureErrors) {
+      captureGlobalErrors(newLogger);
+    }
+    return () => {
+      newLogger.destroy().catch(() => {
+      });
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(DeepTracerContext.Provider, { value: logger, children });
+}
+function readConfigFromEnv() {
+  const endpoint = typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_ENDPOINT : void 0;
+  const apiKey = typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_API_KEY : void 0;
+  const product = typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_PRODUCT : void 0;
+  if (!endpoint || !apiKey || !product) return null;
+  const service = (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_SERVICE : void 0) ?? "web";
+  const environment = (typeof process !== "undefined" ? process.env?.NEXT_PUBLIC_DEEPTRACER_ENVIRONMENT : void 0) ?? "production";
+  return { product, service, environment, endpoint, apiKey };
+}
+
+// src/error-boundary.tsx
+import { Component, useContext, useEffect as useEffect2 } from "react";
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function DeepTracerErrorPage({
+  error,
+  reset
+}) {
+  const logger = useContext(DeepTracerContext);
+  useEffect2(() => {
+    if (logger) {
+      logger.captureError(error, {
+        severity: "high",
+        context: {
+          source: "react-error-page",
+          digest: error.digest
+        }
+      });
+    } else {
+      console.warn(
+        "[@deeptracer/react] DeepTracerErrorPage: No DeepTracerProvider found. Error not reported to DeepTracer. Wrap your app with <DeepTracerProvider>."
+      );
+    }
+  }, [error, logger]);
+  return /* @__PURE__ */ jsxs("div", { style: { padding: "2rem", fontFamily: "system-ui, sans-serif" }, children: [
+    /* @__PURE__ */ jsx2("h2", { style: { marginBottom: "1rem" }, children: "Something went wrong" }),
+    /* @__PURE__ */ jsx2("p", { style: { color: "#666", marginBottom: "1.5rem" }, children: error.message || "An unexpected error occurred." }),
+    /* @__PURE__ */ jsx2(
+      "button",
+      {
+        onClick: reset,
+        style: {
+          padding: "0.5rem 1rem",
+          borderRadius: "0.375rem",
+          border: "1px solid #ccc",
+          background: "#fff",
+          cursor: "pointer",
+          fontSize: "0.875rem"
+        },
+        children: "Try again"
+      }
+    )
+  ] });
+}
+function useDeepTracerErrorReporter(error, severity = "high") {
+  const logger = useContext(DeepTracerContext);
+  useEffect2(() => {
+    if (logger) {
+      logger.captureError(error, {
+        severity,
+        context: { source: "react-error-page" }
+      });
+    }
+  }, [error, logger, severity]);
+}
+var DeepTracerErrorBoundary = class extends Component {
+  static contextType = DeepTracerContext;
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+  componentDidCatch(error, errorInfo) {
+    const logger = this.context;
+    if (logger) {
+      logger.captureError(error, {
+        severity: "high",
+        context: {
+          source: "react-error-boundary",
+          componentStack: errorInfo.componentStack ?? void 0
+        }
+      });
+    } else {
+      console.warn(
+        "[@deeptracer/react] DeepTracerErrorBoundary: No DeepTracerProvider found. Error not reported to DeepTracer."
+      );
+    }
+    this.props.onError?.(error, errorInfo);
+  }
+  resetErrorBoundary = () => {
+    this.setState({ hasError: false, error: null });
+  };
+  render() {
+    if (this.state.hasError && this.state.error) {
+      const { fallback } = this.props;
+      if (typeof fallback === "function") {
+        return fallback({
+          error: this.state.error,
+          resetErrorBoundary: this.resetErrorBoundary
+        });
+      }
+      if (fallback) {
+        return fallback;
+      }
+      return /* @__PURE__ */ jsxs("div", { style: { padding: "2rem", fontFamily: "system-ui, sans-serif" }, children: [
+        /* @__PURE__ */ jsx2("h2", { style: { marginBottom: "1rem" }, children: "Something went wrong" }),
+        /* @__PURE__ */ jsx2("p", { style: { color: "#666", marginBottom: "1.5rem" }, children: this.state.error.message || "An unexpected error occurred." }),
+        /* @__PURE__ */ jsx2(
+          "button",
+          {
+            onClick: this.resetErrorBoundary,
+            style: {
+              padding: "0.5rem 1rem",
+              borderRadius: "0.375rem",
+              border: "1px solid #ccc",
+              background: "#fff",
+              cursor: "pointer",
+              fontSize: "0.875rem"
+            },
+            children: "Try again"
+          }
+        )
+      ] });
+    }
+    return this.props.children;
+  }
+};
+
+// src/hooks.ts
+import { useContext as useContext2 } from "react";
+function useLogger() {
+  const logger = useContext2(DeepTracerContext);
+  if (!logger) {
+    throw new Error(
+      "[@deeptracer/react] useLogger() must be used inside a <DeepTracerProvider>. Wrap your app with <DeepTracerProvider config={{...}}>."
+    );
+  }
+  return logger;
+}
+export {
+  DeepTracerErrorBoundary,
+  DeepTracerErrorPage,
+  DeepTracerProvider,
+  useDeepTracerErrorReporter,
+  useLogger
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deeptracer/react",
-  "version": "0.2.0",
-  "description": "DeepTracer React integration — error boundaries and hooks (coming soon)",
+  "version": "0.3.1",
+  "description": "DeepTracer React integration — provider, error boundary, and hooks for automatic error capture",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -13,9 +13,18 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "sideEffects": false,
-  "keywords": ["deeptracer", "react", "error-boundary"],
+  "keywords": [
+    "deeptracer",
+    "react",
+    "error-boundary",
+    "observability",
+    "hooks"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/getdeeptracer/deeptracer-js.git",
@@ -23,13 +32,18 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@deeptracer/browser": "0.2.0"
+    "@deeptracer/browser": "0.3.1"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3"
   }
 }