@hainiva/agent-sdk 0.0.0-stage → 0.3.0

package/dist/cjs/rest.d.cts

@@ -0,0 +1,172 @@
+/**
+ * The REST client for the Agent API (`/agent/v1/*`).
+ *
+ *  - `baseUrl` is checked with assertSafeUrl (HTTPS only, no credential in it);
+ *  - the access token goes in the Authorization header only — never in a URL;
+ *  - a 401 `token_expired` (or `token_invalid`) refreshes ONCE (single flight
+ *    across every caller: SessionManager) and retries the request once; a
+ *    refused refresh signs in again with a NEW assertion from `getAssertion`;
+ *    a 401 `session_revoked` is final (the facade emits `revoked`);
+ *  - every POST carries an `Idempotency-Key` (the retry after a refresh reuses
+ *    it, so the server never does the action twice);
+ *  - each request has a timeout (default 15 s) and honours an AbortSignal;
+ *  - any non-2xx becomes a HainivaAgentError {status, code, body} from the
+ *    server's `{error:{code,message}}` envelope, redacted; non-JSON or
+ *    non-object bodies are handled defensively.
+ */
+import type { AgentAcceptDto, AgentCallDto, AgentConversationDto, AgentDispositionDto, AgentMeDto, AgentMediaTokenDto, AgentMessageDto, AgentPage, AgentPresenceStatus, AgentPushSubscriptionDto, AgentPushSubscriptionInput, AgentRingDto, AgentDeskSessionDto, AgentSessionDto, SupervisorAgentDto, SupervisorLiveCallDto, SupervisorSuperviseDto } from "./contract.cjs";
+import { HainivaAgentError } from "./errors.cjs";
+import { type Logger } from "./log.cjs";
+import { Redactor } from "./redact.cjs";
+import type { AgentSession, SessionTransport } from "./session.cjs";
+export interface AgentRestOptions {
+    /** e.g. https://api.hainiva.com (HTTPS only). */
+    baseUrl: string;
+    /** Your HAINIVA organisation id: sign-in and refresh name it. */
+    tenantId: string;
+    fetch?: typeof fetch;
+    /** Per request, default 15 000 ms. */
+    timeoutMs?: number;
+    /** Local development only: http://localhost. */
+    allowInsecureLocalhost?: boolean;
+    /** Device shown to the organisation's admins in the session list. */
+    device?: {
+        label?: string;
+        platform?: "ios" | "android" | "web" | "other";
+    };
+    redactor?: Redactor;
+    log?: Logger;
+}
+/** Where the client gets its access token, and how it reports a refused one. */
+export interface TokenSource {
+    accessToken(): Promise<string>;
+    /** The server refused this token: refresh before the next request. */
+    invalidate(refused?: string): void;
+}
+export interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+    signal?: AbortSignal;
+    /** Overrides the client's timeout for this request. */
+    timeoutMs?: number;
+}
+/** LiveKit room credentials for a call. */
+export type MediaCredentials = AgentMediaTokenDto;
+export type AgentStatus = AgentPresenceStatus;
+/** Where a call is transferred. */
+export type CallTransferTarget = {
+    agentId: string;
+    mode?: "warm" | "blind";
+} | {
+    queueId: string;
+} | {
+    number: string;
+    mode?: "warm" | "blind";
+};
+export interface ConversationListQuery {
+    scope?: "all" | "mine";
+    status?: "open" | "closed" | "all";
+    cursor?: string;
+    limit?: number;
+}
+/** A random UUID v4: crypto.randomUUID where it exists (browsers, Node), else getRandomValues, else Math.random (Idempotency-Key only, not a secret). */
+export declare function newIdempotencyKey(): string;
+/** Pure: the error a non-2xx answer becomes. Exported for tests. */
+export declare function errorFromResponse(status: number, data: unknown, redactor?: Redactor, retryAfter?: string | null): HainivaAgentError;
+/**
+ * The Agent API over fetch. `tokens` is normally the SessionManager; the
+ * client's own `sessions` transport is what that SessionManager signs in with.
+ */
+export declare class AgentRestClient {
+    private readonly o;
+    readonly baseUrl: string;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly redactor;
+    private readonly log;
+    private tokens;
+    constructor(o: AgentRestOptions, tokens?: TokenSource);
+    /** Attach the token source after construction (the SessionManager needs `sessions` first). */
+    useTokens(tokens: TokenSource): void;
+    /** The wss:// URL of the event stream, derived from baseUrl (never from a server answer). */
+    get wsUrl(): string;
+    readonly sessions: SessionTransport<AgentSession & AgentSessionDto>;
+    /** An authenticated request: refresh-and-retry once on an expired token. */
+    request<T>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, opts?: RequestOptions): Promise<T>;
+    private raw;
+    me(o?: RequestOptions): Promise<AgentMeDto>;
+    setStatus(status: AgentStatus, o?: RequestOptions): Promise<{
+        status: AgentStatus;
+    }>;
+    /** Rings for this member now (after a cold start, a missed push or a resync). */
+    pendingRings(o?: RequestOptions): Promise<AgentRingDto[]>;
+    getCall(callId: string, o?: RequestOptions): Promise<AgentCallDto>;
+    acceptCall(callId: string, o?: RequestOptions): Promise<AgentAcceptDto>;
+    declineCall(callId: string, o?: RequestOptions): Promise<{
+        callId: string;
+        declined: true;
+    }>;
+    endCall(callId: string, o?: RequestOptions): Promise<{
+        callId: string;
+        ended: true;
+    }>;
+    holdCall(callId: string, on: boolean, o?: RequestOptions): Promise<{
+        callId: string;
+        onHold: boolean;
+    }>;
+    transferCall(callId: string, target: CallTransferTarget, o?: RequestOptions): Promise<{
+        callId: string;
+        transferred: true;
+    }>;
+    /**
+     * A 15-minute desk token for the embedded HAINIVA desk (S4): give it to the
+     * desk over postMessage only (`@hainiva/agent-sdk/embed` does). Never put it
+     * in a URL or storage. Ends with this session.
+     */
+    deskSession(o?: RequestOptions): Promise<AgentDeskSessionDto>;
+    /** Re-mint the LiveKit token while still a participant (reconnect, token near expiry). */
+    mediaToken(callId: string, o?: RequestOptions): Promise<MediaCredentials>;
+    dispositions(channel?: string, o?: RequestOptions): Promise<AgentDispositionDto[]>;
+    wrapUp(callId: string, w?: {
+        dispositionCode?: string;
+        notes?: string;
+    }, o?: RequestOptions): Promise<{
+        callId: string;
+        wrappedUp: true;
+    }>;
+    listConversations(q?: ConversationListQuery, o?: RequestOptions): Promise<AgentPage<AgentConversationDto>>;
+    getConversation(conversationId: string, o?: RequestOptions): Promise<AgentConversationDto>;
+    /** Claim it (no agentId), or — a supervisor — assign it to a colleague. */
+    assignConversation(conversationId: string, agentId?: string, o?: RequestOptions): Promise<unknown>;
+    releaseConversation(conversationId: string, note?: string, o?: RequestOptions): Promise<{
+        conversationId: string;
+        released: true;
+    }>;
+    transferConversation(conversationId: string, to: {
+        agentId: string;
+    } | {
+        queueId: string;
+        note?: string;
+    }, o?: RequestOptions): Promise<unknown>;
+    closeConversation(conversationId: string, o?: RequestOptions): Promise<{
+        conversationId: string;
+        closed: true;
+    }>;
+    listMessages(conversationId: string, q?: {
+        after?: string;
+        limit?: number;
+    }, o?: RequestOptions): Promise<AgentPage<AgentMessageDto>>;
+    sendMessage(conversationId: string, text: string, o?: RequestOptions): Promise<Pick<AgentMessageDto, "id" | "conversationId" | "interactionId" | "createdAt">>;
+    typing(conversationId: string, o?: RequestOptions): Promise<{
+        ok: true;
+    }>;
+    liveCalls(o?: RequestOptions): Promise<SupervisorLiveCallDto[]>;
+    teamAgents(o?: RequestOptions): Promise<SupervisorAgentDto[]>;
+    supervise(callId: string, mode?: "monitor" | "whisper" | "barge", o?: RequestOptions): Promise<SupervisorSuperviseDto>;
+    setSuperviseMode(callId: string, mode: "monitor" | "whisper" | "barge", supervisorTrackSid?: string, o?: RequestOptions): Promise<{
+        callId: string;
+        mode: string;
+    }>;
+    registerPush(sub: AgentPushSubscriptionInput, o?: RequestOptions): Promise<AgentPushSubscriptionDto>;
+    unregisterPush(token: string, o?: RequestOptions): Promise<void>;
+}

package/dist/cjs/session.cjs

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+exports.memoryStore = memoryStore;
+const emitter_js_1 = require("./emitter.cjs");
+const errors_js_1 = require("./errors.cjs");
+const log_js_1 = require("./log.cjs");
+const redact_js_1 = require("./redact.cjs");
+const singleFlight_js_1 = require("./singleFlight.cjs");
+/** Keeps the session for the life of the page / JS context only. The default. */
+function memoryStore() {
+    let v = null;
+    return { get: () => v, set: (x) => { v = x; }, remove: () => { v = null; } };
+}
+const isSession = (v) => {
+    const s = v;
+    return !!s && typeof s === "object" && typeof s["accessToken"] === "string" && typeof s["refreshToken"] === "string"
+        && typeof s["accessExpiresAt"] === "string" && typeof s["refreshExpiresAt"] === "string";
+};
+/**
+ * The staff session: sign in with a fresh assertion, keep it in the store,
+ * refresh before expiry (single flight — one refresh however many callers),
+ * sign in again with a NEW assertion when the refresh is refused.
+ */
+class SessionManager {
+    constructor(o) {
+        this.o = o;
+        this.events = new emitter_js_1.TypedEmitter();
+        this.session = null;
+        this.forceNext = false;
+        this.freshSignIn = (0, singleFlight_js_1.singleFlight)(async () => {
+            // Always a new assertion: never cached, never stored, never reused.
+            let assertion;
+            try {
+                assertion = await this.o.getAssertion();
+            }
+            catch (e) {
+                throw errors_js_1.HainivaAgentError.from(e, "assertion_failed", this.redactor);
+            }
+            if (typeof assertion !== "string" || assertion.split(".").length !== 3) {
+                throw new errors_js_1.HainivaAgentError(0, "invalid_assertion", { hint: "getAssertion must resolve to a signed JWT from your backend" });
+            }
+            this.redactor.add(assertion);
+            try {
+                const s = await this.o.transport.exchange(assertion);
+                if (!isSession(s))
+                    throw new errors_js_1.HainivaAgentError(0, "invalid_session", {}, this.redactor);
+                await this.keep(s);
+                return s;
+            }
+            catch (e) {
+                throw errors_js_1.HainivaAgentError.from(e, "sign_in_failed", this.redactor);
+            }
+            finally {
+                this.redactor.remove(assertion);
+            }
+        });
+        this.store = o.store ?? memoryStore();
+        this.skew = o.refreshSkewMs ?? 60000;
+        this.now = o.now ?? Date.now;
+        this.redactor = o.redactor ?? new redact_js_1.Redactor();
+        this.log = (0, log_js_1.safeLogger)(o.log, this.redactor);
+        this.refreshOnce = (0, singleFlight_js_1.singleFlight)(() => this.doRefresh());
+    }
+    get current() { return this.session; }
+    /** Restore the stored session if it can still be refreshed, else sign in afresh. */
+    async signIn() {
+        const saved = await Promise.resolve().then(() => this.store.get()).catch((e) => { this.log("store_read_failed", e); return null; });
+        if (saved) {
+            try {
+                const s = JSON.parse(saved);
+                if (isSession(s) && Date.parse(s.refreshExpiresAt) > this.now() + this.skew) {
+                    this.adopt(s);
+                    return await this.fresh();
+                }
+            }
+            catch { /* corrupt or refused: sign in afresh */ }
+            await Promise.resolve().then(() => this.store.remove()).catch(() => undefined);
+        }
+        return this.freshSignIn();
+    }
+    /** A valid access token, refreshing first when it is about to expire. */
+    async accessToken() {
+        return (await this.fresh()).accessToken;
+    }
+    /**
+     * The server refused the access token (401 / socket 4001): the next
+     * accessToken() refreshes. Pass the token that was refused: a refusal of an
+     * OLDER token (a request that was in flight while another caller already
+     * refreshed) is ignored, so ten parallel 401s cause one refresh, not ten.
+     */
+    invalidate(refused) {
+        if (refused && this.session && this.session.accessToken !== refused)
+            return;
+        this.forceNext = true;
+    }
+    /** Forget the session here only (the server already ended it): no revoke call. */
+    async clear() {
+        this.adopt(null);
+        await Promise.resolve().then(() => this.store.remove()).catch(() => undefined);
+    }
+    /** End the session here and (best effort) on the server. */
+    async signOut() {
+        const s = this.session;
+        this.adopt(null);
+        await Promise.resolve().then(() => this.store.remove()).catch(() => undefined);
+        if (s && this.o.transport.revoke)
+            await this.o.transport.revoke(s).catch((e) => this.log("revoke_failed", e));
+        this.redactor.clear();
+    }
+    async fresh() {
+        if (!this.session)
+            return this.freshSignIn();
+        const left = Date.parse(this.session.accessExpiresAt) - this.now();
+        if (!this.forceNext && left > this.skew)
+            return this.session;
+        return this.refreshOnce();
+    }
+    async doRefresh() {
+        const s = this.session;
+        if (!s)
+            return this.freshSignIn();
+        this.forceNext = false;
+        try {
+            const r = await this.o.transport.refresh(s.refreshToken);
+            if (!r || typeof r.accessToken !== "string" || !r.accessToken)
+                throw new errors_js_1.HainivaAgentError(0, "refresh_failed", {}, this.redactor);
+            const next = { ...s, ...r };
+            await this.keep(next);
+            return next;
+        }
+        catch (e) {
+            // Refused (expired, revoked, reused): a new session from a NEW assertion.
+            if (e instanceof errors_js_1.HainivaAgentError && (e.status === 401 || e.status === 403)) {
+                this.log("refresh_refused", { status: e.status });
+                await Promise.resolve().then(() => this.store.remove()).catch(() => undefined);
+                this.adopt(null);
+                return this.freshSignIn();
+            }
+            this.forceNext = true;
+            throw errors_js_1.HainivaAgentError.from(e, "refresh_failed", this.redactor);
+        }
+    }
+    async keep(s) {
+        this.adopt(s);
+        await Promise.resolve().then(() => this.store.set(JSON.stringify(s))).catch((e) => this.log("store_write_failed", e));
+    }
+    adopt(s) {
+        const prev = this.session;
+        this.session = s;
+        // Old tokens stay redacted: they may still appear in an in-flight error.
+        if (s)
+            this.redactor.add(s.accessToken, s.refreshToken);
+        this.events.emit("session", s);
+        if (s && s.accessToken !== prev?.accessToken)
+            this.events.emit("token", s.accessToken);
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/cjs/session.d.cts

@@ -0,0 +1,101 @@
+import { TypedEmitter } from "./emitter.cjs";
+import { type Logger } from "./log.cjs";
+import { Redactor } from "./redact.cjs";
+/**
+ * Where the session is kept between launches. Same shape as @hainiva/app-sdk's.
+ * The default is in memory (nothing persisted). On the web, `localStorageStore`
+ * (`@hainiva/agent-sdk/web`) is opt-in; in React Native use
+ * `secureStoreSessionStore` (`@hainiva/agent-sdk/react-native`) — the refresh
+ * token then lives only in the Keychain / Android Keystore.
+ */
+export interface SessionStore {
+    get(): Promise<string | null> | string | null;
+    set(value: string): Promise<void> | void;
+    remove(): Promise<void> | void;
+}
+/** Keeps the session for the life of the page / JS context only. The default. */
+export declare function memoryStore(): SessionStore;
+/** A staff session. Fields beyond these are kept as the server sent them. */
+export interface AgentSession {
+    accessToken: string;
+    /** ISO time. */
+    accessExpiresAt: string;
+    refreshToken: string;
+    /** ISO time. */
+    refreshExpiresAt: string;
+    [field: string]: unknown;
+}
+/**
+ * Ask YOUR backend for a fresh staff assertion (a short-lived JWT it signs with
+ * the agent app's private key). Called every time a new session is needed —
+ * the SDK never caches or stores an assertion, and you must not either: each
+ * one carries a single-use `jti` and expires in minutes.
+ */
+export type GetAssertion = () => Promise<string>;
+/**
+ * How sessions are created and refreshed — bound by the REST client.
+ * TODO(S3b): implemented against `/agent/v1/sessions` once the S2 contract is final.
+ */
+export interface SessionTransport<S extends AgentSession = AgentSession> {
+    /** Exchange an assertion for a session (POST /agent/v1/sessions). */
+    exchange(assertion: string): Promise<S>;
+    /** Rotate: a new access token and (rotating) refresh token. */
+    refresh(refreshToken: string): Promise<Pick<S, "accessToken" | "accessExpiresAt"> & Partial<S>>;
+    /** End the session on the server (best effort). */
+    revoke?(session: S): Promise<void>;
+}
+export interface SessionManagerOptions<S extends AgentSession> {
+    getAssertion: GetAssertion;
+    transport: SessionTransport<S>;
+    /** Default: memoryStore(). */
+    store?: SessionStore;
+    /** Refresh this long before the access token expires. Default 60 s. */
+    refreshSkewMs?: number;
+    now?: () => number;
+    redactor?: Redactor;
+    log?: Logger;
+}
+export interface SessionEvents<S extends AgentSession> {
+    /** A new access token (after sign-in or refresh): e.g. send it on the socket. */
+    token: string;
+    session: S | null;
+}
+/**
+ * The staff session: sign in with a fresh assertion, keep it in the store,
+ * refresh before expiry (single flight — one refresh however many callers),
+ * sign in again with a NEW assertion when the refresh is refused.
+ */
+export declare class SessionManager<S extends AgentSession = AgentSession> {
+    private readonly o;
+    readonly events: TypedEmitter<SessionEvents<S>>;
+    private session;
+    private readonly store;
+    private readonly skew;
+    private readonly now;
+    readonly redactor: Redactor;
+    private readonly log;
+    private readonly refreshOnce;
+    private forceNext;
+    constructor(o: SessionManagerOptions<S>);
+    get current(): S | null;
+    /** Restore the stored session if it can still be refreshed, else sign in afresh. */
+    signIn(): Promise<S>;
+    /** A valid access token, refreshing first when it is about to expire. */
+    accessToken(): Promise<string>;
+    /**
+     * The server refused the access token (401 / socket 4001): the next
+     * accessToken() refreshes. Pass the token that was refused: a refusal of an
+     * OLDER token (a request that was in flight while another caller already
+     * refreshed) is ignored, so ten parallel 401s cause one refresh, not ten.
+     */
+    invalidate(refused?: string): void;
+    /** Forget the session here only (the server already ended it): no revoke call. */
+    clear(): Promise<void>;
+    /** End the session here and (best effort) on the server. */
+    signOut(): Promise<void>;
+    private fresh;
+    private doRefresh;
+    private readonly freshSignIn;
+    private keep;
+    private adopt;
+}

package/dist/cjs/singleFlight.cjs

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.singleFlight = singleFlight;
+exports.createTokenRefresher = createTokenRefresher;
+/**
+ * Calls `fn` at most once at a time: callers that arrive while it runs share its
+ * result (or its error). The next call after it settles runs `fn` again.
+ */
+function singleFlight(fn) {
+    let inFlight = null;
+    return () => {
+        inFlight ?? (inFlight = (async () => {
+            try {
+                return await fn();
+            }
+            finally {
+                inFlight = null;
+            }
+        })());
+        return inFlight;
+    };
+}
+/**
+ * Single-flight token refresh with a pluggable refresh function. Ten requests that
+ * find the token expired cause one refresh, not ten — which also keeps a
+ * rotating refresh token from being spent twice (reuse detection would then
+ * revoke the whole session family).
+ */
+function createTokenRefresher(o) {
+    const skew = o.skewMs ?? 60000;
+    const now = o.now ?? Date.now;
+    let current = null;
+    const run = singleFlight(async () => {
+        const t = await o.refresh();
+        if (!t || typeof t.token !== "string" || !t.token)
+            throw new Error("refresh returned no token");
+        current = t;
+        return t.token;
+    });
+    return {
+        get valid() { return current !== null && current.expiresAt - now() > skew; },
+        async get() {
+            if (current && current.expiresAt - now() > skew)
+                return current.token;
+            return run();
+        },
+        invalidate() { current = null; },
+    };
+}

package/dist/cjs/singleFlight.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Calls `fn` at most once at a time: callers that arrive while it runs share its
+ * result (or its error). The next call after it settles runs `fn` again.
+ */
+export declare function singleFlight<T>(fn: () => Promise<T>): () => Promise<T>;
+export interface RefreshedToken {
+    token: string;
+    /** Epoch ms. */
+    expiresAt: number;
+}
+export interface TokenRefresherOptions {
+    /** Fetch a new token. Called once however many callers wait for it. */
+    refresh: () => Promise<RefreshedToken>;
+    /** Refresh this long before expiry. Default 60 s. */
+    skewMs?: number;
+    now?: () => number;
+}
+export interface TokenRefresher {
+    /** A token valid for at least `skewMs`, refreshing (once, shared) when needed. */
+    get(): Promise<string>;
+    /** Forget the current token (the server refused it): the next get() refreshes. */
+    invalidate(): void;
+    /** Whether a token is held that is still valid beyond the skew. */
+    readonly valid: boolean;
+}
+/**
+ * Single-flight token refresh with a pluggable refresh function. Ten requests that
+ * find the token expired cause one refresh, not ten — which also keeps a
+ * rotating refresh token from being spent twice (reuse detection would then
+ * revoke the whole session family).
+ */
+export declare function createTokenRefresher(o: TokenRefresherOptions): TokenRefresher;

package/dist/cjs/url.cjs

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSafeUrl = assertSafeUrl;
+const errors_js_1 = require("./errors.cjs");
+const LOCAL = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/** Query parameter names that would carry a credential. */
+const CREDENTIAL_PARAM = /token|assertion|secret|password|passw|key|auth|jwt|session|signature|ticket/i;
+/**
+ * A base / socket / media URL a partner configured, checked before use: TLS only,
+ * no user:password@, and no credential in the query string. Tokens travel in
+ * headers or in the socket's first frame — never in a URL, which ends up in
+ * access logs, proxies and browser history.
+ */
+function assertSafeUrl(raw, rules) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new errors_js_1.HainivaAgentError(0, "invalid_url", { kind: rules.kind });
+    }
+    const secure = rules.kind === "http" ? "https:" : "wss:";
+    const insecure = rules.kind === "http" ? "http:" : "ws:";
+    const local = LOCAL.has(u.hostname);
+    if (u.protocol !== secure && !(u.protocol === insecure && local && rules.allowInsecureLocalhost)) {
+        throw new errors_js_1.HainivaAgentError(0, "insecure_url", { expected: secure, got: u.protocol, host: u.host });
+    }
+    if (u.username || u.password)
+        throw new errors_js_1.HainivaAgentError(0, "credentials_in_url", { host: u.host });
+    let param = null;
+    u.searchParams.forEach((_v, name) => { if (!param && CREDENTIAL_PARAM.test(name))
+        param = name; });
+    if (param)
+        throw new errors_js_1.HainivaAgentError(0, "credentials_in_url", { host: u.host, param });
+    if (/eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}/.test(u.search + u.hash + u.pathname)) {
+        throw new errors_js_1.HainivaAgentError(0, "credentials_in_url", { host: u.host });
+    }
+    return u;
+}

package/dist/cjs/url.d.cts

@@ -0,0 +1,13 @@
+export interface UrlRules {
+    /** "http" for REST (https required), "ws" for sockets (wss required). */
+    kind: "http" | "ws";
+    /** Allow http:// / ws:// to localhost (local development only). Default false. */
+    allowInsecureLocalhost?: boolean;
+}
+/**
+ * A base / socket / media URL a partner configured, checked before use: TLS only,
+ * no user:password@, and no credential in the query string. Tokens travel in
+ * headers or in the socket's first frame — never in a URL, which ends up in
+ * access logs, proxies and browser history.
+ */
+export declare function assertSafeUrl(raw: string, rules: UrlRules): URL;

package/dist/cjs/web.cjs

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinCallRoom = exports.memoryStore = void 0;
+exports.localStorageStore = localStorageStore;
+var session_js_1 = require("./session.cjs");
+Object.defineProperty(exports, "memoryStore", { enumerable: true, get: function () { return session_js_1.memoryStore; } });
+var livekit_js_1 = require("./livekit.cjs");
+Object.defineProperty(exports, "joinCallRoom", { enumerable: true, get: function () { return livekit_js_1.joinCallRoom; } });
+/**
+ * OPT-IN: keep the session in localStorage so a reload stays signed in.
+ *
+ * ⚠ Any script running on your origin (an XSS, a compromised third-party script)
+ * can read localStorage — including the 30-day refresh token. Use it only with a
+ * strict Content-Security-Policy and no third-party scripts on the page. The
+ * default (memoryStore) keeps nothing: a reload signs in again with a fresh
+ * assertion from your backend, which is the safer choice.
+ */
+function localStorageStore(o = {}) {
+    const key = o.key ?? "hainiva.agent.session";
+    const storage = o.storage ?? globalThis.localStorage;
+    if (!storage)
+        throw new Error("localStorage is not available here; use memoryStore()");
+    return {
+        get: () => storage.getItem(key),
+        set: (v) => storage.setItem(key, v),
+        remove: () => storage.removeItem(key),
+    };
+}

package/dist/cjs/web.d.cts

@@ -0,0 +1,23 @@
+/**
+ * @hainiva/agent-sdk/web — browser adapters: an opt-in localStorage session store
+ * and LiveKit call media (peer dependency `livekit-client`).
+ */
+import type { SessionStore } from "./session.cjs";
+export { memoryStore } from "./session.cjs";
+export { joinCallRoom, type JoinOptions, type MediaCall, type MediaJoin } from "./livekit.cjs";
+export interface LocalStorageStoreOptions {
+    /** Default "hainiva.agent.session". */
+    key?: string;
+    /** Default globalThis.localStorage. */
+    storage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+/**
+ * OPT-IN: keep the session in localStorage so a reload stays signed in.
+ *
+ * ⚠ Any script running on your origin (an XSS, a compromised third-party script)
+ * can read localStorage — including the 30-day refresh token. Use it only with a
+ * strict Content-Security-Policy and no third-party scripts on the page. The
+ * default (memoryStore) keeps nothing: a reload signs in again with a fresh
+ * assertion from your backend, which is the safer choice.
+ */
+export declare function localStorageStore(o?: LocalStorageStoreOptions): SessionStore;