@kharko/dozor-react 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,340 @@
+# @kharko/dozor-react
+
+React bindings for [`@kharko/dozor`](https://www.npmjs.com/package/@kharko/dozor) — the session recording SDK for [Kharko Dozor](https://github.com/kolia-zamnius/kharko-dozor).
+
+Provides a `<DozorProvider>` and a `useDozor()` hook to control the recorder from any React component with reactive state updates. Compatible with React 18+ and React Server Components (RSC).
+
+## Install
+
+```bash
+npm install @kharko/dozor @kharko/dozor-react
+# or
+pnpm add @kharko/dozor @kharko/dozor-react
+# or
+yarn add @kharko/dozor @kharko/dozor-react
+```
+
+Both packages are required — `@kharko/dozor` is the core SDK, `@kharko/dozor-react` provides the React integration.
+
+## Quick start
+
+Wrap your app (or a subtree) with `<DozorProvider>` and pass your API key via the `options` prop:
+
+```tsx
+import { DozorProvider } from "@kharko/dozor-react";
+
+function App() {
+  return (
+    <DozorProvider options={{ apiKey: "dp_your_public_key" }}>
+      <YourApp />
+    </DozorProvider>
+  );
+}
+```
+
+Recording starts automatically on mount. That's it — no extra code needed for basic usage.
+
+## API
+
+### `<DozorProvider>`
+
+React Context provider that manages the `Dozor` singleton. Must wrap any component that calls `useDozor()`.
+
+```tsx
+<DozorProvider options={dozorOptions}>
+  {children}
+</DozorProvider>
+```
+
+#### Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `options` | `DozorOptions` | No | Pass to auto-initialize Dozor on mount. Omit for manual `init()` via the hook. |
+| `children` | `ReactNode` | Yes | Child components that can access `useDozor()`. |
+
+#### `DozorOptions`
+
+All options from `@kharko/dozor` are supported:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | **required** | Public project API key (`dp_...`). |
+| `endpoint` | `string` | `https://dozor.kharko.dev/api/ingest` | Ingest endpoint URL. |
+| `flushInterval` | `number` | `10000` | Flush interval in ms. |
+| `batchSize` | `number` | `500` | Max events before auto-flush. |
+| `autoStart` | `boolean` | `true` | Start recording on init. |
+| `hold` | `boolean` | `false` | Start with transport held (buffer events without sending). |
+| `userId` | `string` | — | Stable user identifier for cross-session analytics. |
+| `pauseOnHidden` | `boolean` | `true` | Auto-pause recording when the tab is hidden, resume when visible. |
+| `recordConsole` | `boolean` | `true` | Record console.log/warn/error/info/debug calls. Viewable in the dashboard replay. |
+
+#### Auto-init vs manual init
+
+**Auto-init** — pass `options` to start recording on mount:
+
+```tsx
+<DozorProvider options={{ apiKey: "dp_your_key" }}>
+```
+
+**Manual init** — omit `options` and call `init()` from a component:
+
+```tsx
+<DozorProvider>
+  <ManualInitComponent />
+</DozorProvider>
+
+function ManualInitComponent() {
+  const dozor = useDozor();
+
+  function handleStart() {
+    dozor.init({ apiKey: "dp_your_key" });
+  }
+
+  return <button onClick={handleStart}>Start recording</button>;
+}
+```
+
+### `useDozor()`
+
+Hook that returns the current recorder state and control methods. Must be used within a `<DozorProvider>`.
+
+```ts
+import { useDozor } from "@kharko/dozor-react";
+
+function MyComponent() {
+  const dozor = useDozor();
+  // dozor.state, dozor.isRecording, dozor.hold(), etc.
+}
+```
+
+Throws an error if called outside of `<DozorProvider>`.
+
+#### Returned properties
+
+All properties are reactive — they update automatically when the recorder state changes.
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `DozorContextState` | Current state: `"not_initialized"`, `"idle"`, `"recording"`, `"paused"`, or `"stopped"`. |
+| `sessionId` | `string \| null` | Current session ID (UUID v4), or `null` before init. |
+| `isRecording` | `boolean` | `true` when actively recording. |
+| `isPaused` | `boolean` | `true` when paused via `pause()`. |
+| `isHeld` | `boolean` | `true` when transport is held — events are buffered but not sent. |
+| `userId` | `string \| null` | Current user ID, or `null` if not set. |
+| `bufferSize` | `number` | Number of events currently buffered in memory (not yet sent). Useful for monitoring buffer growth during `hold()`. |
+
+> **Note:** `state` includes `"not_initialized"` which doesn't exist in the core SDK — it indicates that `init()` hasn't been called yet.
+>
+> **Note:** `bufferSize` is synced after each method call. It does not update in real-time as rrweb emits events — it reflects the value at the last state sync.
+
+#### Returned methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `init` | `(options: DozorOptions) => void` | Initialize the recorder. No-op if already initialized. |
+| `start` | `() => void` | Start recording (only when `autoStart: false`). |
+| `pause` | `() => void` | Pause recording. Keeps session and buffer alive. |
+| `resume` | `() => void` | Resume recording after a pause. |
+| `stop` | `() => void` | Stop recording, flush all events (even if held), destroy instance. |
+| `cancel` | `() => void` | Discard session — drop buffer, delete from server, destroy instance. |
+| `hold` | `() => void` | Hold transport — recording continues but events are buffered without sending. |
+| `release` | `(options?: { discard?: boolean }) => void` | Release transport hold. Flushes buffer by default, or pass `{ discard: true }` to drop held events. |
+| `setUserId` | `(id: string) => void` | Set or update the user ID. Triggers metadata re-send if needed. |
+
+## Use cases
+
+### Basic recording
+
+```tsx
+import { DozorProvider } from "@kharko/dozor-react";
+
+export default function RootLayout({ children }) {
+  return (
+    <DozorProvider options={{ apiKey: "dp_your_key" }}>
+      {children}
+    </DozorProvider>
+  );
+}
+```
+
+### Conditional recording
+
+Record a session but only send it if the user completes a valuable action.
+
+```tsx
+function CheckoutFlow() {
+  const dozor = useDozor();
+
+  async function handlePurchase() {
+    await submitOrder();
+    dozor.release(); // session was valuable — send it
+  }
+
+  function handleAbandon() {
+    dozor.cancel(); // session was not valuable — discard it
+  }
+
+  return (
+    <>
+      <button onClick={handlePurchase}>Complete purchase</button>
+      <button onClick={handleAbandon}>Leave</button>
+    </>
+  );
+}
+
+// In layout: start with hold so nothing is sent until release()
+<DozorProvider options={{ apiKey: "dp_your_key", hold: true }}>
+  <CheckoutFlow />
+</DozorProvider>
+```
+
+### Network-aware buffering
+
+Pause sending during heavy network activity.
+
+```tsx
+function DataLoader() {
+  const dozor = useDozor();
+
+  async function loadEverything() {
+    dozor.hold();
+    await Promise.all([fetchUsers(), fetchProducts(), fetchOrders()]);
+    dozor.release(); // resume sending, flush what accumulated
+  }
+
+  return <button onClick={loadEverything}>Load data</button>;
+}
+```
+
+### Identify users after login
+
+```tsx
+function LoginForm() {
+  const dozor = useDozor();
+
+  async function handleLogin(credentials) {
+    const user = await login(credentials);
+    dozor.setUserId(user.id); // link this session to the user
+  }
+
+  return <form onSubmit={handleLogin}>...</form>;
+}
+```
+
+Or, if the user is known at mount time:
+
+```tsx
+<DozorProvider options={{ apiKey: "dp_your_key", userId: currentUser.id }}>
+```
+
+### Deferred start
+
+Start recording only when the user enters a specific section.
+
+```tsx
+function RecordingGate({ children }) {
+  const dozor = useDozor();
+
+  useEffect(() => {
+    dozor.init({ apiKey: "dp_your_key", autoStart: false });
+  }, []);
+
+  return (
+    <>
+      <button onClick={() => dozor.start()}>Start recording</button>
+      <button onClick={() => dozor.stop()}>Stop recording</button>
+      {children}
+    </>
+  );
+}
+```
+
+### Pause during sensitive input
+
+```tsx
+function CreditCardForm() {
+  const dozor = useDozor();
+
+  return (
+    <div
+      onFocus={() => dozor.pause()}
+      onBlur={() => dozor.resume()}
+    >
+      <input type="text" placeholder="Card number" />
+    </div>
+  );
+}
+```
+
+### Status indicator
+
+```tsx
+function RecordingStatus() {
+  const { state, isHeld, sessionId } = useDozor();
+
+  return (
+    <div>
+      <span>State: {state}</span>
+      {isHeld && <span> (transport held)</span>}
+      {sessionId && <span> | Session: {sessionId}</span>}
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+| Scenario | Behavior |
+|---|---|
+| `useDozor()` outside `<DozorProvider>` | Throws: `"useDozor must be used within a <DozorProvider>"`. |
+| `init()` called multiple times | Returns existing singleton. Does not re-initialize. |
+| `start()` when already recording | No-op. |
+| `pause()` when not recording | No-op. |
+| `resume()` when not paused | No-op. |
+| `stop()` when already stopped | No-op. |
+| `cancel()` when already stopped | No-op. |
+| `hold()` when already held | No-op. |
+| `hold()` when stopped | No-op. |
+| `release()` when not held | No-op. |
+| `stop()` while held | Releases hold, flushes all events, destroys instance. |
+| `cancel()` while held | Drops buffer, deletes session. |
+| Methods called before `init()` | No-op (safely ignored via optional chaining). |
+| `<DozorProvider>` unmounts | Provider unmounts but the Dozor singleton persists until `stop()` or `cancel()` is called. |
+| Multiple `<DozorProvider>` instances | Both reference the same singleton. Avoid this — use one provider at the app root. |
+| React Server Components | Safe — the `"use client"` directive is bundled into the package output. Only use `<DozorProvider>` and `useDozor()` in client components. |
+| Next.js App Router | Place `<DozorProvider>` in a client component (e.g., `providers.tsx`) that wraps your layout. |
+| Tab hidden with `pauseOnHidden: true` (default) | Recording pauses automatically, `isPaused` becomes `true`. Resumes when the tab is visible again. |
+| Tab hidden after manual `pause()` | Auto-resume does **not** override manual pause. Only `resume()` can resume. |
+| React Strict Mode (dev) | `useEffect` runs twice in development. The provider handles this — `init()` is idempotent. |
+
+## TypeScript
+
+The package exports all types needed for typed usage:
+
+```ts
+import type { DozorContextValue, DozorContextState } from "@kharko/dozor-react";
+import type { DozorOptions, DozorState } from "@kharko/dozor";
+```
+
+### `DozorContextState`
+
+```ts
+type DozorContextState = DozorState | "not_initialized";
+// = "not_initialized" | "idle" | "recording" | "paused" | "stopped"
+```
+
+### `DozorContextValue`
+
+Full type of the object returned by `useDozor()`. See [Returned properties](#returned-properties) and [Returned methods](#returned-methods) above.
+
+## Peer dependencies
+
+| Package | Version |
+|---|---|
+| `@kharko/dozor` | `*` |
+| `react` | `>=18` |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -35,15 +35,24 @@ function DozorProvider({ options, children }) {
   const instanceRef = (0, import_react.useRef)(null);
   const [state, setState] = (0, import_react.useState)("not_initialized");
   const [sessionId, setSessionId] = (0, import_react.useState)(null);
+  const [isHeld, setIsHeld] = (0, import_react.useState)(false);
+  const [userId, setUserIdState] = (0, import_react.useState)(null);
+  const [bufferSize, setBufferSize] = (0, import_react.useState)(0);
   const syncState = (0, import_react.useCallback)(() => {
     const d = instanceRef.current;
     if (!d) {
       setState("not_initialized");
       setSessionId(null);
+      setIsHeld(false);
+      setUserIdState(null);
+      setBufferSize(0);
       return;
     }
     setState(d.state);
     setSessionId(d.sessionId);
+    setIsHeld(d.isHeld);
+    setUserIdState(d.userId);
+    setBufferSize(d.bufferSize);
   }, []);
   const init = (0, import_react.useCallback)(
     (opts) => {
@@ -75,22 +84,51 @@ function DozorProvider({ options, children }) {
     instanceRef.current = null;
     syncState();
   }, [syncState]);
+  const hold = (0, import_react.useCallback)(() => {
+    instanceRef.current?.hold();
+    syncState();
+  }, [syncState]);
+  const release = (0, import_react.useCallback)(
+    (options2) => {
+      instanceRef.current?.release(options2);
+      syncState();
+    },
+    [syncState]
+  );
+  const setUserId = (0, import_react.useCallback)(
+    (id) => {
+      instanceRef.current?.setUserId(id);
+      syncState();
+    },
+    [syncState]
+  );
   (0, import_react.useEffect)(() => {
     if (options && !instanceRef.current) {
       init(options);
     }
   }, []);
+  (0, import_react.useEffect)(() => {
+    const handler = () => syncState();
+    addEventListener("visibilitychange", handler);
+    return () => removeEventListener("visibilitychange", handler);
+  }, [syncState]);
   const value = {
     state,
     sessionId,
     isRecording: state === "recording",
     isPaused: state === "paused",
+    isHeld,
+    userId,
+    bufferSize,
     init,
     start,
     pause,
     resume,
     stop,
-    cancel
+    cancel,
+    hold,
+    release,
+    setUserId
   };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DozorContext.Provider, { value, children });
 }

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/dozor-context.tsx","../src/use-dozor.ts"],"sourcesContent":["export { DozorProvider } from \"./dozor-context.js\";\nexport { useDozor } from \"./use-dozor.js\";\nexport type { DozorContextValue, DozorContextState } from \"./dozor-context.js\";\n","import { createContext, useCallback, useRef, useState, useEffect, type ReactNode } from \"react\";\nimport { Dozor } from \"@kharko/dozor\";\nimport type { DozorOptions, DozorState } from \"@kharko/dozor\";\n\nexport type DozorContextState = DozorState | \"not_initialized\";\n\nexport interface DozorContextValue {\n  /** Current lifecycle state. `\"not_initialized\"` when `init()` hasn't been called yet. */\n  state: DozorContextState;\n  /** Current session ID, or `null` before init. */\n  sessionId: string | null;\n  /** `true` when actively recording. */\n  isRecording: boolean;\n  /** `true` when paused via `pause()`. */\n  isPaused: boolean;\n\n  /** Initialize the Dozor recorder. No-op if already initialized. */\n  init: (options: DozorOptions) => void;\n  /** Start recording (only when `autoStart: false`). */\n  start: () => void;\n  /** Pause recording without destroying the session. */\n  pause: () => void;\n  /** Resume recording after a pause. */\n  resume: () => void;\n  /** Stop recording, flush remaining events, destroy instance. */\n  stop: () => void;\n  /** Discard session — drop buffer + delete from server. */\n  cancel: () => void;\n}\n\nexport const DozorContext = createContext<DozorContextValue | null>(null);\n\ninterface DozorProviderProps {\n  /** Pass options to auto-initialize Dozor on mount. Omit for manual `init()`. */\n  options?: DozorOptions;\n  children: ReactNode;\n}\n\nexport function DozorProvider({ options, children }: DozorProviderProps) {\n  const instanceRef = useRef<Dozor | null>(null);\n\n  const [state, setState] = useState<DozorContextState>(\"not_initialized\");\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  /** Read current values from the Dozor instance and sync to React state. */\n  const syncState = useCallback(() => {\n    const d = instanceRef.current;\n    if (!d) {\n      setState(\"not_initialized\");\n      setSessionId(null);\n      return;\n    }\n    setState(d.state);\n    setSessionId(d.sessionId);\n  }, []);\n\n  const init = useCallback(\n    (opts: DozorOptions) => {\n      if (instanceRef.current) return;\n      instanceRef.current = Dozor.init(opts);\n      syncState();\n    },\n    [syncState],\n  );\n\n  const start = useCallback(() => {\n    instanceRef.current?.start();\n    syncState();\n  }, [syncState]);\n\n  const pause = useCallback(() => {\n    instanceRef.current?.pause();\n    syncState();\n  }, [syncState]);\n\n  const resume = useCallback(() => {\n    instanceRef.current?.resume();\n    syncState();\n  }, [syncState]);\n\n  const stop = useCallback(() => {\n    instanceRef.current?.stop();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  const cancel = useCallback(() => {\n    instanceRef.current?.cancel();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  // Auto-init on mount when options are provided\n  useEffect(() => {\n    if (options && !instanceRef.current) {\n      init(options);\n    }\n  }, []); // eslint-disable-line react-hooks/exhaustive-deps — intentionally run once on mount\n\n  const value: DozorContextValue = {\n    state,\n    sessionId,\n    isRecording: state === \"recording\",\n    isPaused: state === \"paused\",\n    init,\n    start,\n    pause,\n    resume,\n    stop,\n    cancel,\n  };\n\n  return <DozorContext.Provider value={value}>{children}</DozorContext.Provider>;\n}\n","import { useContext } from \"react\";\nimport { DozorContext, type DozorContextValue } from \"./dozor-context.js\";\n\n/**\n * Access the Dozor recorder state and controls.\n * Must be used within a `<DozorProvider>`.\n */\nexport function useDozor(): DozorContextValue {\n  const ctx = useContext(DozorContext);\n  if (!ctx) {\n    throw new Error(\"useDozor must be used within a <DozorProvider>\");\n  }\n  return ctx;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAwF;AACxF,mBAAsB;AA+Gb;AAlFF,IAAM,mBAAe,4BAAwC,IAAI;AAQjE,SAAS,cAAc,EAAE,SAAS,SAAS,GAAuB;AACvE,QAAM,kBAAc,qBAAqB,IAAI;AAE7C,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAA4B,iBAAiB;AACvE,QAAM,CAAC,WAAW,YAAY,QAAI,uBAAwB,IAAI;AAG9D,QAAM,gBAAY,0BAAY,MAAM;AAClC,UAAM,IAAI,YAAY;AACtB,QAAI,CAAC,GAAG;AACN,eAAS,iBAAiB;AAC1B,mBAAa,IAAI;AACjB;AAAA,IACF;AACA,aAAS,EAAE,KAAK;AAChB,iBAAa,EAAE,SAAS;AAAA,EAC1B,GAAG,CAAC,CAAC;AAEL,QAAM,WAAO;AAAA,IACX,CAAC,SAAuB;AACtB,UAAI,YAAY,QAAS;AACzB,kBAAY,UAAU,mBAAM,KAAK,IAAI;AACrC,gBAAU;AAAA,IACZ;AAAA,IACA,CAAC,SAAS;AAAA,EACZ;AAEA,QAAM,YAAQ,0BAAY,MAAM;AAC9B,gBAAY,SAAS,MAAM;AAC3B,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,YAAQ,0BAAY,MAAM;AAC9B,gBAAY,SAAS,MAAM;AAC3B,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,aAAS,0BAAY,MAAM;AAC/B,gBAAY,SAAS,OAAO;AAC5B,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,WAAO,0BAAY,MAAM;AAC7B,gBAAY,SAAS,KAAK;AAC1B,gBAAY,UAAU;AACtB,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,aAAS,0BAAY,MAAM;AAC/B,gBAAY,SAAS,OAAO;AAC5B,gBAAY,UAAU;AACtB,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAGd,8BAAU,MAAM;AACd,QAAI,WAAW,CAAC,YAAY,SAAS;AACnC,WAAK,OAAO;AAAA,IACd;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,QAAM,QAA2B;AAAA,IAC/B;AAAA,IACA;AAAA,IACA,aAAa,UAAU;AAAA,IACvB,UAAU,UAAU;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,SAAO,4CAAC,aAAa,UAAb,EAAsB,OAAe,UAAS;AACxD;;;ACjHA,IAAAA,gBAA2B;AAOpB,SAAS,WAA8B;AAC5C,QAAM,UAAM,0BAAW,YAAY;AACnC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,SAAO;AACT;","names":["import_react"]}
+{"version":3,"sources":["../src/index.ts","../src/dozor-context.tsx","../src/use-dozor.ts"],"sourcesContent":["export { DozorProvider } from \"./dozor-context.js\";\nexport { useDozor } from \"./use-dozor.js\";\nexport type { DozorContextValue, DozorContextState } from \"./dozor-context.js\";\n","import { createContext, useCallback, useRef, useState, useEffect, type ReactNode } from \"react\";\nimport { Dozor } from \"@kharko/dozor\";\nimport type { DozorOptions, DozorState } from \"@kharko/dozor\";\n\nexport type DozorContextState = DozorState | \"not_initialized\";\n\nexport interface DozorContextValue {\n  /** Current lifecycle state. `\"not_initialized\"` when `init()` hasn't been called yet. */\n  state: DozorContextState;\n  /** Current session ID, or `null` before init. */\n  sessionId: string | null;\n  /** `true` when actively recording. */\n  isRecording: boolean;\n  /** `true` when paused via `pause()`. */\n  isPaused: boolean;\n  /** `true` when transport is held — events are buffered locally but not sent. */\n  isHeld: boolean;\n  /** Current user ID, or `null` if not set. */\n  userId: string | null;\n  /** Number of events currently buffered in memory (not yet sent). */\n  bufferSize: number;\n\n  /** Initialize the Dozor recorder. No-op if already initialized. */\n  init: (options: DozorOptions) => void;\n  /** Start recording (only when `autoStart: false`). */\n  start: () => void;\n  /** Pause recording without destroying the session. */\n  pause: () => void;\n  /** Resume recording after a pause. */\n  resume: () => void;\n  /** Stop recording, flush remaining events, destroy instance. */\n  stop: () => void;\n  /** Discard session — drop buffer + delete from server. */\n  cancel: () => void;\n  /** Hold transport — recording continues but events are buffered without sending. */\n  hold: () => void;\n  /** Release transport hold — flush buffered events and resume sending. Pass `{ discard: true }` to drop held events. */\n  release: (options?: { discard?: boolean }) => void;\n  /** Set or update the user ID. Useful when the user logs in after recording has started. */\n  setUserId: (id: string) => void;\n}\n\nexport const DozorContext = createContext<DozorContextValue | null>(null);\n\ninterface DozorProviderProps {\n  /** Pass options to auto-initialize Dozor on mount. Omit for manual `init()`. */\n  options?: DozorOptions;\n  children: ReactNode;\n}\n\nexport function DozorProvider({ options, children }: DozorProviderProps) {\n  const instanceRef = useRef<Dozor | null>(null);\n\n  const [state, setState] = useState<DozorContextState>(\"not_initialized\");\n  const [sessionId, setSessionId] = useState<string | null>(null);\n  const [isHeld, setIsHeld] = useState(false);\n  const [userId, setUserIdState] = useState<string | null>(null);\n  const [bufferSize, setBufferSize] = useState(0);\n\n  /** Read current values from the Dozor instance and sync to React state. */\n  const syncState = useCallback(() => {\n    const d = instanceRef.current;\n    if (!d) {\n      setState(\"not_initialized\");\n      setSessionId(null);\n      setIsHeld(false);\n      setUserIdState(null);\n      setBufferSize(0);\n      return;\n    }\n    setState(d.state);\n    setSessionId(d.sessionId);\n    setIsHeld(d.isHeld);\n    setUserIdState(d.userId);\n    setBufferSize(d.bufferSize);\n  }, []);\n\n  const init = useCallback(\n    (opts: DozorOptions) => {\n      if (instanceRef.current) return;\n      instanceRef.current = Dozor.init(opts);\n      syncState();\n    },\n    [syncState],\n  );\n\n  const start = useCallback(() => {\n    instanceRef.current?.start();\n    syncState();\n  }, [syncState]);\n\n  const pause = useCallback(() => {\n    instanceRef.current?.pause();\n    syncState();\n  }, [syncState]);\n\n  const resume = useCallback(() => {\n    instanceRef.current?.resume();\n    syncState();\n  }, [syncState]);\n\n  const stop = useCallback(() => {\n    instanceRef.current?.stop();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  const cancel = useCallback(() => {\n    instanceRef.current?.cancel();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  const hold = useCallback(() => {\n    instanceRef.current?.hold();\n    syncState();\n  }, [syncState]);\n\n  const release = useCallback(\n    (options?: { discard?: boolean }) => {\n      instanceRef.current?.release(options);\n      syncState();\n    },\n    [syncState],\n  );\n\n  const setUserId = useCallback(\n    (id: string) => {\n      instanceRef.current?.setUserId(id);\n      syncState();\n    },\n    [syncState],\n  );\n\n  // Auto-init on mount when options are provided\n  useEffect(() => {\n    if (options && !instanceRef.current) {\n      init(options);\n    }\n  }, []); // eslint-disable-line react-hooks/exhaustive-deps — intentionally run once on mount\n\n  // Sync React state when the tab visibility changes (the core SDK may auto-pause/resume internally)\n  useEffect(() => {\n    const handler = () => syncState();\n    addEventListener(\"visibilitychange\", handler);\n    return () => removeEventListener(\"visibilitychange\", handler);\n  }, [syncState]);\n\n  const value: DozorContextValue = {\n    state,\n    sessionId,\n    isRecording: state === \"recording\",\n    isPaused: state === \"paused\",\n    isHeld,\n    userId,\n    bufferSize,\n    init,\n    start,\n    pause,\n    resume,\n    stop,\n    cancel,\n    hold,\n    release,\n    setUserId,\n  };\n\n  return <DozorContext.Provider value={value}>{children}</DozorContext.Provider>;\n}\n","import { useContext } from \"react\";\nimport { DozorContext, type DozorContextValue } from \"./dozor-context.js\";\n\n/**\n * Access the Dozor recorder state and controls.\n * Must be used within a `<DozorProvider>`.\n */\nexport function useDozor(): DozorContextValue {\n  const ctx = useContext(DozorContext);\n  if (!ctx) {\n    throw new Error(\"useDozor must be used within a <DozorProvider>\");\n  }\n  return ctx;\n}\n"],"mappings":"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","names":["options","import_react"]}

package/dist/index.d.cts

@@ -12,6 +12,12 @@ interface DozorContextValue {
     isRecording: boolean;
     /** `true` when paused via `pause()`. */
     isPaused: boolean;
+    /** `true` when transport is held — events are buffered locally but not sent. */
+    isHeld: boolean;
+    /** Current user ID, or `null` if not set. */
+    userId: string | null;
+    /** Number of events currently buffered in memory (not yet sent). */
+    bufferSize: number;
     /** Initialize the Dozor recorder. No-op if already initialized. */
     init: (options: DozorOptions) => void;
     /** Start recording (only when `autoStart: false`). */
@@ -24,6 +30,14 @@ interface DozorContextValue {
     stop: () => void;
     /** Discard session — drop buffer + delete from server. */
     cancel: () => void;
+    /** Hold transport — recording continues but events are buffered without sending. */
+    hold: () => void;
+    /** Release transport hold — flush buffered events and resume sending. Pass `{ discard: true }` to drop held events. */
+    release: (options?: {
+        discard?: boolean;
+    }) => void;
+    /** Set or update the user ID. Useful when the user logs in after recording has started. */
+    setUserId: (id: string) => void;
 }
 interface DozorProviderProps {
     /** Pass options to auto-initialize Dozor on mount. Omit for manual `init()`. */

package/dist/index.d.ts

@@ -12,6 +12,12 @@ interface DozorContextValue {
     isRecording: boolean;
     /** `true` when paused via `pause()`. */
     isPaused: boolean;
+    /** `true` when transport is held — events are buffered locally but not sent. */
+    isHeld: boolean;
+    /** Current user ID, or `null` if not set. */
+    userId: string | null;
+    /** Number of events currently buffered in memory (not yet sent). */
+    bufferSize: number;
     /** Initialize the Dozor recorder. No-op if already initialized. */
     init: (options: DozorOptions) => void;
     /** Start recording (only when `autoStart: false`). */
@@ -24,6 +30,14 @@ interface DozorContextValue {
     stop: () => void;
     /** Discard session — drop buffer + delete from server. */
     cancel: () => void;
+    /** Hold transport — recording continues but events are buffered without sending. */
+    hold: () => void;
+    /** Release transport hold — flush buffered events and resume sending. Pass `{ discard: true }` to drop held events. */
+    release: (options?: {
+        discard?: boolean;
+    }) => void;
+    /** Set or update the user ID. Useful when the user logs in after recording has started. */
+    setUserId: (id: string) => void;
 }
 interface DozorProviderProps {
     /** Pass options to auto-initialize Dozor on mount. Omit for manual `init()`. */

package/dist/index.js

@@ -9,15 +9,24 @@ function DozorProvider({ options, children }) {
   const instanceRef = useRef(null);
   const [state, setState] = useState("not_initialized");
   const [sessionId, setSessionId] = useState(null);
+  const [isHeld, setIsHeld] = useState(false);
+  const [userId, setUserIdState] = useState(null);
+  const [bufferSize, setBufferSize] = useState(0);
   const syncState = useCallback(() => {
     const d = instanceRef.current;
     if (!d) {
       setState("not_initialized");
       setSessionId(null);
+      setIsHeld(false);
+      setUserIdState(null);
+      setBufferSize(0);
       return;
     }
     setState(d.state);
     setSessionId(d.sessionId);
+    setIsHeld(d.isHeld);
+    setUserIdState(d.userId);
+    setBufferSize(d.bufferSize);
   }, []);
   const init = useCallback(
     (opts) => {
@@ -49,22 +58,51 @@ function DozorProvider({ options, children }) {
     instanceRef.current = null;
     syncState();
   }, [syncState]);
+  const hold = useCallback(() => {
+    instanceRef.current?.hold();
+    syncState();
+  }, [syncState]);
+  const release = useCallback(
+    (options2) => {
+      instanceRef.current?.release(options2);
+      syncState();
+    },
+    [syncState]
+  );
+  const setUserId = useCallback(
+    (id) => {
+      instanceRef.current?.setUserId(id);
+      syncState();
+    },
+    [syncState]
+  );
   useEffect(() => {
     if (options && !instanceRef.current) {
       init(options);
     }
   }, []);
+  useEffect(() => {
+    const handler = () => syncState();
+    addEventListener("visibilitychange", handler);
+    return () => removeEventListener("visibilitychange", handler);
+  }, [syncState]);
   const value = {
     state,
     sessionId,
     isRecording: state === "recording",
     isPaused: state === "paused",
+    isHeld,
+    userId,
+    bufferSize,
     init,
     start,
     pause,
     resume,
     stop,
-    cancel
+    cancel,
+    hold,
+    release,
+    setUserId
   };
   return /* @__PURE__ */ jsx(DozorContext.Provider, { value, children });
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/dozor-context.tsx","../src/use-dozor.ts"],"sourcesContent":["import { createContext, useCallback, useRef, useState, useEffect, type ReactNode } from \"react\";\nimport { Dozor } from \"@kharko/dozor\";\nimport type { DozorOptions, DozorState } from \"@kharko/dozor\";\n\nexport type DozorContextState = DozorState | \"not_initialized\";\n\nexport interface DozorContextValue {\n  /** Current lifecycle state. `\"not_initialized\"` when `init()` hasn't been called yet. */\n  state: DozorContextState;\n  /** Current session ID, or `null` before init. */\n  sessionId: string | null;\n  /** `true` when actively recording. */\n  isRecording: boolean;\n  /** `true` when paused via `pause()`. */\n  isPaused: boolean;\n\n  /** Initialize the Dozor recorder. No-op if already initialized. */\n  init: (options: DozorOptions) => void;\n  /** Start recording (only when `autoStart: false`). */\n  start: () => void;\n  /** Pause recording without destroying the session. */\n  pause: () => void;\n  /** Resume recording after a pause. */\n  resume: () => void;\n  /** Stop recording, flush remaining events, destroy instance. */\n  stop: () => void;\n  /** Discard session — drop buffer + delete from server. */\n  cancel: () => void;\n}\n\nexport const DozorContext = createContext<DozorContextValue | null>(null);\n\ninterface DozorProviderProps {\n  /** Pass options to auto-initialize Dozor on mount. Omit for manual `init()`. */\n  options?: DozorOptions;\n  children: ReactNode;\n}\n\nexport function DozorProvider({ options, children }: DozorProviderProps) {\n  const instanceRef = useRef<Dozor | null>(null);\n\n  const [state, setState] = useState<DozorContextState>(\"not_initialized\");\n  const [sessionId, setSessionId] = useState<string | null>(null);\n\n  /** Read current values from the Dozor instance and sync to React state. */\n  const syncState = useCallback(() => {\n    const d = instanceRef.current;\n    if (!d) {\n      setState(\"not_initialized\");\n      setSessionId(null);\n      return;\n    }\n    setState(d.state);\n    setSessionId(d.sessionId);\n  }, []);\n\n  const init = useCallback(\n    (opts: DozorOptions) => {\n      if (instanceRef.current) return;\n      instanceRef.current = Dozor.init(opts);\n      syncState();\n    },\n    [syncState],\n  );\n\n  const start = useCallback(() => {\n    instanceRef.current?.start();\n    syncState();\n  }, [syncState]);\n\n  const pause = useCallback(() => {\n    instanceRef.current?.pause();\n    syncState();\n  }, [syncState]);\n\n  const resume = useCallback(() => {\n    instanceRef.current?.resume();\n    syncState();\n  }, [syncState]);\n\n  const stop = useCallback(() => {\n    instanceRef.current?.stop();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  const cancel = useCallback(() => {\n    instanceRef.current?.cancel();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  // Auto-init on mount when options are provided\n  useEffect(() => {\n    if (options && !instanceRef.current) {\n      init(options);\n    }\n  }, []); // eslint-disable-line react-hooks/exhaustive-deps — intentionally run once on mount\n\n  const value: DozorContextValue = {\n    state,\n    sessionId,\n    isRecording: state === \"recording\",\n    isPaused: state === \"paused\",\n    init,\n    start,\n    pause,\n    resume,\n    stop,\n    cancel,\n  };\n\n  return <DozorContext.Provider value={value}>{children}</DozorContext.Provider>;\n}\n","import { useContext } from \"react\";\nimport { DozorContext, type DozorContextValue } from \"./dozor-context.js\";\n\n/**\n * Access the Dozor recorder state and controls.\n * Must be used within a `<DozorProvider>`.\n */\nexport function useDozor(): DozorContextValue {\n  const ctx = useContext(DozorContext);\n  if (!ctx) {\n    throw new Error(\"useDozor must be used within a <DozorProvider>\");\n  }\n  return ctx;\n}\n"],"mappings":";;;AAAA,SAAS,eAAe,aAAa,QAAQ,UAAU,iBAAiC;AACxF,SAAS,aAAa;AA+Gb;AAlFF,IAAM,eAAe,cAAwC,IAAI;AAQjE,SAAS,cAAc,EAAE,SAAS,SAAS,GAAuB;AACvE,QAAM,cAAc,OAAqB,IAAI;AAE7C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAA4B,iBAAiB;AACvE,QAAM,CAAC,WAAW,YAAY,IAAI,SAAwB,IAAI;AAG9D,QAAM,YAAY,YAAY,MAAM;AAClC,UAAM,IAAI,YAAY;AACtB,QAAI,CAAC,GAAG;AACN,eAAS,iBAAiB;AAC1B,mBAAa,IAAI;AACjB;AAAA,IACF;AACA,aAAS,EAAE,KAAK;AAChB,iBAAa,EAAE,SAAS;AAAA,EAC1B,GAAG,CAAC,CAAC;AAEL,QAAM,OAAO;AAAA,IACX,CAAC,SAAuB;AACtB,UAAI,YAAY,QAAS;AACzB,kBAAY,UAAU,MAAM,KAAK,IAAI;AACrC,gBAAU;AAAA,IACZ;AAAA,IACA,CAAC,SAAS;AAAA,EACZ;AAEA,QAAM,QAAQ,YAAY,MAAM;AAC9B,gBAAY,SAAS,MAAM;AAC3B,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,QAAQ,YAAY,MAAM;AAC9B,gBAAY,SAAS,MAAM;AAC3B,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,SAAS,YAAY,MAAM;AAC/B,gBAAY,SAAS,OAAO;AAC5B,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,OAAO,YAAY,MAAM;AAC7B,gBAAY,SAAS,KAAK;AAC1B,gBAAY,UAAU;AACtB,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAEd,QAAM,SAAS,YAAY,MAAM;AAC/B,gBAAY,SAAS,OAAO;AAC5B,gBAAY,UAAU;AACtB,cAAU;AAAA,EACZ,GAAG,CAAC,SAAS,CAAC;AAGd,YAAU,MAAM;AACd,QAAI,WAAW,CAAC,YAAY,SAAS;AACnC,WAAK,OAAO;AAAA,IACd;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,QAAM,QAA2B;AAAA,IAC/B;AAAA,IACA;AAAA,IACA,aAAa,UAAU;AAAA,IACvB,UAAU,UAAU;AAAA,IACpB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,SAAO,oBAAC,aAAa,UAAb,EAAsB,OAAe,UAAS;AACxD;;;ACjHA,SAAS,kBAAkB;AAOpB,SAAS,WAA8B;AAC5C,QAAM,MAAM,WAAW,YAAY;AACnC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/dozor-context.tsx","../src/use-dozor.ts"],"sourcesContent":["import { createContext, useCallback, useRef, useState, useEffect, type ReactNode } from \"react\";\nimport { Dozor } from \"@kharko/dozor\";\nimport type { DozorOptions, DozorState } from \"@kharko/dozor\";\n\nexport type DozorContextState = DozorState | \"not_initialized\";\n\nexport interface DozorContextValue {\n  /** Current lifecycle state. `\"not_initialized\"` when `init()` hasn't been called yet. */\n  state: DozorContextState;\n  /** Current session ID, or `null` before init. */\n  sessionId: string | null;\n  /** `true` when actively recording. */\n  isRecording: boolean;\n  /** `true` when paused via `pause()`. */\n  isPaused: boolean;\n  /** `true` when transport is held — events are buffered locally but not sent. */\n  isHeld: boolean;\n  /** Current user ID, or `null` if not set. */\n  userId: string | null;\n  /** Number of events currently buffered in memory (not yet sent). */\n  bufferSize: number;\n\n  /** Initialize the Dozor recorder. No-op if already initialized. */\n  init: (options: DozorOptions) => void;\n  /** Start recording (only when `autoStart: false`). */\n  start: () => void;\n  /** Pause recording without destroying the session. */\n  pause: () => void;\n  /** Resume recording after a pause. */\n  resume: () => void;\n  /** Stop recording, flush remaining events, destroy instance. */\n  stop: () => void;\n  /** Discard session — drop buffer + delete from server. */\n  cancel: () => void;\n  /** Hold transport — recording continues but events are buffered without sending. */\n  hold: () => void;\n  /** Release transport hold — flush buffered events and resume sending. Pass `{ discard: true }` to drop held events. */\n  release: (options?: { discard?: boolean }) => void;\n  /** Set or update the user ID. Useful when the user logs in after recording has started. */\n  setUserId: (id: string) => void;\n}\n\nexport const DozorContext = createContext<DozorContextValue | null>(null);\n\ninterface DozorProviderProps {\n  /** Pass options to auto-initialize Dozor on mount. Omit for manual `init()`. */\n  options?: DozorOptions;\n  children: ReactNode;\n}\n\nexport function DozorProvider({ options, children }: DozorProviderProps) {\n  const instanceRef = useRef<Dozor | null>(null);\n\n  const [state, setState] = useState<DozorContextState>(\"not_initialized\");\n  const [sessionId, setSessionId] = useState<string | null>(null);\n  const [isHeld, setIsHeld] = useState(false);\n  const [userId, setUserIdState] = useState<string | null>(null);\n  const [bufferSize, setBufferSize] = useState(0);\n\n  /** Read current values from the Dozor instance and sync to React state. */\n  const syncState = useCallback(() => {\n    const d = instanceRef.current;\n    if (!d) {\n      setState(\"not_initialized\");\n      setSessionId(null);\n      setIsHeld(false);\n      setUserIdState(null);\n      setBufferSize(0);\n      return;\n    }\n    setState(d.state);\n    setSessionId(d.sessionId);\n    setIsHeld(d.isHeld);\n    setUserIdState(d.userId);\n    setBufferSize(d.bufferSize);\n  }, []);\n\n  const init = useCallback(\n    (opts: DozorOptions) => {\n      if (instanceRef.current) return;\n      instanceRef.current = Dozor.init(opts);\n      syncState();\n    },\n    [syncState],\n  );\n\n  const start = useCallback(() => {\n    instanceRef.current?.start();\n    syncState();\n  }, [syncState]);\n\n  const pause = useCallback(() => {\n    instanceRef.current?.pause();\n    syncState();\n  }, [syncState]);\n\n  const resume = useCallback(() => {\n    instanceRef.current?.resume();\n    syncState();\n  }, [syncState]);\n\n  const stop = useCallback(() => {\n    instanceRef.current?.stop();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  const cancel = useCallback(() => {\n    instanceRef.current?.cancel();\n    instanceRef.current = null;\n    syncState();\n  }, [syncState]);\n\n  const hold = useCallback(() => {\n    instanceRef.current?.hold();\n    syncState();\n  }, [syncState]);\n\n  const release = useCallback(\n    (options?: { discard?: boolean }) => {\n      instanceRef.current?.release(options);\n      syncState();\n    },\n    [syncState],\n  );\n\n  const setUserId = useCallback(\n    (id: string) => {\n      instanceRef.current?.setUserId(id);\n      syncState();\n    },\n    [syncState],\n  );\n\n  // Auto-init on mount when options are provided\n  useEffect(() => {\n    if (options && !instanceRef.current) {\n      init(options);\n    }\n  }, []); // eslint-disable-line react-hooks/exhaustive-deps — intentionally run once on mount\n\n  // Sync React state when the tab visibility changes (the core SDK may auto-pause/resume internally)\n  useEffect(() => {\n    const handler = () => syncState();\n    addEventListener(\"visibilitychange\", handler);\n    return () => removeEventListener(\"visibilitychange\", handler);\n  }, [syncState]);\n\n  const value: DozorContextValue = {\n    state,\n    sessionId,\n    isRecording: state === \"recording\",\n    isPaused: state === \"paused\",\n    isHeld,\n    userId,\n    bufferSize,\n    init,\n    start,\n    pause,\n    resume,\n    stop,\n    cancel,\n    hold,\n    release,\n    setUserId,\n  };\n\n  return <DozorContext.Provider value={value}>{children}</DozorContext.Provider>;\n}\n","import { useContext } from \"react\";\nimport { DozorContext, type DozorContextValue } from \"./dozor-context.js\";\n\n/**\n * Access the Dozor recorder state and controls.\n * Must be used within a `<DozorProvider>`.\n */\nexport function useDozor(): DozorContextValue {\n  const ctx = useContext(DozorContext);\n  if (!ctx) {\n    throw new Error(\"useDozor must be used within a <DozorProvider>\");\n  }\n  return ctx;\n}\n"],"mappings":"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","names":["options"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kharko/dozor-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React bindings for @kharko/dozor session recording SDK",
   "license": "MIT",
   "type": "module",