farvex 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # farvex
 
+## 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 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?)`.
+- 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

@@ -1,144 +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.
 
-> 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.
+## 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.
 
-```sh
-pnpm add react react-dom
-```
+## Setup
 
-## Subpath exports
+The SDK needs these values from the app:
 
-| 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. |
+| 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 { version } from "farvex";
-import { corePlaceholder } from "farvex/core";
-import { reactPlaceholder } from "farvex/react";
+import { createSessionClient } from "farvex";
+
+const callpad = createSessionClient({
+  apiUrl: "https://api.callpad.example.com",
+  userId: currentUser.id,
+  auth: {
+    getAccessToken,
+    onUnauthorized: () => {
+      auth.signOut();
+    },
+  },
+});
 ```
 
-Both ESM and CJS builds ship. Types resolve correctly for bundlers, Node 16+ ESM, and Node 16+ CJS.
+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.
 
-## Next.js
+```ts
+await callpad.connect();
+await callpad.sessions.sync();
+```
 
-- 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.
+SDK methods throw `CallpadError` for API problem responses. They do not return a
+custom result wrapper.
 
-## Vite
+## Customer App
 
-- Works out of the box. Vite consumes the ESM output.
-- `react` and `react-dom` are `external` at build time; your app supplies them.
+Customer apps use the common session client:
 
-## Local development
+```ts
+import { createSessionClient } from "farvex";
 
-From `websdk/`:
+const callpad = createSessionClient({
+  apiUrl: "https://api.callpad.example.com",
+  userId: customer.id,
+  auth: { getAccessToken },
+});
 
-```sh
-bun install
-bun run dev         # tsup watch mode; rebuilds dist/ on change
-bun run test        # vitest smoke tests
-bun run check       # lint + format + typecheck
-bun run build       # one-off production build
+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");
+}
 ```
 
-### Linking into a consumer app (goagentfe, customer app, etc.)
+`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
+"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],
+  );
+
+  return (
+    <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>
+);
+```
 
-We recommend [`yalc`](https://github.com/wclr/yalc) over `pnpm link` / `bun link` because it survives Vite and Next.js module caches.
+## Vendor App
 
-One-time setup:
+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.
 
-```sh
-# inside websdk/
-bun run dev                # keep running; watches src/ and rebuilds dist/
-npx yalc publish --push    # in another shell, first time
-```
+```ts
+import { createHostClient } from "farvex";
 
-In the consumer app (e.g. `goagentfe`):
+const callpad = createHostClient({
+  apiUrl: "https://api.callpad.example.com",
+  vendor: "acme",
+  userId: user.id,
+  auth: { getAccessToken },
+});
 
-```sh
-npx yalc add farvex
-pnpm install
-```
+const started = await callpad.sessions.start({
+  target: { type: "customer", userId: customer.id },
+});
 
-Each change in `websdk/`:
+await callpad.host.startRecording(started.session.id);
+```
 
-```sh
-# inside websdk/
-npx yalc push              # push built dist/ to subscribers
+### 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.
+
+```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 [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}>
+        Answer
+      </button>
+      <button type="button" onClick={reject}>
+        Decline
+      </button>
+      {join ? (
+        <LiveKitRoom serverUrl={join.url} token={join.token} audio video={false}>
+          <RoomAudioRenderer />
+        </LiveKitRoom>
+      ) : null}
+    </>
+  );
+};
 ```
 
-Before committing in the consumer app, undo the local link so `package.json` doesn't point at `file:.yalc/farvex`:
+### Host Controls
 
-```sh
-npx yalc remove --all
-pnpm install
+```ts
+const sessionId = started.session.id;
+
+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);
 ```
 
-## Release flow
+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
+
+Import `farvex/react` only from client components.
+
+```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>
+  );
+};
+```
 
-See `sdk-scaffold.md` at the repo root for the full plan. Short version (manual, no CI yet):
+Hooks:
 
-```sh
-# while working on a change (from repo root or websdk/):
-bun run changeset
+| 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.
 
-# when ready to publish (from websdk/), on clean main:
-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
+## LiveKit
+
+`farvex/livekit` re-exports first-party LiveKit primitives:
+
+```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>
+);
 ```
 
-Before the first real publish:
+## Development
+
+From `websdk/`:
 
 ```sh
-npm login                    # as the publisher account
-npm view farvex              # must return 404
+bun run generate
+bun run check
 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.
+HTTP calls must go through the generated Hey API client in `src/api/generated/`.
+Do not hand-edit generated files.
 
-## Package conventions
+## Release
 
-- 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.
-- `engines.node >= 18`.
+Changesets lives in `websdk/.changeset`. From `websdk/`:
 
-## Layout
-
-```
-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
-  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)
+```sh
+bun run changeset
+bun run version
+bun run release
 ```