@hainiva/agent-sdk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to `@hainiva/agent-sdk` are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses
+[Semantic Versioning](https://semver.org/). While the version is `0.x`, a minor
+release (`0.2.0`) may change the API; a patch release (`0.1.1`) never does.
+
+## [Unreleased]
+
+## [0.2.0]
+
+Preview, not yet published.
+
+- `HainivaAgent`: one object for a staff member's app — `connect()`, `me`,
+  `setStatus`, `rings.pending`, `calls.accept/decline/end/hold/mute/transfer`,
+  `joinMedia` (through the `/web` or `/react-native` LiveKit adapter),
+  `conversations.*`, `messages.*`, `wrapUp`, `dispositions`, `supervisor.*`,
+  `push.register/unregister`, `on(event)`, `disconnect({ signOut })`.
+- `AgentRestClient`: every `/agent/v1` endpoint, typed with the Agent API
+  contract (`AgentMeDto`, `AgentAcceptDto`, …, exported). Errors are
+  `HainivaAgentError` from the `{error:{code,message}}` envelope. A 401
+  `token_expired` refreshes once (single flight) and retries; a refused refresh
+  signs in again with a new assertion; `session_revoked` is final. Every POST
+  carries an `Idempotency-Key` (reused by the retry). Timeouts and
+  `AbortSignal`. Ids are checked before they go into a path.
+- `/agent/v1/ws` bindings (`agentSocketBindings`): auth first frame with the
+  resume position, `token.refresh`, `session.expiring` (refresh at once),
+  `resync_required` (rings refetched, `resync` event), close codes 4001 / 4003
+  / 4009. `call.*` events drive the `CallStore`.
+- `SessionManager.invalidate(refusedToken)` ignores a refusal of an older token;
+  `SessionManager.clear()` forgets a session the server already ended.
+- `ReconnectingSocket` `closeCodes.fatal`: close codes that stop reconnecting.
+
+## [0.1.0]
+
+Preview, not yet published.
+
+- `SessionManager`: sign-in with a fresh assertion from your backend every
+  time, pluggable `SessionStore` (memory by default), single-flight refresh
+  before expiry, new sign-in when a refresh is refused.
+- `ReconnectingSocket`: first-frame auth, exponential backoff with jitter,
+  heartbeat with dead-connection timeout, `resume {lastSeq}` hook, duplicate
+  frame suppression, revoked / token-expired close codes, pluggable frames.
+- `CallStore` / `transition`: the agent call state machine (ringing,
+  connecting, active, held, transferring, ended; concurrent rings; ring expiry).
+- `TypedEmitter`, `singleFlight`, `createTokenRefresher`, `assertSafeUrl`,
+  `Redactor`, `HainivaAgentError` (redacted).
+- `/web`: `localStorageStore` (opt-in), `joinCallRoom` (LiveKit).
+- `/react-native`: `secureStoreSessionStore`, `joinCallRoom` (LiveKit).
+- `/embed`: placeholder, throws.
+
+[Unreleased]: https://github.com/hainiva/agent-sdk/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/hainiva/agent-sdk/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/hainiva/agent-sdk/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ePacific Telecom (HAINIVA)
+
+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,202 @@
-# Temporary Holding Version
+# @hainiva/agent-sdk
 
-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.
+Build **your own staff app** on [HAINIVA AICC](https://hainiva.com): your staff
+sign in with an assertion from your backend, receive their rings and
+conversations over one reconnecting socket, and take calls with LiveKit — in a
+browser, in React Native, or in Node.
+
+> **Status: 0.x preview.** The API may change in a minor release until 1.0.
+
+| Import | What | Needs |
+| --- | --- | --- |
+| `@hainiva/agent-sdk` | `HainivaAgent`, the REST client, the socket, the call state machine, redaction | nothing (no LiveKit, DOM or React Native) |
+| `@hainiva/agent-sdk/web` | `joinCallRoom` (LiveKit), `localStorageStore` (opt-in) | `livekit-client` |
+| `@hainiva/agent-sdk/react-native` | `joinCallRoom`, `secureStoreSessionStore` | `livekit-client`, `@livekit/react-native`, `expo-secure-store` |
+| `@hainiva/agent-sdk/embed` | the embeddable desk | not yet available (throws) |
+
+Native ringing on phones (CallKit / Android call notification) is
+[`@hainiva/react-native-call`](https://github.com/hainiva/react-native-call).
+Samples: [`examples/`](./examples) — a Node assertion signer, an Expo staff
+app and a web softphone.
+
+## Install
+
+```sh
+npm install @hainiva/agent-sdk livekit-client
+```
+
+## Quickstart
+
+```ts
+import { HainivaAgent } from "@hainiva/agent-sdk";
+import { joinCallRoom } from "@hainiva/agent-sdk/web";
+
+const agent = new HainivaAgent({
+  baseUrl: "https://api.hainiva.com",
+  tenantId: "YOUR_ORGANISATION_ID",
+  // Ask YOUR backend for a fresh assertion — every time (see below).
+  getAssertion: () => fetch("/my-backend/hainiva-assertion", { method: "POST", credentials: "include" })
+    .then((r) => r.json()).then((j) => j.assertion),
+  media: joinCallRoom,
+});
+
+agent.on("call.ringing", (r) => showRing(r.callId, r.contactName ?? r.callerNumber));
+agent.on("calls", (state) => render(state));          // the call state machine
+agent.on("wrapup.required", (w) => askForWrapUp(w.callId));
+agent.on("revoked", () => showSignIn());               // HAINIVA ended the session
+
+const me = await agent.connect();                      // sign in, me, socket, rings waiting
+await agent.setStatus("online");
+
+await agent.calls.accept(callId);                      // answers and joins the room
+await agent.calls.hold(callId, true);
+await agent.calls.transfer(callId, { kind: "queue", queueId, name: "Support" });
+await agent.calls.end(callId);
+await agent.wrapUp(callId, { dispositionCode: "resolved", notes: "…" });
+
+await agent.disconnect({ signOut: true });
+```
+
+Everything else is on the same object: `conversations.list/get/assign/release/
+transfer/close`, `messages.list/send/typing`, `dispositions()`,
+`supervisor.liveCalls/agents/supervise/setMode`, `push.register/unregister`,
+`rings.pending()`, `joinMedia(callId)` (re-join with a fresh LiveKit token).
+`agent.rest` is the typed REST client for every `/agent/v1` endpoint, and the
+response types (`AgentMeDto`, `AgentConversationDto`, …) are exported.
+
+## Sign-in: your backend vouches for your staff member
+
+Your backend holds the agent app's **private key** (HAINIVA stores only the
+public key, or reads your `jwksUrl`). After it has authenticated the staff
+member with **your own** login, it signs a short assertion:
+
+| | |
+| --- | --- |
+| header | `alg: "ES256"` (or `RS256`), `kid`: the key id you registered |
+| `iss` | your agent app id |
+| `sub` | the member's `externalId` (`PUT /v1/members/by-external-id/:externalId`) |
+| `aud` | `hainiva-agent` |
+| `jti` | unique: each assertion works once |
+| `iat` / `exp` | now / at most 5 minutes ahead |
+
+Roles never come from the assertion — HAINIVA uses the role set on the member.
+The SDK calls `getAssertion` every time it needs a new session and never caches
+or stores the assertion. See [`examples/node-signer`](./examples/node-signer)
+for key generation and a complete signer.
+
+**Sessions.** An access token lasts 15 minutes and is refreshed before it
+expires (one refresh however many requests are waiting; the refresh token
+rotates). A request answered `401 token_expired` refreshes and is retried once.
+A refused refresh (expired, revoked, reused) signs in again with a new
+assertion. `401 session_revoked` — signed out elsewhere, member suspended, app
+paused — is final: the SDK forgets the session and emits `revoked`.
+
+## Events
+
+`agent.on(name, fn)` — from the event socket (only this member's events,
+filtered by HAINIVA):
+
+| Event | Data |
+| --- | --- |
+| `call.ringing` | `{callId, conversationId, path: direct\|queue\|transfer, channel, line, contactName, callerNumber, transferMode?, expiresAt}` |
+| `call.ended` | `{callId \| null, conversationId, reason: ended\|failed\|answered_elsewhere\|declined\|expired\|transfer_ended}` |
+| `conversation.assigned` | `{conversationId, callId, channel, contactName}` |
+| `message.created` | `{conversationId, interactionId, channel, preview, contentType, senderName}` |
+| `wrapup.required` | `{callId, conversationId, deadlineAt}` |
+| `presence.changed` | `{callId, participantId, role, presence}` |
+| `supervisor.alert` | the alert (supervisors) |
+| `event.unknown` | an event name newer than this SDK |
+
+And from the SDK itself: `connection` (socket state), `ready`, `calls` (the
+call state), `callEffect` (stop a native ring, leave media — media is handled
+for you), `resync` (events were missed beyond what HAINIVA keeps: rings are
+refetched, refetch your own lists), `session.expiring`, `revoked`, `error`.
+
+The socket authenticates in its **first frame** (the token is never in the
+URL), resumes from the last event after a reconnect, sends a refreshed token
+without reconnecting, and reconnects with backoff — except when HAINIVA revoked
+the session or the member has too many sockets open.
+
+## Calls
+
+`agent.callsState` / the `calls` event is the HAINIVA Agent app's call state
+machine: one call at a time, concurrent rings, ring expiry, decline, taken
+elsewhere, caller hanging up while you answer, hold, mute, warm and blind
+transfer. `CallStore` and the pure `transition(state, event)` are exported for
+Redux, Zustand or tests.
+
+## Push: rings with YOUR app's own credentials
+
+Phones ring through **your** app with **your** Firebase / APNs credentials.
+
+1. **Upload them** on the agent app — Organization → Developer → Agent apps →
+   the bell, or `PUT /v1/agent-apps/:id/push-credentials` (key scope
+   `agent_apps:write`):
+   ```jsonc
+   {
+     "fcm":  { "serviceAccount": { /* the service-account key file */ }, "expiresAt": "2027-11-01T00:00:00Z" },
+     "apns": { "keyP8": "<contents of AuthKey_XXXXXXXXXX.p8>", "keyId": "XXXXXXXXXX", "teamId": "YYYYYYYYYY",
+               "topic": "com.example.agentapp", "environment": "production" }
+   }
+   ```
+   HAINIVA checks each with Google / Apple before saving (a refusal names the
+   problem: `fcm_auth_failed`, `apns_auth_failed`, `apns_topic_not_allowed`, …),
+   stores it encrypted and never returns it — only a fingerprint, the status
+   and the expiry you declare (your admins are alerted 14 days before, and at
+   once if Google or Apple start refusing it). The APNs `topic` must be one of
+   the agent app's `allowedBundleIds`. `null` removes a platform.
+2. **Register each phone** after sign-in:
+   ```ts
+   await agent.push.register({ platform: "android", token: fcmToken, kind: "voip", bundleId: "com.example.agentapp", deviceId });
+   await agent.push.register({ platform: "ios", token: pushKitToken, kind: "voip", bundleId: "com.example.agentapp", deviceId });
+   ```
+   A phone stops ringing when its sign-in ends; call `push.unregister(token)`
+   before signing out anyway.
+3. **Show the ring** with `@hainiva/react-native-call` — Android: the FCM data
+   message `{type: "call", tenantId, interactionId, conversationId, path,
+   caller, line, expiresAt}` (and `call_cancel`); iPhone: a VoIP push to
+   `<topic>.voip` with the same fields, reported to CallKit natively. See
+   [`examples/expo-agent-app`](./examples/expo-agent-app).
+
+## Web
+
+Add your page's exact origin to the agent app's `allowedOrigins`. HAINIVA
+answers the browser's CORS preflight only for origins an agent app lists, and
+checks every request against the origins of the app its session belongs to.
+
+The session is kept **in memory** by default: a reload signs in again with a
+fresh assertion. `localStorageStore()` keeps it across reloads, but **any
+script on your origin can read localStorage, refresh token included** — use it
+only with a strict Content-Security-Policy and no third-party scripts.
+
+## React Native
+
+```ts
+import * as SecureStore from "expo-secure-store";
+import { joinCallRoom, secureStoreSessionStore } from "@hainiva/agent-sdk/react-native";
+const agent = new HainivaAgent({ …, store: secureStoreSessionStore(SecureStore), media: joinCallRoom });
+```
+
+The session lives in the iOS Keychain (readable after first unlock, so a ring
+that wakes a locked phone finds it; never migrated to another device) or the
+Android Keystore. There is no fallback to a plain store. Call
+`registerGlobals()` from `@livekit/react-native` once at startup.
+
+## Security
+
+- **No tokens in URLs or logs.** Tokens travel in the `Authorization` header or
+  the socket's first frame; configured URLs are checked (TLS only, no
+  `user:pass@`, no credential-like query parameter). Errors and the `log`
+  callback are redacted (JWTs, Bearer values, token parameters, HAINIVA key
+  prefixes and the exact tokens the SDK holds). The SDK never writes to the
+  console.
+- **Never put the private key in an app.** Only your backend signs assertions.
+  Rotate keys with `POST /v1/agent-apps/:id/rotate-credential` (the old key
+  keeps working 24 h; `immediate: true` when it leaked) and push credentials by
+  uploading new ones.
+- Every POST carries an `Idempotency-Key`, so a retry never acts twice.
+- See [SECURITY.md](./SECURITY.md).
+
+## License
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not open a public issue**. Email **security@epacific.com.vn** with a
+description, the affected version and steps to reproduce. We acknowledge
+reports within 2 business days and keep you informed until a fix ships.
+
+## Supported versions
+
+The latest minor release receives security fixes.
+
+## Using the SDK safely
+
+- **Never put the agent app's private key (or a test secret) in the app.**
+  Only your backend signs staff assertions, after it has authenticated the
+  staff member itself. Keep assertions short-lived (≤ 5 minutes) with a new
+  `jti` each time; live apps use ES256/RS256.
+- `getAssertion` must fetch a new assertion every time — do not cache one.
+- Web: keep the default in-memory session store unless you need reloads to stay
+  signed in; `localStorageStore` exposes the refresh token to any script on
+  your origin.
+- React Native: use `secureStoreSessionStore`; never AsyncStorage for tokens.
+- Push credentials (Firebase service account, APNs .p8) are uploaded to
+  HAINIVA once, by your admin or your backend — never shipped in the app, never
+  committed. HAINIVA stores them encrypted and shows only fingerprints; upload
+  new ones to rotate, and remove them (`null`) if they leak.
+- Unregister a phone's push token before signing out on it.
+- Do not log raw socket frames or API bodies in production: they carry
+  customer data. The SDK's own `log` callback is already redacted.
+- Every release on npm is published from GitHub Actions with
+  [provenance](https://docs.npmjs.com/generating-provenance-statements); check it
+  with `npm audit signatures`.

package/dist/cjs/agent.cjs

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HainivaAgent = void 0;
+/**
+ * HainivaAgent — one object for a staff member's app: sign-in with your
+ * backend's assertion, the REST API, the live event socket and the agent's
+ * calls, wired together.
+ *
+ *   const agent = new HainivaAgent({ baseUrl, tenantId, getAssertion, media: joinCallRoom });
+ *   agent.on("call.ringing", (r) => showRing(r));
+ *   await agent.connect();
+ *   await agent.calls.accept(callId);   // answers, then joins the room with `media`
+ *
+ * Transport-agnostic: LiveKit, the DOM and React Native come in through options
+ * (`media`, `WebSocket`, `store`), so the core runs in Node too.
+ */
+const calls_js_1 = require("./calls.cjs");
+const emitter_js_1 = require("./emitter.cjs");
+const errors_js_1 = require("./errors.cjs");
+const events_js_1 = require("./events.cjs");
+const log_js_1 = require("./log.cjs");
+const redact_js_1 = require("./redact.cjs");
+const rest_js_1 = require("./rest.cjs");
+const session_js_1 = require("./session.cjs");
+const ws_js_1 = require("./ws.cjs");
+/**
+ * The staff member's app: session, REST, socket and calls.
+ */
+class HainivaAgent {
+    constructor(o) {
+        this.o = o;
+        this.socket = null;
+        this.meDto = null;
+        this.media = new Map();
+        this.offs = [];
+        this.rings = {
+            /** Rings waiting for you now (also fed into the call state). */
+            pending: () => this.syncRings(),
+        };
+        this.calls = {
+            /**
+             * Answer: the server's answer race decides (409 = someone else was
+             * faster). With `media`, joins the room and returns the session.
+             */
+            accept: async (callId, ring) => {
+                const known = this.callStore.state.calls[callId];
+                if (!known || known.phase === "ended") {
+                    // Answered from a push (CallKit / the Android call notification) before
+                    // the socket told us about the ring: the state machine learns it now.
+                    this.callStore.dispatch({ type: "ring", call: {
+                            id: callId, direction: "inbound", path: "queue", from: ring?.from ?? "",
+                            ...(ring?.conversationId ? { conversationId: ring.conversationId } : {}), expiresAt: Date.now() + this.ringMs,
+                        } });
+                }
+                this.callStore.dispatch({ type: "accept", id: callId });
+                let accepted;
+                try {
+                    accepted = await this.guard(this.rest.acceptCall(callId));
+                }
+                catch (e) {
+                    const err = errors_js_1.HainivaAgentError.from(e, "accept_failed", this.redactor);
+                    const reason = err.status === 409 ? "answered_elsewhere" : err.status === 404 || err.code === "call_ended" ? "gone" : "failed";
+                    this.callStore.dispatch({ type: "accept_failed", id: callId, reason, error: err.code });
+                    throw err;
+                }
+                if (!accepted.media || !this.o.media) {
+                    this.callStore.dispatch({ type: "connected", id: callId, answered: true });
+                    return { accepted, media: null };
+                }
+                const media = await this.joinMedia(callId, accepted.media);
+                return { accepted, media };
+            },
+            decline: async (callId) => {
+                this.callStore.dispatch({ type: "decline", id: callId });
+                return this.guard(this.rest.declineCall(callId));
+            },
+            /** Hang up here: media is left at once, then the server ends the call. */
+            end: async (callId) => {
+                this.callStore.dispatch({ type: "hang_up", id: callId });
+                return this.guard(this.rest.endCall(callId));
+            },
+            hold: async (callId, on) => {
+                const r = await this.guard(this.rest.holdCall(callId, on));
+                this.callStore.dispatch(on ? { type: "hold", id: callId } : { type: "resume", id: callId });
+                return r;
+            },
+            mute: async (callId, muted) => {
+                await this.media.get(callId)?.setMuted(muted);
+                this.callStore.dispatch({ type: "mute", id: callId, muted });
+            },
+            /** Warm or blind to a colleague, to a queue (always blind), or to a phone number. */
+            transfer: async (callId, target, mode = "warm") => {
+                this.callStore.dispatch({ type: "transfer_start", id: callId, mode, target });
+                try {
+                    return await this.guard(this.rest.transferCall(callId, target.kind === "agent" ? { agentId: target.agentId, mode } : target.kind === "queue" ? { queueId: target.queueId } : { number: target.number, mode }));
+                }
+                catch (e) {
+                    this.callStore.dispatch({ type: "transfer_cancelled", id: callId, notice: "transfer_failed" });
+                    throw e;
+                }
+            },
+            get: (callId) => this.guard(this.rest.getCall(callId)),
+        };
+        this.conversations = {
+            list: (q) => this.guard(this.rest.listConversations(q)),
+            get: (id) => this.guard(this.rest.getConversation(id)),
+            /** Take it yourself (no agentId) or, a supervisor, give it to a colleague. */
+            assign: (id, agentId) => this.guard(this.rest.assignConversation(id, agentId)),
+            release: (id, note) => this.guard(this.rest.releaseConversation(id, note)),
+            transfer: (id, to) => this.guard(this.rest.transferConversation(id, to)),
+            close: (id) => this.guard(this.rest.closeConversation(id)),
+        };
+        this.messages = {
+            list: (conversationId, q) => this.guard(this.rest.listMessages(conversationId, q)),
+            send: (conversationId, text) => this.guard(this.rest.sendMessage(conversationId, text)),
+            typing: (conversationId) => this.guard(this.rest.typing(conversationId)),
+        };
+        this.supervisor = {
+            liveCalls: () => this.guard(this.rest.liveCalls()),
+            agents: () => this.guard(this.rest.teamAgents()),
+            /** Listen in (monitor), coach the agent (whisper) or join the call (barge). Join `media` with your adapter. */
+            supervise: (callId, mode = "monitor") => this.guard(this.rest.supervise(callId, mode)),
+            setMode: (callId, mode, supervisorTrackSid) => this.guard(this.rest.setSuperviseMode(callId, mode, supervisorTrackSid)),
+        };
+        this.push = {
+            /** Register this device's FCM token (Android) or PushKit/APNs token (iPhone) for YOUR app's credentials. */
+            register: (sub) => this.guard(this.rest.registerPush(sub)),
+            unregister: (token) => this.guard(this.rest.unregisterPush(token)),
+        };
+        this.redactor = new redact_js_1.Redactor();
+        this.log = (0, log_js_1.safeLogger)(o.log, this.redactor);
+        this.events = new emitter_js_1.TypedEmitter((e) => this.log("listener_error", e));
+        this.ringMs = o.ringTimeoutMs ?? 60000;
+        this.rest = new rest_js_1.AgentRestClient({
+            baseUrl: o.baseUrl, tenantId: o.tenantId, redactor: this.redactor,
+            ...(o.fetch ? { fetch: o.fetch } : {}), ...(o.timeoutMs ? { timeoutMs: o.timeoutMs } : {}),
+            ...(o.device ? { device: o.device } : {}), ...(o.log ? { log: o.log } : {}),
+            ...(o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}),
+        });
+        this.session = new session_js_1.SessionManager({
+            getAssertion: o.getAssertion, transport: this.rest.sessions, redactor: this.redactor,
+            ...(o.store ? { store: o.store } : {}), ...(o.log ? { log: o.log } : {}),
+        });
+        this.rest.useTokens(this.session);
+        this.callStore = new calls_js_1.CallStore();
+        this.callStore.events.on("change", (s) => this.events.emit("calls", s));
+        this.callStore.events.on("effect", (e) => this.onEffect(e));
+    }
+    /** The signed-in member (after connect()). */
+    get me() { return this.meDto; }
+    /** The calls now (the state machine): ringing, connecting, active, held, ended. */
+    get callsState() { return this.callStore.state; }
+    get connection() { return this.socket?.state ?? "idle"; }
+    on(event, fn) {
+        return this.events.on(event, fn);
+    }
+    /** Sign in (or restore the stored session), load who you are and the rings waiting, open the event socket. */
+    async connect() {
+        await this.session.signIn();
+        this.meDto = await this.guard(this.rest.me());
+        if (!this.socket)
+            this.openSocket();
+        this.socket.connect();
+        await this.syncRings().catch((e) => this.log("pending_rings_failed", e));
+        return this.meDto;
+    }
+    /**
+     * Close the socket and leave every call's media. `signOut: true` also ends
+     * the session on the server (and removes it from the store) — do that when
+     * the staff member signs out; unregister this device's push first.
+     */
+    async disconnect(opts = {}) {
+        this.socket?.disconnect();
+        this.socket = null;
+        for (const off of this.offs.splice(0))
+            off();
+        await Promise.all([...this.media.values()].map((m) => m.leave().catch(() => undefined)));
+        this.media.clear();
+        if (opts.signOut)
+            await this.session.signOut();
+    }
+    setStatus(status, o) { return this.guard(this.rest.setStatus(status, o)); }
+    /** Join (or re-join) a call's media room. Without credentials, a fresh LiveKit token is minted. */
+    async joinMedia(callId, creds) {
+        if (!this.o.media)
+            throw new errors_js_1.HainivaAgentError(0, "no_media_adapter", { hint: "pass options.media = joinCallRoom from @hainiva/agent-sdk/web or /react-native" });
+        const c = creds ?? await this.guard(this.rest.mediaToken(callId));
+        this.redactor.add(c.token);
+        const previous = this.media.get(callId);
+        if (previous)
+            await previous.leave().catch(() => undefined);
+        let m;
+        try {
+            m = await this.o.media({ url: c.livekitUrl, token: c.token });
+        }
+        catch (e) {
+            this.callStore.dispatch({ type: "accept_failed", id: callId, reason: "failed", error: "media_connect_failed" });
+            throw errors_js_1.HainivaAgentError.from(e, "media_connect_failed", this.redactor);
+        }
+        this.media.set(callId, m);
+        m.onDisconnected(() => {
+            if (this.media.get(callId) !== m)
+                return;
+            this.media.delete(callId);
+            this.callStore.dispatch({ type: "remote_end", id: callId });
+        });
+        // Media that comes up after the caller hung up is left at once (the machine's media.leave effect).
+        this.callStore.dispatch({ type: "connected", id: callId, answered: true });
+        return m;
+    }
+    /** After a call: a disposition code from dispositions() and notes. */
+    wrapUp(callId, w = {}) { return this.guard(this.rest.wrapUp(callId, w)); }
+    dispositions(channel) { return this.guard(this.rest.dispositions(channel)); }
+    // ── Internals ───────────────────────────────────────────────────────────────
+    /** A REST call; a final 401 session_revoked tells the app and forgets the session. */
+    async guard(p) {
+        try {
+            return await p;
+        }
+        catch (e) {
+            if (e instanceof errors_js_1.HainivaAgentError && e.status === 401 && e.code === "session_revoked")
+                await this.onRevoked("session_revoked");
+            throw e;
+        }
+    }
+    async onRevoked(reason) {
+        this.socket?.disconnect();
+        this.socket = null;
+        await this.session.clear();
+        this.events.emit("revoked", { reason });
+    }
+    openSocket() {
+        let sock;
+        sock = new ws_js_1.ReconnectingSocket({
+            url: this.rest.wsUrl,
+            getToken: () => this.session.accessToken(),
+            onTokenRejected: () => this.session.invalidate(),
+            redactor: this.redactor,
+            ...(this.o.WebSocket ? { WebSocket: this.o.WebSocket } : {}),
+            ...(this.o.log ? { log: this.o.log } : {}),
+            ...(this.o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}),
+            ...(0, events_js_1.agentSocketBindings)(() => sock.lastSeq),
+        });
+        this.socket = sock;
+        this.offs.push(sock.events.on("state", (s) => this.events.emit("connection", s)), sock.events.on("error", (e) => this.events.emit("error", e)), sock.events.on("revoked", () => { void this.onRevoked("socket_revoked"); }), sock.events.on("ready", (f) => {
+            const seq = f.type === "ready" && typeof f.seq === "number" ? f.seq : 0;
+            // A first connect starts at the server's newest event: old rings are not replayed.
+            if (sock.lastSeq === 0 && seq > 0)
+                sock.setLastSeq(seq);
+            this.events.emit("ready", { seq });
+        }), sock.events.on("frame", (f) => this.onFrame(sock, f)), this.session.events.on("token", (t) => { sock.updateToken(t); }));
+    }
+    onFrame(sock, f) {
+        switch (f.type) {
+            case "event": {
+                if (!(0, events_js_1.isEventFrame)(f))
+                    return;
+                for (const ev of (0, events_js_1.toCallEvents)(f, this.callStore.state, Date.now(), this.ringMs))
+                    this.callStore.dispatch(ev);
+                if ((0, events_js_1.isKnownEvent)(f.event))
+                    this.events.emit(f.event, f.data);
+                else
+                    this.events.emit("event.unknown", f);
+                return;
+            }
+            case "resync_required": {
+                const from = typeof f.fromSeq === "number" && f.fromSeq >= 0 ? f.fromSeq : 0;
+                sock.setLastSeq(from);
+                void this.syncRings().catch((e) => this.log("pending_rings_failed", e));
+                this.events.emit("resync", { fromSeq: from });
+                return;
+            }
+            case "session.expiring":
+                this.events.emit("session.expiring", { expiresAt: String(f.expiresAt ?? "") });
+                // The server's clock decides: refresh now even if ours thinks there is time.
+                // Refreshing emits "token", which hands the new token to this socket (token.refresh).
+                this.session.invalidate(this.session.current?.accessToken);
+                void this.session.accessToken().catch((e) => this.log("refresh_failed", e));
+                return;
+            case "ack":
+                if (!f.ok)
+                    this.log("socket_ack_refused", { error: f.error });
+                return;
+            default:
+                return;
+        }
+    }
+    /** Rings waiting on the server → the call state (a cold start, a missed push, a resync). */
+    async syncRings() {
+        const rings = await this.guard(this.rest.pendingRings());
+        const now = Date.now();
+        for (const r of rings) {
+            if (!r || typeof r.callId !== "string")
+                continue;
+            this.callStore.dispatch({
+                type: "ring",
+                call: {
+                    id: r.callId, conversationId: r.conversationId, direction: "inbound",
+                    path: r.path === "direct" ? "direct" : "queue",
+                    from: r.contactName ?? r.callerNumber ?? "", expiresAt: now + this.ringMs,
+                },
+            });
+        }
+        return rings;
+    }
+    onEffect(e) {
+        if (e.type === "media.leave") {
+            const m = this.media.get(e.id);
+            this.media.delete(e.id);
+            if (m)
+                void m.leave().catch(() => undefined);
+        }
+        this.events.emit("callEffect", e);
+    }
+}
+exports.HainivaAgent = HainivaAgent;