@hainiva/agent-sdk 0.0.0-stage → 0.3.0

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;
+}

package/dist/cjs/events.cjs

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isKnownEvent = exports.AGENT_CLOSE_CODES = void 0;
+exports.agentSocketBindings = agentSocketBindings;
+exports.isEventFrame = isEventFrame;
+exports.ringInfo = ringInfo;
+exports.toCallEvents = toCallEvents;
+const contract_js_1 = require("./contract.cjs");
+exports.AGENT_CLOSE_CODES = { tokenExpired: 4001, revoked: 4003, authTimeout: 4008, tooManySockets: 4009, rateLimited: 4029 };
+let tokenFrameSeq = 0;
+/** The protocol as ReconnectingSocket options. `lastSeq()` is read when the auth frame is built. */
+function agentSocketBindings(lastSeq) {
+    return {
+        authFrame: (token) => {
+            const s = lastSeq();
+            return s > 0 ? { type: "auth", token, lastSeq: s } : { type: "auth", token };
+        },
+        isReady: (f) => f?.type === "ready",
+        // Resume rides in the auth frame (above): no separate frame after ready.
+        resume: () => null,
+        seqOf: (f) => (f?.type === "event" && typeof f.seq === "number" && Number.isInteger(f.seq) ? f.seq : undefined),
+        tokenFrame: (token) => ({ type: "token.refresh", token, id: `t${++tokenFrameSeq}` }),
+        closeCodes: { tokenExpired: exports.AGENT_CLOSE_CODES.tokenExpired, revoked: exports.AGENT_CLOSE_CODES.revoked, fatal: [exports.AGENT_CLOSE_CODES.tooManySockets, 1003] },
+        // The server closes a socket that sends more than 120 frames a minute; 20 s is 3.
+        heartbeat: { intervalMs: 20000, timeoutMs: 60000, frame: () => ({ type: "ping" }) },
+    };
+}
+/** Is this a well-formed event frame with a name this SDK knows? Unknown names are passed on as `event.unknown`. */
+function isEventFrame(f) {
+    const x = f;
+    return !!x && x["type"] === "event" && typeof x["event"] === "string" && typeof x["seq"] === "number"
+        && !!x["data"] && typeof x["data"] === "object" && !Array.isArray(x["data"]);
+}
+const isKnownEvent = (name) => contract_js_1.AGENT_EVENT_NAMES.includes(name);
+exports.isKnownEvent = isKnownEvent;
+const str = (v) => (typeof v === "string" && v ? v : null);
+/** Pure: call.ringing data → the state machine's CallInfo (null when malformed). */
+function ringInfo(d, now, defaultRingMs) {
+    const r = d;
+    const callId = str(r.callId);
+    if (!callId)
+        return null;
+    const path = r.path === "direct" || r.path === "queue" || r.path === "transfer" ? r.path : "queue";
+    const exp = str(r.expiresAt) ? Date.parse(r.expiresAt) : NaN;
+    const conversationId = str(r.conversationId);
+    const line = str(r.line);
+    return {
+        id: callId,
+        ...(conversationId ? { conversationId } : {}),
+        direction: "inbound",
+        path,
+        from: str(r.contactName) ?? str(r.callerNumber) ?? str(r.fromAgentName) ?? "",
+        ...(line ? { line } : {}),
+        // A ring without an end the server knows still ends: a lost cancel must not leave a ghost ring.
+        expiresAt: Number.isFinite(exp) ? exp : now + defaultRingMs,
+        ...(path === "transfer" ? { transfer: { mode: r.transferMode === "blind" ? "blind" : "warm" } } : {}),
+    };
+}
+/**
+ * Pure: an event → the state-machine events it causes (empty when it is not
+ * about calls this device knows). `state` resolves a call.ended that names only
+ * the conversation.
+ */
+function toCallEvents(frame, state, now, defaultRingMs = 60000) {
+    if (frame.event === "call.ringing") {
+        const call = ringInfo(frame.data, now, defaultRingMs);
+        return call ? [{ type: "ring", call, at: now }] : [];
+    }
+    if (frame.event !== "call.ended")
+        return [];
+    const d = frame.data;
+    const ids = [];
+    const callId = str(d.callId);
+    if (callId)
+        ids.push(callId);
+    else if (str(d.conversationId)) {
+        for (const c of Object.values(state.calls))
+            if (c.info.conversationId === d.conversationId && c.phase !== "ended")
+                ids.push(c.info.id);
+    }
+    const out = [];
+    for (const id of ids) {
+        const c = state.calls[id];
+        if (!c || c.phase === "ended")
+            continue;
+        if (c.phase === "ringing" || c.phase === "connecting") {
+            const reason = d.reason === "answered_elsewhere" ? "answered_elsewhere"
+                : d.reason === "ended" || d.reason === "failed" ? "remote_ended" : "cancelled";
+            out.push({ type: "ring_cancelled", id, reason, at: now });
+        }
+        else if (d.reason !== "answered_elsewhere") {
+            // On the call: the caller hung up, the server ended it, or a blind transfer handed it over.
+            out.push({ type: "remote_end", id, at: now });
+        }
+    }
+    return out;
+}

package/dist/cjs/events.d.cts

@@ -0,0 +1,97 @@
+/**
+ * The `/agent/v1/ws` protocol (v1) as ReconnectingSocket options, and the
+ * mapping of its events to the SDK's typed events and to the call state machine.
+ *
+ *   client → auth {token, lastSeq?}   FIRST frame (the token never rides in the URL)
+ *          → token.refresh {token, id} swap in a refreshed access token
+ *          → ping
+ *   server → ready {seq, expiresAt}
+ *          → event {seq, event, data, at}
+ *          → resync_required {fromSeq} events after your lastSeq are gone: refetch over REST
+ *          → ack {id, ok, error?} · session.expiring {expiresAt} · pong · error {code}
+ *   close  4001 token refused/expired (refresh, reconnect) · 4003 revoked (stop)
+ *          4008 auth timeout · 4029 rate limited (reconnect with backoff)
+ *          4009 too many sockets · 1003 binary frame (stop: retrying cannot fix them)
+ *
+ * The resume position travels in the auth frame, so the server replays from it
+ * atomically with authentication (no window in which a live event overtakes
+ * the replay).
+ */
+import type { CallEvent, CallInfo, CallsState } from "./calls.cjs";
+import type { AgentEventName } from "./contract.cjs";
+import type { SocketOptions } from "./ws.cjs";
+export type { AgentEventName } from "./contract.cjs";
+/** One event frame from the server. */
+export interface AgentEventFrame<D = Record<string, unknown>> {
+    v?: number;
+    type: "event";
+    event: AgentEventName;
+    seq: number;
+    at: string;
+    data: D;
+}
+/** Any frame from the server. */
+export type AgentServerFrame = AgentEventFrame | {
+    v?: number;
+    type: "ready";
+    seq: number;
+    expiresAt?: string;
+    protocol?: number;
+} | {
+    v?: number;
+    type: "resync_required";
+    fromSeq: number;
+} | {
+    v?: number;
+    type: "ack";
+    id: string;
+    ok: boolean;
+    error?: string;
+    expiresAt?: string;
+} | {
+    v?: number;
+    type: "session.expiring";
+    expiresAt: string;
+} | {
+    v?: number;
+    type: "pong";
+} | {
+    v?: number;
+    type: "error";
+    code?: string;
+};
+export type AgentClientFrame = {
+    type: "auth";
+    token: string;
+    lastSeq?: number;
+} | {
+    type: "token.refresh";
+    token: string;
+    id: string;
+} | {
+    type: "resume";
+    lastSeq: number;
+    id?: string;
+} | {
+    type: "ping";
+};
+export declare const AGENT_CLOSE_CODES: {
+    readonly tokenExpired: 4001;
+    readonly revoked: 4003;
+    readonly authTimeout: 4008;
+    readonly tooManySockets: 4009;
+    readonly rateLimited: 4029;
+};
+/** The protocol as ReconnectingSocket options. `lastSeq()` is read when the auth frame is built. */
+export declare function agentSocketBindings(lastSeq: () => number): Pick<SocketOptions<AgentServerFrame, AgentClientFrame>, "authFrame" | "isReady" | "resume" | "seqOf" | "tokenFrame" | "closeCodes" | "heartbeat">;
+/** Is this a well-formed event frame with a name this SDK knows? Unknown names are passed on as `event.unknown`. */
+export declare function isEventFrame(f: unknown): f is AgentEventFrame;
+export declare const isKnownEvent: (name: string) => name is AgentEventName;
+/** Pure: call.ringing data → the state machine's CallInfo (null when malformed). */
+export declare function ringInfo(d: Record<string, unknown>, now: number, defaultRingMs: number): CallInfo | null;
+/**
+ * Pure: an event → the state-machine events it causes (empty when it is not
+ * about calls this device knows). `state` resolves a call.ended that names only
+ * the conversation.
+ */
+export declare function toCallEvents(frame: AgentEventFrame, state: CallsState, now: number, defaultRingMs?: number): CallEvent[];

package/dist/cjs/index.cjs

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * @hainiva/agent-sdk — build your own agent app on HAINIVA AICC: staff sign-in
+ * with your backend's assertion, the live event stream, and calls.
+ *
+ * Entry points:
+ *   "@hainiva/agent-sdk"              transport-agnostic core (this file) — no LiveKit, no DOM, no React Native
+ *   "@hainiva/agent-sdk/web"          localStorage store (opt-in), LiveKit call media
+ *   "@hainiva/agent-sdk/react-native" secure-store session, LiveKit call media, <HainivaDesk/>
+ *   "@hainiva/agent-sdk/embed"        mountDesk(): the HAINIVA desk in your web page (iframe)
+ *
+ * Start with HainivaAgent (./agent): it wires the session, the REST client,
+ * the event socket and the call state machine together. The parts are exported
+ * too, for apps that want their own wiring.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCallEvents = exports.ringInfo = exports.isEventFrame = exports.agentSocketBindings = exports.AGENT_CLOSE_CODES = exports.newIdempotencyKey = exports.errorFromResponse = exports.AgentRestClient = exports.HainivaAgent = exports.initialCallsState = exports.ringingCalls = exports.activeCall = exports.transition = exports.CallStore = exports.backoffDelay = exports.ReconnectingSocket = exports.memoryStore = exports.SessionManager = exports.createTokenRefresher = exports.singleFlight = exports.TypedEmitter = exports.assertSafeUrl = exports.safeLogger = exports.redactValue = exports.redactString = exports.Redactor = exports.HainivaAgentError = exports.SDK_VERSION = void 0;
+exports.SDK_VERSION = "0.3.0";
+var errors_js_1 = require("./errors.cjs");
+Object.defineProperty(exports, "HainivaAgentError", { enumerable: true, get: function () { return errors_js_1.HainivaAgentError; } });
+var redact_js_1 = require("./redact.cjs");
+Object.defineProperty(exports, "Redactor", { enumerable: true, get: function () { return redact_js_1.Redactor; } });
+Object.defineProperty(exports, "redactString", { enumerable: true, get: function () { return redact_js_1.redactString; } });
+Object.defineProperty(exports, "redactValue", { enumerable: true, get: function () { return redact_js_1.redactValue; } });
+var log_js_1 = require("./log.cjs");
+Object.defineProperty(exports, "safeLogger", { enumerable: true, get: function () { return log_js_1.safeLogger; } });
+var url_js_1 = require("./url.cjs");
+Object.defineProperty(exports, "assertSafeUrl", { enumerable: true, get: function () { return url_js_1.assertSafeUrl; } });
+var emitter_js_1 = require("./emitter.cjs");
+Object.defineProperty(exports, "TypedEmitter", { enumerable: true, get: function () { return emitter_js_1.TypedEmitter; } });
+var singleFlight_js_1 = require("./singleFlight.cjs");
+Object.defineProperty(exports, "singleFlight", { enumerable: true, get: function () { return singleFlight_js_1.singleFlight; } });
+Object.defineProperty(exports, "createTokenRefresher", { enumerable: true, get: function () { return singleFlight_js_1.createTokenRefresher; } });
+var session_js_1 = require("./session.cjs");
+Object.defineProperty(exports, "SessionManager", { enumerable: true, get: function () { return session_js_1.SessionManager; } });
+Object.defineProperty(exports, "memoryStore", { enumerable: true, get: function () { return session_js_1.memoryStore; } });
+var ws_js_1 = require("./ws.cjs");
+Object.defineProperty(exports, "ReconnectingSocket", { enumerable: true, get: function () { return ws_js_1.ReconnectingSocket; } });
+Object.defineProperty(exports, "backoffDelay", { enumerable: true, get: function () { return ws_js_1.backoffDelay; } });
+var calls_js_1 = require("./calls.cjs");
+Object.defineProperty(exports, "CallStore", { enumerable: true, get: function () { return calls_js_1.CallStore; } });
+Object.defineProperty(exports, "transition", { enumerable: true, get: function () { return calls_js_1.transition; } });
+Object.defineProperty(exports, "activeCall", { enumerable: true, get: function () { return calls_js_1.activeCall; } });
+Object.defineProperty(exports, "ringingCalls", { enumerable: true, get: function () { return calls_js_1.ringingCalls; } });
+Object.defineProperty(exports, "initialCallsState", { enumerable: true, get: function () { return calls_js_1.initialCallsState; } });
+var agent_js_1 = require("./agent.cjs");
+Object.defineProperty(exports, "HainivaAgent", { enumerable: true, get: function () { return agent_js_1.HainivaAgent; } });
+var rest_js_1 = require("./rest.cjs");
+Object.defineProperty(exports, "AgentRestClient", { enumerable: true, get: function () { return rest_js_1.AgentRestClient; } });
+Object.defineProperty(exports, "errorFromResponse", { enumerable: true, get: function () { return rest_js_1.errorFromResponse; } });
+Object.defineProperty(exports, "newIdempotencyKey", { enumerable: true, get: function () { return rest_js_1.newIdempotencyKey; } });
+var events_js_1 = require("./events.cjs");
+Object.defineProperty(exports, "AGENT_CLOSE_CODES", { enumerable: true, get: function () { return events_js_1.AGENT_CLOSE_CODES; } });
+Object.defineProperty(exports, "agentSocketBindings", { enumerable: true, get: function () { return events_js_1.agentSocketBindings; } });
+Object.defineProperty(exports, "isEventFrame", { enumerable: true, get: function () { return events_js_1.isEventFrame; } });
+Object.defineProperty(exports, "ringInfo", { enumerable: true, get: function () { return events_js_1.ringInfo; } });
+Object.defineProperty(exports, "toCallEvents", { enumerable: true, get: function () { return events_js_1.toCallEvents; } });
+__exportStar(require("./contract.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -0,0 +1,28 @@
+/**
+ * @hainiva/agent-sdk — build your own agent app on HAINIVA AICC: staff sign-in
+ * with your backend's assertion, the live event stream, and calls.
+ *
+ * Entry points:
+ *   "@hainiva/agent-sdk"              transport-agnostic core (this file) — no LiveKit, no DOM, no React Native
+ *   "@hainiva/agent-sdk/web"          localStorage store (opt-in), LiveKit call media
+ *   "@hainiva/agent-sdk/react-native" secure-store session, LiveKit call media, <HainivaDesk/>
+ *   "@hainiva/agent-sdk/embed"        mountDesk(): the HAINIVA desk in your web page (iframe)
+ *
+ * Start with HainivaAgent (./agent): it wires the session, the REST client,
+ * the event socket and the call state machine together. The parts are exported
+ * too, for apps that want their own wiring.
+ */
+export declare const SDK_VERSION = "0.3.0";
+export { HainivaAgentError } from "./errors.cjs";
+export { Redactor, redactString, redactValue } from "./redact.cjs";
+export { safeLogger, type Logger } from "./log.cjs";
+export { assertSafeUrl, type UrlRules } from "./url.cjs";
+export { TypedEmitter } from "./emitter.cjs";
+export { singleFlight, createTokenRefresher, type RefreshedToken, type TokenRefresher, type TokenRefresherOptions } from "./singleFlight.cjs";
+export { SessionManager, memoryStore, type AgentSession, type GetAssertion, type SessionEvents, type SessionManagerOptions, type SessionStore, type SessionTransport, } from "./session.cjs";
+export { ReconnectingSocket, backoffDelay, type ConnectionState, type SocketEvents, type SocketOptions, type WebSocketCtor, type WebSocketLike, } from "./ws.cjs";
+export { CallStore, transition, activeCall, ringingCalls, initialCallsState, type Call, type CallDirection, type CallEffect, type CallEvent, type CallInfo, type CallPath, type CallPhase, type CallsState, type CallStoreEvents, type CallStoreOptions, type EndReason, type Transition, type TransferState, type TransferTarget, } from "./calls.cjs";
+export { HainivaAgent, type HainivaAgentEvents, type HainivaAgentOptions, type JoinMedia, type MediaSession } from "./agent.cjs";
+export { AgentRestClient, errorFromResponse, newIdempotencyKey, type AgentRestOptions, type AgentStatus, type CallTransferTarget, type ConversationListQuery, type MediaCredentials, type RequestOptions, type TokenSource, } from "./rest.cjs";
+export { AGENT_CLOSE_CODES, agentSocketBindings, isEventFrame, ringInfo, toCallEvents, type AgentClientFrame, type AgentEventFrame, type AgentServerFrame, } from "./events.cjs";
+export * from "./contract.cjs";

package/dist/cjs/livekit.cjs

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinCallRoom = joinCallRoom;
+/**
+ * Joining a call's LiveKit room. Used by the /web and /react-native entry points
+ * only: `livekit-client` is a peer dependency, and the core never imports it.
+ */
+const livekit_client_1 = require("livekit-client");
+const errors_js_1 = require("./errors.cjs");
+const redact_js_1 = require("./redact.cjs");
+const url_js_1 = require("./url.cjs");
+/**
+ * Join with the call's media credentials, microphone on. The token is handed to
+ * LiveKit only; errors are redacted (LiveKit's own error text can contain its
+ * signalling URL, which carries the token).
+ */
+async function joinCallRoom(join, o = {}) {
+    const redactor = o.redactor ?? new redact_js_1.Redactor();
+    redactor.add(join.token);
+    (0, url_js_1.assertSafeUrl)(join.url, { kind: "ws", ...(o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}) });
+    if (!join.token)
+        throw new errors_js_1.HainivaAgentError(0, "no_media_token");
+    const room = new livekit_client_1.Room(o.roomOptions);
+    try {
+        await room.connect(join.url, join.token, { autoSubscribe: true, ...o.connectOptions });
+        if (o.microphone !== false)
+            await room.localParticipant.setMicrophoneEnabled(true);
+    }
+    catch (e) {
+        await room.disconnect().catch(() => undefined);
+        throw errors_js_1.HainivaAgentError.from(e, "media_connect_failed", redactor);
+    }
+    let left = false;
+    return {
+        room,
+        async setMuted(muted) {
+            try {
+                await room.localParticipant.setMicrophoneEnabled(!muted);
+            }
+            catch (e) {
+                throw errors_js_1.HainivaAgentError.from(e, "media_mute_failed", redactor);
+            }
+        },
+        async leave() {
+            if (left)
+                return;
+            left = true;
+            await room.disconnect().catch(() => undefined);
+        },
+        onDisconnected(fn) {
+            const h = () => fn();
+            room.on(livekit_client_1.RoomEvent.Disconnected, h);
+            return () => { room.off(livekit_client_1.RoomEvent.Disconnected, h); };
+        },
+    };
+}

package/dist/cjs/livekit.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Joining a call's LiveKit room. Used by the /web and /react-native entry points
+ * only: `livekit-client` is a peer dependency, and the core never imports it.
+ */
+import { Room, type RoomConnectOptions, type RoomOptions } from "livekit-client";
+import { Redactor } from "./redact.cjs";
+export interface MediaJoin {
+    /** wss:// LiveKit URL. */
+    url: string;
+    /** Room token for this call — kept out of every error. */
+    token: string;
+}
+export interface JoinOptions {
+    /** Start with the microphone on. Default true. */
+    microphone?: boolean;
+    roomOptions?: RoomOptions;
+    connectOptions?: RoomConnectOptions;
+    /** ws://localhost in development. Default false. */
+    allowInsecureLocalhost?: boolean;
+    redactor?: Redactor;
+}
+export interface MediaCall {
+    readonly room: Room;
+    setMuted(muted: boolean): Promise<void>;
+    /** Leave the room (idempotent). */
+    leave(): Promise<void>;
+    /** The room closed (far end hung up, server ended it, network lost). Returns an unsubscribe. */
+    onDisconnected(fn: () => void): () => void;
+}
+/**
+ * Join with the call's media credentials, microphone on. The token is handed to
+ * LiveKit only; errors are redacted (LiveKit's own error text can contain its
+ * signalling URL, which carries the token).
+ */
+export declare function joinCallRoom(join: MediaJoin, o?: JoinOptions): Promise<MediaCall>;

package/dist/cjs/log.cjs

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeLogger = safeLogger;
+const redact_js_1 = require("./redact.cjs");
+/** A logger that redacts every detail before the partner's logger sees it. */
+function safeLogger(log, redactor = new redact_js_1.Redactor()) {
+    if (!log)
+        return () => { };
+    return (event, detail) => {
+        try {
+            log(redactor.string(event), detail === undefined ? undefined : redactor.value(detail));
+        }
+        catch { /* a broken logger must not break a call */ }
+    };
+}

package/dist/cjs/log.d.cts

@@ -0,0 +1,5 @@
+import { Redactor } from "./redact.cjs";
+/** The partner's logger. The SDK logs nothing unless one is given. */
+export type Logger = (event: string, detail?: unknown) => void;
+/** A logger that redacts every detail before the partner's logger sees it. */
+export declare function safeLogger(log: Logger | undefined, redactor?: Redactor): Logger;

package/dist/cjs/react-native.cjs

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deskBridgeScript = exports.HainivaDesk = exports.joinCallRoom = void 0;
+exports.secureStoreSessionStore = secureStoreSessionStore;
+var livekit_js_1 = require("./livekit.cjs");
+Object.defineProperty(exports, "joinCallRoom", { enumerable: true, get: function () { return livekit_js_1.joinCallRoom; } });
+/**
+ * The session (and so the refresh token) in secure storage only. There is
+ * deliberately no fallback to AsyncStorage or another plain store: if secure
+ * storage fails, the session stays in memory and the next launch signs in again
+ * with a fresh assertion.
+ *
+ *   import * as SecureStore from "expo-secure-store";
+ *   const store = secureStoreSessionStore(SecureStore);
+ */
+function secureStoreSessionStore(secure, o = {}) {
+    const key = o.key ?? "hainiva.agent.session";
+    if (!/^[A-Za-z0-9._-]+$/.test(key))
+        throw new Error("secureStoreSessionStore: key may use only letters, digits, '.', '-' and '_'");
+    const access = o.keychainAccessible ?? secure.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY;
+    const opts = access === undefined ? {} : { keychainAccessible: access };
+    return {
+        get: () => secure.getItemAsync(key, opts),
+        set: (v) => secure.setItemAsync(key, v, opts),
+        remove: () => secure.deleteItemAsync(key, opts),
+    };
+}
+// The embedded HAINIVA desk in a WebView (react-native-webview, an optional
+// peer), signed in with your agent session; calls stay native in your app.
+var reactNativeDesk_js_1 = require("./reactNativeDesk.cjs");
+Object.defineProperty(exports, "HainivaDesk", { enumerable: true, get: function () { return reactNativeDesk_js_1.HainivaDesk; } });
+Object.defineProperty(exports, "deskBridgeScript", { enumerable: true, get: function () { return reactNativeDesk_js_1.deskBridgeScript; } });

package/dist/cjs/react-native.d.cts

@@ -0,0 +1,39 @@
+/**
+ * @hainiva/agent-sdk/react-native — React Native adapters: the session in the
+ * Keychain / Android Keystore (expo-secure-store) and LiveKit call media.
+ *
+ * Call `registerGlobals()` from `@livekit/react-native` once at startup before
+ * joining a room. Native ringing (CallKit / Android call notification) is
+ * `@hainiva/react-native-call`.
+ */
+import type { SessionStore } from "./session.cjs";
+export { joinCallRoom, type JoinOptions, type MediaCall, type MediaJoin } from "./livekit.cjs";
+/** The part of `expo-secure-store` this adapter uses: pass the module itself. */
+export interface SecureStoreModule {
+    getItemAsync(key: string, options?: Record<string, unknown>): Promise<string | null>;
+    setItemAsync(key: string, value: string, options?: Record<string, unknown>): Promise<void>;
+    deleteItemAsync(key: string, options?: Record<string, unknown>): Promise<void>;
+    /** expo-secure-store's constant; used as the default accessibility. */
+    AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY?: unknown;
+}
+export interface SecureStoreSessionOptions {
+    /** Default "hainiva.agent.session". Letters, digits, ".", "-" and "_" only. */
+    key?: string;
+    /**
+     * iPhone Keychain accessibility. Default AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY:
+     * readable while the phone is locked (a call that wakes the app must find the
+     * session) and never migrated to another device.
+     */
+    keychainAccessible?: unknown;
+}
+/**
+ * The session (and so the refresh token) in secure storage only. There is
+ * deliberately no fallback to AsyncStorage or another plain store: if secure
+ * storage fails, the session stays in memory and the next launch signs in again
+ * with a fresh assertion.
+ *
+ *   import * as SecureStore from "expo-secure-store";
+ *   const store = secureStoreSessionStore(SecureStore);
+ */
+export declare function secureStoreSessionStore(secure: SecureStoreModule, o?: SecureStoreSessionOptions): SessionStore;
+export { HainivaDesk, deskBridgeScript, type HainivaDeskProps, type WebViewLike } from "./reactNativeDesk.cjs";