@kibee/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,465 @@
+import { AnalyticsEvent, BridgeEventType, BridgeEnvelope, RegisteredTarget, FlowDefinition, IntentMatch, TargetRef as TargetRef$1, StartSessionRequest, SessionState, ResolveIntentRequest, RecoveryRequest, RecoveryResponse, TrackEventRequest, VisitorPollResponse, FlowCommand, VisibleTarget, SurfaceId } from '@kibee/contracts';
+import { BeeRenderer } from '@kibee/renderer-three';
+
+type BookmarkKind = "honey" | "sting";
+interface FlowBeeBookmark {
+    id: string;
+    kind: BookmarkKind;
+    label: string;
+    note?: string;
+    pageUrl: string;
+    pageTitle: string;
+    target: {
+        kibeeId?: string;
+        beeId?: string;
+        selector?: string;
+        textHints?: string[];
+    };
+    /** Auto-captured positional/DOM context (see captureContext.ts) plus any
+     *  extra fields the caller wants to attach. Backend uses this for clustering. */
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateBookmarkInput {
+    kind: BookmarkKind;
+    label: string;
+    note?: string;
+    target: {
+        kibeeId?: string;
+        beeId?: string;
+        selector?: string;
+        textHints?: string[];
+    };
+    metadata?: Record<string, unknown>;
+}
+declare class BookmarkMemory {
+    private storageKey;
+    list(): FlowBeeBookmark[];
+    create(input: CreateBookmarkInput): FlowBeeBookmark;
+    update(id: string, patch: Partial<Pick<FlowBeeBookmark, "label" | "note">>): FlowBeeBookmark | null;
+    remove(id: string): void;
+    findByPage(url?: string): FlowBeeBookmark[];
+    private read;
+    private write;
+    private generateId;
+}
+
+interface KiBeeClientOptions {
+    apiBaseUrl?: string;
+    websiteId?: string;
+    publicKey?: string;
+    /** @deprecated alias for publicKey, removed in v1.0 */
+    apiKey?: string;
+    renderer: BeeRenderer;
+    mountContainer?: HTMLElement;
+    onEvent?: (event: AnalyticsEvent) => void;
+    /**
+     * Stable visitor id when the host cannot rely on normal page `localStorage`
+     * (e.g. Chrome extensions). When omitted, an id is created and stored under
+     * `kibee:visitor_id` in `localStorage` when available.
+     */
+    visitorId?: string;
+    /**
+     * When true, the client constructs a BridgeClient and connects to /v1/bridge.
+     * Requires `apiToken` (a kibee-api JWT) to fetch a bridge token. Default false.
+     */
+    useBridge?: boolean;
+    /**
+     * kibee-api JWT used to authenticate the POST /v1/bridge/token call.
+     * Required when `useBridge` is true. The host page is responsible for
+     * obtaining this token (via Auth0 sign-in flow on the web side).
+     */
+    apiToken?: string;
+}
+declare class KiBeeClient {
+    private options;
+    private api;
+    private locator;
+    private highlight;
+    private bookmarks;
+    private registry;
+    private controller;
+    private initPromise;
+    private mountContainer?;
+    private currentPageId;
+    private currentSession;
+    private currentFlowId;
+    private adminSyncTimer;
+    /** Polling cadence when SSE is unavailable / closed — the visitor
+     *  experience depends on this for new admin messages, so it stays
+     *  tight (5s default; afforestation passes 2.5s). */
+    private fastPollInterval;
+    /** Cadence when SSE is healthy. Polling becomes a heartbeat — it only
+     *  needs to catch state SSE doesn't push (friction score, pending
+     *  pushes) and recover any messages we somehow missed. */
+    private readonly slowPollInterval;
+    private presenceSessionPromise;
+    /** EventSource subscription for the per-session visitor stream. */
+    private visitorStream;
+    /** Last-seen message timestamp for the polling fallback `?since=`. */
+    private lastVisitorMessageAt;
+    /** Set of message ids the SDK has emitted to the panel — dedupes when a
+     *  message arrives via SSE *and* a subsequent poll. */
+    private seenMessageIds;
+    /** Distress signals tracker. Reset on a high-confidence resolve so the
+     *  bee doesn't nag if the visitor recovers on their own. */
+    private consecutiveLowConfidence;
+    private lastDistressPromptAt;
+    /** Current chat mode mirrored from the server. The panel reads this to
+     *  hide the "talk to a human" chip when an agent is on. */
+    private chatMode;
+    /** Mirror of whether the host's chat panel is currently visible. The
+     *  panel dispatches kibee-panel-open / -close — we listen so we can
+     *  decide whether to surface an inbound admin message as a bee tooltip
+     *  (panel closed → speak it so the visitor notices) or stay quiet
+     *  (panel open → the thread already shows it; tooltip would dupe). */
+    private panelOpen;
+    /** S3 T5: optional cross-surface bridge client. Initialized only when
+     *  `useBridge: true` AND `apiToken` are passed at construction. */
+    private bridgeClient?;
+    /** S4 T4: unsubscribes for handlers registered against `bridgeClient`. Drained
+     *  in `destroy()` so we don't leave dangling handlers if a host swaps clients. */
+    private bridgeUnsubscribes;
+    /** S4 T4: in-flight `flow:handoff` flowIds. Guards against the same flow being
+     *  started twice if duplicate envelopes arrive (e.g. retried publish). */
+    private inflightHandoffFlowIds;
+    /** S4 T7: mirrors whether another surface (extension/desktop) is currently
+     *  holding the listening floor (announced via `voice:state` over the bridge).
+     *  The SDK has no built-in voice listening UI today — voice is host-implemented
+     *  — so this is exposed as a flag + a `kibee-voice-state` CustomEvent that hosts
+     *  can subscribe to in order to suppress their own listening indicator. */
+    private otherSurfaceListening;
+    readonly visitorId: string;
+    constructor(options: KiBeeClientOptions);
+    /**
+     * Connects to the cross-surface bridge (`/v1/bridge`). No-op when
+     * `useBridge` was false or `apiToken` was missing at construction.
+     */
+    connectBridge(): Promise<void>;
+    /**
+     * Register a handler for inbound bridge envelopes of a specific type.
+     * Returns an unsubscribe function. No-op (returns a noop unsubscribe)
+     * when the bridge isn't initialized.
+     */
+    onBridgeEvent(type: BridgeEventType, handler: (envelope: BridgeEnvelope) => void): () => void;
+    /**
+     * S4 T6: ask another surface (typically `desktop`) to point its on-screen
+     * bee at a global screen coordinate. No-op when the bridge isn't wired
+     * (`useBridge: false` or `apiToken` missing) — the caller doesn't need
+     * to feature-detect.
+     *
+     * `tenantId`, `workspaceId`, and `visitorId` set here are advisory: the
+     * broker overwrites identity fields with JWT-derived values on receipt
+     * (S2 T2 invariant). `source: "web"` is hardcoded because the SDK ships
+     * web-only by default; the broker also enforces source against the
+     * value bound at WS handshake.
+     */
+    requestPointTo(coord: {
+        x: number;
+        y: number;
+        screenIndex: number;
+    }): Promise<void>;
+    init(): Promise<void>;
+    identifyPage(pageId: string, metadata?: Record<string, unknown>): void;
+    registerTargets(targets: RegisteredTarget[]): void;
+    getRegisteredTargets(): RegisteredTarget[];
+    runFlow(flowOrId: string | FlowDefinition): Promise<FlowDefinition>;
+    /**
+     * Run a flow in interactive step-through mode: the bee tooltip shows
+     * prev / next buttons so the user controls the pace instead of
+     * auto-advancing on click/input events.
+     */
+    runInteractiveFlow(flowOrId: string | FlowDefinition): Promise<FlowDefinition>;
+    ask(input: string): Promise<IntentMatch>;
+    /**
+     * Visitor-facing chat send. Wraps `ask()` so the rule-matched answer
+     * still drives flows when intent is clear, but ALSO:
+     *   - emits a `kibee-message-received` event for each customer + ai
+     *     message so the panel renders them as bubbles even before the SSE
+     *     stream catches up
+     *   - tracks distress signals (low confidence streaks, "human"
+     *     keywords) and dispatches `kibee-distress-detected` so the panel
+     *     can surface the inline "want a teammate?" prompt
+     */
+    send(input: string): Promise<void>;
+    /**
+     * Visitor-initiated escalation. Called by the panel's "Talk to a human"
+     * chip and by the inline distress prompt's "Yes please" button.
+     */
+    escalateToHuman(): Promise<void>;
+    /**
+     * Surface an incoming agent / AI message as a bee speech bubble when the
+     * panel is closed, so a passive visitor sees that someone replied. The
+     * panel-open path stays quiet because the panel thread already shows the
+     * message — speaking would dupe it.
+     *
+     * Skipped for `customer` (the visitor's own echoed message) and `system`
+     * (admin annotations like "Sahil joined the conversation" — visible only
+     * inside the panel).
+     */
+    private maybeSpeakIncomingMessage;
+    private shouldShowDistressPrompt;
+    private dispatchDistressPrompt;
+    private requestHumanFromKeyword;
+    saveHoney(label: string, target: TargetRef$1, note?: string): Promise<FlowBeeBookmark | null>;
+    saveSting(label: string, target: TargetRef$1, note?: string): Promise<FlowBeeBookmark | null>;
+    listBookmarks(): FlowBeeBookmark[];
+    removeBookmark(id: string): void;
+    revisitBookmark(bookmark: FlowBeeBookmark): Promise<void>;
+    clearFocus(): void;
+    /**
+     * When true, the dock button toggles the in-app assistant (kibee-assist-toggle)
+     * instead of immediately undocking the bee.
+     */
+    setDockAssistPanel(enabled: boolean): void;
+    track(type: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Returns the dock's current screen position (center of the dock button) */
+    getDockPosition(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Polls the API for admin-pushed flows/targets AND drains new chat
+     * messages on the same tick. Also opens the per-session visitor SSE
+     * stream so messages arrive in real time when the network supports it
+     * (polling stays as a guaranteed-delivery backstop).
+     *
+     * Call after init() and startSession() to enable admin push support.
+     *
+     * Cadence is SSE-aware: when the visitor stream is OPEN (realtime is
+     * delivering messages), polling backs off to a 30s heartbeat — just
+     * enough to catch state the SSE channel can't push (e.g. friction
+     * score, drained pending pushes). On SSE error/close the interval
+     * snaps back to `intervalMs` so polling carries the load until SSE
+     * reconnects.
+     *
+     * The single `/v1/visitor/sync` endpoint returns messages + pending
+     * pushes + mode + friction in one round-trip, so each tick is one
+     * request instead of two.
+     */
+    enableAdminSync(intervalMs?: number): void;
+    disableAdminSync(): void;
+    /** (Re)arm the polling interval based on current SSE health. Called
+     *  whenever SSE state changes (open / error) so the interval reflects
+     *  reality without dropping a tick. */
+    private armSyncTimer;
+    /**
+     * Single visitor poll. Drains pending flow pushes (admin → SDK) AND
+     * sucks in new chat messages in one HTTP request. Always runs alongside
+     * SSE so a missed event during network blips eventually shows up;
+     * `seenMessageIds` dedupes anything SSE already delivered.
+     */
+    private pollVisitorSync;
+    private handleVisitorPoll;
+    private openVisitorStream;
+    destroy(): void;
+    /**
+     * S4 T4: run a flow handed off via the bridge. Wraps `runFlow(flowId)` with
+     * an in-flight guard so duplicate `flow:handoff` envelopes for the same
+     * flowId (e.g. retried publish) don't start two concurrent runs.
+     */
+    private runFlowFromHandoff;
+    private startSession;
+    /**
+     * Creates a server session once the page is known so admin "Visitors" and
+     * analytics can attach to a real `sessionId` (not only when a flow runs).
+     */
+    private ensurePresenceSession;
+}
+
+/** /v1/visitor/sync — unified poll envelope. Drains pending pushes as it
+ *  reads messages so the SDK doesn't have to round-trip twice per tick. */
+interface VisitorSyncResponse extends VisitorPollResponse {
+    pendingPushes: Array<{
+        flowId?: string;
+        targets?: TargetRef$1[];
+    }>;
+}
+interface KiBeeApiClientOptions {
+    websiteId?: string;
+    publicKey?: string;
+    /** @deprecated legacy x-kibee-key header — replaced by websiteId + publicKey */
+    legacyApiKey?: string;
+}
+declare class KiBeeApiClient {
+    private baseUrl;
+    private options;
+    constructor(baseUrl: string, options?: KiBeeApiClientOptions);
+    fetchFlow(id: string): Promise<FlowDefinition>;
+    startSession(input: StartSessionRequest): Promise<SessionState>;
+    resolveIntent(input: ResolveIntentRequest): Promise<IntentMatch>;
+    resolveRecovery(input: RecoveryRequest): Promise<RecoveryResponse>;
+    trackEvent(event: TrackEventRequest): Promise<void>;
+    /**
+     * Unified visitor poll. One round-trip pulls messages + pending pushes
+     * + mode + friction. Replaces the previous fetchVisitorMessages +
+     * /admin/sessions/:id/pending pair for visitors using publishable-key
+     * auth. The legacy fetchVisitorMessages remains for shipped SDK
+     * builds that haven't been updated yet.
+     */
+    fetchVisitorSync(sessionId: string, since: string | null): Promise<VisitorSyncResponse>;
+    /**
+     * Legacy split poll — kept for backward compat. Prefer fetchVisitorSync.
+     */
+    fetchVisitorMessages(sessionId: string, since: string | null): Promise<VisitorPollResponse>;
+    /**
+     * Visitor (or distress detector) requests a human. Sets
+     * `requested_human_at`, generates an AI summary for the agent, and lights
+     * up the "Needs help" badge in admin Hive.
+     */
+    escalateToHuman(sessionId: string): Promise<void>;
+    /**
+     * Open the visitor's per-session SSE stream. EventSource can't pass auth
+     * headers, so the publishable key + websiteId ride along as query params.
+     * Caller wires `onmessage` and is responsible for re-opening on disconnect.
+     *
+     * Returns null when EventSource isn't available (older browsers / strict
+     * proxies) — caller falls back to polling `fetchVisitorMessages`.
+     */
+    openVisitorStream(sessionId: string): EventSource | null;
+    private buildHeaders;
+    private request;
+}
+
+interface TargetRef {
+    kibeeId?: string;
+    beeId?: string;
+    selector?: string;
+    textHints?: string[];
+}
+interface ResolvedTarget {
+    element: HTMLElement;
+    rect: DOMRect;
+    centerX: number;
+    centerY: number;
+}
+declare class Locator {
+    resolve(target: TargetRef): ResolvedTarget | null;
+    findElement(target: TargetRef): HTMLElement | null;
+    scrollIntoView(target: TargetRef, behavior?: ScrollBehavior): void;
+    private getSearchableText;
+}
+
+type HighlightVariant = "pulse" | "ring" | "soft";
+declare class HighlightRenderer {
+    private el;
+    mount(container?: HTMLElement): void;
+    show(rect: DOMRect, variant?: HighlightVariant): void;
+    hide(): void;
+    destroy(): void;
+}
+
+interface FlowExecutionHook {
+    (command: FlowCommand, phase: "started" | "completed" | "missing_target"): void;
+}
+declare class FlowController {
+    private bee;
+    private locator;
+    private highlight;
+    private bookmarks;
+    private onCommand?;
+    constructor(bee: BeeRenderer, locator: Locator, highlight: HighlightRenderer, bookmarks?: BookmarkMemory, onCommand?: FlowExecutionHook | undefined);
+    init(): Promise<void>;
+    runFlow(flow: FlowDefinition): Promise<void>;
+    /**
+     * Interactive step-through mode: bee flies to each `fly_to` step and shows
+     * prev / next buttons in the tooltip so the user controls the pace.
+     */
+    runInteractiveFlow(flow: FlowDefinition): Promise<void>;
+    clearFocus(): void;
+    createHoneyBookmark(label: string, target: TargetRef$1, note?: string): Promise<FlowBeeBookmark | null>;
+    createStingBookmark(label: string, target: TargetRef$1, note?: string): Promise<FlowBeeBookmark | null>;
+    listBookmarks(): FlowBeeBookmark[];
+    getPageBookmarks(): FlowBeeBookmark[];
+    revisitBookmark(bookmark: FlowBeeBookmark): Promise<void>;
+    removeBookmark(id: string): void;
+    private execute;
+    private createBookmark;
+    private guideTo;
+    private waitForClick;
+    private waitForInput;
+    private delay;
+    private resolveGuidePlacement;
+    private pickGuideSide;
+    private resolveTopRightBeeOffset;
+    /** Area of intersection of two axis-aligned rectangles (px²). */
+    private rectOverlapArea;
+    /**
+     * Place the speech bubble with a healthy gap from the bee and pick left-vs-right
+     * by scoring overlap with the bee body and the highlighted target.
+     */
+    private resolveTooltipPosition;
+    private notifyMissingTarget;
+    private finishAndDock;
+    /** Like finishAndDock but without docking — bee stays wherever it landed. */
+    private finishInPlace;
+}
+
+declare class TargetRegistry {
+    private targets;
+    set(targets: RegisteredTarget[]): void;
+    list(): RegisteredTarget[];
+    getVisibleTargets(doc?: Document): VisibleTarget[];
+}
+
+interface BridgeClientOptions {
+    bridgeUrl: string;
+    source: SurfaceId;
+    visitorId: string;
+    tokenFetcher: () => Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+}
+interface ReconnectOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    capDelayMs?: number;
+}
+type BridgeClientState = "disconnected" | "connecting" | "connected" | "failed";
+type Handler = (envelope: BridgeEnvelope) => void;
+/**
+ * Browser-side WebSocket client for the cross-surface bridge.
+ *
+ * Lifecycle (S3 — no auto-reconnect; that's S4 hardening):
+ * 1. `connect()` — fetches a bridge token via `tokenFetcher`, opens WS.
+ * 2. On open, sends `presence:hello` to bind the source server-side.
+ * 3. Inbound envelopes are validated via `isBridgeEnvelope` and dispatched
+ *    to handlers registered via `on(type, handler)`.
+ * 4. `close()` — sends `presence:bye`, closes the WS.
+ *
+ * Identity overwrite happens server-side at the broker (per S1 T3 review).
+ * The client supplies `visitorId` only for envelope construction; the broker
+ * trusts the JWT.
+ */
+declare class BridgeClient {
+    private ws;
+    private handlers;
+    private opts;
+    state: BridgeClientState;
+    private heartbeatTimer?;
+    private lastPongAt;
+    constructor(opts: BridgeClientOptions);
+    on(eventType: BridgeEventType, handler: Handler): () => void;
+    connect(): Promise<void>;
+    private startHeartbeat;
+    private markDegraded;
+    send(envelope: BridgeEnvelope): void;
+    close(): void;
+    /**
+     * Wraps `connect()` with exponential backoff. Defaults: 10 attempts,
+     * 1s base, 30s cap (delays: 1s, 2s, 4s, 8s, 16s, 30s, 30s, ...). Adds
+     * 0–20% jitter per attempt.
+     *
+     * On success, `state` is `connected` and the method resolves.
+     * After `maxAttempts` failures, `state` is `failed` and the last error
+     * is re-thrown.
+     *
+     * `connect()` itself remains a single-attempt method so existing callers
+     * are unaffected.
+     */
+    connectWithReconnect(opts?: ReconnectOptions): Promise<void>;
+}
+
+export { type BookmarkKind, BookmarkMemory, BridgeClient, type BridgeClientOptions, type CreateBookmarkInput, type FlowBeeBookmark, FlowController, type FlowExecutionHook, HighlightRenderer, type HighlightVariant, KiBeeApiClient, type KiBeeApiClientOptions, KiBeeClient, type KiBeeClientOptions, Locator, type ResolvedTarget, type TargetRef, TargetRegistry, type VisitorSyncResponse };