farvex 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # farvex
 
+## 0.2.0
+
+### Minor Changes
+
+- **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 `SessionRouteContext` accessible as `session.route`.
+- Added `useSessionCapabilities(sessionId?)` returning a capability `Set` for self.
+- Added `session.capabilitiesOf(participantId?)`.
+- Added `InviteManager.dropBySession` triggered on `session.remove` pulse messages so invites tied to ended sessions are reaped without waiting for per-invite removes.
+- Tests now live beside source (`foo.test.ts` next to `foo.ts`).
+- Regenerated API types against the rewritten session module (JSON-aggregate backend).
+- Added `./livekit` and `./mock` subpath exports.
+- Added `Session.mediaRoom` getter exposing the underlying `livekit-client` `Room`, so the React provider can share it with the LiveKit context.
+- Fixed: `CallpadProvider` now reuses the SDK's internal `Room` via `<RoomContext.Provider>` instead of instantiating a second `Room` through `<LiveKitRoom>`. Eliminates duplicate-identity races; mute state reflects the `Room` that actually publishes audio.
+- Fixed: `SessionEffectsExecutor` DI binding was missing from `sessionModule`; webhook jobs failed silently with `No bindings found for service: "SessionEffectsExecutor"`.
+- Fixed: inbound SIP caller participant is now created with `initialState: "joined"` (was `"accepted"`). Normal hangups now emit `session.participant.left` (reason `left`) instead of `session.participant.failed` (reason `unreachable`).
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -2,8 +2,6 @@
 
 Web SDK for Callpad sessions — a thin, React-friendly wrapper over LiveKit and the Callpad Pulse realtime layer for managing WebRTC and SIP sessions.
 
-> Scaffold state. No SDK surface is exposed yet beyond placeholder exports that prove the build pipeline. The first published version will be `0.1.0`; the real SDK surface lands in the next iteration.
-
 ## Install
 
 ```sh
@@ -22,30 +20,123 @@ pnpm add react react-dom
 
 ## Subpath exports
 
-| Entry          | Use when                                                       |
-| -------------- | -------------------------------------------------------------- |
-| `farvex`       | Curated top-level exports (ships placeholder during scaffold). |
-| `farvex/core`  | Framework-agnostic client (browser-safe at module load).       |
-| `farvex/react` | React hooks and providers. Carries `"use client"` for Next.js. |
-
-```ts
-import { version } from "farvex";
-import { corePlaceholder } from "farvex/core";
-import { reactPlaceholder } from "farvex/react";
+| 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.                 |
+
+## Quickstart (React)
+
+```tsx
+import {
+  CallpadProvider,
+  useIncomingInvite,
+  useCallControls,
+} from "farvex/react";
+
+export default function App() {
+  return (
+    <CallpadProvider
+      config={{
+        apiBaseUrl: "https://api.callpad.example.com",
+        vendor: "acme",
+        auth: { getAccessToken: async () => myToken() },
+      }}
+    >
+      <CallScreen />
+    </CallpadProvider>
+  );
+}
+
+function CallScreen() {
+  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>
+    );
+  }
+
+  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>
+      <button disabled={!controls.end.enabled} onClick={controls.end.run}>
+        End
+      </button>
+    </div>
+  );
+}
 ```
 
-Both ESM and CJS builds ship. Types resolve correctly for bundlers, Node 16+ ESM, and Node 16+ CJS.
-
-## Next.js
-
-- Import from `farvex/react` directly inside client components — the build preserves the `"use client"` directive, so no transpile hack is needed.
-- Import from `farvex/core` from server components (no DOM access at module load).
-- No `next.config.js` `transpilePackages` changes required.
-
-## Vite
-
-- Works out of the box. Vite consumes the ESM output.
-- `react` and `react-dom` are `external` at build time; your app supplies them.
+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
 
@@ -54,11 +145,18 @@ From `websdk/`:
 ```sh
 bun install
 bun run dev         # tsup watch mode; rebuilds dist/ on change
-bun run test        # vitest smoke tests
+bun run test        # vitest; includes unit tests next to source files
 bun run check       # lint + format + typecheck
 bun run build       # one-off production build
 ```
 
+API types are generated from the backend's OpenAPI spec:
+
+```sh
+# start the backend first: `bun run docker:up && docker compose up callpad.http`
+bun run generate:api   # writes src/api/generated/
+```
+
 ### Linking into a consumer app (goagentfe, customer app, etc.)
 
 We recommend [`yalc`](https://github.com/wclr/yalc) over `pnpm link` / `bun link` because it survives Vite and Next.js module caches.
@@ -85,7 +183,7 @@ Each change in `websdk/`:
 npx yalc push              # push built dist/ to subscribers
 ```
 
-Before committing in the consumer app, undo the local link so `package.json` doesn't point at `file:.yalc/farvex`:
+Before committing in the consumer app, undo the local link:
 
 ```sh
 npx yalc remove --all
@@ -94,36 +192,22 @@ pnpm install
 
 ## Release flow
 
-See `sdk-scaffold.md` at the repo root for the full plan. Short version (manual, no CI yet):
-
 ```sh
-# while working on a change (from repo root or websdk/):
-bun run changeset
-
-# when ready to publish (from websdk/), on clean main:
+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
 ```
 
-Before the first real publish:
-
-```sh
-npm login                    # as the publisher account
-npm view farvex              # must return 404
-bun run build
-bunx publint
-bun pm pack                  # inspect the tarball contents
-```
-
 Pre-1.0: every feature ships as a `minor` bump; breaking changes allowed without a major.
 
 ## Package conventions
 
 - 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.
-- `typescript/no-explicit-any` is enforced by oxlint; we avoid `unknown` in exported types by convention.
+- No `any` or `unknown` in exported types.
+- Tests live next to source (`foo.test.ts` beside `foo.ts`).
 - `engines.node >= 18`.
 
 ## Layout
@@ -131,14 +215,16 @@ Pre-1.0: every feature ships as a `minor` bump; breaking changes allowed without
 ```
 websdk/
   src/
-    index.ts              public entry (curated re-exports later)
-    core/index.ts         framework-agnostic client
-    react/index.ts        React hooks + providers
-  test/                   vitest + jsdom smoke tests
+    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
-  .oxlintrc.json          lint rules (matches apps/main)
-  .oxfmtrc.json           format rules (matches apps/main)
+  vitest.config.ts        jsdom test env (includes src/**/*.test.ts)
 ```