@upscopeio/react-native-sdk 2026.3.0

package/src/Upscope.ts

@@ -0,0 +1,113 @@
+import { NativeEventEmitter } from "react-native";
+import NativeUpscopeModule from "./NativeUpscopeModule";
+import type {
+  UpscopeConfig,
+  ConnectionUpdateParams,
+  UpscopeEventMap,
+  UpscopeEventName,
+} from "./types";
+
+/**
+ * Subscription handle returned by addListener. Callers must invoke remove()
+ * to avoid memory leaks when the component/scope unmounts.
+ */
+export interface EventSubscription {
+  remove(): void;
+}
+
+// Module-level emitter — one instance for the lifetime of the JS runtime.
+const emitter = new NativeEventEmitter(NativeUpscopeModule);
+
+/**
+ * Imperative JS API over the native Upscope TurboModule.
+ *
+ * All methods are thin typed wrappers; no business logic lives here.
+ * Prefer using the React hooks in this package inside components.
+ */
+const Upscope = {
+  /** Initialise the SDK. Must be called before any other method. */
+  initialize(config: UpscopeConfig): void {
+    NativeUpscopeModule.initialize(config as unknown as Object);
+  },
+
+  /** Open a WebSocket connection to the Upscope service. */
+  connect(): void {
+    NativeUpscopeModule.connect();
+  },
+
+  /** Close the WebSocket connection. */
+  disconnect(): void {
+    NativeUpscopeModule.disconnect();
+  },
+
+  /**
+   * Reset the connection state.
+   * @param reconnect - Whether to reconnect immediately after reset. Defaults to true.
+   */
+  reset(reconnect: boolean = true): void {
+    NativeUpscopeModule.reset(reconnect);
+  },
+
+  /**
+   * Update user identity and metadata sent to the Upscope service.
+   * Safe to call at any time; changes are pushed on the next sync.
+   */
+  updateConnection(params: ConnectionUpdateParams): void {
+    NativeUpscopeModule.updateConnection(params as unknown as Object);
+  },
+
+  /** Terminate the active co-browsing session. */
+  stopSession(): void {
+    NativeUpscopeModule.stopSession();
+  },
+
+  /** Request that an agent join the current session. */
+  requestAgent(): void {
+    NativeUpscopeModule.requestAgent();
+  },
+
+  /** Cancel a pending agent-join request. */
+  cancelAgentRequest(): void {
+    NativeUpscopeModule.cancelAgentRequest();
+  },
+
+  /**
+   * Ask the native layer to emit the current lookup code via the
+   * `lookupCodeChanged` event. The lookup code itself is delivered
+   * asynchronously through the event system.
+   */
+  getLookupCode(): void {
+    NativeUpscopeModule.getLookupCode();
+  },
+
+  /** Resolve the current short ID, or null if not yet assigned. */
+  getShortId(): Promise<string | null> {
+    return NativeUpscopeModule.getShortId();
+  },
+
+  /** Resolve the watch link for the current session, or null if unavailable. */
+  getWatchLink(): Promise<string | null> {
+    return NativeUpscopeModule.getWatchLink();
+  },
+
+  /** Send an arbitrary string message to all connected observers. */
+  sendCustomMessage(message: string): void {
+    NativeUpscopeModule.sendCustomMessage(message);
+  },
+
+  /**
+   * Subscribe to a typed Upscope event.
+   *
+   * @param eventName - One of the well-known event names from UpscopeEventMap.
+   * @param callback  - Invoked with the strongly-typed payload on each event.
+   * @returns A subscription handle. Call `.remove()` to unsubscribe.
+   */
+  addListener<E extends UpscopeEventName>(
+    eventName: E,
+    callback: (event: UpscopeEventMap[E]) => void,
+  ): EventSubscription {
+    return emitter.addListener(eventName, callback);
+  },
+} as const;
+
+export default Upscope;

package/src/UpscopeMasked.tsx

@@ -0,0 +1,19 @@
+import React from "react";
+import type { ViewProps } from "react-native";
+import NativeUpscopeMaskedView from "./NativeUpscopeMaskedView";
+
+export interface UpscopeMaskedProps extends ViewProps {
+  children: React.ReactNode;
+}
+
+export function UpscopeMasked({
+  children,
+  style,
+  ...props
+}: UpscopeMaskedProps) {
+  return (
+    <NativeUpscopeMaskedView style={style} {...props}>
+      {children}
+    </NativeUpscopeMaskedView>
+  );
+}

package/src/hooks.ts

@@ -0,0 +1,99 @@
+import { useState, useEffect, useMemo } from "react";
+import Upscope from "./Upscope";
+import type { ConnectionState, SessionState } from "./types";
+
+/**
+ * Returns the current WebSocket connection state, updated reactively via the
+ * `connectionStateChanged` event. Starts as "inactive" before the first event.
+ */
+export function useConnectionState(): ConnectionState {
+  const [state, setState] = useState<ConnectionState>("inactive");
+
+  useEffect(() => {
+    const sub = Upscope.addListener("connectionStateChanged", (event) => {
+      setState(event.state);
+    });
+    return () => sub.remove();
+  }, []);
+
+  return state;
+}
+
+/**
+ * Returns the current co-browsing session state. Transitions to "active" on
+ * `sessionStarted` and back to "inactive" on `sessionEnded`.
+ */
+export function useSessionState(): SessionState {
+  const [state, setState] = useState<SessionState>("inactive");
+
+  useEffect(() => {
+    const subStart = Upscope.addListener("sessionStarted", () => {
+      setState("active");
+    });
+    const subEnd = Upscope.addListener("sessionEnded", () => {
+      setState("inactive");
+    });
+    return () => {
+      subStart.remove();
+      subEnd.remove();
+    };
+  }, []);
+
+  return state;
+}
+
+/**
+ * Returns the SDK short ID, or null if not yet assigned.
+ * Resolves the current value on mount and stays in sync via `shortIdChanged`.
+ */
+export function useShortId(): string | null {
+  const [shortId, setShortId] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Seed with the current value; the listener handles all subsequent changes.
+    Upscope.getShortId().then(setShortId);
+    const sub = Upscope.addListener("shortIdChanged", (event) => {
+      setShortId(event.shortId);
+    });
+    return () => sub.remove();
+  }, []);
+
+  return shortId;
+}
+
+/**
+ * Returns the current lookup code, or null until the native layer emits one.
+ * Updated reactively via `lookupCodeChanged`.
+ */
+export function useLookupCode(): string | null {
+  const [code, setCode] = useState<string | null>(null);
+
+  useEffect(() => {
+    const sub = Upscope.addListener("lookupCodeChanged", (event) => {
+      setCode(event.lookupCode);
+    });
+    return () => sub.remove();
+  }, []);
+
+  return code;
+}
+
+/**
+ * Returns a stable object of imperative Upscope action methods.
+ * Safe to use as a dependency in `useCallback` / `useEffect`.
+ */
+export function useUpscope() {
+  return useMemo(
+    () => ({
+      connect: Upscope.connect,
+      disconnect: Upscope.disconnect,
+      stopSession: Upscope.stopSession,
+      requestAgent: Upscope.requestAgent,
+      cancelAgentRequest: Upscope.cancelAgentRequest,
+      sendCustomMessage: Upscope.sendCustomMessage,
+      getLookupCode: Upscope.getLookupCode,
+      reset: Upscope.reset,
+    }),
+    [],
+  );
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export { default as default } from "./Upscope";
+export { default as Upscope } from "./Upscope";
+export type { EventSubscription } from "./Upscope";
+
+export {
+  useConnectionState,
+  useSessionState,
+  useShortId,
+  useLookupCode,
+  useUpscope,
+} from "./hooks";
+
+export { UpscopeMasked } from "./UpscopeMasked";
+export type { UpscopeMaskedProps } from "./UpscopeMasked";
+
+export type {
+  ConnectionState,
+  SessionState,
+  SessionEndReason,
+  UpscopeError,
+  UpscopeConfig,
+  ConnectionUpdateParams,
+  Observer,
+  UpscopeEventMap,
+  UpscopeEventName,
+  ConnectionStateChangedEvent,
+  SessionStartedEvent,
+  SessionEndedEvent,
+  CustomMessageEvent,
+  ObserverCountChangedEvent,
+  ObserverLeftEvent,
+  ShortIdChangedEvent,
+  LookupCodeChangedEvent,
+} from "./types";

package/src/types.ts

@@ -0,0 +1,109 @@
+export type ConnectionState =
+  | "inactive"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "error";
+
+export type SessionState =
+  | "inactive"
+  | "pendingRequest"
+  | "active"
+  | "paused"
+  | "ended";
+
+export type SessionEndReason =
+  | "userStopped"
+  | "agentStopped"
+  | "timeout"
+  | "error";
+
+export interface UpscopeError {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface UpscopeConfig {
+  readonly apiKey: string;
+  readonly requireAuthorizationForSession?: boolean;
+  readonly autoConnect?: boolean;
+  readonly region?: string;
+  readonly showBanner?: boolean;
+  readonly showTerminateButton?: boolean;
+  readonly authorizationPromptTitle?: string;
+  readonly authorizationPromptMessage?: string;
+  readonly endOfSessionMessage?: string;
+  readonly stopSessionText?: string;
+  readonly allowRemoteClick?: boolean;
+  readonly allowRemoteScroll?: boolean;
+  readonly requireControlRequest?: boolean;
+}
+
+export interface ConnectionUpdateParams {
+  readonly uniqueId?: string;
+  readonly callName?: string;
+  readonly tags?: readonly string[];
+  readonly identities?: readonly string[];
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+
+export interface Observer {
+  readonly id: string;
+  readonly name: string | null;
+  readonly screenWidth: number;
+  readonly screenHeight: number;
+  readonly windowWidth: number;
+  readonly windowHeight: number;
+  readonly hasFocus: boolean;
+}
+
+// Event payload types
+export interface ConnectionStateChangedEvent {
+  readonly state: ConnectionState;
+  readonly error?: UpscopeError;
+}
+
+export interface SessionStartedEvent {
+  readonly agentName: string | null;
+}
+
+export interface SessionEndedEvent {
+  readonly reason: SessionEndReason;
+  readonly error?: UpscopeError;
+}
+
+export interface CustomMessageEvent {
+  readonly message: string;
+  readonly observerId: string;
+}
+
+export interface ObserverCountChangedEvent {
+  readonly count: number;
+}
+
+export interface ObserverLeftEvent {
+  readonly observerId: string;
+}
+
+export interface ShortIdChangedEvent {
+  readonly shortId: string | null;
+}
+
+export interface LookupCodeChangedEvent {
+  readonly lookupCode: string | null;
+}
+
+export type UpscopeEventMap = {
+  readonly connectionStateChanged: ConnectionStateChangedEvent;
+  readonly sessionStarted: SessionStartedEvent;
+  readonly sessionEnded: SessionEndedEvent;
+  readonly customMessageReceived: CustomMessageEvent;
+  readonly error: UpscopeError;
+  readonly observerJoined: Observer;
+  readonly observerLeft: ObserverLeftEvent;
+  readonly observerCountChanged: ObserverCountChangedEvent;
+  readonly shortIdChanged: ShortIdChangedEvent;
+  readonly lookupCodeChanged: LookupCodeChangedEvent;
+};
+
+export type UpscopeEventName = keyof UpscopeEventMap;

package/upscopeio-react-native-sdk.podspec

@@ -0,0 +1,17 @@
+Pod::Spec.new do |s|
+  s.name         = "upscopeio-react-native-sdk"
+  s.version      = "0.1.0"
+  s.summary      = "React Native SDK for Upscope cobrowsing"
+  s.homepage     = "https://github.com/upscopeio/react-native-sdk"
+  s.license      = "MIT"
+  s.authors      = "Upscope"
+  s.source       = { :git => "https://github.com/upscopeio/react-native-sdk.git", :tag => s.version }
+
+  s.platforms    = { :ios => "14.0" }
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.swift_version = "5.9"
+
+  s.dependency "UpscopeSDK"
+
+  install_modules_dependencies(s)
+end