@calloop/agent-react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PCGLOBALCO
+
+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

@@ -1,3 +1,130 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @calloop/agent-react
+
+React bindings for [`@calloop/agent-sdk`](https://docs.calloop.net/sdks/js): a provider
+that connects once, and hooks that re-render when calls, availability, queues
+or the supervisor board change. The SDK's objects and actions are used as they
+are — this package only wires them into React. React 18+.
+
+```sh
+npm install @calloop/agent-react @calloop/agent-sdk
+```
+
+```jsx
+import { CalloopProvider, useAgent, useIncomingCalls, useActiveCall, useCall, RemoteAudio } from '@calloop/agent-react';
+
+export default function App() {
+  return (
+    <CalloopProvider url="https://api.calloop.net" getToken={() => fetch('/api/calloop-token').then((r) => r.text())}>
+      <AgentScreen />
+    </CalloopProvider>
+  );
+}
+
+function AgentScreen() {
+  const { me, availability, setAvailability } = useAgent();
+  const ringing = useIncomingCalls();
+  const active = useActiveCall();
+  return (
+    <>
+      <p>{me?.name} — {availability}</p>
+      <button onClick={() => setAvailability('AVAILABLE')}>Available</button>
+      {ringing.map((call) => <Ringing key={call.id} call={call} />)}
+      {active && <OnCall call={active} />}
+    </>
+  );
+}
+
+function Ringing({ call }) {
+  const { customer, accept, decline } = useCall(call);
+  return <div>{customer.address} <button onClick={() => accept()}>Answer</button> <button onClick={decline}>Decline</button></div>;
+}
+
+function OnCall({ call }) {
+  const { state, customer, remoteStream, muted, mute, hangup, transfer } = useCall(call);
+  return (
+    <div>
+      {customer.address} — {state}
+      <RemoteAudio stream={remoteStream} />
+      <button onClick={() => mute(!muted)}>{muted ? 'Unmute' : 'Mute'}</button>
+      <button onClick={() => transfer({ queueId: 3 })}>Transfer</button>
+      <button onClick={hangup}>Hang up</button>
+    </div>
+  );
+}
+```
+
+## Security
+
+The rules of the [JS SDK](https://docs.calloop.net/sdks/js#security) apply: only
+short-lived agent tokens from your backend in the browser (never an API key),
+`getToken` for a fresh one on every connect, `role` on every token, https only.
+
+## Provider
+
+`<CalloopProvider>` takes `connect()`'s options (`url`, `token` | `getToken`,
+`deviceId`, `webrtc`, `getUserMedia`, `purpose`, `io`) or `agent` — an already
+connected `CalloopAgent`. `connect` replaces the SDK's `connect()` (e.g. in
+tests). The latest `token` / `getToken` is used on every (re)connect,
+so passing a fresh token doesn't reconnect; only another `url` or `deviceId`
+does. A connection the provider made closes on unmount; an `agent` passed in
+is left open — close it yourself.
+
+## Hooks
+
+| Hook | Returns |
+|---|---|
+| `useCalloop()` | `{ agent, status, error }` — `status`: `connecting` · `ready` · `reconnecting` · `closed` · `error`. `closed`: Calloop ended the connection and won't take it back (e.g. the token's signing key was revoked; `error` says why) — remount the provider (e.g. change its `key`) to connect again |
+| `useAgent()` | `{ agent, me, tenant, availability, isSupervisor, setAvailability(value, { agentId? }) }` — `agent` is the SDK's `CalloopAgent` |
+| `useCalls()` | this agent's calls (SDK `Call` objects) |
+| `useIncomingCalls()` | the ringing ones |
+| `useActiveCall()` | the call being set up / on / dialing, or `null` |
+| `useCall(call)` | `{ call, state, data, customer, remoteStream, muted, lastDigit, endReason, accept, decline, hangup, mute, transfer, setPrivate, switchHere }` — `lastDigit`: the customer's last key press |
+| `useQueues()` | queue snapshots (supervisors, and agents whose tenant allows the team view; otherwise empty) |
+| `useTeam()` | the tenant's agents' availability (likewise; otherwise only this agent) |
+| `useBoard()` | supervisors: the tenant's live calls |
+| `useMonitor(callId)` | supervisors: `{ monitor, state, mode, stream, error, start(), stop(), setMode(), mute() }` — `state`: `idle` · `connecting` · `active`, back to `idle` when monitoring ends; `stream` is the call as they hear it; stops on unmount. `error`: `start()` rejected, Calloop refused or failed the monitor (it then ended; `error.code` is Calloop's), or refused a `setMode()` (monitoring goes on in the current mode; cleared by the next mode change) |
+
+`<RemoteAudio stream />` plays a stream (a call's `remoteStream`, a monitor's
+`stream`); other props go to the `<audio>` element.
+
+## Supervisor screen
+
+```jsx
+import { useEffect, useState } from 'react';
+import { useBoard, useMonitor, RemoteAudio } from '@calloop/agent-react';
+
+function Board() {
+  const calls = useBoard();
+  const [watching, setWatching] = useState(null);
+  return (
+    <>
+      {calls.map((c) => (
+        <div key={c.callId}>
+          {c.customer?.address} · {c.status} · {c.agentName ?? 'waiting'} {c.ivr && `· IVR ${c.ivr.nodeType}`}
+          <button onClick={() => setWatching(c.callId)}>Listen</button>
+        </div>
+      ))}
+      {watching && <Listening callId={watching} />}
+    </>
+  );
+}
+
+function Listening({ callId }) {
+  const { state, mode, stream, start, setMode, stop } = useMonitor(callId);
+  useEffect(() => { start(); }, [start]);
+  return (
+    <div>
+      {state} · {mode}
+      <RemoteAudio stream={stream} />
+      <button onClick={() => setMode('whisper')}>Whisper</button>
+      <button onClick={() => setMode('barge')}>Barge</button>
+      <button onClick={stop}>Stop</button>
+    </div>
+  );
+}
+```
+
+## No build step
+
+The package is plain ES modules (`React.createElement`, no JSX) with
+TypeScript types, so any bundler takes it as is.

package/package.json

@@ -1,6 +1,42 @@
-{
-  "name": "@calloop/agent-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@calloop/agent-react",
+  "version": "0.1.0",
+  "description": "React bindings for @calloop/agent-sdk: a provider and hooks for agent and supervisor screens.",
+  "keywords": [
+    "calloop",
+    "react",
+    "hooks",
+    "call-center",
+    "webrtc",
+    "voip"
+  ],
+  "homepage": "https://docs.calloop.net/sdks/react",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PCGlobalCo/calloop-sdks.git",
+    "directory": "agent-react"
+  },
+  "bugs": {
+    "url": "https://github.com/PCGlobalCo/calloop-sdks/issues"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "@calloop/agent-sdk": "^0.2.0",
+    "react": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,81 @@
+// Types for @calloop/agent-react.
+import type { ReactNode, ReactElement, AudioHTMLAttributes } from 'react';
+import type {
+    CalloopAgent, Call, Monitor, ConnectOptions, Session, Availability, CallStateName, CallData, Customer,
+    QueueSnapshot, TeamMember, BoardCall, MonitorMode,
+} from '@calloop/agent-sdk';
+
+/** 'closed': Calloop ended the connection and won't reconnect it (e.g. a revoked signing key); error says why. */
+export type ConnectionStatus = 'connecting' | 'ready' | 'reconnecting' | 'closed' | 'error';
+
+export type CalloopProviderProps = Partial<ConnectOptions> & {
+    children?: ReactNode;
+    /** An already connected agent, instead of connecting here. */
+    agent?: CalloopAgent;
+    /** Replaces the SDK's connect (tests). */
+    connect?: (opts: ConnectOptions) => Promise<CalloopAgent>;
+};
+
+/** Connects once and shares the agent with every hook below it. */
+export function CalloopProvider(props: CalloopProviderProps): ReactElement;
+
+export function useCalloop(): { agent: CalloopAgent | null; status: ConnectionStatus; error: Error | null };
+
+export function useAgent(): {
+    agent: CalloopAgent | null;
+    me: Session['agent'] | null;
+    tenant: Session['tenant'] | null;
+    availability: Availability | null;
+    isSupervisor: boolean;
+    setAvailability(value: 'AVAILABLE' | 'OFFLINE', opts?: { agentId?: number | string }): void;
+};
+
+/** This agent's calls. */
+export function useCalls(): Call[];
+/** Calls ringing for this agent. */
+export function useIncomingCalls(): Call[];
+/** The call this agent is on (connecting, active or dialing). */
+export function useActiveCall(): Call | null;
+
+export function useCall(call: Call | null | undefined): {
+    call: Call | null | undefined;
+    state: CallStateName | null;
+    data: CallData | null;
+    customer: Customer | null;
+    remoteStream: MediaStream | null;
+    endReason: string | null;
+    muted: boolean;
+    /** The last key the customer pressed during the call. */
+    lastDigit: string | null;
+    accept(opts?: { stream?: MediaStream }): Promise<void> | undefined;
+    decline(): void;
+    hangup(): void;
+    mute(value?: boolean): void;
+    transfer(target: { agentId: number | string } | { queueId: number | string }): void;
+    setPrivate(active: boolean): void;
+    switchHere(opts?: { stream?: MediaStream }): Promise<void> | undefined;
+};
+
+export function useQueues(): QueueSnapshot[];
+export function useTeam(): TeamMember[];
+
+/** Supervisors: the tenant's live calls. */
+export function useBoard(): BoardCall[];
+
+/** Supervisors: monitoring one call. Stops on unmount or when callId changes. */
+export function useMonitor(callId: number | string | null | undefined): {
+    monitor: Monitor | null;
+    state: 'idle' | 'connecting' | 'active';
+    mode: MonitorMode | null;
+    /** The call as the supervisor hears it: the customer and the agent, mixed. */
+    stream: MediaStream | null;
+    /** start() rejected, the monitor failed or was refused, or a setMode() was refused (code: Calloop's error code). */
+    error: (Error & { code?: string }) | null;
+    start(opts?: { stream?: MediaStream }): Promise<Monitor | null>;
+    stop(): void;
+    setMode(mode: MonitorMode): void;
+    mute(value?: boolean): void;
+};
+
+/** Plays a MediaStream in an <audio> element. */
+export function RemoteAudio(props: { stream: MediaStream | null | undefined; muted?: boolean } & AudioHTMLAttributes<HTMLAudioElement>): ReactElement;

package/src/index.js

@@ -0,0 +1,251 @@
+// @calloop/agent-react — React bindings for @calloop/agent-sdk.
+//
+//   <CalloopProvider url=… getToken={…}>
+//     <App />
+//   </CalloopProvider>
+//
+// Hooks re-render when the SDK's objects change; the objects themselves (the
+// agent, calls, monitors) are the SDK's, and their actions are used as they are.
+// No JSX, no build step: plain ES modules.
+import { createContext, createElement, useCallback, useContext, useEffect, useReducer, useRef, useState } from 'react';
+import { connect as sdkConnect } from '@calloop/agent-sdk';
+
+const CalloopContext = createContext(null);
+
+// Re-render when any of `events` fires on `emitter` (null emitter: never).
+function useEmitter(emitter, events) {
+    const [, bump] = useReducer((n) => n + 1, 0);
+    const key = events.join('|');
+    useEffect(() => {
+        if (!emitter) return undefined;
+        const offs = events.map((e) => emitter.on(e, bump));
+        // Whatever changed between the render and subscribing would be missed: re-read once.
+        bump();
+        return () => offs.forEach((off) => off());
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [emitter, key]);
+}
+
+/**
+ * Connects once and shares the agent with every hook below it.
+ * Props: url, token | getToken, deviceId?, webrtc?, getUserMedia? (as connect()),
+ * or agent — an already connected CalloopAgent. connect: a replacement for the
+ * SDK's connect (tests).
+ */
+export function CalloopProvider({ children, agent: given, connect = sdkConnect, ...options }) {
+    const [state, setState] = useState(() => ({ agent: given ?? null, status: given ? 'ready' : 'connecting', error: null }));
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    // A new token is not a new connection: the latest token / getToken is read
+    // on every (re)connect. Only another url or device reconnects.
+    const identity = `${options.url}|${options.deviceId ?? ''}`;
+
+    useEffect(() => {
+        if (given) { setState({ agent: given, status: 'ready', error: null }); return undefined; }
+        let closed = false;
+        let agent = null;
+        setState({ agent: null, status: 'connecting', error: null });
+        const latestToken = () => {
+            const o = optionsRef.current;
+            return o.getToken ? o.getToken() : o.token;
+        };
+        connect({ ...optionsRef.current, token: undefined, getToken: latestToken }).then((a) => {
+            agent = a;
+            if (closed) { a.close(); return; }
+            setState({ agent: a, status: 'ready', error: null });
+        }, (error) => {
+            if (!closed) setState({ agent: null, status: 'error', error });
+        });
+        return () => { closed = true; agent?.close(); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [given, identity]);
+
+    // Connection status after the first connect.
+    useEffect(() => {
+        const agent = state.agent;
+        if (!agent) return undefined;
+        const offs = [
+            agent.on('disconnected', () => setState((s) => ({ ...s, status: 'reconnecting' }))),
+            agent.on('ready', () => setState((s) => ({ ...s, status: 'ready', error: null }))),
+            // Calloop ended the connection for good (e.g. its signing key was
+            // revoked): no reconnect will come. A remount (or a new key) connects again.
+            agent.on('closed', ({ reason }) => setState((s) => ({ ...s, status: 'closed', error: new Error(`Calloop closed the connection (${reason})`) }))),
+        ];
+        if (agent.closedReason) setState((s) => ({ ...s, status: 'closed', error: new Error(`Calloop closed the connection (${agent.closedReason})`) }));
+        return () => offs.forEach((off) => off());
+    }, [state.agent]);
+
+    return createElement(CalloopContext.Provider, { value: state }, children);
+}
+
+/**
+ * { agent, status: 'connecting' | 'ready' | 'reconnecting' | 'closed' | 'error', error }.
+ * 'closed': Calloop ended the connection and won't take it back (error says why).
+ */
+export function useCalloop() {
+    const ctx = useContext(CalloopContext);
+    if (!ctx) throw new Error('useCalloop must be used inside <CalloopProvider>');
+    return ctx;
+}
+
+/** This agent: identity, availability, role, and setAvailability. */
+export function useAgent() {
+    const { agent } = useCalloop();
+    useEmitter(agent, ['ready', 'availability', 'sessionRefreshed']);
+    const setAvailability = useCallback((value, opts) => agent?.setAvailability(value, opts), [agent]);
+    return {
+        agent,
+        me: agent?.agent ?? null,
+        tenant: agent?.session?.tenant ?? null,
+        availability: agent?.availability ?? null,
+        isSupervisor: Boolean(agent?.isSupervisor),
+        setAvailability,
+    };
+}
+
+const CALL_LIST_EVENTS = ['incoming', 'elsewhere', 'callState', 'callEnded', 'ready'];
+
+/** This agent's calls (the SDK's Call objects). */
+export function useCalls() {
+    const { agent } = useCalloop();
+    useEmitter(agent, CALL_LIST_EVENTS);
+    return agent ? [...agent.calls.values()] : [];
+}
+
+/** Calls ringing for this agent. */
+export function useIncomingCalls() {
+    return useCalls().filter((c) => c.state === 'ringing');
+}
+
+/** The call this agent is on (connecting, active or dialing), or null. */
+export function useActiveCall() {
+    return useCalls().find((c) => ['connecting', 'active', 'dialing'].includes(c.state)) ?? null;
+}
+
+const CALL_EVENTS = ['state', 'updated', 'remoteStream', 'ended', 'dtmf', 'customerMedia', 'supervisorMode', 'privateChanged'];
+
+/** One call, kept current: its state, data, streams, and its actions. */
+export function useCall(call) {
+    useEmitter(call, CALL_EVENTS);
+    const [muted, setMuted] = useState(call?.muted ?? false);
+    const [lastDigit, setLastDigit] = useState(null);
+    useEffect(() => {
+        if (!call) return undefined;
+        setMuted(call.muted);
+        return call.on('dtmf', ({ digit }) => setLastDigit(digit));
+    }, [call]);
+
+    // Built on every render: the SDK updates call.data in place.
+    return {
+        call,
+        state: call?.state ?? null,
+        data: call?.data ?? null,
+        customer: call?.customer ?? null,
+        remoteStream: call?.remoteStream ?? null,
+        endReason: call?.endReason ?? null,
+        muted,
+        lastDigit,
+        accept: (opts) => call?.accept(opts),
+        decline: () => call?.decline(),
+        hangup: () => call?.hangup(),
+        mute: (value = true) => { call?.mute(value); setMuted(Boolean(value)); },
+        transfer: (target) => call?.transfer(target),
+        setPrivate: (active) => call?.setPrivate(active),
+        switchHere: (opts) => call?.switchHere(opts),
+    };
+}
+
+/** Queue snapshots. */
+export function useQueues() {
+    const { agent } = useCalloop();
+    useEmitter(agent, ['queue', 'ready']);
+    return agent ? [...agent.queues.values()] : [];
+}
+
+/** The tenant's agents' availability, as reported since connecting. */
+export function useTeam() {
+    const { agent } = useCalloop();
+    useEmitter(agent, ['team', 'ready']);
+    return agent ? [...agent.team.values()] : [];
+}
+
+/** Supervisors: the tenant's live calls. */
+export function useBoard() {
+    const { agent } = useCalloop();
+    useEmitter(agent, ['board', 'boardCall', 'boardCallEnded', 'ready']);
+    return agent ? [...agent.board.values()] : [];
+}
+
+const MONITOR_EVENTS = ['state', 'mode', 'stream', 'ended'];
+
+/**
+ * Supervisors: monitoring one call. start() asks for the microphone and
+ * listens; setMode('whisper' | 'barge'); stop(). Stops when the component
+ * unmounts or callId changes.
+ */
+export function useMonitor(callId) {
+    const { agent } = useCalloop();
+    const [monitor, setMonitor] = useState(null);
+    const [error, setError] = useState(null);
+    const current = useRef(null);
+    useEmitter(monitor, MONITOR_EVENTS);
+    // Refused or failed after start() resolved: Calloop's answer comes later.
+    useEffect(() => {
+        if (!monitor) return undefined;
+        const failed = ({ code, message }) => setError(Object.assign(new Error(message ?? 'Monitoring failed'), { code }));
+        const offs = [
+            monitor.on('ended', ({ reason, code, message }) => {
+                if (reason === 'failed' || reason === 'not_allowed') failed({ code, message: message ?? `Monitoring ${reason}` });
+            }),
+            monitor.on('modeRefused', failed),
+            monitor.on('mode', () => setError(null)),
+        ];
+        return () => offs.forEach((off) => off());
+    }, [monitor]);
+
+    const start = useCallback(async (opts) => {
+        if (!agent || callId == null) return null;
+        setError(null);
+        try {
+            const m = await agent.monitor(callId, opts);
+            current.current = m;
+            setMonitor(m);
+            return m;
+        } catch (err) {
+            setError(err);
+            return null;
+        }
+    }, [agent, callId]);
+
+    // Leaving this call (another callId, or unmount) stops its monitor — only
+    // its own: this cleanup can run after a monitor for the next call started.
+    useEffect(() => () => {
+        const m = current.current;
+        if (m && String(m.callId) === String(callId)) m.stop();
+    }, [callId]);
+
+    const active = monitor && monitor.state !== 'ended' && String(monitor.callId) === String(callId) ? monitor : null;
+    return {
+        monitor: active,
+        state: active?.state ?? 'idle',
+        mode: active?.mode ?? null,
+        stream: active?.stream ?? null,
+        error,
+        start,
+        stop: () => active?.stop(),
+        setMode: (mode) => active?.setMode(mode),
+        mute: (value = true) => active?.mute(value),
+    };
+}
+
+/** Plays a MediaStream (a call's remoteStream, a monitor's agent/customer stream). */
+export function RemoteAudio({ stream, muted = false, ...props }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el) return;
+        if (el.srcObject !== stream) el.srcObject = stream ?? null;
+        if (stream) el.play?.().catch(() => { /* autoplay policies: a user gesture starts it */ });
+    }, [stream]);
+    return createElement('audio', { ref, autoPlay: true, playsInline: true, muted, ...props });
+}