@hainiva/agent-sdk 0.0.0-stage → 0.2.0

package/dist/cjs/calls.d.cts

@@ -0,0 +1,232 @@
+import { TypedEmitter } from "./emitter.cjs";
+/**
+ * The agent's calls as a pure state machine — ported from the HAINIVA Agent app
+ * (apps/agent-mobile/src/calls.ts), without React Native, LiveKit or HTTP: the
+ * host feeds it events (a ring push, the user's answer, "media connected", the
+ * server's cancel…) and acts on the effects it returns (stop the native ring,
+ * leave the room). Same rules as the app:
+ *
+ *  - one call at a time: a ring while on a call is turned away ("busy"), and
+ *    answering one ring turns away the others;
+ *  - a ring ends at its expiresAt ("missed"), when declined, or when the server
+ *    cancels it (taken elsewhere, caller gone);
+ *  - while answering, "taken elsewhere" is ignored (the server's answer race
+ *    decides, via accept_failed) but the caller hanging up ends it, and media
+ *    that connects after that is left at once;
+ *  - hold, mute and warm/blind transfer as on the desk.
+ *
+ *   ringing ──accept──▶ connecting ──connected──▶ active ⇄ held
+ *      │                    │                       │  └─transfer_start─▶ transferring
+ *      ├─decline/expire/    └─accept_failed/        │                       │
+ *      │ ring_cancelled       remote_end/hang_up    └─remote_end/hang_up    ├─transfer_completed
+ *      ▼                         ▼                         ▼                ▼
+ *    ended ◀──────────────────────────────────────────────────────────── ended
+ */
+export type CallDirection = "inbound" | "outbound";
+/** direct / queue: a ring; transfer: a colleague's transfer invite; out: placed here. */
+export type CallPath = "direct" | "queue" | "transfer" | "out";
+export interface CallInfo {
+    /** The interaction id (or a client id for an outgoing call until the server's arrives). */
+    id: string;
+    conversationId?: string;
+    direction: CallDirection;
+    path: CallPath;
+    /** Caller (inbound) or callee (outbound) as shown. */
+    from: string;
+    line?: string;
+    /** Epoch ms when an unanswered ring ends. */
+    expiresAt?: number;
+    /** A transfer invite: how the colleague is handing it over. */
+    transfer?: {
+        mode: "warm" | "blind";
+    };
+}
+export type CallPhase = "ringing" | "connecting" | "active" | "held" | "transferring" | "ended";
+export type EndReason = "declined" | "missed" | "answered_elsewhere" | "remote_ended" | "hung_up" | "transferred" | "busy" | "failed" | "cancelled";
+export type TransferTarget = {
+    kind: "agent";
+    agentId: string;
+    name: string;
+} | {
+    kind: "queue";
+    queueId: string;
+    name: string;
+} | {
+    kind: "external";
+    number: string;
+};
+export interface TransferState {
+    mode: "warm" | "blind";
+    target: TransferTarget;
+    /** Warm: the colleague / number is in the call. */
+    joined: boolean;
+    startedAt: number;
+    /** Where a cancelled transfer returns to. */
+    resumeTo: "active" | "held";
+}
+export interface Call {
+    readonly info: CallInfo;
+    readonly phase: CallPhase;
+    readonly muted: boolean;
+    /** When talking started; null while an outgoing call still rings at the far end. */
+    readonly since: number | null;
+    readonly ringingSince: number | null;
+    readonly transfer: TransferState | null;
+    /** A short note for the UI (e.g. "colleague left"). */
+    readonly notice: string | null;
+    readonly endReason: EndReason | null;
+    readonly endedAt: number | null;
+    readonly error: string | null;
+}
+export interface CallsState {
+    readonly calls: Readonly<Record<string, Call>>;
+    /** The call that holds the line (connecting, active, held, transferring), if any. */
+    readonly activeId: string | null;
+}
+export declare const initialCallsState: CallsState;
+export type CallEvent = {
+    type: "ring";
+    call: CallInfo;
+    at: number;
+} | {
+    type: "dial";
+    call: CallInfo;
+    at: number;
+} | {
+    type: "accept";
+    id: string;
+    at: number;
+} | {
+    type: "decline";
+    id: string;
+    at: number;
+} | {
+    type: "expire";
+    id: string;
+    at: number;
+} | {
+    type: "ring_cancelled";
+    id: string;
+    reason: "answered_elsewhere" | "remote_ended" | "cancelled";
+    at: number;
+} | {
+    type: "accept_failed";
+    id: string;
+    reason: "answered_elsewhere" | "gone" | "failed";
+    error?: string;
+    at: number;
+} | {
+    type: "connected";
+    id: string;
+    answered: boolean;
+    at: number;
+} | {
+    type: "answered";
+    id: string;
+    at: number;
+} | {
+    type: "mute";
+    id: string;
+    muted: boolean;
+} | {
+    type: "hold";
+    id: string;
+} | {
+    type: "resume";
+    id: string;
+} | {
+    type: "transfer_start";
+    id: string;
+    mode: "warm" | "blind";
+    target: TransferTarget;
+    at: number;
+} | {
+    type: "transfer_joined";
+    id: string;
+} | {
+    type: "transfer_cancelled";
+    id: string;
+    notice?: string;
+} | {
+    type: "transfer_completed";
+    id: string;
+    at: number;
+} | {
+    type: "remote_end";
+    id: string;
+    at: number;
+} | {
+    type: "hang_up";
+    id: string;
+    at: number;
+} | {
+    type: "rekey";
+    id: string;
+    newId: string;
+    conversationId?: string;
+} | {
+    type: "dismiss";
+    id: string;
+};
+/** What the host must do after a transition. */
+export type CallEffect = {
+    type: "ring.show";
+    call: CallInfo;
+}
+/** Stop this device ringing for the call (native ring / CallKit). */
+ | {
+    type: "ring.cancel";
+    id: string;
+}
+/** Leave the call's media room (or never join it). */
+ | {
+    type: "media.leave";
+    id: string;
+} | {
+    type: "ended";
+    id: string;
+    reason: EndReason;
+};
+export interface Transition {
+    state: CallsState;
+    effects: CallEffect[];
+    /** False when the event did not apply (state is the same object). */
+    changed: boolean;
+}
+/** Apply one event. Pure: never mutates `state`. */
+export declare function transition(state: CallsState, ev: CallEvent): Transition;
+/** The call holding the line, if any. */
+export declare function activeCall(state: CallsState): Call | null;
+/** Calls ringing now, oldest first. */
+export declare function ringingCalls(state: CallsState): Call[];
+export interface CallStoreEvents {
+    change: CallsState;
+    effect: CallEffect;
+}
+export interface CallStoreOptions {
+    now?: () => number;
+    /** Remove ended calls this long after they end (0 = keep until dismissed). Default 0. */
+    forgetEndedAfterMs?: number;
+}
+/**
+ * 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.
+ */
+export declare class CallStore {
+    private readonly o;
+    readonly events: TypedEmitter<CallStoreEvents>;
+    private st;
+    private readonly timers;
+    private readonly now;
+    constructor(o?: CallStoreOptions);
+    get state(): CallsState;
+    /** Apply an event. `at` is filled from the clock when omitted. */
+    dispatch(ev: DistributiveOmit<CallEvent, "at"> & {
+        at?: number;
+    }): Transition;
+    /** Stop every timer (e.g. on sign-out). */
+    dispose(): void;
+    private syncTimers;
+}
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export {};

package/dist/cjs/contract.cjs

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * GENERATED from the HAINIVA monorepo (@aicc/types agentApi.ts and
+ * agentEvents.ts) — do not edit by hand. The Agent API's response shapes and
+ * event names: additive changes only within a major version.
+ */
+/* eslint-disable */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_EVENT_NAMES = void 0;
+// ── The event stream (/agent/v1/ws) ──────────────────────────────────────────
+exports.AGENT_EVENT_NAMES = [
+    "call.ringing", "call.ended", "conversation.assigned", "message.created",
+    "wrapup.required", "presence.changed", "supervisor.alert",
+];

package/dist/cjs/contract.d.cts

@@ -0,0 +1,215 @@
+/**
+ * GENERATED from the HAINIVA monorepo (@aicc/types agentApi.ts and
+ * agentEvents.ts) — do not edit by hand. The Agent API's response shapes and
+ * event names: additive changes only within a major version.
+ */
+export type AgentPresenceStatus = "online" | "busy" | "away" | "offline";
+export type AgentRole = "agent" | "supervisor";
+export interface AgentMeDto {
+    id: string;
+    externalId: string | null;
+    displayName: string | null;
+    role: AgentRole;
+    /** Team ids this member works in; null = the whole organisation. */
+    teams: string[] | null;
+    status: AgentPresenceStatus | null;
+    session: {
+        id: string;
+        agentAppId: string;
+        mode: "live" | "test";
+        expiresAt: string;
+    };
+}
+export interface AgentRingDto {
+    callId: string;
+    conversationId: string;
+    kind: "voice" | "video" | "chat";
+    channel: string;
+    contactName: string | null;
+    callerNumber: string | null;
+    /** direct = routed to you; queue = offered to your queue; escalation = a live call handed to you. */
+    path: "direct" | "queue" | "escalation";
+    startedAt: string;
+}
+export interface AgentCallDto {
+    callId: string;
+    conversationId: string;
+    kind: "voice" | "video" | "chat";
+    channel: string;
+    direction: "inbound" | "outbound" | "internal";
+    status: string;
+    assignedToMe: boolean;
+    startedAt: string;
+    endedAt: string | null;
+    contactName: string | null;
+    callerNumber: string | null;
+}
+export interface AgentMediaTokenDto {
+    token: string;
+    roomName: string;
+    livekitUrl: string;
+    expiresAt: string;
+}
+export interface AgentConversationDto {
+    id: string;
+    status: string;
+    subject: string | null;
+    channel: string | null;
+    chatType: string | null;
+    contact: {
+        id: string;
+        name: string | null;
+        phone: string | null;
+    };
+    assignedAgentId: string | null;
+    assignedToMe: boolean;
+    queueId: string | null;
+    /** The open interaction a message or file goes to (null when none is open). */
+    activeInteractionId: string | null;
+    lastMessageAt: string | null;
+    createdAt: string;
+    closedAt: string | null;
+}
+export interface AgentMessageDto {
+    id: string;
+    conversationId: string;
+    interactionId: string;
+    direction: string;
+    senderType: string;
+    /** agents.id of the sender when an agent wrote it. */
+    senderAgentId: string | null;
+    senderName: string | null;
+    type: string;
+    text: string | null;
+    attachment: {
+        name: string | null;
+        mimeType: string | null;
+        size: number | null;
+    } | null;
+    createdAt: string;
+}
+export interface AgentDispositionDto {
+    code: string;
+    label: string;
+    channel: string | null;
+    required: boolean;
+}
+export interface SupervisorLiveCallDto {
+    callId: string;
+    conversationId: string;
+    agentId: string | null;
+    agentName: string | null;
+    channel: string;
+    status: string;
+    startedAt: string;
+    contactName: string | null;
+    callerNumber: string | null;
+    queueId: string | null;
+}
+export interface SupervisorAgentDto {
+    id: string;
+    displayName: string;
+    externalId: string | null;
+    role: AgentRole;
+    teamId: string | null;
+    status: AgentPresenceStatus;
+    activeCalls: number;
+    openConversations: number;
+}
+export interface AgentPage<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+/** POST /agent/v1/sessions (201) and POST /agent/v1/sessions/refresh (200). */
+export interface AgentSessionDto {
+    accessToken: string;
+    accessExpiresAt: string;
+    /** hnv_rt_…, rotating: each refresh answers a new one and the old one stops working. */
+    refreshToken: string;
+    refreshExpiresAt: string;
+    sessionId: string;
+    member: {
+        id: string;
+        externalId: string | null;
+        displayName: string;
+        role: AgentRole;
+    };
+    app: {
+        id: string;
+        name: string;
+        mode: "live" | "test";
+    };
+    /** The event socket on the host the app reached; SDKs derive their own from their base URL. */
+    wsUrl: string;
+}
+/** POST /agent/v1/calls/:id/accept. `media` is null for a call without a room (chat). */
+export interface AgentAcceptDto {
+    callId: string;
+    accepted: true;
+    media: AgentMediaTokenDto | null;
+}
+/** POST /agent/v1/supervisor/calls/:id/supervise. */
+export interface SupervisorSuperviseDto {
+    callId: string;
+    mode: "monitor" | "whisper" | "barge";
+    media: AgentMediaTokenDto;
+}
+/** POST /agent/v1/push/subscriptions body. */
+export interface AgentPushSubscriptionInput {
+    platform: "ios" | "android";
+    /** FCM registration token (Android) or APNs device token, hex (iPhone). */
+    token: string;
+    /** voip = rings (PushKit on iPhone, high-priority data on Android); alert = ordinary notices. */
+    kind: "voip" | "alert";
+    /** Must be one of the agent app's allowedBundleIds. */
+    bundleId: string;
+    /** A stable id for this install: a new token from the same install replaces the old one. */
+    deviceId?: string;
+}
+/** POST /agent/v1/push/subscriptions (201). The token is never echoed. */
+export interface AgentPushSubscriptionDto {
+    id: string;
+    platform: "ios" | "android";
+    kind: "voip" | "alert";
+    bundleId: string;
+    /** Whether the agent app has working push credentials for this platform right now. */
+    deliverable: boolean;
+    createdAt: string;
+}
+/** Event data of the stream's call.ringing. */
+export interface AgentCallRingingData {
+    callId: string;
+    conversationId: string;
+    path: "direct" | "queue" | "transfer";
+    channel?: string | null;
+    line?: string | null;
+    contactName: string | null;
+    callerNumber?: string | null;
+    fromAgentId?: string | null;
+    fromAgentName?: string | null;
+    transferMode?: "warm" | "blind";
+    /** ISO time the ring ends, when the server knows it. */
+    expiresAt: string | null;
+}
+/** Event data of the stream's call.ended. callId is null when only the conversation is known. */
+export interface AgentCallEndedData {
+    callId: string | null;
+    conversationId: string | null;
+    reason: "ended" | "failed" | "answered_elsewhere" | "declined" | "expired" | "transfer_ended";
+    answeredBy?: string | null;
+    failure?: {
+        reason: string;
+    };
+}
+export declare const AGENT_EVENT_NAMES: readonly ["call.ringing", "call.ended", "conversation.assigned", "message.created", "wrapup.required", "presence.changed", "supervisor.alert"];
+export type AgentEventName = (typeof AGENT_EVENT_NAMES)[number];
+export interface AgentEvent {
+    event: AgentEventName;
+    data: Record<string, unknown>;
+}
+/** What the stream delivers: the event plus its position (resume from it). */
+export interface AgentStreamFrame extends AgentEvent {
+    type: "event";
+    seq: number;
+    at: string;
+}

package/dist/cjs/embed.cjs

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * @hainiva/agent-sdk/embed — the embeddable HAINIVA desk (iframe / WebView with a
+ * postMessage bridge). Planned for milestone M3; not part of this release.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mountDesk = mountDesk;
+/** Not yet available: throws. */
+function mountDesk(_options) {
+    throw new Error("@hainiva/agent-sdk/embed is not yet available");
+}

package/dist/cjs/embed.d.cts

@@ -0,0 +1,13 @@
+/**
+ * @hainiva/agent-sdk/embed — the embeddable HAINIVA desk (iframe / WebView with a
+ * postMessage bridge). Planned for milestone M3; not part of this release.
+ */
+export interface MountDeskOptions {
+    container: unknown;
+    getAccessToken: () => Promise<string>;
+}
+export interface MountedDesk {
+    destroy(): void;
+}
+/** Not yet available: throws. */
+export declare function mountDesk(_options?: MountDeskOptions): MountedDesk;

package/dist/cjs/emitter.cjs

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedEmitter = void 0;
+/**
+ * A small typed event emitter. `Events` maps each event name to its payload:
+ *
+ *   const e = new TypedEmitter<{ state: ConnectionState; ready: undefined }>();
+ *   const off = e.on("state", (s) => …);   e.emit("state", "open");   e.emit("ready", undefined);
+ *
+ * A listener that throws does not stop the others; the error goes to `onError`.
+ */
+class TypedEmitter {
+    constructor(onError) {
+        this.onError = onError;
+        this.listeners = new Map();
+    }
+    on(event, fn) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(fn);
+        return () => this.off(event, fn);
+    }
+    once(event, fn) {
+        const off = this.on(event, (p) => { off(); fn(p); });
+        return off;
+    }
+    /** Remove a listener added with on(). (A once() listener is removed by the function once() returned.) */
+    off(event, fn) {
+        this.listeners.get(event)?.delete(fn);
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const fn of [...set]) {
+            try {
+                fn(payload);
+            }
+            catch (e) {
+                this.onError?.(e, event);
+            }
+        }
+    }
+    listenerCount(event) { return this.listeners.get(event)?.size ?? 0; }
+    removeAll() { this.listeners.clear(); }
+}
+exports.TypedEmitter = TypedEmitter;

package/dist/cjs/emitter.d.cts

@@ -0,0 +1,22 @@
+/**
+ * A small typed event emitter. `Events` maps each event name to its payload:
+ *
+ *   const e = new TypedEmitter<{ state: ConnectionState; ready: undefined }>();
+ *   const off = e.on("state", (s) => …);   e.emit("state", "open");   e.emit("ready", undefined);
+ *
+ * A listener that throws does not stop the others; the error goes to `onError`.
+ */
+export declare class TypedEmitter<Events extends {
+    [K in keyof Events]: unknown;
+}> {
+    private readonly onError?;
+    private readonly listeners;
+    constructor(onError?: ((error: unknown, event: keyof Events) => void) | undefined);
+    on<K extends keyof Events>(event: K, fn: (payload: Events[K]) => void): () => void;
+    once<K extends keyof Events>(event: K, fn: (payload: Events[K]) => void): () => void;
+    /** Remove a listener added with on(). (A once() listener is removed by the function once() returned.) */
+    off<K extends keyof Events>(event: K, fn: (payload: Events[K]) => void): void;
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    listenerCount(event: keyof Events): number;
+    removeAll(): void;
+}

package/dist/cjs/errors.cjs

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HainivaAgentError = void 0;
+const redact_js_1 = require("./redact.cjs");
+/**
+ * Every error the SDK raises. The message is only `status code`, and the body is
+ * redacted when the error is made: a partner who logs errors (or sends them to a
+ * crash reporter) never ships a token with them.
+ */
+class HainivaAgentError extends Error {
+    /** status 0 = raised by the SDK itself (configuration, network), not by HAINIVA. */
+    constructor(status, code, body = {}, redactor) {
+        const c = redactor ? redactor.string(code) : (0, redact_js_1.redactString)(code);
+        super(`${status} ${c}`);
+        this.name = "HainivaAgentError";
+        this.status = status;
+        this.code = c;
+        this.body = (redactor ? redactor.value(body) : (0, redact_js_1.redactValue)(body));
+    }
+    /** Wrap anything thrown below the SDK (fetch, WebSocket, LiveKit) without carrying its secrets along. */
+    static from(e, code = "failed", redactor) {
+        if (e instanceof HainivaAgentError)
+            return e;
+        const message = e instanceof Error ? e.message : String(e);
+        return new HainivaAgentError(0, code, { cause: message }, redactor);
+    }
+}
+exports.HainivaAgentError = HainivaAgentError;

package/dist/cjs/errors.d.cts

@@ -0,0 +1,15 @@
+import { Redactor } from "./redact.cjs";
+/**
+ * Every error the SDK raises. The message is only `status code`, and the body is
+ * redacted when the error is made: a partner who logs errors (or sends them to a
+ * crash reporter) never ships a token with them.
+ */
+export declare class HainivaAgentError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body: Record<string, unknown>;
+    /** status 0 = raised by the SDK itself (configuration, network), not by HAINIVA. */
+    constructor(status: number, code: string, body?: Record<string, unknown>, redactor?: Redactor);
+    /** Wrap anything thrown below the SDK (fetch, WebSocket, LiveKit) without carrying its secrets along. */
+    static from(e: unknown, code?: string, redactor?: Redactor): HainivaAgentError;
+}