@hainiva/agent-sdk 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# 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.3.0] - 2026-11-14
+
+- `@hainiva/agent-sdk/embed`: `mountDesk(container, { agent, appId, baseUrl,
+  theme?, locale?, onEnded?, onDial?, onDialer?, onOpenUrl?, onMediaError? })`
+  shows the HAINIVA desk in a sandboxed iframe signed in with your agent
+  session and returns `{ destroy(), setTheme(), setLocale(), iframe }`. The
+  handshake checks `event.source` and the desk origin, posts to the desk origin
+  only, supplies and refreshes the desk token (single flight), and ends on a
+  refused session or when the desk does not load (`load_failed`). Exports the
+  protocol (`DeskToHost`, `HostToDesk`, `parseDeskMessage`), `DESK_SANDBOX`,
+  `DESK_ALLOW` and `deskUrl()`.
+- `@hainiva/agent-sdk/react-native`: `<HainivaDesk agent appId baseUrl onDial …/>`
+  in a `react-native-webview` WebView (optional peer, or pass `WebView`):
+  bridge injected before the desk's scripts on the desk origin only,
+  `originWhitelist` limited to the desk, no `window.open` passthrough; calls
+  are handed to your app (`onDial`, `onDialer`).
+- `agent.desk.session()` / `AgentRestClient.deskSession()`:
+  `POST /agent/v1/desk-session` → `AgentDeskSessionDto {token, expiresAt}`.
+- Optional peers `react` and `react-native-webview` (only for `<HainivaDesk/>`).
+
+## [0.2.0] - 2026-11-14
+
+- `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]
+
+Not published to npm; its contents shipped in 0.2.0.
+
+- `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.3.0...HEAD
+[0.3.0]: https://github.com/hainiva/agent-sdk/compare/v0.2.0...v0.3.0
+[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,279 @@
-# 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`, `<HainivaDesk/>` | `livekit-client`, `@livekit/react-native`, `expo-secure-store`; `react-native-webview` for `<HainivaDesk/>` |
+| `@hainiva/agent-sdk/embed` | `mountDesk()`: the full HAINIVA desk inside your web page | a browser |
+
+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. `HS256` works only for a test app on a sandbox organisation. |
+| `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, sessions revoked,
+member suspended, role changed, app paused) ends this session: the SDK forgets
+it and emits `revoked`.
+
+**Revoking sessions does not cut a member off.** The next `connect()`, or the
+embedded desk asking for a token, signs in again with a fresh assertion, and
+your backend still vouches for the member, so it succeeds. To stop someone
+working, suspend or delete the member (`PATCH /v1/members/:id
+{"status":"suspended"}`, `DELETE /v1/members/:id`) or pause the agent app; then
+sign-in is refused (`401 session_refused`, `403 agent_app_paused`). Stop
+signing assertions for them on your side too.
+
+## 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, transferMode?}` (all strings; `expiresAt` in Unix
+   milliseconds) and `{type: "call_cancel", tenantId, interactionId, reason}`;
+   iPhone: a VoIP push to `<topic>.voip` with the same fields, reported to
+   CallKit natively (ring ends come over the socket, not as a push). 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
+(`403 origin_not_allowed`). A page on an origin that no app lists is refused at
+the preflight, before any sign-in: `connect()` fails with a
+`HainivaAgentError` of status `0` (`network_error`), which in the browser's
+network panel is a CORS error.
+
+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.
+
+## The embedded desk
+
+Show the whole HAINIVA desk inside your product, signed in as your staff
+member with **your** agent session — no HAINIVA login screen, no password.
+
+```ts
+import { mountDesk } from "@hainiva/agent-sdk/embed";
+
+await agent.connect();
+const desk = mountDesk(document.getElementById("desk")!, {
+  agent,                                   // your connected HainivaAgent
+  appId: "YOUR_AGENT_APP_ID",
+  baseUrl: "https://app.hainiva.com",      // the HAINIVA desk
+  theme: "light", locale: "vi",
+  onEnded: (reason) => showSignedOut(reason),
+});
+desk.setTheme("dark");
+desk.destroy();
+```
+
+- **Your page's origin must be in the agent app's `allowedOrigins`.** That list
+  is also the desk's CSP `frame-ancestors`: any other site gets a blank frame
+  (and `onEnded("load_failed")`). Adding an origin lets that site embed the desk
+  for this app's staff — list only sites you control.
+- The SDK exchanges your agent session for a 15-minute **desk token**
+  (`POST /agent/v1/desk-session`, `agent.desk.session()`) and hands it to the
+  desk over `postMessage` — never in the URL, never stored. The desk asks for a
+  new one before it expires. When your session ends for good (sign-out,
+  member suspended or deleted, app paused) the desk shows "ended" at once and
+  `onEnded` fires. Revoking sessions alone does not end the desk: the SDK signs
+  in again with a fresh assertion (see Sessions above).
+- The desk token works only for the desk's own work (conversations, calls,
+  contacts, tickets…). Settings, team, billing, developer and admin pages are
+  refused, and it can never switch organisation.
+- The iframe is created with
+  `sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals"`
+  (never top navigation: the desk cannot navigate your page) and
+  `allow="microphone; camera; autoplay; clipboard-write"`. On the web **the desk
+  carries calls itself (WebRTC)**; if your own iframe or Permissions-Policy does
+  not delegate the microphone, or the person refuses it, `onMediaError(name)`
+  tells you.
+- Messages are read only from that iframe's window **and** the desk origin, and
+  only in the documented shapes; everything is sent to the desk origin only.
+
+React Native — calls stay native in your app (`@hainiva/react-native-call`),
+the desk hands them to you:
+
+```tsx
+import { WebView } from "react-native-webview";
+import { HainivaDesk } from "@hainiva/agent-sdk/react-native";
+
+<HainivaDesk agent={agent} appId={APP_ID} baseUrl="https://app.hainiva.com" WebView={WebView}
+  onDial={(number, contactId) => placeCall(number, contactId)}
+  onDialer={(prefill) => openDialer(prefill)}
+  onOpenUrl={(url) => Linking.openURL(url)}
+  onEnded={(reason) => signOut(reason)} />
+```
+
+The WebView stays on the desk origin (`originWhitelist`, every other URL goes
+to `onOpenUrl`), opens no windows, and gets its bridge before the desk's
+scripts, on the desk origin only.
+
+## 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`.