farvex 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # farvex
 
+## 2.0.0
+
+### Major Changes
+
+- Add a first-class current-session controller for browser media sessions.
+
+  This release introduces `client.session`, `useCurrentSession`, `useCurrentSessionActions`, and `SessionRoom` so consumers can start, accept, join, end, and render the current media session without maintaining separate join-grant state.
+
+  Breaking changes:
+  - `useSession()` and `sessions.get()` now require an explicit session ID and no longer infer the newest non-ended session.
+  - Consumers should use `client.session.start()` and `client.session.accept()` for user-facing media flows instead of low-level `client.sessions.start()` / `client.sessions.accept()`.
+  - Current session state is now represented by the SDK's `CurrentSession` snapshot rather than consumer-local LiveKit token state.
+
+## 1.0.1
+
+### Patch Changes
+
+- Fix host client disposal, expire stale incoming invites, and export host start input types for frontend integrations.
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -1,17 +1,16 @@
 # farvex
 
 Web SDK for Callpad voice sessions. It wraps the generated session HTTP client,
-Centrifugo realtime updates, and LiveKit re-exports. Calls history, notes,
-wrap-up, billing, metrics, and recording playback should use the normal REST
-API clients.
+Centrifugo realtime updates, a current browser session controller, React hooks,
+and LiveKit helpers.
 
 ## Exports
 
-| Entry            | Purpose                                     |
-| ---------------- | ------------------------------------------- |
-| `farvex`         | Session client factories and SDK/API types. |
-| `farvex/react`   | React provider and focused session hooks.   |
-| `farvex/livekit` | LiveKit React/client re-exports.            |
+| Entry            | Purpose                                   |
+| ---------------- | ----------------------------------------- |
+| `farvex`         | Client factories and SDK/API types.       |
+| `farvex/react`   | React provider and focused session hooks. |
+| `farvex/livekit` | LiveKit re-exports and `SessionRoom`.     |
 
 ## Install
 
@@ -20,309 +19,236 @@ npm install farvex livekit-client @livekit/components-react
 ```
 
 `livekit-client`, `@livekit/components-react`, `react`, and `react-dom` are
-peer dependencies. Install the LiveKit packages only in apps that render call
-media.
+peer dependencies. Install the LiveKit packages only in apps that render media.
 
-## Setup
-
-The SDK needs these values from the app:
-
-| Value    | Description                                     |
-| -------- | ----------------------------------------------- |
-| `apiUrl` | Base URL for the Callpad API.                   |
-| `userId` | Callpad user ID for the signed-in app user.     |
-| `auth`   | Function that returns a bearer token on demand. |
-| `vendor` | Vendor slug. Required by host clients.          |
-
-`getAccessToken` is called before API requests and when realtime auth needs a
-fresh token. Keep token minting in your app backend or existing auth layer; the
-browser client should only receive a user-scoped token. The examples below
-assume `getAccessToken` already exists in the app.
+## Client Setup
 
 ```ts
-import { createSessionClient } from "farvex";
+import { createHostClient } from "farvex";
 
-const callpad = createSessionClient({
+const client = createHostClient({
   apiUrl: "https://api.callpad.example.com",
-  userId: currentUser.id,
+  vendor: "acme",
+  userId: user.id,
   auth: {
     getAccessToken,
-    onUnauthorized: () => {
-      auth.signOut();
-    },
+    onUnauthorized: () => auth.signOut(),
   },
 });
-```
 
-Call `connect()` once when the voice UI mounts. This opens the realtime
-connection and keeps `sessions`, `invites`, and `status` updated. Call
-`disconnect()` when the user leaves the voice UI, or `dispose()` when the client
-will not be reused.
-
-```ts
-await callpad.connect();
-await callpad.sessions.sync();
+await client.connect();
+await client.sessions.sync(undefined, { mode: "replaceVisible" });
 ```
 
-SDK methods throw `CallpadError` for API problem responses. They do not return a
-custom result wrapper.
+`getAccessToken` is called before REST requests and realtime token refreshes.
+SDK methods throw `CallpadError` for API problem responses.
 
-## Customer App
+## API Shape
 
-Customer apps use the common session client:
+Use `client.session` for the current browser media session lifecycle:
 
 ```ts
-import { createSessionClient } from "farvex";
-
-const callpad = createSessionClient({
-  apiUrl: "https://api.callpad.example.com",
-  userId: customer.id,
-  auth: { getAccessToken },
+const current = await client.session.start({
+  target: { type: "customer", userId: customer.id },
 });
 
-await callpad.connect();
+await client.session.end();
+```
 
-const started = await callpad.sessions.start({
-  vendor: "acme",
-  target: { type: "vendor_user", userId: 42 },
-});
+Use `client.sessions` for the low-level collection/data API:
 
-if (!started.join) {
-  throw new Error("This session did not return a media grant");
-}
+```ts
+const sessions = await client.sessions.sync();
+const session = client.sessions.get(current.sessionId);
+const canRecord = session ? client.sessions.can(session, "startRecording") : false;
 ```
 
-`started.session` is the current `VoiceSession`. `started.join` is a LiveKit
-grant for the caller when the current user should join the media room.
+The backend can support many live sessions. The browser SDK defaults to one
+current media session per client instance. `client.session.start()` and
+`client.session.accept()` use `rejectWhileBusy` by default, so starting or
+accepting while a non-terminal current session exists fails locally with
+`session.busy`. Pass `{ behavior: "allowParallel" }` only when intentionally
+creating and selecting another backend session.
 
-### Customer Calls A Vendor User
+`StartedSession.join` from the generated API is nullable. The high-level
+`client.session` methods require a media grant by default and fail with
+`session.join_unavailable` if the backend creates/accepts a session but does not
+return a browser media grant.
 
-This example starts an app-to-app call from a customer to a specific vendor user
-and renders the audio room after the session is created.
+## React Usage
+
+Import `farvex/react` from client components.
 
 ```tsx
 "use client";
 
-import { useMemo, useState } from "react";
-import { createSessionClient, type SessionClient, type VoiceJoinGrant } from "farvex";
-import { CallpadProvider, useCallpad } from "farvex/react";
-import { LiveKitRoom, RoomAudioRenderer } from "farvex/livekit";
-
-const vendor = "acme";
-const vendorUserId = 42;
+import { useMemo, type ReactNode } from "react";
+import { createHostClient, type HostClient } from "farvex";
+import { CallpadProvider } from "farvex/react";
 
-export const CustomerVoice = ({ customerId }: { customerId: number }) => {
-  const client = useMemo<SessionClient>(
+export const VoiceProvider = ({ children }: { children: ReactNode }) => {
+  const client = useMemo<HostClient>(
     () =>
-      createSessionClient({
+      createHostClient({
         apiUrl: process.env.NEXT_PUBLIC_CALLPAD_API_URL!,
-        userId: customerId,
+        vendor: "acme",
+        userId: 42,
         auth: { getAccessToken },
       }),
-    [customerId],
+    [],
   );
 
   return (
     <CallpadProvider client={client} connect disposeOnUnmount>
-      <CustomerCallButton />
+      {children}
     </CallpadProvider>
   );
 };
-
-const CustomerCallButton = () => {
-  const callpad = useCallpad();
-  const [join, setJoin] = useState<VoiceJoinGrant | null>(null);
-
-  const startCall = async () => {
-    const started = await callpad.sessions.start({
-      vendor,
-      target: { type: "vendor_user", userId: vendorUserId },
-    });
-    setJoin(started.join);
-  };
-
-  return (
-    <>
-      <button type="button" onClick={startCall}>
-        Call support
-      </button>
-      {join ? <SessionMedia join={join} /> : null}
-    </>
-  );
-};
-
-const SessionMedia = ({ join }: { join: VoiceJoinGrant }) => (
-  <LiveKitRoom serverUrl={join.url} token={join.token} audio video={false}>
-    <RoomAudioRenderer />
-  </LiveKitRoom>
-);
 ```
 
-## Vendor App
+Hooks:
 
-Vendor-side apps use the host client. Host clients can start calls to customers,
-contacts, and phone numbers, and can use elevated controls such as recording and
-ending a session.
+| Hook                         | Purpose                                     |
+| ---------------------------- | ------------------------------------------- |
+| `useCallpad()`               | Current SDK client.                         |
+| `useStatus()`                | Realtime connection status.                 |
+| `useSessions()`              | Visible session collection.                 |
+| `useSession(id)`             | Exact session lookup. Pass `null` for none. |
+| `useCurrentSession()`        | Current browser media-session snapshot.     |
+| `useCurrentSessionActions()` | Current session commands and media events.  |
+| `useIncomingInvites()`       | Pending invites for the current user.       |
+| `useIncomingInvite()`        | First pending invite shortcut.              |
+| `useCan(id, action)`         | UI helper for low-level session actions.    |
+| `useSessionDuration(id)`     | Live elapsed time for an exact session ID.  |
+
+Starting a session:
 
-```ts
-import { createHostClient } from "farvex";
+```tsx
+import { useCallpad, useCurrentSession } from "farvex/react";
 
-const callpad = createHostClient({
-  apiUrl: "https://api.callpad.example.com",
-  vendor: "acme",
-  userId: user.id,
-  auth: { getAccessToken },
-});
+const StartButton = () => {
+  const client = useCallpad<HostClient>();
+  const { busy } = useCurrentSession();
 
-const started = await callpad.sessions.start({
-  target: { type: "customer", userId: customer.id },
-});
+  const start = () =>
+    client.session.start({
+      target: { type: "phone", phone: "+15551234567" },
+    });
 
-await callpad.host.startRecording(started.session.id);
+  return (
+    <button type="button" disabled={busy} onClick={start}>
+      Start session
+    </button>
+  );
+};
 ```
 
-### Receiving Customer Calls
-
-When a customer calls a vendor user, the vendor app receives an incoming invite
-over realtime. Accepting the invite returns a join grant for the vendor user.
+Accepting an invite:
 
 ```tsx
-"use client";
-
-import { useState } from "react";
-import { type VoiceJoinGrant } from "farvex";
 import { useCallpad, useIncomingInvite } from "farvex/react";
-import { LiveKitRoom, RoomAudioRenderer } from "farvex/livekit";
 
-export const IncomingCall = () => {
-  const callpad = useCallpad();
+const IncomingInvite = () => {
+  const client = useCallpad<HostClient>();
   const invite = useIncomingInvite();
-  const [join, setJoin] = useState<VoiceJoinGrant | null>(null);
 
   if (!invite) {
     return null;
   }
 
-  const accept = async () => {
-    const started = await callpad.sessions.accept({
-      sessionId: invite.session.id,
-      participantId: invite.participant.id,
-    });
-    setJoin(started.join);
-  };
-
-  const reject = () =>
-    callpad.sessions.reject({
-      sessionId: invite.session.id,
-      participantId: invite.participant.id,
-    });
-
   return (
     <>
-      <button type="button" onClick={accept}>
+      <button
+        type="button"
+        onClick={() =>
+          client.session.accept({
+            sessionId: invite.session.id,
+            participantId: invite.participant.id,
+          })
+        }
+      >
         Answer
       </button>
-      <button type="button" onClick={reject}>
+      <button
+        type="button"
+        onClick={() =>
+          client.sessions.reject({
+            sessionId: invite.session.id,
+            participantId: invite.participant.id,
+          })
+        }
+      >
         Decline
       </button>
-      {join ? (
-        <LiveKitRoom serverUrl={join.url} token={join.token} audio video={false}>
-          <RoomAudioRenderer />
-        </LiveKitRoom>
-      ) : null}
     </>
   );
 };
 ```
 
-### Host Controls
+Overlay and media should use the same current session ID:
 
-```ts
-const sessionId = started.session.id;
+```tsx
+import { RoomAudioRenderer, SessionRoom } from "farvex/livekit";
+import { useCurrentSession, useCurrentSessionActions, useSession } from "farvex/react";
 
-await callpad.host.addParticipant({
-  sessionId,
-  target: { type: "phone", phone: "+15551234567" },
-});
+const SessionOverlay = () => {
+  const snapshot = useCurrentSession();
+  const actions = useCurrentSessionActions();
+  const session = useSession(snapshot.current?.sessionId ?? null);
 
-await callpad.host.startRecording(sessionId);
-await callpad.host.stopRecording(sessionId);
-await callpad.host.end(sessionId);
+  return (
+    <>
+      <SessionRoom session={snapshot.current} controls={actions}>
+        <RoomAudioRenderer />
+      </SessionRoom>
+      {snapshot.current && session ? (
+        <SessionPanel session={session} phase={snapshot.current.phase} />
+      ) : null}
+    </>
+  );
+};
 ```
 
-Use `sessions.can(session, action)` or the React `useCan(id, action)` hook to
-gate controls before calling actions such as `accept`, `leave`, `end`, or
-`startRecording`.
-
-## React
+## LiveKit
 
-Import `farvex/react` only from client components.
+`farvex/livekit` re-exports first-party LiveKit primitives and adds
+`SessionRoom`. Use `SessionRoom` for the normal SDK flow; use raw `LiveKitRoom`
+only for advanced media ownership.
 
 ```tsx
-"use client";
-
-import { useMemo, type ReactNode } from "react";
-import { createHostClient, type HostClient } from "farvex";
-import {
-  CallpadProvider,
-  useCallpad,
-  useIncomingInvite,
-  useSession,
-  useStatus,
-} from "farvex/react";
-
-export const VoiceProvider = ({ children }: { children: ReactNode }) => {
-  const client = useMemo<HostClient>(
-    () =>
-      createHostClient({
-        apiUrl: process.env.NEXT_PUBLIC_CALLPAD_API_URL!,
-        vendor: "acme",
-        userId: 42,
-        auth: { getAccessToken },
-      }),
-    [],
-  );
-
-  return (
-    <CallpadProvider client={client} connect disposeOnUnmount>
-      {children}
-    </CallpadProvider>
-  );
-};
+<SessionRoom session={current} controls={client.session} audio video={false}>
+  <RoomAudioRenderer />
+</SessionRoom>
 ```
 
-Hooks:
+`SessionRoom` renders nothing without a current session or join grant. It passes
+`session.join.url` and `session.join.token` to LiveKit and reports connected,
+disconnected, and error events back to the session controller when `controls` is
+provided.
 
-| Hook                      | Purpose                                           |
-| ------------------------- | ------------------------------------------------- |
-| `useCallpad()`            | Current SDK client.                               |
-| `useStatus()`             | Realtime connection status.                       |
-| `useSessions()`           | Visible live sessions.                            |
-| `useSession(id?)`         | Specific session, or active session when omitted. |
-| `useIncomingInvites()`    | Pending invites for the current user.             |
-| `useIncomingInvite()`     | First pending invite.                             |
-| `useCan(id, action)`      | UI helper for session actions.                    |
-| `useSessionDuration(id?)` | Live elapsed time.                                |
-
-Session participants and metadata are exposed on `VoiceSession.participants`.
-Use LiveKit hooks for media participants, tracks, mute state, speaking state,
-device selection, and room lifecycle.
+## Ringing Timeout
 
-## LiveKit
+The SDK may hide expired incoming invites locally for immediate UX, but backend
+REST/realtime state is authoritative for final session state. Apps should render
+terminal state from `VoiceSession.state`, realtime events, and REST
+reconciliation rather than treating a local timer as final.
 
-`farvex/livekit` re-exports first-party LiveKit primitives:
+## Migration Notes
+
+Replace no-ID `useSession()`:
 
 ```tsx
-import { LiveKitRoom, RoomAudioRenderer } from "farvex/livekit";
-import type { VoiceJoinGrant } from "farvex";
-
-export const SessionMedia = ({ join }: { join: VoiceJoinGrant }) => (
-  <LiveKitRoom serverUrl={join.url} token={join.token} audio video={false}>
-    <RoomAudioRenderer />
-  </LiveKitRoom>
-);
+const { current } = useCurrentSession();
+const session = useSession(current?.sessionId ?? null);
 ```
 
+Replace local raw join-grant state with `client.session` and `SessionRoom`.
+The current session stores `{ sessionId, participantId, join }`, so the overlay,
+media room, controls, and participant UI all target the same session.
+
+SDK source should use the exported `Nullable<T>` alias for nullable types instead
+of direct null unions in public SDK types.
+
 ## Development
 
 From `websdk/`: