@hainiva/agent-sdk 0.0.0-stage → 0.2.0

package/dist/cjs/agent.d.cts

@@ -0,0 +1,235 @@
+/**
+ * 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.
+ */
+import { CallStore, type CallEffect, type CallsState, type TransferTarget } from "./calls.cjs";
+import type { AgentAcceptDto, AgentCallEndedData, AgentCallRingingData, AgentConversationDto, AgentDispositionDto, AgentMeDto, AgentMessageDto, AgentPage, AgentPushSubscriptionDto, AgentPushSubscriptionInput, AgentRingDto, AgentSessionDto, SupervisorAgentDto, SupervisorLiveCallDto, SupervisorSuperviseDto } from "./contract.cjs";
+import { TypedEmitter } from "./emitter.cjs";
+import { HainivaAgentError } from "./errors.cjs";
+import { type AgentEventFrame } from "./events.cjs";
+import { type Logger } from "./log.cjs";
+import { AgentRestClient, type AgentStatus, type ConversationListQuery, type MediaCredentials, type RequestOptions } from "./rest.cjs";
+import { SessionManager, type AgentSession, type GetAssertion, type SessionStore } from "./session.cjs";
+import { type ConnectionState, type WebSocketCtor } from "./ws.cjs";
+/** A joined media room — what `joinCallRoom` from `/web` or `/react-native` returns. */
+export interface MediaSession {
+    leave(): Promise<void>;
+    setMuted(muted: boolean): Promise<void>;
+    onDisconnected(fn: () => void): () => void;
+}
+/** Join a room: pass `joinCallRoom` from `@hainiva/agent-sdk/web` or `/react-native`. */
+export type JoinMedia = (join: {
+    url: string;
+    token: string;
+}) => Promise<MediaSession>;
+export interface HainivaAgentOptions {
+    /** https://api.hainiva.com (or your organisation's API host). */
+    baseUrl: string;
+    tenantId: string;
+    /** Ask YOUR backend for a fresh assertion — every time; never cache one. */
+    getAssertion: GetAssertion;
+    /** Where the session is kept. Default in memory (a restart signs in again). */
+    store?: SessionStore;
+    /** Joins call media. Without it, `calls.accept` answers and returns the credentials only. */
+    media?: JoinMedia;
+    /** WebSocket implementation (browsers and React Native have one; Node 22 too). */
+    WebSocket?: WebSocketCtor;
+    fetch?: typeof fetch;
+    device?: {
+        label?: string;
+        platform?: "ios" | "android" | "web" | "other";
+    };
+    /** Per REST request. Default 15 s. */
+    timeoutMs?: number;
+    /** How long a ring with no server-known end may ring here. Default 60 s. */
+    ringTimeoutMs?: number;
+    /** A redacted log of what the SDK does. Nothing is logged without it. */
+    log?: Logger;
+    /** Local development only (http://localhost, ws://localhost). */
+    allowInsecureLocalhost?: boolean;
+}
+export interface HainivaAgentEvents {
+    /** Socket state. */
+    connection: ConnectionState;
+    /** The socket is authenticated (after every reconnect). */
+    ready: {
+        seq: number;
+    };
+    "call.ringing": AgentCallRingingData;
+    "call.ended": AgentCallEndedData;
+    "conversation.assigned": Record<string, unknown>;
+    "message.created": Record<string, unknown>;
+    "wrapup.required": {
+        callId: string;
+        conversationId: string;
+        deadlineAt: string | null;
+    };
+    "presence.changed": Record<string, unknown>;
+    "supervisor.alert": Record<string, unknown>;
+    /** An event name this SDK version does not know yet (the server added one). */
+    "event.unknown": AgentEventFrame;
+    /** The calls changed (state machine). */
+    calls: CallsState;
+    /** Something the host must do for a call (stop the native ring, leave media). Handled for media already. */
+    callEffect: CallEffect;
+    /** Events were missed beyond what the server keeps: state was refetched (rings); refetch your own lists. */
+    resync: {
+        fromSeq: number;
+    };
+    /** The session expires within a minute: the SDK is refreshing it. */
+    "session.expiring": {
+        expiresAt: string;
+    };
+    /** The session was ended by HAINIVA (sign-out elsewhere, suspended, app paused, key rotated). Call connect() to sign in again. */
+    revoked: {
+        reason: string;
+    };
+    error: HainivaAgentError;
+}
+/**
+ * The staff member's app: session, REST, socket and calls.
+ */
+export declare class HainivaAgent {
+    private readonly o;
+    readonly events: TypedEmitter<HainivaAgentEvents>;
+    readonly session: SessionManager<AgentSession & AgentSessionDto>;
+    readonly rest: AgentRestClient;
+    readonly callStore: CallStore;
+    private socket;
+    private meDto;
+    private readonly media;
+    private readonly offs;
+    private readonly redactor;
+    private readonly log;
+    private readonly ringMs;
+    constructor(o: HainivaAgentOptions);
+    /** The signed-in member (after connect()). */
+    get me(): AgentMeDto | null;
+    /** The calls now (the state machine): ringing, connecting, active, held, ended. */
+    get callsState(): CallsState;
+    get connection(): ConnectionState;
+    on<K extends keyof HainivaAgentEvents>(event: K, fn: (payload: HainivaAgentEvents[K]) => void): () => void;
+    /** Sign in (or restore the stored session), load who you are and the rings waiting, open the event socket. */
+    connect(): Promise<AgentMeDto>;
+    /**
+     * 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.
+     */
+    disconnect(opts?: {
+        signOut?: boolean;
+    }): Promise<void>;
+    setStatus(status: AgentStatus, o?: RequestOptions): Promise<{
+        status: AgentStatus;
+    }>;
+    readonly rings: {
+        /** Rings waiting for you now (also fed into the call state). */
+        pending: () => Promise<AgentRingDto[]>;
+    };
+    readonly calls: {
+        /**
+         * Answer: the server's answer race decides (409 = someone else was
+         * faster). With `media`, joins the room and returns the session.
+         */
+        accept: (callId: string, ring?: {
+            from?: string;
+            conversationId?: string;
+        }) => Promise<{
+            accepted: AgentAcceptDto;
+            media: MediaSession | null;
+        }>;
+        decline: (callId: string) => Promise<{
+            callId: string;
+            declined: true;
+        }>;
+        /** Hang up here: media is left at once, then the server ends the call. */
+        end: (callId: string) => Promise<{
+            callId: string;
+            ended: true;
+        }>;
+        hold: (callId: string, on: boolean) => Promise<{
+            callId: string;
+            onHold: boolean;
+        }>;
+        mute: (callId: string, muted: boolean) => Promise<void>;
+        /** Warm or blind to a colleague, to a queue (always blind), or to a phone number. */
+        transfer: (callId: string, target: TransferTarget, mode?: "warm" | "blind") => Promise<{
+            callId: string;
+            transferred: true;
+        }>;
+        get: (callId: string) => Promise<import("./contract.cjs").AgentCallDto>;
+    };
+    /** Join (or re-join) a call's media room. Without credentials, a fresh LiveKit token is minted. */
+    joinMedia(callId: string, creds?: MediaCredentials): Promise<MediaSession>;
+    readonly conversations: {
+        list: (q?: ConversationListQuery) => Promise<AgentPage<AgentConversationDto>>;
+        get: (id: string) => Promise<AgentConversationDto>;
+        /** Take it yourself (no agentId) or, a supervisor, give it to a colleague. */
+        assign: (id: string, agentId?: string) => Promise<unknown>;
+        release: (id: string, note?: string) => Promise<{
+            conversationId: string;
+            released: true;
+        }>;
+        transfer: (id: string, to: {
+            agentId: string;
+        } | {
+            queueId: string;
+            note?: string;
+        }) => Promise<unknown>;
+        close: (id: string) => Promise<{
+            conversationId: string;
+            closed: true;
+        }>;
+    };
+    readonly messages: {
+        list: (conversationId: string, q?: {
+            after?: string;
+            limit?: number;
+        }) => Promise<AgentPage<AgentMessageDto>>;
+        send: (conversationId: string, text: string) => Promise<Pick<AgentMessageDto, "id" | "conversationId" | "interactionId" | "createdAt">>;
+        typing: (conversationId: string) => Promise<{
+            ok: true;
+        }>;
+    };
+    /** After a call: a disposition code from dispositions() and notes. */
+    wrapUp(callId: string, w?: {
+        dispositionCode?: string;
+        notes?: string;
+    }): Promise<{
+        callId: string;
+        wrappedUp: true;
+    }>;
+    dispositions(channel?: string): Promise<AgentDispositionDto[]>;
+    readonly supervisor: {
+        liveCalls: () => Promise<SupervisorLiveCallDto[]>;
+        agents: () => Promise<SupervisorAgentDto[]>;
+        /** Listen in (monitor), coach the agent (whisper) or join the call (barge). Join `media` with your adapter. */
+        supervise: (callId: string, mode?: "monitor" | "whisper" | "barge") => Promise<SupervisorSuperviseDto>;
+        setMode: (callId: string, mode: "monitor" | "whisper" | "barge", supervisorTrackSid?: string) => Promise<{
+            callId: string;
+            mode: string;
+        }>;
+    };
+    readonly push: {
+        /** Register this device's FCM token (Android) or PushKit/APNs token (iPhone) for YOUR app's credentials. */
+        register: (sub: AgentPushSubscriptionInput) => Promise<AgentPushSubscriptionDto>;
+        unregister: (token: string) => Promise<void>;
+    };
+    /** A REST call; a final 401 session_revoked tells the app and forgets the session. */
+    private guard;
+    private onRevoked;
+    private openSocket;
+    private onFrame;
+    /** Rings waiting on the server → the call state (a cold start, a missed push, a resync). */
+    private syncRings;
+    private onEffect;
+}

package/dist/cjs/calls.cjs

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallStore = exports.initialCallsState = void 0;
+exports.transition = transition;
+exports.activeCall = activeCall;
+exports.ringingCalls = ringingCalls;
+const emitter_js_1 = require("./emitter.cjs");
+exports.initialCallsState = Object.freeze({ calls: Object.freeze({}), activeId: null });
+const LIVE = new Set(["connecting", "active", "held", "transferring"]);
+const IN_CALL = new Set(["active", "held", "transferring"]);
+function newCall(info, phase, at) {
+    return { info, phase, muted: false, since: null, ringingSince: phase === "ringing" ? at : null, transfer: null, notice: null, endReason: null, endedAt: null, error: null };
+}
+function activeOf(calls) {
+    for (const c of Object.values(calls))
+        if (LIVE.has(c.phase))
+            return c.info.id;
+    return null;
+}
+/** Apply one event. Pure: never mutates `state`. */
+function transition(state, ev) {
+    const calls = { ...state.calls };
+    const effects = [];
+    const same = { state, effects: [], changed: false };
+    const id = ev.type === "ring" || ev.type === "dial" ? ev.call.id : ev.id;
+    const c = calls[id];
+    const put = (next) => { calls[next.info.id] = next; };
+    const end = (call, reason, at, extra = {}) => {
+        if (call.phase === "ringing")
+            effects.push({ type: "ring.cancel", id: call.info.id });
+        else if (LIVE.has(call.phase))
+            effects.push({ type: "media.leave", id: call.info.id });
+        put({ ...call, ...extra, phase: "ended", endReason: reason, endedAt: at, transfer: null });
+        effects.push({ type: "ended", id: call.info.id, reason });
+    };
+    const done = () => {
+        const next = { calls, activeId: activeOf(calls) };
+        return { state: next, effects, changed: true };
+    };
+    switch (ev.type) {
+        case "ring": {
+            if (!ev.call.id)
+                return same;
+            if (c && c.phase !== "ended")
+                return same; // the same ring again (push + socket)
+            if (ev.call.expiresAt !== undefined && ev.call.expiresAt <= ev.at)
+                return same; // arrived too late
+            if (state.activeId) {
+                // On a call: this device turns it away (iPhone: CallKit already shows it).
+                return { state, effects: [{ type: "ring.cancel", id }], changed: false };
+            }
+            put(newCall({ ...ev.call, direction: "inbound" }, "ringing", ev.at));
+            effects.push({ type: "ring.show", call: ev.call });
+            return done();
+        }
+        case "dial": {
+            if (!ev.call.id || state.activeId)
+                return same;
+            if (Object.values(state.calls).some((x) => x.phase === "ringing"))
+                return same; // answer or decline first
+            if (c && c.phase !== "ended")
+                return same;
+            put(newCall({ ...ev.call, direction: "outbound", path: "out" }, "connecting", ev.at));
+            return done();
+        }
+        case "accept": {
+            if (!c || c.phase !== "ringing" || state.activeId)
+                return same;
+            if (c.info.expiresAt !== undefined && c.info.expiresAt <= ev.at) {
+                end(c, "missed", ev.at);
+                return done();
+            }
+            effects.push({ type: "ring.cancel", id });
+            put({ ...c, phase: "connecting" });
+            for (const other of Object.values(calls)) {
+                if (other.info.id !== id && other.phase === "ringing")
+                    end(other, "busy", ev.at);
+            }
+            return done();
+        }
+        case "decline": {
+            if (!c || c.phase !== "ringing")
+                return same;
+            end(c, "declined", ev.at);
+            return done();
+        }
+        case "expire": {
+            if (!c || c.phase !== "ringing")
+                return same;
+            if (c.info.expiresAt !== undefined && c.info.expiresAt > ev.at)
+                return same;
+            end(c, "missed", ev.at);
+            return done();
+        }
+        case "ring_cancelled": {
+            if (!c)
+                return same;
+            if (c.phase === "ringing") {
+                end(c, ev.reason, ev.at);
+                return done();
+            }
+            // Answering here: "taken elsewhere" is about the race the server decides
+            // (accept_failed tells); the caller hanging up ends it.
+            if (c.phase === "connecting" && ev.reason === "remote_ended") {
+                end(c, "remote_ended", ev.at);
+                return done();
+            }
+            return same;
+        }
+        case "accept_failed": {
+            if (!c || c.phase !== "connecting")
+                return same;
+            const reason = ev.reason === "answered_elsewhere" ? "answered_elsewhere" : ev.reason === "gone" ? "remote_ended" : "failed";
+            end(c, reason, ev.at, { error: ev.error ?? null });
+            return done();
+        }
+        case "connected": {
+            if (!c || c.phase === "ended") {
+                // Media came up after the call ended (caller hung up during the answer): leave it.
+                return { state, effects: [{ type: "media.leave", id }], changed: false };
+            }
+            if (c.phase !== "connecting")
+                return same;
+            put({ ...c, phase: "active", since: ev.answered ? ev.at : null, muted: false });
+            return done();
+        }
+        case "answered": {
+            if (!c || !IN_CALL.has(c.phase) || c.since !== null)
+                return same;
+            put({ ...c, since: ev.at });
+            return done();
+        }
+        case "mute": {
+            if (!c || !IN_CALL.has(c.phase) || c.muted === ev.muted)
+                return same;
+            put({ ...c, muted: ev.muted });
+            return done();
+        }
+        case "hold": {
+            if (!c || c.phase !== "active")
+                return same;
+            put({ ...c, phase: "held" });
+            return done();
+        }
+        case "resume": {
+            if (!c || c.phase !== "held")
+                return same;
+            put({ ...c, phase: "active" });
+            return done();
+        }
+        case "transfer_start": {
+            if (!c || (c.phase !== "active" && c.phase !== "held"))
+                return same;
+            const mode = ev.target.kind === "queue" ? "blind" : ev.mode;
+            put({ ...c, phase: "transferring", notice: null, transfer: { mode, target: ev.target, joined: false, startedAt: ev.at, resumeTo: c.phase } });
+            return done();
+        }
+        case "transfer_joined": {
+            if (!c || c.phase !== "transferring" || !c.transfer || c.transfer.mode !== "warm" || c.transfer.joined)
+                return same;
+            put({ ...c, transfer: { ...c.transfer, joined: true } });
+            return done();
+        }
+        case "transfer_cancelled": {
+            if (!c || c.phase !== "transferring" || !c.transfer)
+                return same;
+            put({ ...c, phase: c.transfer.resumeTo, transfer: null, notice: ev.notice ?? null });
+            return done();
+        }
+        case "transfer_completed": {
+            if (!c || c.phase !== "transferring")
+                return same;
+            end(c, "transferred", ev.at);
+            return done();
+        }
+        case "remote_end": {
+            if (!c || c.phase === "ended")
+                return same;
+            // A blind transfer ends here when the server hands the call over.
+            const reason = c.phase === "transferring" && c.transfer?.mode === "blind" ? "transferred" : "remote_ended";
+            end(c, reason, ev.at);
+            return done();
+        }
+        case "hang_up": {
+            if (!c || !LIVE.has(c.phase))
+                return same;
+            end(c, "hung_up", ev.at);
+            return done();
+        }
+        case "rekey": {
+            // An outgoing call learns its server id.
+            if (!c || c.phase === "ended" || !ev.newId || ev.newId === id || calls[ev.newId])
+                return same;
+            delete calls[id];
+            put({ ...c, info: { ...c.info, id: ev.newId, ...(ev.conversationId ? { conversationId: ev.conversationId } : {}) } });
+            return done();
+        }
+        case "dismiss": {
+            if (!c || c.phase !== "ended")
+                return same;
+            delete calls[id];
+            return done();
+        }
+    }
+}
+/** The call holding the line, if any. */
+function activeCall(state) {
+    return state.activeId ? state.calls[state.activeId] ?? null : null;
+}
+/** Calls ringing now, oldest first. */
+function ringingCalls(state) {
+    return Object.values(state.calls).filter((c) => c.phase === "ringing").sort((a, b) => (a.ringingSince ?? 0) - (b.ringingSince ?? 0));
+}
+/**
+ * The state machine with a clock: rings expire on their own, and listeners hear
+ * every change and effect. Still free of React Native, LiveKit and HTTP.
+ */
+class CallStore {
+    constructor(o = {}) {
+        this.o = o;
+        this.events = new emitter_js_1.TypedEmitter();
+        this.st = exports.initialCallsState;
+        this.timers = new Map();
+        this.now = o.now ?? Date.now;
+    }
+    get state() { return this.st; }
+    /** Apply an event. `at` is filled from the clock when omitted. */
+    dispatch(ev) {
+        const full = ("at" in ev && typeof ev.at === "number" ? ev : { ...ev, at: this.now() });
+        const t = transition(this.st, full);
+        if (t.changed) {
+            this.st = t.state;
+            this.syncTimers();
+            this.events.emit("change", this.st);
+        }
+        for (const e of t.effects)
+            this.events.emit("effect", e);
+        return t;
+    }
+    /** Stop every timer (e.g. on sign-out). */
+    dispose() {
+        for (const t of this.timers.values())
+            clearTimeout(t);
+        this.timers.clear();
+        this.events.removeAll();
+    }
+    syncTimers() {
+        for (const [key, t] of this.timers) {
+            const cut = key.indexOf(":");
+            const kind = key.slice(0, cut);
+            const id = key.slice(cut + 1);
+            const c = this.st.calls[id];
+            if (!c || (kind === "expire" && c.phase !== "ringing") || (kind === "forget" && c.phase !== "ended")) {
+                clearTimeout(t);
+                this.timers.delete(key);
+            }
+        }
+        for (const c of Object.values(this.st.calls)) {
+            const id = c.info.id;
+            if (c.phase === "ringing" && c.info.expiresAt !== undefined && !this.timers.has(`expire:${id}`)) {
+                const left = Math.max(0, c.info.expiresAt - this.now());
+                this.timers.set(`expire:${id}`, setTimeout(() => {
+                    this.timers.delete(`expire:${id}`);
+                    this.dispatch({ type: "expire", id, at: Math.max(this.now(), c.info.expiresAt ?? 0) });
+                }, left));
+            }
+            const forget = this.o.forgetEndedAfterMs ?? 0;
+            if (c.phase === "ended" && forget > 0 && !this.timers.has(`forget:${id}`)) {
+                this.timers.set(`forget:${id}`, setTimeout(() => {
+                    this.timers.delete(`forget:${id}`);
+                    this.dispatch({ type: "dismiss", id });
+                }, forget));
+            }
+        }
+    }
+}
+exports.CallStore = CallStore;