@hainiva/agent-sdk 0.0.0-stage → 0.2.0

package/dist/cjs/rest.cjs

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRestClient = void 0;
+exports.newIdempotencyKey = newIdempotencyKey;
+exports.errorFromResponse = errorFromResponse;
+const errors_js_1 = require("./errors.cjs");
+const log_js_1 = require("./log.cjs");
+const redact_js_1 = require("./redact.cjs");
+const url_js_1 = require("./url.cjs");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TENANT = /^[A-Za-z0-9_-]{1,64}$/;
+/** A random UUID v4: crypto.randomUUID where it exists (browsers, Node), else getRandomValues, else Math.random (Idempotency-Key only, not a secret). */
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    const b = new Uint8Array(16);
+    if (c?.getRandomValues)
+        c.getRandomValues(b);
+    else
+        for (let i = 0; i < 16; i++)
+            b[i] = Math.floor(Math.random() * 256);
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+/** An id that goes into a path: a UUID, or the request is refused before it leaves (no path tricks). */
+function id(v, what) {
+    if (typeof v !== "string" || !UUID.test(v))
+        throw new errors_js_1.HainivaAgentError(0, "invalid_id", { field: what });
+    return v.toLowerCase();
+}
+function isObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/** Pure: the error a non-2xx answer becomes. Exported for tests. */
+function errorFromResponse(status, data, redactor, retryAfter) {
+    const e = isObject(data) ? data["error"] : undefined;
+    let code = status === 401 ? "unauthorized" : status === 403 ? "forbidden" : status === 404 ? "not_found" : status === 409 ? "conflict" : status === 429 ? "rate_limited" : status >= 500 ? "server_error" : "invalid_request";
+    let message;
+    if (isObject(e)) {
+        if (typeof e["code"] === "string" && e["code"])
+            code = e["code"].slice(0, 80);
+        if (typeof e["message"] === "string")
+            message = e["message"].slice(0, 500);
+    }
+    else if (typeof e === "string") {
+        message = e.slice(0, 500);
+    }
+    const body = {};
+    if (message)
+        body["message"] = message;
+    if (retryAfter && /^\d{1,6}$/.test(retryAfter))
+        body["retryAfterSec"] = Number(retryAfter);
+    return new errors_js_1.HainivaAgentError(status, code, body, redactor);
+}
+/**
+ * The Agent API over fetch. `tokens` is normally the SessionManager; the
+ * client's own `sessions` transport is what that SessionManager signs in with.
+ */
+class AgentRestClient {
+    constructor(o, tokens) {
+        this.o = o;
+        // ── Sessions (the SessionManager's transport) ───────────────────────────────
+        this.sessions = {
+            exchange: (assertion) => this.raw("POST", "/agent/v1/sessions", {
+                body: { tenantId: this.o.tenantId, assertion, ...(this.o.device ? { device: this.o.device } : {}) },
+            }, null).then((s) => s),
+            refresh: (refreshToken) => this.raw("POST", "/agent/v1/sessions/refresh", {
+                body: { tenantId: this.o.tenantId, refreshToken },
+            }, null).then((s) => s),
+            revoke: async (session) => {
+                await this.raw("DELETE", "/agent/v1/sessions/current", {}, session.accessToken);
+            },
+        };
+        const u = (0, url_js_1.assertSafeUrl)(o.baseUrl, { kind: "http", ...(o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}) });
+        if (u.search || u.hash)
+            throw new errors_js_1.HainivaAgentError(0, "invalid_url", { hint: "baseUrl takes no query or fragment" });
+        if (typeof o.tenantId !== "string" || !TENANT.test(o.tenantId))
+            throw new errors_js_1.HainivaAgentError(0, "invalid_tenant_id");
+        this.baseUrl = u.origin + u.pathname.replace(/\/+$/, "");
+        const f = o.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new errors_js_1.HainivaAgentError(0, "no_fetch", { hint: "pass options.fetch" });
+        this.fetchFn = f.bind(globalThis);
+        this.timeoutMs = o.timeoutMs ?? 15000;
+        this.redactor = o.redactor ?? new redact_js_1.Redactor();
+        this.log = (0, log_js_1.safeLogger)(o.log, this.redactor);
+        this.tokens = tokens ?? null;
+    }
+    /** Attach the token source after construction (the SessionManager needs `sessions` first). */
+    useTokens(tokens) { this.tokens = tokens; }
+    /** The wss:// URL of the event stream, derived from baseUrl (never from a server answer). */
+    get wsUrl() {
+        return `${this.baseUrl.replace(/^http/, "ws")}/agent/v1/ws`;
+    }
+    // ── The generic request ─────────────────────────────────────────────────────
+    /** An authenticated request: refresh-and-retry once on an expired token. */
+    async request(method, path, opts = {}) {
+        if (!this.tokens)
+            throw new errors_js_1.HainivaAgentError(0, "not_signed_in");
+        const idem = method === "POST" ? newIdempotencyKey() : undefined;
+        const token = await this.tokens.accessToken();
+        try {
+            return await this.raw(method, path, opts, token, idem);
+        }
+        catch (e) {
+            if (!(e instanceof errors_js_1.HainivaAgentError) || e.status !== 401 || (e.code !== "token_expired" && e.code !== "token_invalid"))
+                throw e;
+            this.log("access_token_refused", { code: e.code });
+            this.tokens.invalidate(token);
+            const next = await this.tokens.accessToken();
+            return this.raw(method, path, opts, next, idem);
+        }
+    }
+    async raw(method, path, opts, token, idem) {
+        let url = `${this.baseUrl}${path}`;
+        if (opts.query) {
+            const q = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.query))
+                if (v !== undefined && v !== "")
+                    q.set(k, String(v));
+            const s = q.toString();
+            if (s)
+                url += `?${s}`;
+        }
+        const headers = { accept: "application/json" };
+        if (token) {
+            this.redactor.add(token);
+            headers["authorization"] = `Bearer ${token}`;
+        }
+        if (idem)
+            headers["idempotency-key"] = idem;
+        let body;
+        if (opts.body !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        const ctl = new AbortController();
+        const timeout = opts.timeoutMs ?? this.timeoutMs;
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; ctl.abort(); }, timeout);
+        const onAbort = () => ctl.abort();
+        if (opts.signal) {
+            if (opts.signal.aborted) {
+                clearTimeout(timer);
+                throw new errors_js_1.HainivaAgentError(0, "aborted");
+            }
+            opts.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        let res;
+        try {
+            res = await this.fetchFn(url, { method, headers, ...(body !== undefined ? { body } : {}), signal: ctl.signal });
+        }
+        catch (e) {
+            if (timedOut)
+                throw new errors_js_1.HainivaAgentError(0, "timeout", { timeoutMs: timeout });
+            if (opts.signal?.aborted)
+                throw new errors_js_1.HainivaAgentError(0, "aborted");
+            throw errors_js_1.HainivaAgentError.from(e, "network_error", this.redactor);
+        }
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+        }
+        if (res.status === 204)
+            return undefined;
+        let data = null;
+        const text = await res.text().catch(() => "");
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = null;
+            }
+        }
+        if (!res.ok)
+            throw errorFromResponse(res.status, data, this.redactor, res.headers?.get?.("retry-after") ?? null);
+        if (data === null || typeof data !== "object")
+            throw new errors_js_1.HainivaAgentError(res.status, "invalid_response", {}, this.redactor);
+        return data;
+    }
+    // ── Me ──────────────────────────────────────────────────────────────────────
+    async me(o) { return this.request("GET", "/agent/v1/me", o); }
+    async setStatus(status, o) {
+        return this.request("PUT", "/agent/v1/me/status", { ...o, body: { status } });
+    }
+    /** Rings for this member now (after a cold start, a missed push or a resync). */
+    async pendingRings(o) {
+        const r = await this.request("GET", "/agent/v1/rings/pending", o);
+        return Array.isArray(r.data) ? r.data : [];
+    }
+    // ── Calls ───────────────────────────────────────────────────────────────────
+    async getCall(callId, o) { return this.request("GET", `/agent/v1/calls/${id(callId, "callId")}`, o); }
+    async acceptCall(callId, o) { return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/accept`, { ...o, body: {} }); }
+    async declineCall(callId, o) { return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/decline`, { ...o, body: {} }); }
+    async endCall(callId, o) { return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/end`, { ...o, body: {} }); }
+    async holdCall(callId, on, o) {
+        return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/hold`, { ...o, body: { on } });
+    }
+    async transferCall(callId, target, o) {
+        let body;
+        if ("agentId" in target)
+            body = { targetAgentId: id(target.agentId, "agentId"), mode: target.mode ?? "warm" };
+        else if ("queueId" in target)
+            body = { queueId: id(target.queueId, "queueId") };
+        else
+            body = { number: target.number, mode: target.mode ?? "warm" };
+        return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/transfer`, { ...o, body });
+    }
+    /** Re-mint the LiveKit token while still a participant (reconnect, token near expiry). */
+    async mediaToken(callId, o) { return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/media-token`, { ...o, body: {} }); }
+    // ── Wrap-up ─────────────────────────────────────────────────────────────────
+    async dispositions(channel, o) {
+        const r = await this.request("GET", "/agent/v1/dispositions", { ...o, ...(channel ? { query: { channel } } : {}) });
+        return Array.isArray(r.data) ? r.data : [];
+    }
+    async wrapUp(callId, w = {}, o) {
+        return this.request("POST", `/agent/v1/calls/${id(callId, "callId")}/wrapup`, { ...o, body: w });
+    }
+    // ── Conversations and messages ──────────────────────────────────────────────
+    async listConversations(q = {}, o) {
+        return this.request("GET", "/agent/v1/conversations", { ...o, query: { scope: q.scope, status: q.status, cursor: q.cursor, limit: q.limit } }).then((page));
+    }
+    async getConversation(conversationId, o) {
+        return this.request("GET", `/agent/v1/conversations/${id(conversationId, "conversationId")}`, o);
+    }
+    /** Claim it (no agentId), or — a supervisor — assign it to a colleague. */
+    async assignConversation(conversationId, agentId, o) {
+        return this.request("POST", `/agent/v1/conversations/${id(conversationId, "conversationId")}/assign`, { ...o, body: agentId ? { agentId: id(agentId, "agentId") } : {} });
+    }
+    async releaseConversation(conversationId, note, o) {
+        return this.request("POST", `/agent/v1/conversations/${id(conversationId, "conversationId")}/release`, { ...o, body: note ? { note } : {} });
+    }
+    async transferConversation(conversationId, to, o) {
+        const body = "agentId" in to ? { agentId: id(to.agentId, "agentId") } : { queueId: id(to.queueId, "queueId"), ...(to.note ? { note: to.note } : {}) };
+        return this.request("POST", `/agent/v1/conversations/${id(conversationId, "conversationId")}/transfer`, { ...o, body });
+    }
+    async closeConversation(conversationId, o) {
+        return this.request("POST", `/agent/v1/conversations/${id(conversationId, "conversationId")}/close`, { ...o, body: {} });
+    }
+    async listMessages(conversationId, q = {}, o) {
+        return this.request("GET", `/agent/v1/conversations/${id(conversationId, "conversationId")}/messages`, { ...o, query: { after: q.after, limit: q.limit } }).then((page));
+    }
+    async sendMessage(conversationId, text, o) {
+        return this.request("POST", `/agent/v1/conversations/${id(conversationId, "conversationId")}/messages`, { ...o, body: { text } });
+    }
+    async typing(conversationId, o) {
+        return this.request("POST", `/agent/v1/conversations/${id(conversationId, "conversationId")}/typing`, { ...o, body: {} });
+    }
+    // ── Supervisor ──────────────────────────────────────────────────────────────
+    async liveCalls(o) {
+        const r = await this.request("GET", "/agent/v1/supervisor/live-calls", o);
+        return Array.isArray(r.data) ? r.data : [];
+    }
+    async teamAgents(o) {
+        const r = await this.request("GET", "/agent/v1/supervisor/agents", o);
+        return Array.isArray(r.data) ? r.data : [];
+    }
+    async supervise(callId, mode = "monitor", o) {
+        return this.request("POST", `/agent/v1/supervisor/calls/${id(callId, "callId")}/supervise`, { ...o, body: { mode } });
+    }
+    async setSuperviseMode(callId, mode, supervisorTrackSid, o) {
+        return this.request("PUT", `/agent/v1/supervisor/calls/${id(callId, "callId")}/supervise-mode`, { ...o, body: { mode, ...(supervisorTrackSid ? { supervisorTrackSid } : {}) } });
+    }
+    // ── Push (your app's own FCM / APNs credentials, uploaded by your admin) ─────
+    async registerPush(sub, o) {
+        return this.request("POST", "/agent/v1/push/subscriptions", { ...o, body: sub });
+    }
+    async unregisterPush(token, o) {
+        await this.request("DELETE", "/agent/v1/push/subscriptions", { ...o, body: { token } });
+    }
+}
+exports.AgentRestClient = AgentRestClient;
+function page(r) {
+    const x = isObject(r) ? r : {};
+    return { data: Array.isArray(x["data"]) ? x["data"] : [], nextCursor: typeof x["nextCursor"] === "string" ? x["nextCursor"] : null };
+}

package/dist/cjs/rest.d.cts

@@ -0,0 +1,166 @@
+/**
+ * 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, 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;
+    }>;
+    /** 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;