@nexbasira/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NexBasira
+
+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/README.md

@@ -0,0 +1,113 @@
+# @nexbasira/react
+
+React component + hook wrapping the [`@nexbasira/embed`](../embed) browser widget.
+
+Thin by design — the iframe and postMessage plumbing live in `@nexbasira/embed`; this package just makes the widget feel native to a React app (mount, unmount, ref-based imperative access, fresh-closure callbacks).
+
+## Install
+
+```bash
+npm install @nexbasira/react @nexbasira/embed react
+```
+
+`react` and `@nexbasira/embed` are peer dependencies — they aren't bundled.
+
+## Quick start (component)
+
+```tsx
+import { NexBasiraSession } from "@nexbasira/react";
+
+function InspectionPage({ joinUrl }: { joinUrl: string }) {
+  return (
+    <NexBasiraSession
+      sessionUrl={joinUrl}
+      height="720px"
+      onSessionComplete={(id) => {
+        console.log("inspection done:", id);
+      }}
+    />
+  );
+}
+```
+
+`sessionUrl` is the field-join URL your backend mints via `POST /v1/public/sessions/{id}/invites` (or the SPA equivalent). Never embed an API secret in the URL.
+
+## Imperative control (ref)
+
+```tsx
+import { useRef } from "react";
+import { NexBasiraSession, type NexBasiraSessionHandle } from "@nexbasira/react";
+
+function ToolbarHost({ joinUrl }: { joinUrl: string }) {
+  const session = useRef<NexBasiraSessionHandle>(null);
+  return (
+    <>
+      <button onClick={() => session.current?.requestSnapshot()}>
+        Capture
+      </button>
+      <NexBasiraSession ref={session} sessionUrl={joinUrl} />
+    </>
+  );
+}
+```
+
+Methods on the handle:
+
+- `requestSnapshot()`
+- `openWhiteboard()` / `closeWhiteboard()`
+- `switchCamera()`
+- `mute()` / `unmute()`
+- `endSession()`
+
+## Hook variant
+
+Use this when `<NexBasiraSession>`'s wrapper `<div>` doesn't fit your layout, or when you want to share the widget handle across multiple components without prop-drilling refs.
+
+```tsx
+import { useNexBasiraSession } from "@nexbasira/react";
+
+function CustomLayout({ joinUrl }: { joinUrl: string }) {
+  const [containerRef, widget] = useNexBasiraSession({
+    sessionUrl: joinUrl,
+    onSessionComplete: (id) => navigate(`/inspections/${id}`),
+  });
+  return (
+    <div className="my-layout">
+      <header>
+        <button onClick={() => widget.current?.requestSnapshot()}>
+          Snap
+        </button>
+      </header>
+      <div ref={containerRef} style={{ flex: 1 }} />
+    </div>
+  );
+}
+```
+
+## Lifecycle callbacks
+
+Every callback supported by `@nexbasira/embed` is passed through unchanged:
+
+| Prop | Fires when |
+|---|---|
+| `onReady` | The iframe finished loading + handshake completed. |
+| `onSessionJoined(id)` | The field user joined the session. |
+| `onSessionComplete(id)` | The session was closed (final state, recording paths queued). |
+| `onEvidenceAdded(ev)` | A new evidence row was created (snapshot, whiteboard, etc.). |
+| `onWhiteboardOpened` / `onWhiteboardSaved(ev)` | Whiteboard lifecycle. |
+| `onParticipantJoined(p)` / `onParticipantLeft(p)` | Participant changes. |
+| `onError({message, code})` | Anything the iframe surfaces as an error. |
+
+Callbacks are always re-read from the latest props on every re-render — closing over fresh state in your handlers works without remounting the iframe.
+
+## When the iframe rebuilds
+
+The iframe is re-created **only** when `sessionUrl` changes. Every other prop (callbacks, `width`, `height`, `expectedOrigin`) is applied without remounting, so toolbars and overlays stay continuous through a session.
+
+## TypeScript
+
+`NexBasiraSessionProps`, `NexBasiraSessionHandle`, `EmbedOptions`, and `EmbedWidget` are all exported. The component is a `forwardRef`, so `useRef<NexBasiraSessionHandle>()` gives you typed handle access.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import type { EmbedOptions, EmbedWidget } from "@nexbasira/embed";
+import { type CSSProperties, type Ref } from "react";
+/** Props for `<NexBasiraSession>` — superset of `EmbedOptions`
+ * minus `container` (the component manages its own div). Adds a
+ * `className` + `style` so callers can position the wrapper. */
+export type NexBasiraSessionProps = Omit<EmbedOptions, "container"> & {
+    className?: string;
+    style?: CSSProperties;
+};
+/** Imperative handle exposed via `ref` — mirrors the methods on
+ * `EmbedWidget`, so callers get the same shape they'd get from
+ * `@nexbasira/embed` directly. */
+export interface NexBasiraSessionHandle {
+    requestSnapshot(): void;
+    openWhiteboard(): void;
+    closeWhiteboard(): void;
+    switchCamera(): void;
+    mute(): void;
+    unmute(): void;
+    endSession(): void;
+    /** Phase 1B-I — recording lifecycle from the host page. Routes
+     *  through to the iframe's RecordingControl. */
+    startRecording(): void;
+    stopRecording(): void;
+    pauseRecording(): void;
+    resumeRecording(): void;
+}
+export declare const NexBasiraSession: import("react").ForwardRefExoticComponent<Omit<EmbedOptions, "container"> & {
+    className?: string;
+    style?: CSSProperties;
+} & import("react").RefAttributes<NexBasiraSessionHandle>>;
+/** Hook variant. Returns `[containerRef, widget]`. Attach
+ * `containerRef` to the host element (typically a `<div>`), and
+ * call methods on `widget.current` once the component is mounted.
+ *
+ * Use this when `<NexBasiraSession>`'s built-in wrapper div
+ * doesn't fit your layout, or when you want fine-grained control
+ * over when the embed widget initialises. */
+export declare function useNexBasiraSession(options: Omit<EmbedOptions, "container">): [Ref<HTMLDivElement>, {
+    current: EmbedWidget | null;
+}];
+export type { EmbedOptions, EmbedWidget } from "@nexbasira/embed";

package/dist/index.js

@@ -0,0 +1,126 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @nexbasira/react — React wrapper around `@nexbasira/embed`.
+ *
+ * Two surfaces:
+ *
+ *   1. `<NexBasiraSession>` — drop-in component for the common
+ *      case. Render it with `sessionUrl` and the lifecycle props
+ *      you care about; the iframe lives inside, the widget gets
+ *      created on mount, the listener is torn down on unmount.
+ *
+ *   2. `useNexBasiraSession()` — hook for callers that need
+ *      imperative access (forwarding camera commands from a
+ *      separate toolbar, hooking into an existing layout). Returns
+ *      both the container ref to attach + the widget handle so
+ *      you can call `.requestSnapshot()` etc. from anywhere.
+ *
+ * The wrapper is intentionally a leaf — it doesn't restyle the
+ * iframe or impose layout decisions, and lifecycle callbacks pass
+ * through unchanged so existing `@nexbasira/embed` consumers can
+ * migrate without rewiring handler signatures.
+ *
+ * Usage:
+ *   import { NexBasiraSession } from "@nexbasira/react";
+ *
+ *   <NexBasiraSession
+ *     sessionUrl={mintedFieldJoinUrl}
+ *     onSessionComplete={(id) => router.push(`/inspections/${id}`)}
+ *     height="720px"
+ *   />
+ */
+import { embed } from "@nexbasira/embed";
+import { forwardRef, useEffect, useImperativeHandle, useRef, } from "react";
+export const NexBasiraSession = forwardRef(function NexBasiraSession(props, ref) {
+    const { className, style, ...embedProps } = props;
+    const containerRef = useRef(null);
+    const widgetRef = useRef(null);
+    // Stash the latest props in a ref so the embed widget's
+    // lifecycle callbacks always read fresh closures — without
+    // this, a parent that re-renders with a new onSessionComplete
+    // (e.g. closing over fresh state) would see the stale one
+    // because the embed widget was created with the first mount's
+    // props.
+    const propsRef = useRef(embedProps);
+    propsRef.current = embedProps;
+    useEffect(() => {
+        if (!containerRef.current)
+            return;
+        const widget = embed({
+            ...propsRef.current,
+            container: containerRef.current,
+            // Wrap each callback so the embed widget always invokes the
+            // current prop value, not the snapshot from the mount.
+            onReady: () => propsRef.current.onReady?.(),
+            onSessionJoined: (id) => propsRef.current.onSessionJoined?.(id),
+            onSessionComplete: (id) => propsRef.current.onSessionComplete?.(id),
+            onEvidenceAdded: (ev) => propsRef.current.onEvidenceAdded?.(ev),
+            onWhiteboardOpened: () => propsRef.current.onWhiteboardOpened?.(),
+            onWhiteboardSaved: (ev) => propsRef.current.onWhiteboardSaved?.(ev),
+            onParticipantJoined: (p) => propsRef.current.onParticipantJoined?.(p),
+            onParticipantLeft: (p) => propsRef.current.onParticipantLeft?.(p),
+            onError: (err) => propsRef.current.onError?.(err),
+        });
+        widgetRef.current = widget;
+        return () => {
+            widget.destroy();
+            widgetRef.current = null;
+        };
+        // Intentionally re-create the iframe only when sessionUrl
+        // changes — every other prop is read through propsRef. A
+        // sessionUrl change means a different session; the iframe
+        // must reload.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [embedProps.sessionUrl]);
+    useImperativeHandle(ref, () => ({
+        requestSnapshot: () => widgetRef.current?.requestSnapshot(),
+        openWhiteboard: () => widgetRef.current?.openWhiteboard(),
+        closeWhiteboard: () => widgetRef.current?.closeWhiteboard(),
+        switchCamera: () => widgetRef.current?.switchCamera(),
+        mute: () => widgetRef.current?.mute(),
+        unmute: () => widgetRef.current?.unmute(),
+        endSession: () => widgetRef.current?.endSession(),
+        startRecording: () => widgetRef.current?.startRecording(),
+        stopRecording: () => widgetRef.current?.stopRecording(),
+        pauseRecording: () => widgetRef.current?.pauseRecording(),
+        resumeRecording: () => widgetRef.current?.resumeRecording(),
+    }), []);
+    return _jsx("div", { ref: containerRef, className: className, style: style });
+});
+/** Hook variant. Returns `[containerRef, widget]`. Attach
+ * `containerRef` to the host element (typically a `<div>`), and
+ * call methods on `widget.current` once the component is mounted.
+ *
+ * Use this when `<NexBasiraSession>`'s built-in wrapper div
+ * doesn't fit your layout, or when you want fine-grained control
+ * over when the embed widget initialises. */
+export function useNexBasiraSession(options) {
+    const containerRef = useRef(null);
+    const widgetRef = useRef(null);
+    const propsRef = useRef(options);
+    propsRef.current = options;
+    useEffect(() => {
+        if (!containerRef.current)
+            return;
+        const widget = embed({
+            ...propsRef.current,
+            container: containerRef.current,
+            onReady: () => propsRef.current.onReady?.(),
+            onSessionJoined: (id) => propsRef.current.onSessionJoined?.(id),
+            onSessionComplete: (id) => propsRef.current.onSessionComplete?.(id),
+            onEvidenceAdded: (ev) => propsRef.current.onEvidenceAdded?.(ev),
+            onWhiteboardOpened: () => propsRef.current.onWhiteboardOpened?.(),
+            onWhiteboardSaved: (ev) => propsRef.current.onWhiteboardSaved?.(ev),
+            onParticipantJoined: (p) => propsRef.current.onParticipantJoined?.(p),
+            onParticipantLeft: (p) => propsRef.current.onParticipantLeft?.(p),
+            onError: (err) => propsRef.current.onError?.(err),
+        });
+        widgetRef.current = widget;
+        return () => {
+            widget.destroy();
+            widgetRef.current = null;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [options.sessionUrl]);
+    return [containerRef, widgetRef];
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@nexbasira/react",
+  "version": "0.1.0",
+  "description": "React component + hook wrapping the NexBasira embed widget.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codelounge-io/certivisiopro_backend.git",
+    "directory": "sdks/react"
+  },
+  "homepage": "https://github.com/codelounge-io/certivisiopro_backend/tree/main/sdks/react",
+  "bugs": {
+    "url": "https://github.com/codelounge-io/certivisiopro_backend/issues"
+  },
+  "keywords": [
+    "nexbasira",
+    "remote-inspection",
+    "react",
+    "component",
+    "embed",
+    "iframe"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "@nexbasira/embed": "^0.1.0"
+  },
+  "devDependencies": {
+    "@nexbasira/embed": "file:../embed",
+    "@testing-library/react": "^15.0.0",
+    "@types/react": "^18.2.0",
+    "jsdom": "^24.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0"
+  }
+}