@kibee/contracts 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,588 @@
+/**
+ * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
+ * (broker) and Track B (macOS) leads.
+ *
+ * Spec: docs/superpowers/specs/2026-04-28-bee-mesh-sprint-plan-design.md
+ *       Section 2 (Architecture — mesh of bees), Section 3 (Source-of-truth
+ *       contracts).
+ *
+ * Mirrored to Swift in apps/macos-kibee (Sprint 1 T5/T7 — BridgeEnvelope
+ * Swift port lands in Sprint 4 convergence).
+ *
+ * Wire-stable note: the string raw values for `SurfaceId` and
+ * `BridgeEventType` (e.g. "presence:hello") are part of the wire format.
+ * Do not rename or re-shape them in the Swift mirror — they must JSON-encode
+ * to the exact same strings.
+ */
+/**
+ * Surfaces that participate in the bee mesh. Every BridgeEnvelope declares
+ * its source and target by surface id.
+ */
+type SurfaceId = "web" | "extension" | "desktop";
+/**
+ * The frozen event-type union for the cross-surface bus. Adding a new event
+ * type after Sprint 1 requires joint sign-off from both track leads.
+ */
+type BridgeEventType = "presence:hello" | "presence:bye" | "flow:handoff" | "flow:resume" | "pointer:show" | "memory:share" | "voice:state" | "capture:promote" | "tenant:attach" | "tenant:detach";
+/**
+ * The wire format for every cross-surface message. `tenantId` is `null`
+ * when the surface is in personal mode (not attached to a workspace).
+ */
+interface BridgeEnvelope<T = unknown> {
+    /** Protocol version. Bump on any breaking change. */
+    v: 1;
+    source: SurfaceId;
+    /** A specific surface or "broadcast" to all subscribers in the same scope. */
+    target: SurfaceId | "broadcast";
+    /** Null in personal mode; required for tenant-attached and admin-attached modes. */
+    tenantId: string | null;
+    workspaceId: string | null;
+    /** Stable across surfaces for the same visitor. Drives the fan-out scope. */
+    visitorId: string;
+    sessionId: string | null;
+    type: BridgeEventType;
+    /** Wall-clock millis at emit. */
+    ts: number;
+    payload: T;
+}
+/**
+ * Type guard usable at runtime when receiving an envelope from the wire.
+ * Validates every field strictly — unknown surface ids, unknown event types,
+ * missing fields, or arrays are all rejected. Use at the trust boundary
+ * (broker, SDK receive handler, Swift port) before treating data as a
+ * `BridgeEnvelope`.
+ */
+declare function isBridgeEnvelope(value: unknown): value is BridgeEnvelope;
+/**
+ * Claims extracted from the bridge JWT after `authenticateBridgeUpgrade`
+ * succeeds. Shared between the broker and the route to keep the trust
+ * boundary consistent.
+ */
+interface BridgeClaims {
+    visitorId: string;
+    tenantId: string | null;
+    workspaceId: string | null;
+}
+
+/**
+ * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
+ * (broker) and Track B (macOS) leads.
+ *
+ * Spec: docs/superpowers/specs/2026-04-28-bee-mesh-sprint-plan-design.md
+ *       Section 3 (Source-of-truth contracts).
+ *
+ * Mirrored to Swift in apps/macos-kibee/Sources/KiBee/BeeBuddyState.swift
+ * (Sprint 1 T5). The Swift `allowedTransitions` table must match
+ * BUDDY_TRANSITIONS below exactly.
+ */
+/**
+ * The macOS Buddy state machine. Frozen end of Sprint 1 — additions require
+ * joint sign-off from both track leads.
+ *
+ * Transition table (15 transitions, including cancel/escape paths to ambient):
+ *
+ *   ambient    → listening    (voice hotkey)
+ *   ambient    → actionRing   (hover 400ms over bee)
+ *
+ *   listening  → thinking     (transcript finalized)
+ *   listening  → ambient      (cancel / hotkey released / silence timeout)
+ *
+ *   thinking   → speaking     (Claude responds)
+ *   thinking   → ambient      (cancel / response error)
+ *
+ *   speaking   → pointing     (POINT tag parsed)
+ *   speaking   → followUp     (TTS finishes, no point tag)
+ *   speaking   → ambient      (cancel / TTS interrupted)
+ *
+ *   pointing   → followUp     (TTS finishes after point)
+ *   pointing   → ambient      (cancel / target lost)
+ *
+ *   followUp   → ambient      (silence timeout)
+ *   followUp   → listening    (auto re-listen)
+ *
+ *   actionRing → ambient      (mouse leaves bee region)
+ *   actionRing → listening    (tap mic icon)
+ *
+ * Self-transitions are not allowed. The Swift mirror in
+ * apps/macos-kibee/Sources/KiBee/BeeBuddyState.swift uses the same table.
+ */
+type BuddyState = "ambient" | "listening" | "thinking" | "speaking" | "pointing" | "followUp" | "actionRing";
+/**
+ * Allowed transitions, expressed as `from → to[]`. Used by tests and by the
+ * Swift state machine to reject illegal transitions.
+ */
+declare const BUDDY_TRANSITIONS: Record<BuddyState, BuddyState[]>;
+declare function canTransition(from: BuddyState, to: BuddyState): boolean;
+
+/**
+ * Frozen Sprint 2 contract. Edits require joint sign-off.
+ *
+ * Spec: docs/superpowers/specs/2026-04-28-bee-mesh-sprint-plan-design.md
+ *       Section 4 Sprint 2 row.
+ *
+ * The macOS Buddy calls `GET /v1/identity` after Auth0 sign-in to obtain
+ * the canonical visitor record. Web SDK gets the same `visitorId` from
+ * the existing visitor cookie path (no contract change there).
+ */
+/**
+ * The canonical visitor identity returned to any surface authenticating
+ * a real human. Stable for the lifetime of the user account.
+ *
+ * Note: structurally identical to `BridgeClaims` (bridge.ts) by design —
+ * same shape, different trust boundaries (HTTP response vs JWT claims).
+ * Do not unify; their lifecycles diverge in S3+.
+ */
+interface VisitorIdentity {
+    /** Stable identifier for the authenticated user across all surfaces. */
+    visitorId: string;
+    /**
+     * Same value as `workspaceId` today (workspaces ARE tenants in the
+     * current schema). Kept as a separate field so the two can diverge
+     * without a contract break in future sprints.
+     */
+    tenantId: string | null;
+    /**
+     * For users with multiple workspace memberships, this is the OLDEST
+     * by `createdAt`. Workspace switching is a future feature (Sprint 6+
+     * tenant attachment). `null` means the user is in personal mode.
+     */
+    workspaceId: string | null;
+}
+/**
+ * Optional payload on `GET /v1/identity` (sent in body for first-time
+ * users only — typically the macOS app on first launch). Web surfaces
+ * never send this since they already have a visitor cookie.
+ */
+interface IdentityRequest {
+    contactHint?: {
+        email?: string;
+        auth0Sub?: string;
+    };
+}
+/**
+ * Response envelope. `issuedAt` lets clients age out the local cache.
+ */
+interface IdentityResponse {
+    identity: VisitorIdentity;
+    /** Wall-clock millis at issue (matches BridgeEnvelope.ts convention). */
+    issuedAt: number;
+}
+
+type HighlightVariant = "pulse" | "ring" | "soft";
+interface TargetRef {
+    kibeeId?: string;
+    selector?: string;
+    textHints?: string[];
+    /**
+     * Legacy compatibility for older prototypes.
+     */
+    beeId?: string;
+}
+interface RegisteredTarget {
+    id: string;
+    label: string;
+    target: TargetRef;
+    description?: string;
+    phrases?: string[];
+}
+interface VisibleTarget extends RegisteredTarget {
+    matchedText?: string;
+}
+interface FlowMoveOptions {
+    duration?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+type FlowCommand = {
+    type: "fly_to";
+    target: TargetRef;
+    message?: string;
+    highlight?: HighlightVariant;
+    moveTo?: FlowMoveOptions;
+} | {
+    type: "highlight";
+    target: TargetRef;
+    variant?: HighlightVariant;
+} | {
+    type: "wait_for_click";
+    target: TargetRef;
+    timeoutMs?: number;
+} | {
+    type: "wait_for_input";
+    target: TargetRef;
+    timeoutMs?: number;
+} | {
+    type: "speak";
+    message: string;
+} | {
+    type: "celebrate";
+    message?: string;
+} | {
+    type: "end_flow";
+    status: "completed" | "abandoned";
+    message?: string;
+};
+interface FlowDefinition {
+    id: string;
+    title: string;
+    pageId: string;
+    goal: string;
+    audience?: string;
+    introMessage?: string;
+    phrases?: string[];
+    steps: FlowCommand[];
+    /**
+     * Optional cross-site continuation steps executed by the extension on external pages.
+     * Each step targets a page the SaaS does not control (e.g. stripe.com, meta.com).
+     */
+    crossSiteSteps?: CrossSiteFlowStep[];
+    /**
+     * External hostnames this flow may navigate to.
+     * Must be a subset of the tenant's allowedExternalHosts.
+     */
+    externalHosts?: string[];
+    /**
+     * The surface this flow is pinned to. Drives cross-surface `flow:handoff`
+     * routing — if the visitor's current surface != `surface` (and `surface`
+     * is not "both"), the broker emits a handoff so the other surface's bee
+     * can pick the flow up. Defaults to `"web"` at the DB layer.
+     */
+    surface?: "web" | "desktop" | "both";
+}
+interface SessionState {
+    id: string;
+    visitorId: string;
+    pageId: string;
+    flowId?: string;
+    currentStepIndex: number;
+    status: "idle" | "active" | "completed" | "abandoned";
+    startedAt: string;
+    updatedAt: string;
+    /** Present when session is linked to a CRM contact (e.g. admin session detail). */
+    contactId?: string | null;
+}
+interface IntentMatch {
+    flowId: string | null;
+    confidence: number;
+    message: string;
+    /**
+     * Surface the matched flow is pinned to, or undefined when no flow matched.
+     * Used by the route to decide whether to emit a `flow:handoff` envelope on
+     * the bridge. The literal union mirrors `FlowDefinition.surface` — the
+     * runtime emitter still tolerates unknown strings (it no-ops outside this
+     * union), but the type narrowing prevents accidental writes of values like
+     * `"mobile"` or `"extension"` typechecking silently.
+     */
+    flowSurface?: "web" | "desktop" | "both";
+    /** Present only in dev/debug mode — stripped before client delivery in production. */
+    _debug?: {
+        flowScore: number;
+        journeyScore: number;
+        pageCtxScore: number;
+        frictionPenalty: number;
+        fusedScore: number;
+        tier: "high" | "medium" | "low" | "none";
+        method: "fusion" | "phrase" | "none";
+    };
+}
+/**
+ * Discriminated union of known event metadata shapes.
+ * The catch-all `Record<string, unknown>` arm preserves forward-compatibility
+ * for unknown event types — all existing callers that pass untyped objects
+ * remain valid.
+ */
+type EventMetadata = {
+    eventType: "page_identified";
+    title?: string;
+    url?: string;
+    referrer?: string;
+} | {
+    eventType: "element_clicked";
+    kibeeId?: string;
+    selector?: string;
+    label?: string;
+    /** X / Y relative to viewport as 0–1 fractions */
+    relX?: number;
+    relY?: number;
+} | {
+    eventType: "scroll_depth";
+    /** 0–1 fraction of page scrolled when threshold was crossed */
+    depth: number;
+    /** Milliseconds since page load when the threshold was first crossed */
+    dwellMs: number;
+} | {
+    eventType: "bee_dismissed";
+    flowId?: string;
+    stepIndex?: number;
+    reason?: "manual" | "timeout" | "page_nav";
+} | {
+    eventType: "flow_step_completed";
+    flowId: string;
+    stepIndex: number;
+    dwellMs?: number;
+} | {
+    eventType: "intent_submitted";
+    input: string;
+    resolvedFlowId?: string;
+    confidence?: number;
+} | {
+    eventType: "pairing_started";
+    /** Public tenant ID of the SaaS that initiated pairing */
+    tenantPublicId: string;
+    /** Hostname of the SaaS page where pairing was established */
+    originHost: string;
+    /** Shared session ID adopted for the pairing */
+    sessionId: string;
+} | {
+    eventType: "pairing_ended";
+    reason: "tab_closed" | "tab_navigated" | "ttl_expired" | "user_request" | "session_expired";
+    /** Number of cross-site steps completed before pairing ended */
+    stepsCompleted: number;
+} | {
+    eventType: "cross_site_step_completed";
+    /** Hostname where the step was executed, e.g. "stripe.com" */
+    externalHost: string;
+    stepIndex: number;
+    flowId: string;
+    dwellMs?: number;
+} | Record<string, unknown>;
+interface AnalyticsEvent {
+    type: string;
+    pageId: string;
+    timestamp: string;
+    visitorId?: string;
+    sessionId?: string;
+    flowId?: string;
+    targetId?: string;
+    metadata?: EventMetadata;
+}
+interface StartSessionRequest {
+    visitorId: string;
+    pageId: string;
+    flowId?: string;
+}
+interface ResolveIntentRequest {
+    input: string;
+    pageId: string;
+    visibleTargets: VisibleTarget[];
+    /** Optional: passed through to inference_outcomes for outcome tracking */
+    sessionId?: string;
+    /**
+     * Optional: stable visitor identifier shared across surfaces. Required for
+     * cross-surface `flow:handoff` emission. When omitted, no handoff is emitted
+     * (back-compat with older SDKs that haven't been updated for Sprint 4).
+     */
+    visitorId?: string;
+    /**
+     * Optional: the surface the request originated from ("web" | "desktop" |
+     * "extension"). Required for cross-surface `flow:handoff` emission. When
+     * omitted, no handoff is emitted.
+     */
+    currentSource?: "web" | "desktop" | "extension";
+}
+interface RecoveryRequest {
+    pageId: string;
+    target: TargetRef;
+    visibleTargets: VisibleTarget[];
+}
+interface RecoveryResponse {
+    target: TargetRef | null;
+    confidence: number;
+    message: string;
+}
+interface TrackEventRequest {
+    event: AnalyticsEvent;
+}
+type DockPositionPreset = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+interface DockInlineAnchor {
+    /** CSS selector or HTMLElement for the container to render inside */
+    container: string | HTMLElement;
+    /** Alignment within container */
+    align?: "left" | "center" | "right";
+}
+type DockPositionConfig = DockPositionPreset | {
+    preset: DockPositionPreset;
+    offsetX?: number;
+    offsetY?: number;
+} | {
+    custom: {
+        x: number;
+        y: number;
+    };
+} | {
+    inline: DockInlineAnchor;
+};
+interface AdminSessionSummary {
+    id: string;
+    pageId: string;
+    flowId?: string;
+    status: SessionState["status"];
+    startedAt: string;
+    updatedAt: string;
+    eventCount: number;
+}
+/** Who produced a message in the chat thread.
+ *  - `customer`: visitor's own input (echoed in their panel, primary in admin)
+ *  - `agent`: human support agent
+ *  - `ai`: KiBee bee's freeform reply (Claude Haiku) or matched flow message
+ *  - `system`: thread-level annotation (escalations, take-overs, releases)
+ */
+type ChatSender = "agent" | "customer" | "ai" | "system";
+/** Whether the conversation is currently driven by the AI or a human agent.
+ *  Set per-session; flips on take-over / release. The visitor SDK uses this
+ *  to hide its "talk to a human" chip when an agent is already on. */
+type ChatMode = "ai" | "human";
+interface ChatMessage {
+    id: string;
+    sessionId: string;
+    sender: ChatSender;
+    text: string;
+    timestamp: string;
+}
+interface VisitorPollResponse {
+    messages: ChatMessage[];
+    mode: ChatMode;
+    /** True when an agent has taken over (assigned_agent_id IS NOT NULL). */
+    hasAgent: boolean;
+    /** Page-level friction score (0-100), used by the SDK to surface the
+     *  proactive "want a guided tour?" prompt. */
+    frictionScore: number;
+    /** The session's last_message_at — clients echo it back as `?since=` on
+     *  the next poll. */
+    lastMessageAt: string | null;
+}
+interface MessageTemplate {
+    id: string;
+    label: string;
+    body: string;
+    kind: "greeting" | "ack" | "handoff" | "custom";
+    createdAt: string;
+    updatedAt: string;
+}
+interface PushFlowRequest {
+    flowId: string;
+    /** Optional cross-site continuation steps, executed by the extension on external pages */
+    crossSiteSteps?: CrossSiteFlowStep[];
+}
+/**
+ * A flow step that executes on an external page not controlled by the SaaS.
+ * Must use textHints only — kibeeId and selector are unavailable on third-party pages.
+ */
+interface CrossSiteFlowStep {
+    /** Hostname the step executes on, e.g. "stripe.com" */
+    externalHost: string;
+    /** Path glob pattern, e.g. "/dashboard/apikeys*" — matches any path if absent */
+    pathPattern?: string;
+    /** Message shown to user before they navigate to the external page */
+    navigationMessage?: string;
+    /** The flow command to execute. Target must use textHints only. */
+    command: {
+        type: FlowCommand["type"];
+        message?: string;
+        /** textHints only — kibeeId and selector are disallowed for cross-site steps */
+        target?: {
+            textHints: string[];
+        };
+        timeoutMs?: number;
+        status?: "completed" | "abandoned";
+        variant?: HighlightVariant;
+    };
+}
+/** An item in the cross-site flow queue delivered to the extension via polling */
+interface CrossSiteFlowQueueItem {
+    flowId: string;
+    flowTitle: string;
+    crossSiteSteps: CrossSiteFlowStep[];
+    /** Unix ms — item expires if not picked up by the extension */
+    expiresAt: number;
+}
+/** Sent by the extension content script to the embedded SDK page to initiate pairing */
+interface KiBeePairRequest {
+    type: "KIBEE_PAIR_REQUEST";
+    /** chrome.runtime.id of the extension */
+    extensionId: string;
+    /** Manifest version string of the extension */
+    version: string;
+}
+/** Sent by the embedded SDK back to the extension content script to accept pairing */
+interface KiBeePairAccept {
+    type: "KIBEE_PAIR_ACCEPT";
+    /** Public tenant identifier (same as websiteId) */
+    tenantPublicId: string;
+    /**
+     * The SaaS session ID — extension adopts this for all subordinate API calls.
+     * Analytics for both surfaces land in one session timeline.
+     */
+    sessionId: string;
+    /** Domains the extension may activate on in subordinate mode, server-enforced by the API */
+    allowedExternalHosts: string[];
+    /** Pre-queued cross-site flows to execute on allowed external hosts */
+    flowQueue: CrossSiteFlowQueueItem[];
+    /** Pairing validity window in milliseconds, e.g. 1_800_000 (30 min) */
+    ttlMs: number;
+    /**
+     * Short-lived server-issued credential for the extension to authenticate
+     * subordinate polling requests. Scoped to this session only.
+     */
+    pairingToken: string;
+}
+/** Sent by the extension content script to the embedded SDK to reject pairing */
+interface KiBeePairReject {
+    type: "KIBEE_PAIR_REJECT";
+    reason: string;
+}
+/**
+ * Pairing state persisted in chrome.storage.local under key "kibee_pairing".
+ * Cleared on unpair. extensionVisitorId is NEVER overwritten by pairing.
+ */
+interface PairingState {
+    tenantPublicId: string;
+    /** The SaaS session ID shared for this pairing — used for all subordinate API calls */
+    sessionId: string;
+    /** Hostname of the SaaS page where the handshake started, e.g. "acme.com" */
+    originHostname: string;
+    /** Chrome tab ID where the handshake started — monitored for close/navigate-away */
+    originTabId: number;
+    /** Domains the extension may operate on in subordinate mode */
+    allowedExternalHosts: string[];
+    /** Cross-site flow steps cached from the last poll response */
+    flowQueue: CrossSiteFlowQueueItem[];
+    /** Short-lived token for authenticating subordinate polling requests */
+    pairingToken: string;
+    /** Unix ms when pairing was established */
+    pairedAt: number;
+    /** How long the pairing is valid in milliseconds */
+    ttlMs: number;
+    /**
+     * Index of the cross-site flow step currently executing.
+     * null = idle (no step in progress).
+     * Used to decide immediate vs deferred unpair when origin tab closes.
+     */
+    activeFlowStepIndex: number | null;
+    /**
+     * Set to true when origin tab closes while a step is in progress.
+     * Content script detects this after step completion and clears pairing.
+     */
+    pendingUnpair: boolean;
+    /**
+     * The extension's own permanent visitor ID.
+     * Preserved independently of pairing — NEVER replaced by the SaaS visitor ID.
+     * Used for event attribution even in subordinate mode.
+     */
+    extensionVisitorId: string;
+}
+interface PushTargetsRequest {
+    targets: TargetRef[];
+    highlight?: HighlightVariant;
+}
+interface WidgetConfig {
+    position: DockPositionConfig;
+    size: number;
+    theme: {
+        primary: string;
+        tooltipBg: string;
+        tooltipColor: string;
+    };
+}
+
+export { type AdminSessionSummary, type AnalyticsEvent, BUDDY_TRANSITIONS, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MessageTemplate, type PairingState, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type SessionState, type StartSessionRequest, type SurfaceId, type TargetRef, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, type WidgetConfig, canTransition, isBridgeEnvelope };

package/dist/index.d.ts

@@ -0,0 +1,588 @@
+/**
+ * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
+ * (broker) and Track B (macOS) leads.
+ *
+ * Spec: docs/superpowers/specs/2026-04-28-bee-mesh-sprint-plan-design.md
+ *       Section 2 (Architecture — mesh of bees), Section 3 (Source-of-truth
+ *       contracts).
+ *
+ * Mirrored to Swift in apps/macos-kibee (Sprint 1 T5/T7 — BridgeEnvelope
+ * Swift port lands in Sprint 4 convergence).
+ *
+ * Wire-stable note: the string raw values for `SurfaceId` and
+ * `BridgeEventType` (e.g. "presence:hello") are part of the wire format.
+ * Do not rename or re-shape them in the Swift mirror — they must JSON-encode
+ * to the exact same strings.
+ */
+/**
+ * Surfaces that participate in the bee mesh. Every BridgeEnvelope declares
+ * its source and target by surface id.
+ */
+type SurfaceId = "web" | "extension" | "desktop";
+/**
+ * The frozen event-type union for the cross-surface bus. Adding a new event
+ * type after Sprint 1 requires joint sign-off from both track leads.
+ */
+type BridgeEventType = "presence:hello" | "presence:bye" | "flow:handoff" | "flow:resume" | "pointer:show" | "memory:share" | "voice:state" | "capture:promote" | "tenant:attach" | "tenant:detach";
+/**
+ * The wire format for every cross-surface message. `tenantId` is `null`
+ * when the surface is in personal mode (not attached to a workspace).
+ */
+interface BridgeEnvelope<T = unknown> {
+    /** Protocol version. Bump on any breaking change. */
+    v: 1;
+    source: SurfaceId;
+    /** A specific surface or "broadcast" to all subscribers in the same scope. */
+    target: SurfaceId | "broadcast";
+    /** Null in personal mode; required for tenant-attached and admin-attached modes. */
+    tenantId: string | null;
+    workspaceId: string | null;
+    /** Stable across surfaces for the same visitor. Drives the fan-out scope. */
+    visitorId: string;
+    sessionId: string | null;
+    type: BridgeEventType;
+    /** Wall-clock millis at emit. */
+    ts: number;
+    payload: T;
+}
+/**
+ * Type guard usable at runtime when receiving an envelope from the wire.
+ * Validates every field strictly — unknown surface ids, unknown event types,
+ * missing fields, or arrays are all rejected. Use at the trust boundary
+ * (broker, SDK receive handler, Swift port) before treating data as a
+ * `BridgeEnvelope`.
+ */
+declare function isBridgeEnvelope(value: unknown): value is BridgeEnvelope;
+/**
+ * Claims extracted from the bridge JWT after `authenticateBridgeUpgrade`
+ * succeeds. Shared between the broker and the route to keep the trust
+ * boundary consistent.
+ */
+interface BridgeClaims {
+    visitorId: string;
+    tenantId: string | null;
+    workspaceId: string | null;
+}
+
+/**
+ * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
+ * (broker) and Track B (macOS) leads.
+ *
+ * Spec: docs/superpowers/specs/2026-04-28-bee-mesh-sprint-plan-design.md
+ *       Section 3 (Source-of-truth contracts).
+ *
+ * Mirrored to Swift in apps/macos-kibee/Sources/KiBee/BeeBuddyState.swift
+ * (Sprint 1 T5). The Swift `allowedTransitions` table must match
+ * BUDDY_TRANSITIONS below exactly.
+ */
+/**
+ * The macOS Buddy state machine. Frozen end of Sprint 1 — additions require
+ * joint sign-off from both track leads.
+ *
+ * Transition table (15 transitions, including cancel/escape paths to ambient):
+ *
+ *   ambient    → listening    (voice hotkey)
+ *   ambient    → actionRing   (hover 400ms over bee)
+ *
+ *   listening  → thinking     (transcript finalized)
+ *   listening  → ambient      (cancel / hotkey released / silence timeout)
+ *
+ *   thinking   → speaking     (Claude responds)
+ *   thinking   → ambient      (cancel / response error)
+ *
+ *   speaking   → pointing     (POINT tag parsed)
+ *   speaking   → followUp     (TTS finishes, no point tag)
+ *   speaking   → ambient      (cancel / TTS interrupted)
+ *
+ *   pointing   → followUp     (TTS finishes after point)
+ *   pointing   → ambient      (cancel / target lost)
+ *
+ *   followUp   → ambient      (silence timeout)
+ *   followUp   → listening    (auto re-listen)
+ *
+ *   actionRing → ambient      (mouse leaves bee region)
+ *   actionRing → listening    (tap mic icon)
+ *
+ * Self-transitions are not allowed. The Swift mirror in
+ * apps/macos-kibee/Sources/KiBee/BeeBuddyState.swift uses the same table.
+ */
+type BuddyState = "ambient" | "listening" | "thinking" | "speaking" | "pointing" | "followUp" | "actionRing";
+/**
+ * Allowed transitions, expressed as `from → to[]`. Used by tests and by the
+ * Swift state machine to reject illegal transitions.
+ */
+declare const BUDDY_TRANSITIONS: Record<BuddyState, BuddyState[]>;
+declare function canTransition(from: BuddyState, to: BuddyState): boolean;
+
+/**
+ * Frozen Sprint 2 contract. Edits require joint sign-off.
+ *
+ * Spec: docs/superpowers/specs/2026-04-28-bee-mesh-sprint-plan-design.md
+ *       Section 4 Sprint 2 row.
+ *
+ * The macOS Buddy calls `GET /v1/identity` after Auth0 sign-in to obtain
+ * the canonical visitor record. Web SDK gets the same `visitorId` from
+ * the existing visitor cookie path (no contract change there).
+ */
+/**
+ * The canonical visitor identity returned to any surface authenticating
+ * a real human. Stable for the lifetime of the user account.
+ *
+ * Note: structurally identical to `BridgeClaims` (bridge.ts) by design —
+ * same shape, different trust boundaries (HTTP response vs JWT claims).
+ * Do not unify; their lifecycles diverge in S3+.
+ */
+interface VisitorIdentity {
+    /** Stable identifier for the authenticated user across all surfaces. */
+    visitorId: string;
+    /**
+     * Same value as `workspaceId` today (workspaces ARE tenants in the
+     * current schema). Kept as a separate field so the two can diverge
+     * without a contract break in future sprints.
+     */
+    tenantId: string | null;
+    /**
+     * For users with multiple workspace memberships, this is the OLDEST
+     * by `createdAt`. Workspace switching is a future feature (Sprint 6+
+     * tenant attachment). `null` means the user is in personal mode.
+     */
+    workspaceId: string | null;
+}
+/**
+ * Optional payload on `GET /v1/identity` (sent in body for first-time
+ * users only — typically the macOS app on first launch). Web surfaces
+ * never send this since they already have a visitor cookie.
+ */
+interface IdentityRequest {
+    contactHint?: {
+        email?: string;
+        auth0Sub?: string;
+    };
+}
+/**
+ * Response envelope. `issuedAt` lets clients age out the local cache.
+ */
+interface IdentityResponse {
+    identity: VisitorIdentity;
+    /** Wall-clock millis at issue (matches BridgeEnvelope.ts convention). */
+    issuedAt: number;
+}
+
+type HighlightVariant = "pulse" | "ring" | "soft";
+interface TargetRef {
+    kibeeId?: string;
+    selector?: string;
+    textHints?: string[];
+    /**
+     * Legacy compatibility for older prototypes.
+     */
+    beeId?: string;
+}
+interface RegisteredTarget {
+    id: string;
+    label: string;
+    target: TargetRef;
+    description?: string;
+    phrases?: string[];
+}
+interface VisibleTarget extends RegisteredTarget {
+    matchedText?: string;
+}
+interface FlowMoveOptions {
+    duration?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+type FlowCommand = {
+    type: "fly_to";
+    target: TargetRef;
+    message?: string;
+    highlight?: HighlightVariant;
+    moveTo?: FlowMoveOptions;
+} | {
+    type: "highlight";
+    target: TargetRef;
+    variant?: HighlightVariant;
+} | {
+    type: "wait_for_click";
+    target: TargetRef;
+    timeoutMs?: number;
+} | {
+    type: "wait_for_input";
+    target: TargetRef;
+    timeoutMs?: number;
+} | {
+    type: "speak";
+    message: string;
+} | {
+    type: "celebrate";
+    message?: string;
+} | {
+    type: "end_flow";
+    status: "completed" | "abandoned";
+    message?: string;
+};
+interface FlowDefinition {
+    id: string;
+    title: string;
+    pageId: string;
+    goal: string;
+    audience?: string;
+    introMessage?: string;
+    phrases?: string[];
+    steps: FlowCommand[];
+    /**
+     * Optional cross-site continuation steps executed by the extension on external pages.
+     * Each step targets a page the SaaS does not control (e.g. stripe.com, meta.com).
+     */
+    crossSiteSteps?: CrossSiteFlowStep[];
+    /**
+     * External hostnames this flow may navigate to.
+     * Must be a subset of the tenant's allowedExternalHosts.
+     */
+    externalHosts?: string[];
+    /**
+     * The surface this flow is pinned to. Drives cross-surface `flow:handoff`
+     * routing — if the visitor's current surface != `surface` (and `surface`
+     * is not "both"), the broker emits a handoff so the other surface's bee
+     * can pick the flow up. Defaults to `"web"` at the DB layer.
+     */
+    surface?: "web" | "desktop" | "both";
+}
+interface SessionState {
+    id: string;
+    visitorId: string;
+    pageId: string;
+    flowId?: string;
+    currentStepIndex: number;
+    status: "idle" | "active" | "completed" | "abandoned";
+    startedAt: string;
+    updatedAt: string;
+    /** Present when session is linked to a CRM contact (e.g. admin session detail). */
+    contactId?: string | null;
+}
+interface IntentMatch {
+    flowId: string | null;
+    confidence: number;
+    message: string;
+    /**
+     * Surface the matched flow is pinned to, or undefined when no flow matched.
+     * Used by the route to decide whether to emit a `flow:handoff` envelope on
+     * the bridge. The literal union mirrors `FlowDefinition.surface` — the
+     * runtime emitter still tolerates unknown strings (it no-ops outside this
+     * union), but the type narrowing prevents accidental writes of values like
+     * `"mobile"` or `"extension"` typechecking silently.
+     */
+    flowSurface?: "web" | "desktop" | "both";
+    /** Present only in dev/debug mode — stripped before client delivery in production. */
+    _debug?: {
+        flowScore: number;
+        journeyScore: number;
+        pageCtxScore: number;
+        frictionPenalty: number;
+        fusedScore: number;
+        tier: "high" | "medium" | "low" | "none";
+        method: "fusion" | "phrase" | "none";
+    };
+}
+/**
+ * Discriminated union of known event metadata shapes.
+ * The catch-all `Record<string, unknown>` arm preserves forward-compatibility
+ * for unknown event types — all existing callers that pass untyped objects
+ * remain valid.
+ */
+type EventMetadata = {
+    eventType: "page_identified";
+    title?: string;
+    url?: string;
+    referrer?: string;
+} | {
+    eventType: "element_clicked";
+    kibeeId?: string;
+    selector?: string;
+    label?: string;
+    /** X / Y relative to viewport as 0–1 fractions */
+    relX?: number;
+    relY?: number;
+} | {
+    eventType: "scroll_depth";
+    /** 0–1 fraction of page scrolled when threshold was crossed */
+    depth: number;
+    /** Milliseconds since page load when the threshold was first crossed */
+    dwellMs: number;
+} | {
+    eventType: "bee_dismissed";
+    flowId?: string;
+    stepIndex?: number;
+    reason?: "manual" | "timeout" | "page_nav";
+} | {
+    eventType: "flow_step_completed";
+    flowId: string;
+    stepIndex: number;
+    dwellMs?: number;
+} | {
+    eventType: "intent_submitted";
+    input: string;
+    resolvedFlowId?: string;
+    confidence?: number;
+} | {
+    eventType: "pairing_started";
+    /** Public tenant ID of the SaaS that initiated pairing */
+    tenantPublicId: string;
+    /** Hostname of the SaaS page where pairing was established */
+    originHost: string;
+    /** Shared session ID adopted for the pairing */
+    sessionId: string;
+} | {
+    eventType: "pairing_ended";
+    reason: "tab_closed" | "tab_navigated" | "ttl_expired" | "user_request" | "session_expired";
+    /** Number of cross-site steps completed before pairing ended */
+    stepsCompleted: number;
+} | {
+    eventType: "cross_site_step_completed";
+    /** Hostname where the step was executed, e.g. "stripe.com" */
+    externalHost: string;
+    stepIndex: number;
+    flowId: string;
+    dwellMs?: number;
+} | Record<string, unknown>;
+interface AnalyticsEvent {
+    type: string;
+    pageId: string;
+    timestamp: string;
+    visitorId?: string;
+    sessionId?: string;
+    flowId?: string;
+    targetId?: string;
+    metadata?: EventMetadata;
+}
+interface StartSessionRequest {
+    visitorId: string;
+    pageId: string;
+    flowId?: string;
+}
+interface ResolveIntentRequest {
+    input: string;
+    pageId: string;
+    visibleTargets: VisibleTarget[];
+    /** Optional: passed through to inference_outcomes for outcome tracking */
+    sessionId?: string;
+    /**
+     * Optional: stable visitor identifier shared across surfaces. Required for
+     * cross-surface `flow:handoff` emission. When omitted, no handoff is emitted
+     * (back-compat with older SDKs that haven't been updated for Sprint 4).
+     */
+    visitorId?: string;
+    /**
+     * Optional: the surface the request originated from ("web" | "desktop" |
+     * "extension"). Required for cross-surface `flow:handoff` emission. When
+     * omitted, no handoff is emitted.
+     */
+    currentSource?: "web" | "desktop" | "extension";
+}
+interface RecoveryRequest {
+    pageId: string;
+    target: TargetRef;
+    visibleTargets: VisibleTarget[];
+}
+interface RecoveryResponse {
+    target: TargetRef | null;
+    confidence: number;
+    message: string;
+}
+interface TrackEventRequest {
+    event: AnalyticsEvent;
+}
+type DockPositionPreset = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+interface DockInlineAnchor {
+    /** CSS selector or HTMLElement for the container to render inside */
+    container: string | HTMLElement;
+    /** Alignment within container */
+    align?: "left" | "center" | "right";
+}
+type DockPositionConfig = DockPositionPreset | {
+    preset: DockPositionPreset;
+    offsetX?: number;
+    offsetY?: number;
+} | {
+    custom: {
+        x: number;
+        y: number;
+    };
+} | {
+    inline: DockInlineAnchor;
+};
+interface AdminSessionSummary {
+    id: string;
+    pageId: string;
+    flowId?: string;
+    status: SessionState["status"];
+    startedAt: string;
+    updatedAt: string;
+    eventCount: number;
+}
+/** Who produced a message in the chat thread.
+ *  - `customer`: visitor's own input (echoed in their panel, primary in admin)
+ *  - `agent`: human support agent
+ *  - `ai`: KiBee bee's freeform reply (Claude Haiku) or matched flow message
+ *  - `system`: thread-level annotation (escalations, take-overs, releases)
+ */
+type ChatSender = "agent" | "customer" | "ai" | "system";
+/** Whether the conversation is currently driven by the AI or a human agent.
+ *  Set per-session; flips on take-over / release. The visitor SDK uses this
+ *  to hide its "talk to a human" chip when an agent is already on. */
+type ChatMode = "ai" | "human";
+interface ChatMessage {
+    id: string;
+    sessionId: string;
+    sender: ChatSender;
+    text: string;
+    timestamp: string;
+}
+interface VisitorPollResponse {
+    messages: ChatMessage[];
+    mode: ChatMode;
+    /** True when an agent has taken over (assigned_agent_id IS NOT NULL). */
+    hasAgent: boolean;
+    /** Page-level friction score (0-100), used by the SDK to surface the
+     *  proactive "want a guided tour?" prompt. */
+    frictionScore: number;
+    /** The session's last_message_at — clients echo it back as `?since=` on
+     *  the next poll. */
+    lastMessageAt: string | null;
+}
+interface MessageTemplate {
+    id: string;
+    label: string;
+    body: string;
+    kind: "greeting" | "ack" | "handoff" | "custom";
+    createdAt: string;
+    updatedAt: string;
+}
+interface PushFlowRequest {
+    flowId: string;
+    /** Optional cross-site continuation steps, executed by the extension on external pages */
+    crossSiteSteps?: CrossSiteFlowStep[];
+}
+/**
+ * A flow step that executes on an external page not controlled by the SaaS.
+ * Must use textHints only — kibeeId and selector are unavailable on third-party pages.
+ */
+interface CrossSiteFlowStep {
+    /** Hostname the step executes on, e.g. "stripe.com" */
+    externalHost: string;
+    /** Path glob pattern, e.g. "/dashboard/apikeys*" — matches any path if absent */
+    pathPattern?: string;
+    /** Message shown to user before they navigate to the external page */
+    navigationMessage?: string;
+    /** The flow command to execute. Target must use textHints only. */
+    command: {
+        type: FlowCommand["type"];
+        message?: string;
+        /** textHints only — kibeeId and selector are disallowed for cross-site steps */
+        target?: {
+            textHints: string[];
+        };
+        timeoutMs?: number;
+        status?: "completed" | "abandoned";
+        variant?: HighlightVariant;
+    };
+}
+/** An item in the cross-site flow queue delivered to the extension via polling */
+interface CrossSiteFlowQueueItem {
+    flowId: string;
+    flowTitle: string;
+    crossSiteSteps: CrossSiteFlowStep[];
+    /** Unix ms — item expires if not picked up by the extension */
+    expiresAt: number;
+}
+/** Sent by the extension content script to the embedded SDK page to initiate pairing */
+interface KiBeePairRequest {
+    type: "KIBEE_PAIR_REQUEST";
+    /** chrome.runtime.id of the extension */
+    extensionId: string;
+    /** Manifest version string of the extension */
+    version: string;
+}
+/** Sent by the embedded SDK back to the extension content script to accept pairing */
+interface KiBeePairAccept {
+    type: "KIBEE_PAIR_ACCEPT";
+    /** Public tenant identifier (same as websiteId) */
+    tenantPublicId: string;
+    /**
+     * The SaaS session ID — extension adopts this for all subordinate API calls.
+     * Analytics for both surfaces land in one session timeline.
+     */
+    sessionId: string;
+    /** Domains the extension may activate on in subordinate mode, server-enforced by the API */
+    allowedExternalHosts: string[];
+    /** Pre-queued cross-site flows to execute on allowed external hosts */
+    flowQueue: CrossSiteFlowQueueItem[];
+    /** Pairing validity window in milliseconds, e.g. 1_800_000 (30 min) */
+    ttlMs: number;
+    /**
+     * Short-lived server-issued credential for the extension to authenticate
+     * subordinate polling requests. Scoped to this session only.
+     */
+    pairingToken: string;
+}
+/** Sent by the extension content script to the embedded SDK to reject pairing */
+interface KiBeePairReject {
+    type: "KIBEE_PAIR_REJECT";
+    reason: string;
+}
+/**
+ * Pairing state persisted in chrome.storage.local under key "kibee_pairing".
+ * Cleared on unpair. extensionVisitorId is NEVER overwritten by pairing.
+ */
+interface PairingState {
+    tenantPublicId: string;
+    /** The SaaS session ID shared for this pairing — used for all subordinate API calls */
+    sessionId: string;
+    /** Hostname of the SaaS page where the handshake started, e.g. "acme.com" */
+    originHostname: string;
+    /** Chrome tab ID where the handshake started — monitored for close/navigate-away */
+    originTabId: number;
+    /** Domains the extension may operate on in subordinate mode */
+    allowedExternalHosts: string[];
+    /** Cross-site flow steps cached from the last poll response */
+    flowQueue: CrossSiteFlowQueueItem[];
+    /** Short-lived token for authenticating subordinate polling requests */
+    pairingToken: string;
+    /** Unix ms when pairing was established */
+    pairedAt: number;
+    /** How long the pairing is valid in milliseconds */
+    ttlMs: number;
+    /**
+     * Index of the cross-site flow step currently executing.
+     * null = idle (no step in progress).
+     * Used to decide immediate vs deferred unpair when origin tab closes.
+     */
+    activeFlowStepIndex: number | null;
+    /**
+     * Set to true when origin tab closes while a step is in progress.
+     * Content script detects this after step completion and clears pairing.
+     */
+    pendingUnpair: boolean;
+    /**
+     * The extension's own permanent visitor ID.
+     * Preserved independently of pairing — NEVER replaced by the SaaS visitor ID.
+     * Used for event attribution even in subordinate mode.
+     */
+    extensionVisitorId: string;
+}
+interface PushTargetsRequest {
+    targets: TargetRef[];
+    highlight?: HighlightVariant;
+}
+interface WidgetConfig {
+    position: DockPositionConfig;
+    size: number;
+    theme: {
+        primary: string;
+        tooltipBg: string;
+        tooltipColor: string;
+    };
+}
+
+export { type AdminSessionSummary, type AnalyticsEvent, BUDDY_TRANSITIONS, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MessageTemplate, type PairingState, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type SessionState, type StartSessionRequest, type SurfaceId, type TargetRef, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, type WidgetConfig, canTransition, isBridgeEnvelope };

package/dist/index.js

@@ -0,0 +1,76 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BUDDY_TRANSITIONS: () => BUDDY_TRANSITIONS,
+  canTransition: () => canTransition,
+  isBridgeEnvelope: () => isBridgeEnvelope
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/bridge.ts
+var SURFACE_IDS = /* @__PURE__ */ new Set(["web", "extension", "desktop"]);
+var BRIDGE_TARGETS = /* @__PURE__ */ new Set([
+  "web",
+  "extension",
+  "desktop",
+  "broadcast"
+]);
+var BRIDGE_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "presence:hello",
+  "presence:bye",
+  "flow:handoff",
+  "flow:resume",
+  "pointer:show",
+  "memory:share",
+  "voice:state",
+  "capture:promote",
+  "tenant:attach",
+  "tenant:detach"
+]);
+function isBridgeEnvelope(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const e = value;
+  const isStringOrNull = (v) => v === null || typeof v === "string";
+  return e.v === 1 && typeof e.source === "string" && SURFACE_IDS.has(e.source) && typeof e.target === "string" && BRIDGE_TARGETS.has(e.target) && isStringOrNull(e.tenantId) && isStringOrNull(e.workspaceId) && typeof e.visitorId === "string" && isStringOrNull(e.sessionId) && typeof e.type === "string" && BRIDGE_EVENT_TYPES.has(e.type) && typeof e.ts === "number" && Number.isFinite(e.ts) && "payload" in e;
+}
+
+// src/buddy.ts
+var BUDDY_TRANSITIONS = {
+  ambient: ["listening", "actionRing"],
+  listening: ["thinking", "ambient"],
+  thinking: ["speaking", "ambient"],
+  speaking: ["pointing", "followUp", "ambient"],
+  pointing: ["followUp", "ambient"],
+  followUp: ["ambient", "listening"],
+  actionRing: ["ambient", "listening"]
+};
+function canTransition(from, to) {
+  return BUDDY_TRANSITIONS[from].includes(to);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BUDDY_TRANSITIONS,
+  canTransition,
+  isBridgeEnvelope
+});

package/dist/index.mjs

@@ -0,0 +1,47 @@
+// src/bridge.ts
+var SURFACE_IDS = /* @__PURE__ */ new Set(["web", "extension", "desktop"]);
+var BRIDGE_TARGETS = /* @__PURE__ */ new Set([
+  "web",
+  "extension",
+  "desktop",
+  "broadcast"
+]);
+var BRIDGE_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "presence:hello",
+  "presence:bye",
+  "flow:handoff",
+  "flow:resume",
+  "pointer:show",
+  "memory:share",
+  "voice:state",
+  "capture:promote",
+  "tenant:attach",
+  "tenant:detach"
+]);
+function isBridgeEnvelope(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const e = value;
+  const isStringOrNull = (v) => v === null || typeof v === "string";
+  return e.v === 1 && typeof e.source === "string" && SURFACE_IDS.has(e.source) && typeof e.target === "string" && BRIDGE_TARGETS.has(e.target) && isStringOrNull(e.tenantId) && isStringOrNull(e.workspaceId) && typeof e.visitorId === "string" && isStringOrNull(e.sessionId) && typeof e.type === "string" && BRIDGE_EVENT_TYPES.has(e.type) && typeof e.ts === "number" && Number.isFinite(e.ts) && "payload" in e;
+}
+
+// src/buddy.ts
+var BUDDY_TRANSITIONS = {
+  ambient: ["listening", "actionRing"],
+  listening: ["thinking", "ambient"],
+  thinking: ["speaking", "ambient"],
+  speaking: ["pointing", "followUp", "ambient"],
+  pointing: ["followUp", "ambient"],
+  followUp: ["ambient", "listening"],
+  actionRing: ["ambient", "listening"]
+};
+function canTransition(from, to) {
+  return BUDDY_TRANSITIONS[from].includes(to);
+}
+export {
+  BUDDY_TRANSITIONS,
+  canTransition,
+  isBridgeEnvelope
+};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@kibee/contracts",
+  "version": "0.2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.build.json",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1"
+  }
+}