farvex 0.2.0 → 1.0.1

package/CHANGELOG.md

@@ -1,15 +1,32 @@
 # farvex
 
+## 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
+
+- Prepare the SDK for a stable release with expanded customer and vendor integration documentation.
+
 ## 0.2.0
 
 ### Minor Changes
 
+- **BREAKING**: Session APIs are now vendor-scoped. The SDK uses `/api/v1/vendors/{slug}/sessions...` and no longer calls `/api/v1/sessions`.
+- **BREAKING**: `CallpadConfig` now requires `audience: "agent" | "customer"`. Agent clients fetch vendor Pulse grants; customer clients fetch global user Pulse grants.
+- **BREAKING**: Removed root `client.createSession`. Use `client.sessions.create(...)` for agent-originated sessions and `client.sessions.request(...)` for customer-originated sessions.
+- Added customer session request flow with default auto-join and `useSessionRequest()`.
+- Added `session.updated` client event and React hook invalidation for session upserts.
 - **BREAKING**: Replaced Offer with Invite. `OfferManager` → `InviteManager`, `Offer` → `Invite`, `useIncomingOffer` → `useIncomingInvite`, pulse topics `session.offer.*` → `session.invite.*`, endpoints `/sessions/offers/{offerId}/*` → `/sessions/{sessionId}/invites/{inviteId}/*`. No deprecation shims — all offer-era symbols are removed.
 - **BREAKING**: `Session.telephonyLegs` is now derived from `participant.operations[]` where `kind === "sip_leg"`. The backend no longer returns a top-level `telephonyLegs[]`.
 - **BREAKING**: Participant lifecycle states changed. Removed `ringing`, `joining`. Added `accepted`, `declined`, `withdrawn`. New `SessionEventMap` keys: `participant.accepted`, `participant.declined`, `participant.withdrawn`.
 - **BREAKING**: `isSelf` is now keyed by `participantId` instead of `participantIdentity`. `SessionManagerOptions.selfIdentity` renamed to `selfParticipantId`. The join grant now carries `participantId`; `Session.join()` uses it.
 - **BREAKING**: `useCallControls` controls now expose `enabled: boolean` on each slot and gate actions by the current participant's `capabilities[]`. `leave`/`end` return `{enabled, run}` instead of a bare function. Disabled when capability is missing; never hidden.
-- Added `Dispatch` surface (ring-group) with `session.dispatches`, `useSessionDispatches`, and events: `dispatch.started`, `dispatch.resolved`, `dispatch.cancelled`, `dispatch.expired`.
+- Added `Dispatch` surface for team fan-out with `session.dispatches` and events: `dispatch.started`, `dispatch.resolved`, `dispatch.cancelled`.
 - Added `SessionRouteContext` accessible as `session.route`.
 - Added `useSessionCapabilities(sessionId?)` returning a capability `Set` for self.
 - Added `session.capabilitiesOf(participantId?)`.

package/README.md

@@ -1,230 +1,347 @@
 # farvex
 
-Web SDK for Callpad sessions — a thin, React-friendly wrapper over LiveKit and the Callpad Pulse realtime layer for managing WebRTC and SIP sessions.
+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.
+
+## 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.            |
 
 ## Install
 
 ```sh
-npm i farvex
-# or
-pnpm add farvex
-# or
-bun add farvex
+npm install farvex livekit-client @livekit/components-react
 ```
 
-React and react-dom are optional peer dependencies (only needed when you import from `farvex/react`):
+`livekit-client`, `@livekit/components-react`, `react`, and `react-dom` are
+peer dependencies. Install the LiveKit packages only in apps that render call
+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.
+
+```ts
+import { createSessionClient } from "farvex";
+
+const callpad = createSessionClient({
+  apiUrl: "https://api.callpad.example.com",
+  userId: currentUser.id,
+  auth: {
+    getAccessToken,
+    onUnauthorized: () => {
+      auth.signOut();
+    },
+  },
+});
+```
 
-```sh
-pnpm add react react-dom
+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();
 ```
 
-## Subpath exports
+SDK methods throw `CallpadError` for API problem responses. They do not return a
+custom result wrapper.
 
-| Entry            | Use when                                                       |
-| ---------------- | -------------------------------------------------------------- |
-| `farvex`         | Curated top-level exports.                                     |
-| `farvex/core`    | Framework-agnostic client (browser-safe at module load).       |
-| `farvex/react`   | React hooks and providers. Carries `"use client"` for Next.js. |
-| `farvex/livekit` | Re-exports livekit-client + @livekit/components-react types.   |
-| `farvex/mock`    | In-memory mock client for tests and storybook.                 |
+## Customer App
 
-## Quickstart (React)
+Customer apps use the common session client:
+
+```ts
+import { createSessionClient } from "farvex";
+
+const callpad = createSessionClient({
+  apiUrl: "https://api.callpad.example.com",
+  userId: customer.id,
+  auth: { getAccessToken },
+});
+
+await callpad.connect();
+
+const started = await callpad.sessions.start({
+  vendor: "acme",
+  target: { type: "vendor_user", userId: 42 },
+});
+
+if (!started.join) {
+  throw new Error("This session did not return a media grant");
+}
+```
+
+`started.session` is the current `VoiceSession`. `started.join` is a LiveKit
+grant for the caller when the current user should join the media room.
+
+### Customer Calls A Vendor User
+
+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.
 
 ```tsx
-import {
-  CallpadProvider,
-  useIncomingInvite,
-  useCallControls,
-} from "farvex/react";
+"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;
+
+export const CustomerVoice = ({ customerId }: { customerId: number }) => {
+  const client = useMemo<SessionClient>(
+    () =>
+      createSessionClient({
+        apiUrl: process.env.NEXT_PUBLIC_CALLPAD_API_URL!,
+        userId: customerId,
+        auth: { getAccessToken },
+      }),
+    [customerId],
+  );
 
-export default function App() {
   return (
-    <CallpadProvider
-      config={{
-        apiBaseUrl: "https://api.callpad.example.com",
-        vendor: "acme",
-        auth: { getAccessToken: async () => myToken() },
-      }}
-    >
-      <CallScreen />
+    <CallpadProvider client={client} connect disposeOnUnmount>
+      <CustomerCallButton />
     </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
+
+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.
+
+```ts
+import { createHostClient } from "farvex";
+
+const callpad = createHostClient({
+  apiUrl: "https://api.callpad.example.com",
+  vendor: "acme",
+  userId: user.id,
+  auth: { getAccessToken },
+});
+
+const started = await callpad.sessions.start({
+  target: { type: "customer", userId: customer.id },
+});
+
+await callpad.host.startRecording(started.session.id);
+```
+
+### Receiving Customer Calls
 
-function CallScreen() {
+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.
+
+```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 invite = useIncomingInvite();
-  const controls = useCallControls();
-
-  if (invite) {
-    return (
-      <div>
-        <p>Incoming invite from {invite.inviterParticipantId ?? "unknown"}</p>
-        <button onClick={() => invite.accept()}>Accept</button>
-        <button onClick={() => invite.reject()}>Decline</button>
-      </div>
-    );
+  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 (
-    <div>
-      <button disabled={!controls.hold.enabled} onClick={controls.hold.toggle}>
-        {controls.hold.active ? "Resume" : "Hold"}
-      </button>
-      <button
-        disabled={!controls.recording.enabled}
-        onClick={controls.recording.toggle}
-      >
-        {controls.recording.active ? "Stop recording" : "Record"}
+    <>
+      <button type="button" onClick={accept}>
+        Answer
       </button>
-      <button disabled={!controls.end.enabled} onClick={controls.end.run}>
-        End
+      <button type="button" onClick={reject}>
+        Decline
       </button>
-    </div>
+      {join ? (
+        <LiveKitRoom serverUrl={join.url} token={join.token} audio video={false}>
+          <RoomAudioRenderer />
+        </LiveKitRoom>
+      ) : null}
+    </>
   );
-}
+};
 ```
 
-Controls are capability-gated: the backend sends a per-participant `capabilities[]` list, and hooks return `enabled: false` when the required capability is missing. Render them disabled rather than hidden.
-
-## Core concepts
-
-- **Session** — one call. Has `participants`, `dispatches`, `recordings`, `route`. State is derived: `ringing | active | on_hold | ended`. Telephony legs (SIP) live inside each participant's `operations[]`.
-- **Invite** — a pending app invite sent to a specific recipient (agent or user). The recipient accepts via `POST /api/v1/sessions/{sessionId}/invites/{inviteId}/accept`.
-- **Dispatch** — a ring-group: one or more agents rung in parallel or sequentially. When one answers, the dispatch `resolves` and the siblings transition to `withdrawn`.
-- **Capability** — per-participant permission: `hold_session`, `end_session`, `start_recording`, etc. Use `session.capabilitiesOf()` to gate UI.
-
-## React hooks
-
-| Hook                                                                                          | Purpose                                                                  |
-| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `useCallpadClient()`                                                                          | Access underlying client + connection status.                            |
-| `useSessions()` / `useSession(id?)`                                                           | All sessions / active session or by id.                                  |
-| `useIncomingInvite()` / `useIncomingInvites()`                                                | First pending invite / all pending invites for the current user.         |
-| `useSessionParticipants(id?)` / `useSessionParticipant(pid, id?)` / `useSelfParticipant(id?)` | Participants in a session.                                               |
-| `useSessionCapabilities(id?)`                                                                 | Capability `Set` for self in the active session.                         |
-| `useSessionDispatches(id?)`                                                                   | Active ring-group dispatches in a session.                               |
-| `useCallControls(id?)`                                                                        | Capability-gated mic / camera / screen / hold / recording / leave / end. |
-| `useCallDuration(id?)`                                                                        | `{formatted, elapsedSeconds}` since session activated.                   |
-| `useIsHeld(id?)`                                                                              | Whether the session is on hold.                                          |
-| `useActiveRecording(id?)`                                                                     | Current in-progress recording (if any).                                  |
-| `useSessionEvent(event, handler, id?)`                                                        | Subscribe to a session event with auto cleanup.                          |
-| `useClientEvent(event, handler)`                                                              | Subscribe to a client event with auto cleanup.                           |
-| `usePresence(refs)` / `useMyPresence()`                                                       | Presence query + my presence control.                                    |
-
-## Realtime events
-
-Pulse pushes these topics (SDK forwards them on `PulseTransport`):
-
-| Topic                   | Payload                                                                  |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `session.upsert`        | Full `SessionView`.                                                      |
-| `session.remove`        | `{sessionId, version}`. Also drops any pending invites for that session. |
-| `session.invite.upsert` | `SessionInviteView` — add/update a pending invite for the current user.  |
-| `session.invite.remove` | `{inviteId, sessionId, participantId, state}`.                           |
-
-## HTTP endpoints used
-
-All under `/api/v1`:
-
-- `GET /sessions` — prime the session list.
-- `POST /sessions` — create a session.
-- `GET /sessions/{sessionId}` — fetch by id.
-- `PATCH /sessions/{sessionId}` — update name.
-- `POST /sessions/{sessionId}/join` — get a LiveKit token grant.
-- `POST /sessions/{sessionId}/hold` / `.../unhold` / `.../cancel` / `.../leave` / `.../end`
-- `POST /sessions/{sessionId}/participants` — invite a target (agent/user/contact/phone).
-- `DELETE /sessions/{sessionId}/participants/{participantId}` — remove a participant.
-- `POST /sessions/{sessionId}/recordings` / `.../recordings/{recordingId}/stop` — recording control.
-- `GET /sessions/invites` — list pending invites for the current user.
-- `POST /sessions/{sessionId}/invites/{inviteId}/accept` / `.../reject` — act on an invite.
-
-## Local development
+### Host Controls
 
-From `websdk/`:
+```ts
+const sessionId = started.session.id;
 
-```sh
-bun install
-bun run dev         # tsup watch mode; rebuilds dist/ on change
-bun run test        # vitest; includes unit tests next to source files
-bun run check       # lint + format + typecheck
-bun run build       # one-off production build
+await callpad.host.addParticipant({
+  sessionId,
+  target: { type: "phone", phone: "+15551234567" },
+});
+
+await callpad.host.startRecording(sessionId);
+await callpad.host.stopRecording(sessionId);
+await callpad.host.end(sessionId);
 ```
 
-API types are generated from the backend's OpenAPI spec:
+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`.
 
-```sh
-# start the backend first: `bun run docker:up && docker compose up callpad.http`
-bun run generate:api   # writes src/api/generated/
-```
+## React
 
-### Linking into a consumer app (goagentfe, customer app, etc.)
+Import `farvex/react` only from client components.
 
-We recommend [`yalc`](https://github.com/wclr/yalc) over `pnpm link` / `bun link` because it survives Vite and Next.js module caches.
+```tsx
+"use client";
 
-One-time setup:
+import { useMemo, type ReactNode } from "react";
+import { createHostClient, type HostClient } from "farvex";
+import {
+  CallpadProvider,
+  useCallpad,
+  useIncomingInvite,
+  useSession,
+  useStatus,
+} from "farvex/react";
 
-```sh
-# inside websdk/
-bun run dev                # keep running; watches src/ and rebuilds dist/
-npx yalc publish --push    # in another shell, first time
+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>
+  );
+};
 ```
 
-In the consumer app (e.g. `goagentfe`):
+Hooks:
 
-```sh
-npx yalc add farvex
-pnpm install
-```
+| 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.                                |
 
-Each change in `websdk/`:
+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.
 
-```sh
-# inside websdk/
-npx yalc push              # push built dist/ to subscribers
-```
+## LiveKit
 
-Before committing in the consumer app, undo the local link:
+`farvex/livekit` re-exports first-party LiveKit primitives:
 
-```sh
-npx yalc remove --all
-pnpm install
+```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>
+);
 ```
 
-## Release flow
+## Development
+
+From `websdk/`:
 
 ```sh
-bun run changeset            # while working on a change
-bun run version              # applies pending changesets, writes CHANGELOG.md
-git commit -am "chore: release farvex@x.y.z"
-bun run release              # builds, runs changeset publish
-git push --follow-tags
+bun run generate
+bun run check
+bun run build
 ```
 
-Pre-1.0: every feature ships as a `minor` bump; breaking changes allowed without a major.
-
-## Package conventions
+HTTP calls must go through the generated Hey API client in `src/api/generated/`.
+Do not hand-edit generated files.
 
-- Side-effect free — `"sideEffects": false` in `package.json`. Tree-shakes cleanly.
-- No top-level access to `window`, `document`, `navigator`, `RTCPeerConnection`, or `localStorage`. Any such access happens inside methods or effects.
-- No `any` or `unknown` in exported types.
-- Tests live next to source (`foo.test.ts` beside `foo.ts`).
-- `engines.node >= 18`.
+## Release
 
-## Layout
+Changesets lives in `websdk/.changeset`. From `websdk/`:
 
-```
-websdk/
-  src/
-    index.ts              public entry
-    core/                 framework-agnostic client
-      session/            Session class + commands
-      managers/           SessionManager, InviteManager, PresenceManager
-      transport/          PulseTransport, MediaRoomAdapter
-    react/                React hooks + providers
-    mock/                 in-memory mock client + scenarios
-  test/                   setup + cross-cutting smoke tests
-  dist/                   build output (gitignored)
-  tsup.config.ts          build config (ESM + CJS + dts, use-client preserved)
-  tsconfig.json           strict TS, bundler resolution
-  vitest.config.ts        jsdom test env (includes src/**/*.test.ts)
+```sh
+bun run changeset
+bun run version
+bun run release
 ```