@obsrviq/react 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obsrviq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ObsrviqInitConfig } from '@obsrviq/types';
+
+/** The public surface of the Obsrviq client (the singleton structurally satisfies it). */
+interface ObsrviqClient {
+    readonly sessionId: string | null;
+    init(config: ObsrviqInitConfig): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    setMetadata(props: Record<string, unknown>): void;
+    reset(): void;
+    track(name: string, props?: Record<string, unknown>): void;
+    /** Mark a client-defined conversion by name (e.g. "checkout", "signup"). */
+    conversion(name: string, props?: Record<string, unknown>): void;
+    /** Attach free-form, searchable labels to the current session. */
+    tag(...names: string[]): void;
+    /** Open a named sub-event span; returns a handle whose end() closes it. */
+    startTask(name: string, props?: Record<string, unknown>): {
+        end: (endProps?: Record<string, unknown>) => void;
+    };
+    /** Close a named sub-event span opened by startTask(name). */
+    endTask(name: string, props?: Record<string, unknown>): void;
+    setConsent(granted: boolean): void;
+    flush(): Promise<boolean>;
+    stop(): void;
+}
+interface ObsrviqProviderProps extends Omit<ObsrviqInitConfig, 'userId' | 'metadata'> {
+    /** Raw application user id. Re-applied via identify() whenever it changes
+     *  (e.g. it resolves after login). */
+    userId?: string;
+    /** Session metadata. Re-merged via setMetadata() whenever it changes. */
+    metadata?: Record<string, unknown>;
+    children: ReactNode;
+}
+/**
+ * Initialises the Obsrviq tracker once and keeps identity in sync with props.
+ *
+ * Late identity is first-class: pass `userId` once it resolves after login and
+ * the provider calls Obsrviq.identify(), which retro-stamps the already-running
+ * session. Safe under React 18 StrictMode (double-mount) and alongside a prior
+ * script-tag init — Obsrviq.init() is idempotent, so the first init wins and any
+ * later identity is applied via identify()/setMetadata().
+ */
+declare function ObsrviqProvider({ children, userId, metadata, ...config }: ObsrviqProviderProps): react.FunctionComponentElement<react.ProviderProps<ObsrviqClient | null>>;
+/** Access the Obsrviq client (identify / setMetadata / track / reset / setConsent). */
+declare function useObsrviq(): ObsrviqClient;
+
+export { type ObsrviqClient, ObsrviqProvider, type ObsrviqProviderProps, useObsrviq };

package/dist/index.js

@@ -0,0 +1,39 @@
+// src/index.ts
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useRef
+} from "react";
+import { Obsrviq } from "@obsrviq/tracker";
+var client = Obsrviq;
+var ObsrviqContext = createContext(null);
+function ObsrviqProvider({ children, userId, metadata, ...config }) {
+  useEffect(() => {
+    Obsrviq.init(config);
+    if (userId != null) Obsrviq.identify(userId, metadata);
+    else if (metadata) Obsrviq.setMetadata(metadata);
+  }, []);
+  const metaKey = metadata ? JSON.stringify(metadata) : "";
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      return;
+    }
+    if (userId != null) Obsrviq.identify(userId, metadata);
+    else if (metadata) Obsrviq.setMetadata(metadata);
+  }, [userId, metaKey]);
+  return createElement(ObsrviqContext.Provider, { value: client }, children);
+}
+function useObsrviq() {
+  const ctx = useContext(ObsrviqContext);
+  if (!ctx) throw new Error("useObsrviq() must be used within a <ObsrviqProvider>.");
+  return ctx;
+}
+export {
+  ObsrviqProvider,
+  useObsrviq
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  createContext,\n  createElement,\n  useContext,\n  useEffect,\n  useRef,\n  type ReactNode,\n} from 'react';\nimport { Obsrviq } from '@obsrviq/tracker';\nimport type { ObsrviqInitConfig } from '@obsrviq/types';\n\n/** The public surface of the Obsrviq client (the singleton structurally satisfies it). */\nexport interface ObsrviqClient {\n  readonly sessionId: string | null;\n  init(config: ObsrviqInitConfig): void;\n  identify(userId: string, traits?: Record<string, unknown>): void;\n  setMetadata(props: Record<string, unknown>): void;\n  reset(): void;\n  track(name: string, props?: Record<string, unknown>): void;\n  /** Mark a client-defined conversion by name (e.g. \"checkout\", \"signup\"). */\n  conversion(name: string, props?: Record<string, unknown>): void;\n  /** Attach free-form, searchable labels to the current session. */\n  tag(...names: string[]): void;\n  /** Open a named sub-event span; returns a handle whose end() closes it. */\n  startTask(name: string, props?: Record<string, unknown>): { end: (endProps?: Record<string, unknown>) => void };\n  /** Close a named sub-event span opened by startTask(name). */\n  endTask(name: string, props?: Record<string, unknown>): void;\n  setConsent(granted: boolean): void;\n  flush(): Promise<boolean>;\n  stop(): void;\n}\n\nconst client: ObsrviqClient = Obsrviq;\nconst ObsrviqContext = createContext<ObsrviqClient | null>(null);\n\nexport interface ObsrviqProviderProps extends Omit<ObsrviqInitConfig, 'userId' | 'metadata'> {\n  /** Raw application user id. Re-applied via identify() whenever it changes\n   *  (e.g. it resolves after login). */\n  userId?: string;\n  /** Session metadata. Re-merged via setMetadata() whenever it changes. */\n  metadata?: Record<string, unknown>;\n  children: ReactNode;\n}\n\n/**\n * Initialises the Obsrviq tracker once and keeps identity in sync with props.\n *\n * Late identity is first-class: pass `userId` once it resolves after login and\n * the provider calls Obsrviq.identify(), which retro-stamps the already-running\n * session. Safe under React 18 StrictMode (double-mount) and alongside a prior\n * script-tag init — Obsrviq.init() is idempotent, so the first init wins and any\n * later identity is applied via identify()/setMetadata().\n */\nexport function ObsrviqProvider({ children, userId, metadata, ...config }: ObsrviqProviderProps) {\n  // Init once (idempotent in the tracker; StrictMode double-invoke is harmless).\n  useEffect(() => {\n    Obsrviq.init(config as ObsrviqInitConfig);\n    if (userId != null) Obsrviq.identify(userId, metadata);\n    else if (metadata) Obsrviq.setMetadata(metadata);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  // Sync identity on subsequent changes (login, plan change, …).\n  const metaKey = metadata ? JSON.stringify(metadata) : '';\n  const mounted = useRef(false);\n  useEffect(() => {\n    if (!mounted.current) {\n      mounted.current = true;\n      return; // mount run already handled above\n    }\n    if (userId != null) Obsrviq.identify(userId, metadata);\n    else if (metadata) Obsrviq.setMetadata(metadata);\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [userId, metaKey]);\n\n  return createElement(ObsrviqContext.Provider, { value: client }, children);\n}\n\n/** Access the Obsrviq client (identify / setMetadata / track / reset / setConsent). */\nexport function useObsrviq(): ObsrviqClient {\n  const ctx = useContext(ObsrviqContext);\n  if (!ctx) throw new Error('useObsrviq() must be used within a <ObsrviqProvider>.');\n  return ctx;\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,SAAS,eAAe;AAwBxB,IAAM,SAAwB;AAC9B,IAAM,iBAAiB,cAAoC,IAAI;AAoBxD,SAAS,gBAAgB,EAAE,UAAU,QAAQ,UAAU,GAAG,OAAO,GAAyB;AAE/F,YAAU,MAAM;AACd,YAAQ,KAAK,MAA2B;AACxC,QAAI,UAAU,KAAM,SAAQ,SAAS,QAAQ,QAAQ;AAAA,aAC5C,SAAU,SAAQ,YAAY,QAAQ;AAAA,EAEjD,GAAG,CAAC,CAAC;AAGL,QAAM,UAAU,WAAW,KAAK,UAAU,QAAQ,IAAI;AACtD,QAAM,UAAU,OAAO,KAAK;AAC5B,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ,SAAS;AACpB,cAAQ,UAAU;AAClB;AAAA,IACF;AACA,QAAI,UAAU,KAAM,SAAQ,SAAS,QAAQ,QAAQ;AAAA,aAC5C,SAAU,SAAQ,YAAY,QAAQ;AAAA,EAEjD,GAAG,CAAC,QAAQ,OAAO,CAAC;AAEpB,SAAO,cAAc,eAAe,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC3E;AAGO,SAAS,aAA4B;AAC1C,QAAM,MAAM,WAAW,cAAc;AACrC,MAAI,CAAC,IAAK,OAAM,IAAI,MAAM,uDAAuD;AACjF,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@obsrviq/react",
+  "version": "0.3.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "React adapter for the Obsrviq tracker — <ObsrviqProvider> + useObsrviq().",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "dependencies": {
+    "@obsrviq/tracker": "0.3.0",
+    "@obsrviq/types": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.17",
+    "react": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactNode,
+} from 'react';
+import { Obsrviq } from '@obsrviq/tracker';
+import type { ObsrviqInitConfig } from '@obsrviq/types';
+
+/** The public surface of the Obsrviq client (the singleton structurally satisfies it). */
+export interface ObsrviqClient {
+  readonly sessionId: string | null;
+  init(config: ObsrviqInitConfig): void;
+  identify(userId: string, traits?: Record<string, unknown>): void;
+  setMetadata(props: Record<string, unknown>): void;
+  reset(): void;
+  track(name: string, props?: Record<string, unknown>): void;
+  /** Mark a client-defined conversion by name (e.g. "checkout", "signup"). */
+  conversion(name: string, props?: Record<string, unknown>): void;
+  /** Attach free-form, searchable labels to the current session. */
+  tag(...names: string[]): void;
+  /** Open a named sub-event span; returns a handle whose end() closes it. */
+  startTask(name: string, props?: Record<string, unknown>): { end: (endProps?: Record<string, unknown>) => void };
+  /** Close a named sub-event span opened by startTask(name). */
+  endTask(name: string, props?: Record<string, unknown>): void;
+  setConsent(granted: boolean): void;
+  flush(): Promise<boolean>;
+  stop(): void;
+}
+
+const client: ObsrviqClient = Obsrviq;
+const ObsrviqContext = createContext<ObsrviqClient | null>(null);
+
+export interface ObsrviqProviderProps extends Omit<ObsrviqInitConfig, 'userId' | 'metadata'> {
+  /** Raw application user id. Re-applied via identify() whenever it changes
+   *  (e.g. it resolves after login). */
+  userId?: string;
+  /** Session metadata. Re-merged via setMetadata() whenever it changes. */
+  metadata?: Record<string, unknown>;
+  children: ReactNode;
+}
+
+/**
+ * Initialises the Obsrviq tracker once and keeps identity in sync with props.
+ *
+ * Late identity is first-class: pass `userId` once it resolves after login and
+ * the provider calls Obsrviq.identify(), which retro-stamps the already-running
+ * session. Safe under React 18 StrictMode (double-mount) and alongside a prior
+ * script-tag init — Obsrviq.init() is idempotent, so the first init wins and any
+ * later identity is applied via identify()/setMetadata().
+ */
+export function ObsrviqProvider({ children, userId, metadata, ...config }: ObsrviqProviderProps) {
+  // Init once (idempotent in the tracker; StrictMode double-invoke is harmless).
+  useEffect(() => {
+    Obsrviq.init(config as ObsrviqInitConfig);
+    if (userId != null) Obsrviq.identify(userId, metadata);
+    else if (metadata) Obsrviq.setMetadata(metadata);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Sync identity on subsequent changes (login, plan change, …).
+  const metaKey = metadata ? JSON.stringify(metadata) : '';
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      return; // mount run already handled above
+    }
+    if (userId != null) Obsrviq.identify(userId, metadata);
+    else if (metadata) Obsrviq.setMetadata(metadata);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [userId, metaKey]);
+
+  return createElement(ObsrviqContext.Provider, { value: client }, children);
+}
+
+/** Access the Obsrviq client (identify / setMetadata / track / reset / setConsent). */
+export function useObsrviq(): ObsrviqClient {
+  const ctx = useContext(ObsrviqContext);
+  if (!ctx) throw new Error('useObsrviq() must be used within a <ObsrviqProvider>.');
+  return ctx;
+}