@kibee/contracts 0.2.0 → 0.8.0

package/dist/index.d.mts

@@ -1,3 +1,84 @@
+type WidgetDockPreset = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+type WidgetDockPosition = WidgetDockPreset | {
+    preset: WidgetDockPreset;
+    offsetX?: number;
+    offsetY?: number;
+};
+type AvatarMode = "default" | "preset" | "custom" | "vector" | "lottie";
+type AvatarPresetId = "orb" | "ring";
+type AvatarMotion = "breathe" | "pulse" | "spin" | "none";
+/** Relative path — embed apps fetch via API with publishable key (bucket URLs are often private). */
+declare const WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+/** Query appended to WIDGET_AVATAR_PROXY_PATH to fetch the tenant's Lottie JSON. */
+declare const WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+type WidgetAvatarConfig = {
+    mode: "default";
+} | {
+    mode: "preset";
+    preset: AvatarPresetId;
+} | {
+    mode: "custom";
+    assetUrl: string;
+} | {
+    mode: "vector";
+    svg: string;
+    motion: AvatarMotion;
+    color?: string;
+} | {
+    mode: "lottie";
+    assetUrl: string;
+    motion: AvatarMotion;
+};
+interface WidgetConfigResponse {
+    dockPosition: WidgetDockPosition;
+    dockSize: number;
+    theme: {
+        primary: string;
+        tooltipBg: string;
+        tooltipColor: string;
+    };
+    avatar: WidgetAvatarConfig;
+}
+/** Flat keys persisted in tenants.settings JSONB */
+interface WidgetSettingsRecord {
+    dockPosition?: WidgetDockPreset;
+    dockSize?: number;
+    primaryColor?: string;
+    tooltipBg?: string;
+    tooltipColor?: string;
+    avatarMode?: AvatarMode;
+    avatarPreset?: AvatarPresetId;
+    avatarAssetUrl?: string;
+    avatarAssetKey?: string;
+    avatarSvg?: string;
+    avatarColor?: string;
+    avatarLottieKey?: string;
+    avatarMotion?: AvatarMotion;
+    [key: string]: unknown;
+}
+declare function isAvatarMode(value: unknown): value is AvatarMode;
+declare function isAvatarPresetId(value: unknown): value is AvatarPresetId;
+declare function isAvatarMotion(value: unknown): value is AvatarMotion;
+declare function isWidgetAvatarProxyUrl(url: string): boolean;
+declare function parseWidgetAvatar(settings: WidgetSettingsRecord): WidgetAvatarConfig;
+declare function buildWidgetConfigResponse(settings: WidgetSettingsRecord): WidgetConfigResponse;
+/** Map widget avatar config to ThreeBeeRenderer constructor options. */
+declare function resolveRendererAvatarOptions(avatar: WidgetAvatarConfig): {
+    avatarPreset: "bee" | AvatarPresetId;
+    assetUrl?: string;
+};
+type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
+type AnimationSpec = {
+    kind: "css";
+    className: string | null;
+} | {
+    kind: "lottie";
+    segment: string;
+    loop: boolean;
+};
+/** Per-state animation descriptor consumed by DomAvatarRenderer. */
+declare function getAvatarStateAnimations(mode: "vector" | "lottie", motion: AvatarMotion): Record<BeeVisualState, AnimationSpec>;
+
 /**
  * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
  * (broker) and Track B (macOS) leads.
@@ -168,6 +249,28 @@ interface IdentityResponse {
     issuedAt: number;
 }
 
+/** Trust scope of a memory write. In Sprint 5, all writes hardcode "personal".
+ *  Sprint 6 introduces the tenant-scoped writer during the `tenant:attach` flow. */
+type MemoryScope = "personal" | "tenant-scoped";
+/** A single recalled memory entry. Returned by `GET /v1/memory/recent`. */
+interface MemoryRecallItem {
+    /** mem0 entry id — opaque, used as React key on the client. */
+    id: string;
+    /** mem0-derived short summary (e.g. "Asked about carbon credits on Carbon Hub"). */
+    topic: string;
+    /** Surface where the memory was recorded — drives the "On X yesterday" badge. */
+    surface: SurfaceId;
+    /** ISO 8601 timestamp of when the memory was created. */
+    capturedAt: string;
+}
+/** Response envelope for `GET /v1/memory/recent`. */
+interface MemoryRecallResponse {
+    items: MemoryRecallItem[];
+    /** True when mem0 was unreachable / timed out and the items list is incomplete or empty.
+     *  Clients should treat as empty (silent open) rather than show stale data. */
+    degraded?: boolean;
+}
+
 type HighlightVariant = "pulse" | "ring" | "soft";
 interface TargetRef {
     kibeeId?: string;
@@ -583,6 +686,197 @@ interface WidgetConfig {
         tooltipBg: string;
         tooltipColor: string;
     };
+    avatar?: WidgetAvatarConfig;
+}
+
+/** A row in the per-workspace allowed-domains table. Shown in the admin UI
+ *  and consumed by the bridge JWT auth path during the trust handshake. */
+interface AllowedDomain {
+    id: string;
+    workspaceId: string;
+    /** Apex domain only (e.g. "acme.com"). Apex-matches subdomains at runtime. */
+    domain: string;
+    /** Auth0 sub of the admin who added this entry. */
+    createdBy: string;
+    /** ISO 8601. */
+    createdAt: string;
 }
+/** Response for `GET /v1/workspace/allowlist/check?domain=X`.
+ *  When >1 workspace allowlists the same domain for the same visitor,
+ *  `workspaces` returns all matches and the macOS Buddy shows a picker. */
+interface AllowlistCheckResponse {
+    allowed: boolean;
+    workspaces?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/** Payload carried by `tenant:attach` and `tenant:detach` BridgeEnvelope.
+ *  `attachedAt` mirrors the original attach time even on detach so telemetry
+ *  can compute durationMs server-side. */
+interface TenantAttachPayload {
+    workspaceId: string;
+    domain: string;
+    attachedAt: string;
+}
+/** Response for `GET /v1/tenant/flows`. Returns published flows for the
+ *  workspace identified by `claims.tenantId` on the bridge JWT. */
+interface TenantFlowsResponse {
+    flows: FlowDefinition[];
+}
+type FlowStep = {
+    kind: "web_tooltip";
+    selector: string;
+    instruction: string;
+    onPageId?: string;
+} | {
+    kind: "desktop_click";
+    target: {
+        role: string;
+        label: string;
+        axPath: string;
+    };
+    modifiers: ReadonlyArray<"shift" | "control" | "option" | "command">;
+    description?: string;
+    fallbackCoord?: {
+        x: number;
+        y: number;
+    };
+};
+type CaptureStatus = "pending" | "promoted" | "rejected" | "withdrawn";
+interface CaptureSummary {
+    id: string;
+    workspaceId: string;
+    captorVisitorId: string;
+    signature: string;
+    stepCount: number;
+    durationMs: number;
+    status: CaptureStatus;
+    promotedFlowId?: string;
+    rejectionReason?: string;
+    createdAt: string;
+}
+interface CaptureUploadPayload {
+    v: 2;
+    visitorId: string;
+    scope: "tenant-scoped";
+    capturedAt: string;
+    durationMs: number;
+    aborted: boolean;
+    steps: ReadonlyArray<{
+        ts: number;
+        type: "mousedown";
+        button: 0 | 1 | 2;
+        modifiers: ReadonlyArray<string>;
+        target: {
+            role: string;
+            label: string;
+            axPath: string;
+        };
+        fallbackCoord: {
+            x: number;
+            y: number;
+        };
+    }>;
+}
+interface CaptureUploadResponse {
+    captureId: string;
+    signature: string;
+}
+interface CaptureUploadEnvelope {
+    payload: CaptureUploadPayload;
+    warnings?: ReadonlyArray<string>;
+}
+interface CandidateGroup {
+    signature: string;
+    captures: ReadonlyArray<CaptureSummary>;
+    proposedTitle: string;
+    representativeId: string;
+}
+interface PromoteCandidatePayload {
+    editedSteps: ReadonlyArray<FlowStep>;
+    title: string;
+    pageId?: string;
+    audience?: string;
+    introMessage?: string;
+    replaceFlowId?: string;
+}
+type AuditAction = "capture.uploaded" | "capture.withdrawn" | "capture.promoted" | "capture.rejected" | "capture.edited" | "flag.flipped" | "slo.token.minted";
+interface AuditEvent {
+    id: string;
+    workspaceId: string;
+    actor: {
+        kind: "visitor" | "admin" | "system";
+        id: string;
+    };
+    action: AuditAction;
+    target: {
+        kind: "capture" | "flow" | "flag";
+        id: string;
+    };
+    metadata?: Record<string, unknown>;
+    ts: string;
+}
+interface DiffPreview {
+    matchKind: "new" | "update";
+    matchedFlowId?: string;
+    matchedFlowTitle?: string;
+    stepDiff: ReadonlyArray<{
+        kind: "added" | "removed" | "changed" | "unchanged";
+        step: FlowStep;
+    }>;
+}
+interface FeatureFlag {
+    key: string;
+    defaultValue: boolean;
+    description: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FeatureFlagOverride {
+    workspaceId: string;
+    key: string;
+    value: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ResolvedFlagSet {
+    workspaceId: string;
+    flags: Record<string, boolean>;
+    fetchedAt: string;
+}
+interface SloWindow {
+    captureUploadSuccessRate: number;
+    captureUploadCount: number;
+    tenantAttachDeniedRate: number;
+    tenantAttachAttemptCount: number;
+    adminPromotionLatencyP50Ms: number;
+    adminPromotionLatencyP95Ms: number;
+    bridgeUptimePerVisitorMedian: number;
+    replayFallbackRate: number;
+    replayAttemptCount: number;
+}
+interface SloSnapshot {
+    computedAt: string;
+    workspaceId: string;
+    windows: {
+        last24h: SloWindow;
+        last7d: SloWindow;
+    };
+}
+declare const SLO_THRESHOLDS: {
+    readonly captureUploadSuccessRate: {
+        readonly min: 0.99;
+    };
+    readonly tenantAttachDeniedRate: {
+        readonly max: 0.01;
+    };
+    readonly adminPromotionLatencyP95Ms: {
+        readonly max: 2000;
+    };
+    readonly bridgeUptimePerVisitorMedian: {
+        readonly min: 0.99;
+    };
+};
 
-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 };
+export { type AdminSessionSummary, type AllowedDomain, type AllowlistCheckResponse, type AnalyticsEvent, type AnimationSpec, type AuditAction, type AuditEvent, type AvatarMode, type AvatarMotion, type AvatarPresetId, BUDDY_TRANSITIONS, type BeeVisualState, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type CandidateGroup, type CaptureStatus, type CaptureSummary, type CaptureUploadEnvelope, type CaptureUploadPayload, type CaptureUploadResponse, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DiffPreview, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FeatureFlag, type FeatureFlagOverride, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type FlowStep, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MemoryRecallItem, type MemoryRecallResponse, type MemoryScope, type MessageTemplate, type PairingState, type PromoteCandidatePayload, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type ResolvedFlagSet, SLO_THRESHOLDS, type SessionState, type SloSnapshot, type SloWindow, type StartSessionRequest, type SurfaceId, type TargetRef, type TenantAttachPayload, type TenantFlowsResponse, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, WIDGET_AVATAR_LOTTIE_PROXY_PATH, WIDGET_AVATAR_PROXY_PATH, type WidgetAvatarConfig, type WidgetConfig, type WidgetConfigResponse, type WidgetDockPosition, type WidgetDockPreset, type WidgetSettingsRecord, buildWidgetConfigResponse, canTransition, getAvatarStateAnimations, isAvatarMode, isAvatarMotion, isAvatarPresetId, isBridgeEnvelope, isWidgetAvatarProxyUrl, parseWidgetAvatar, resolveRendererAvatarOptions };

package/dist/index.d.ts

@@ -1,3 +1,84 @@
+type WidgetDockPreset = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+type WidgetDockPosition = WidgetDockPreset | {
+    preset: WidgetDockPreset;
+    offsetX?: number;
+    offsetY?: number;
+};
+type AvatarMode = "default" | "preset" | "custom" | "vector" | "lottie";
+type AvatarPresetId = "orb" | "ring";
+type AvatarMotion = "breathe" | "pulse" | "spin" | "none";
+/** Relative path — embed apps fetch via API with publishable key (bucket URLs are often private). */
+declare const WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+/** Query appended to WIDGET_AVATAR_PROXY_PATH to fetch the tenant's Lottie JSON. */
+declare const WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+type WidgetAvatarConfig = {
+    mode: "default";
+} | {
+    mode: "preset";
+    preset: AvatarPresetId;
+} | {
+    mode: "custom";
+    assetUrl: string;
+} | {
+    mode: "vector";
+    svg: string;
+    motion: AvatarMotion;
+    color?: string;
+} | {
+    mode: "lottie";
+    assetUrl: string;
+    motion: AvatarMotion;
+};
+interface WidgetConfigResponse {
+    dockPosition: WidgetDockPosition;
+    dockSize: number;
+    theme: {
+        primary: string;
+        tooltipBg: string;
+        tooltipColor: string;
+    };
+    avatar: WidgetAvatarConfig;
+}
+/** Flat keys persisted in tenants.settings JSONB */
+interface WidgetSettingsRecord {
+    dockPosition?: WidgetDockPreset;
+    dockSize?: number;
+    primaryColor?: string;
+    tooltipBg?: string;
+    tooltipColor?: string;
+    avatarMode?: AvatarMode;
+    avatarPreset?: AvatarPresetId;
+    avatarAssetUrl?: string;
+    avatarAssetKey?: string;
+    avatarSvg?: string;
+    avatarColor?: string;
+    avatarLottieKey?: string;
+    avatarMotion?: AvatarMotion;
+    [key: string]: unknown;
+}
+declare function isAvatarMode(value: unknown): value is AvatarMode;
+declare function isAvatarPresetId(value: unknown): value is AvatarPresetId;
+declare function isAvatarMotion(value: unknown): value is AvatarMotion;
+declare function isWidgetAvatarProxyUrl(url: string): boolean;
+declare function parseWidgetAvatar(settings: WidgetSettingsRecord): WidgetAvatarConfig;
+declare function buildWidgetConfigResponse(settings: WidgetSettingsRecord): WidgetConfigResponse;
+/** Map widget avatar config to ThreeBeeRenderer constructor options. */
+declare function resolveRendererAvatarOptions(avatar: WidgetAvatarConfig): {
+    avatarPreset: "bee" | AvatarPresetId;
+    assetUrl?: string;
+};
+type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
+type AnimationSpec = {
+    kind: "css";
+    className: string | null;
+} | {
+    kind: "lottie";
+    segment: string;
+    loop: boolean;
+};
+/** Per-state animation descriptor consumed by DomAvatarRenderer. */
+declare function getAvatarStateAnimations(mode: "vector" | "lottie", motion: AvatarMotion): Record<BeeVisualState, AnimationSpec>;
+
 /**
  * Frozen Sprint 1 contract. Edits require joint sign-off from Track A
  * (broker) and Track B (macOS) leads.
@@ -168,6 +249,28 @@ interface IdentityResponse {
     issuedAt: number;
 }
 
+/** Trust scope of a memory write. In Sprint 5, all writes hardcode "personal".
+ *  Sprint 6 introduces the tenant-scoped writer during the `tenant:attach` flow. */
+type MemoryScope = "personal" | "tenant-scoped";
+/** A single recalled memory entry. Returned by `GET /v1/memory/recent`. */
+interface MemoryRecallItem {
+    /** mem0 entry id — opaque, used as React key on the client. */
+    id: string;
+    /** mem0-derived short summary (e.g. "Asked about carbon credits on Carbon Hub"). */
+    topic: string;
+    /** Surface where the memory was recorded — drives the "On X yesterday" badge. */
+    surface: SurfaceId;
+    /** ISO 8601 timestamp of when the memory was created. */
+    capturedAt: string;
+}
+/** Response envelope for `GET /v1/memory/recent`. */
+interface MemoryRecallResponse {
+    items: MemoryRecallItem[];
+    /** True when mem0 was unreachable / timed out and the items list is incomplete or empty.
+     *  Clients should treat as empty (silent open) rather than show stale data. */
+    degraded?: boolean;
+}
+
 type HighlightVariant = "pulse" | "ring" | "soft";
 interface TargetRef {
     kibeeId?: string;
@@ -583,6 +686,197 @@ interface WidgetConfig {
         tooltipBg: string;
         tooltipColor: string;
     };
+    avatar?: WidgetAvatarConfig;
+}
+
+/** A row in the per-workspace allowed-domains table. Shown in the admin UI
+ *  and consumed by the bridge JWT auth path during the trust handshake. */
+interface AllowedDomain {
+    id: string;
+    workspaceId: string;
+    /** Apex domain only (e.g. "acme.com"). Apex-matches subdomains at runtime. */
+    domain: string;
+    /** Auth0 sub of the admin who added this entry. */
+    createdBy: string;
+    /** ISO 8601. */
+    createdAt: string;
 }
+/** Response for `GET /v1/workspace/allowlist/check?domain=X`.
+ *  When >1 workspace allowlists the same domain for the same visitor,
+ *  `workspaces` returns all matches and the macOS Buddy shows a picker. */
+interface AllowlistCheckResponse {
+    allowed: boolean;
+    workspaces?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/** Payload carried by `tenant:attach` and `tenant:detach` BridgeEnvelope.
+ *  `attachedAt` mirrors the original attach time even on detach so telemetry
+ *  can compute durationMs server-side. */
+interface TenantAttachPayload {
+    workspaceId: string;
+    domain: string;
+    attachedAt: string;
+}
+/** Response for `GET /v1/tenant/flows`. Returns published flows for the
+ *  workspace identified by `claims.tenantId` on the bridge JWT. */
+interface TenantFlowsResponse {
+    flows: FlowDefinition[];
+}
+type FlowStep = {
+    kind: "web_tooltip";
+    selector: string;
+    instruction: string;
+    onPageId?: string;
+} | {
+    kind: "desktop_click";
+    target: {
+        role: string;
+        label: string;
+        axPath: string;
+    };
+    modifiers: ReadonlyArray<"shift" | "control" | "option" | "command">;
+    description?: string;
+    fallbackCoord?: {
+        x: number;
+        y: number;
+    };
+};
+type CaptureStatus = "pending" | "promoted" | "rejected" | "withdrawn";
+interface CaptureSummary {
+    id: string;
+    workspaceId: string;
+    captorVisitorId: string;
+    signature: string;
+    stepCount: number;
+    durationMs: number;
+    status: CaptureStatus;
+    promotedFlowId?: string;
+    rejectionReason?: string;
+    createdAt: string;
+}
+interface CaptureUploadPayload {
+    v: 2;
+    visitorId: string;
+    scope: "tenant-scoped";
+    capturedAt: string;
+    durationMs: number;
+    aborted: boolean;
+    steps: ReadonlyArray<{
+        ts: number;
+        type: "mousedown";
+        button: 0 | 1 | 2;
+        modifiers: ReadonlyArray<string>;
+        target: {
+            role: string;
+            label: string;
+            axPath: string;
+        };
+        fallbackCoord: {
+            x: number;
+            y: number;
+        };
+    }>;
+}
+interface CaptureUploadResponse {
+    captureId: string;
+    signature: string;
+}
+interface CaptureUploadEnvelope {
+    payload: CaptureUploadPayload;
+    warnings?: ReadonlyArray<string>;
+}
+interface CandidateGroup {
+    signature: string;
+    captures: ReadonlyArray<CaptureSummary>;
+    proposedTitle: string;
+    representativeId: string;
+}
+interface PromoteCandidatePayload {
+    editedSteps: ReadonlyArray<FlowStep>;
+    title: string;
+    pageId?: string;
+    audience?: string;
+    introMessage?: string;
+    replaceFlowId?: string;
+}
+type AuditAction = "capture.uploaded" | "capture.withdrawn" | "capture.promoted" | "capture.rejected" | "capture.edited" | "flag.flipped" | "slo.token.minted";
+interface AuditEvent {
+    id: string;
+    workspaceId: string;
+    actor: {
+        kind: "visitor" | "admin" | "system";
+        id: string;
+    };
+    action: AuditAction;
+    target: {
+        kind: "capture" | "flow" | "flag";
+        id: string;
+    };
+    metadata?: Record<string, unknown>;
+    ts: string;
+}
+interface DiffPreview {
+    matchKind: "new" | "update";
+    matchedFlowId?: string;
+    matchedFlowTitle?: string;
+    stepDiff: ReadonlyArray<{
+        kind: "added" | "removed" | "changed" | "unchanged";
+        step: FlowStep;
+    }>;
+}
+interface FeatureFlag {
+    key: string;
+    defaultValue: boolean;
+    description: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FeatureFlagOverride {
+    workspaceId: string;
+    key: string;
+    value: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ResolvedFlagSet {
+    workspaceId: string;
+    flags: Record<string, boolean>;
+    fetchedAt: string;
+}
+interface SloWindow {
+    captureUploadSuccessRate: number;
+    captureUploadCount: number;
+    tenantAttachDeniedRate: number;
+    tenantAttachAttemptCount: number;
+    adminPromotionLatencyP50Ms: number;
+    adminPromotionLatencyP95Ms: number;
+    bridgeUptimePerVisitorMedian: number;
+    replayFallbackRate: number;
+    replayAttemptCount: number;
+}
+interface SloSnapshot {
+    computedAt: string;
+    workspaceId: string;
+    windows: {
+        last24h: SloWindow;
+        last7d: SloWindow;
+    };
+}
+declare const SLO_THRESHOLDS: {
+    readonly captureUploadSuccessRate: {
+        readonly min: 0.99;
+    };
+    readonly tenantAttachDeniedRate: {
+        readonly max: 0.01;
+    };
+    readonly adminPromotionLatencyP95Ms: {
+        readonly max: 2000;
+    };
+    readonly bridgeUptimePerVisitorMedian: {
+        readonly min: 0.99;
+    };
+};
 
-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 };
+export { type AdminSessionSummary, type AllowedDomain, type AllowlistCheckResponse, type AnalyticsEvent, type AnimationSpec, type AuditAction, type AuditEvent, type AvatarMode, type AvatarMotion, type AvatarPresetId, BUDDY_TRANSITIONS, type BeeVisualState, type BridgeClaims, type BridgeEnvelope, type BridgeEventType, type BuddyState, type CandidateGroup, type CaptureStatus, type CaptureSummary, type CaptureUploadEnvelope, type CaptureUploadPayload, type CaptureUploadResponse, type ChatMessage, type ChatMode, type ChatSender, type CrossSiteFlowQueueItem, type CrossSiteFlowStep, type DiffPreview, type DockInlineAnchor, type DockPositionConfig, type DockPositionPreset, type EventMetadata, type FeatureFlag, type FeatureFlagOverride, type FlowCommand, type FlowDefinition, type FlowMoveOptions, type FlowStep, type HighlightVariant, type IdentityRequest, type IdentityResponse, type IntentMatch, type KiBeePairAccept, type KiBeePairReject, type KiBeePairRequest, type MemoryRecallItem, type MemoryRecallResponse, type MemoryScope, type MessageTemplate, type PairingState, type PromoteCandidatePayload, type PushFlowRequest, type PushTargetsRequest, type RecoveryRequest, type RecoveryResponse, type RegisteredTarget, type ResolveIntentRequest, type ResolvedFlagSet, SLO_THRESHOLDS, type SessionState, type SloSnapshot, type SloWindow, type StartSessionRequest, type SurfaceId, type TargetRef, type TenantAttachPayload, type TenantFlowsResponse, type TrackEventRequest, type VisibleTarget, type VisitorIdentity, type VisitorPollResponse, WIDGET_AVATAR_LOTTIE_PROXY_PATH, WIDGET_AVATAR_PROXY_PATH, type WidgetAvatarConfig, type WidgetConfig, type WidgetConfigResponse, type WidgetDockPosition, type WidgetDockPreset, type WidgetSettingsRecord, buildWidgetConfigResponse, canTransition, getAvatarStateAnimations, isAvatarMode, isAvatarMotion, isAvatarPresetId, isBridgeEnvelope, isWidgetAvatarProxyUrl, parseWidgetAvatar, resolveRendererAvatarOptions };

package/dist/index.js

@@ -21,11 +21,106 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BUDDY_TRANSITIONS: () => BUDDY_TRANSITIONS,
+  SLO_THRESHOLDS: () => SLO_THRESHOLDS,
+  WIDGET_AVATAR_LOTTIE_PROXY_PATH: () => WIDGET_AVATAR_LOTTIE_PROXY_PATH,
+  WIDGET_AVATAR_PROXY_PATH: () => WIDGET_AVATAR_PROXY_PATH,
+  buildWidgetConfigResponse: () => buildWidgetConfigResponse,
   canTransition: () => canTransition,
-  isBridgeEnvelope: () => isBridgeEnvelope
+  getAvatarStateAnimations: () => getAvatarStateAnimations,
+  isAvatarMode: () => isAvatarMode,
+  isAvatarMotion: () => isAvatarMotion,
+  isAvatarPresetId: () => isAvatarPresetId,
+  isBridgeEnvelope: () => isBridgeEnvelope,
+  isWidgetAvatarProxyUrl: () => isWidgetAvatarProxyUrl,
+  parseWidgetAvatar: () => parseWidgetAvatar,
+  resolveRendererAvatarOptions: () => resolveRendererAvatarOptions
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/widget.ts
+var WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+var WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+var AVATAR_MODES = ["default", "preset", "custom", "vector", "lottie"];
+var AVATAR_PRESETS = ["orb", "ring"];
+var AVATAR_MOTIONS = ["breathe", "pulse", "spin", "none"];
+function isAvatarMode(value) {
+  return typeof value === "string" && AVATAR_MODES.includes(value);
+}
+function isAvatarPresetId(value) {
+  return typeof value === "string" && AVATAR_PRESETS.includes(value);
+}
+function isAvatarMotion(value) {
+  return typeof value === "string" && AVATAR_MOTIONS.includes(value);
+}
+function isWidgetAvatarProxyUrl(url) {
+  const trimmed = url.trim();
+  return trimmed === WIDGET_AVATAR_PROXY_PATH || trimmed.endsWith(WIDGET_AVATAR_PROXY_PATH);
+}
+function parseWidgetAvatar(settings) {
+  const mode = isAvatarMode(settings.avatarMode) ? settings.avatarMode : "default";
+  const motion = isAvatarMotion(settings.avatarMotion) ? settings.avatarMotion : "breathe";
+  if (mode === "preset") {
+    const preset = isAvatarPresetId(settings.avatarPreset) ? settings.avatarPreset : "orb";
+    return { mode, preset };
+  }
+  if (mode === "custom") {
+    const assetKey = typeof settings.avatarAssetKey === "string" ? settings.avatarAssetKey.trim() : "";
+    if (assetKey) return { mode, assetUrl: WIDGET_AVATAR_PROXY_PATH };
+    if (typeof settings.avatarAssetUrl === "string" && settings.avatarAssetUrl.trim()) {
+      return { mode, assetUrl: settings.avatarAssetUrl.trim() };
+    }
+    return { mode: "default" };
+  }
+  if (mode === "vector") {
+    const svg = typeof settings.avatarSvg === "string" ? settings.avatarSvg.trim() : "";
+    if (!svg) return { mode: "default" };
+    const color = typeof settings.avatarColor === "string" && settings.avatarColor.trim() ? settings.avatarColor.trim() : void 0;
+    return color ? { mode, svg, motion, color } : { mode, svg, motion };
+  }
+  if (mode === "lottie") {
+    const key = typeof settings.avatarLottieKey === "string" ? settings.avatarLottieKey.trim() : "";
+    if (!key) return { mode: "default" };
+    return { mode, assetUrl: WIDGET_AVATAR_LOTTIE_PROXY_PATH, motion };
+  }
+  return { mode: "default" };
+}
+function buildWidgetConfigResponse(settings) {
+  const dockPosition = settings.dockPosition ?? "bottom-right";
+  const dockSize = typeof settings.dockSize === "number" ? settings.dockSize : 60;
+  return {
+    dockPosition,
+    dockSize,
+    theme: {
+      primary: typeof settings.primaryColor === "string" ? settings.primaryColor : "#a77a2f",
+      tooltipBg: typeof settings.tooltipBg === "string" ? settings.tooltipBg : "#fbf6ec",
+      tooltipColor: typeof settings.tooltipColor === "string" ? settings.tooltipColor : "#241b11"
+    },
+    avatar: parseWidgetAvatar(settings)
+  };
+}
+function resolveRendererAvatarOptions(avatar) {
+  if (avatar.mode === "preset") return { avatarPreset: avatar.preset };
+  if (avatar.mode === "custom") return { avatarPreset: "bee", assetUrl: avatar.assetUrl };
+  return { avatarPreset: "bee" };
+}
+function getAvatarStateAnimations(mode, motion) {
+  if (mode === "lottie") {
+    return {
+      idle: { kind: "lottie", segment: "idle", loop: true },
+      guiding: { kind: "lottie", segment: "idle", loop: true },
+      thinking: { kind: "lottie", segment: "thinking", loop: true },
+      celebrating: { kind: "lottie", segment: "celebrate", loop: false }
+    };
+  }
+  const idleClass = motion === "none" ? null : `kibee-2d-motion--${motion}`;
+  return {
+    idle: { kind: "css", className: idleClass },
+    guiding: { kind: "css", className: "kibee-2d-state--guiding" },
+    thinking: { kind: "css", className: "kibee-2d-state--thinking" },
+    celebrating: { kind: "css", className: "kibee-2d-state--celebrating" }
+  };
+}
+
 // src/bridge.ts
 var SURFACE_IDS = /* @__PURE__ */ new Set(["web", "extension", "desktop"]);
 var BRIDGE_TARGETS = /* @__PURE__ */ new Set([
@@ -68,9 +163,28 @@ var BUDDY_TRANSITIONS = {
 function canTransition(from, to) {
   return BUDDY_TRANSITIONS[from].includes(to);
 }
+
+// src/index.ts
+var SLO_THRESHOLDS = {
+  captureUploadSuccessRate: { min: 0.99 },
+  tenantAttachDeniedRate: { max: 0.01 },
+  adminPromotionLatencyP95Ms: { max: 2e3 },
+  bridgeUptimePerVisitorMedian: { min: 0.99 }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUDDY_TRANSITIONS,
+  SLO_THRESHOLDS,
+  WIDGET_AVATAR_LOTTIE_PROXY_PATH,
+  WIDGET_AVATAR_PROXY_PATH,
+  buildWidgetConfigResponse,
   canTransition,
-  isBridgeEnvelope
+  getAvatarStateAnimations,
+  isAvatarMode,
+  isAvatarMotion,
+  isAvatarPresetId,
+  isBridgeEnvelope,
+  isWidgetAvatarProxyUrl,
+  parseWidgetAvatar,
+  resolveRendererAvatarOptions
 });

package/dist/index.mjs

@@ -1,3 +1,87 @@
+// src/widget.ts
+var WIDGET_AVATAR_PROXY_PATH = "/widget-avatar";
+var WIDGET_AVATAR_LOTTIE_PROXY_PATH = "/widget-avatar?type=lottie";
+var AVATAR_MODES = ["default", "preset", "custom", "vector", "lottie"];
+var AVATAR_PRESETS = ["orb", "ring"];
+var AVATAR_MOTIONS = ["breathe", "pulse", "spin", "none"];
+function isAvatarMode(value) {
+  return typeof value === "string" && AVATAR_MODES.includes(value);
+}
+function isAvatarPresetId(value) {
+  return typeof value === "string" && AVATAR_PRESETS.includes(value);
+}
+function isAvatarMotion(value) {
+  return typeof value === "string" && AVATAR_MOTIONS.includes(value);
+}
+function isWidgetAvatarProxyUrl(url) {
+  const trimmed = url.trim();
+  return trimmed === WIDGET_AVATAR_PROXY_PATH || trimmed.endsWith(WIDGET_AVATAR_PROXY_PATH);
+}
+function parseWidgetAvatar(settings) {
+  const mode = isAvatarMode(settings.avatarMode) ? settings.avatarMode : "default";
+  const motion = isAvatarMotion(settings.avatarMotion) ? settings.avatarMotion : "breathe";
+  if (mode === "preset") {
+    const preset = isAvatarPresetId(settings.avatarPreset) ? settings.avatarPreset : "orb";
+    return { mode, preset };
+  }
+  if (mode === "custom") {
+    const assetKey = typeof settings.avatarAssetKey === "string" ? settings.avatarAssetKey.trim() : "";
+    if (assetKey) return { mode, assetUrl: WIDGET_AVATAR_PROXY_PATH };
+    if (typeof settings.avatarAssetUrl === "string" && settings.avatarAssetUrl.trim()) {
+      return { mode, assetUrl: settings.avatarAssetUrl.trim() };
+    }
+    return { mode: "default" };
+  }
+  if (mode === "vector") {
+    const svg = typeof settings.avatarSvg === "string" ? settings.avatarSvg.trim() : "";
+    if (!svg) return { mode: "default" };
+    const color = typeof settings.avatarColor === "string" && settings.avatarColor.trim() ? settings.avatarColor.trim() : void 0;
+    return color ? { mode, svg, motion, color } : { mode, svg, motion };
+  }
+  if (mode === "lottie") {
+    const key = typeof settings.avatarLottieKey === "string" ? settings.avatarLottieKey.trim() : "";
+    if (!key) return { mode: "default" };
+    return { mode, assetUrl: WIDGET_AVATAR_LOTTIE_PROXY_PATH, motion };
+  }
+  return { mode: "default" };
+}
+function buildWidgetConfigResponse(settings) {
+  const dockPosition = settings.dockPosition ?? "bottom-right";
+  const dockSize = typeof settings.dockSize === "number" ? settings.dockSize : 60;
+  return {
+    dockPosition,
+    dockSize,
+    theme: {
+      primary: typeof settings.primaryColor === "string" ? settings.primaryColor : "#a77a2f",
+      tooltipBg: typeof settings.tooltipBg === "string" ? settings.tooltipBg : "#fbf6ec",
+      tooltipColor: typeof settings.tooltipColor === "string" ? settings.tooltipColor : "#241b11"
+    },
+    avatar: parseWidgetAvatar(settings)
+  };
+}
+function resolveRendererAvatarOptions(avatar) {
+  if (avatar.mode === "preset") return { avatarPreset: avatar.preset };
+  if (avatar.mode === "custom") return { avatarPreset: "bee", assetUrl: avatar.assetUrl };
+  return { avatarPreset: "bee" };
+}
+function getAvatarStateAnimations(mode, motion) {
+  if (mode === "lottie") {
+    return {
+      idle: { kind: "lottie", segment: "idle", loop: true },
+      guiding: { kind: "lottie", segment: "idle", loop: true },
+      thinking: { kind: "lottie", segment: "thinking", loop: true },
+      celebrating: { kind: "lottie", segment: "celebrate", loop: false }
+    };
+  }
+  const idleClass = motion === "none" ? null : `kibee-2d-motion--${motion}`;
+  return {
+    idle: { kind: "css", className: idleClass },
+    guiding: { kind: "css", className: "kibee-2d-state--guiding" },
+    thinking: { kind: "css", className: "kibee-2d-state--thinking" },
+    celebrating: { kind: "css", className: "kibee-2d-state--celebrating" }
+  };
+}
+
 // src/bridge.ts
 var SURFACE_IDS = /* @__PURE__ */ new Set(["web", "extension", "desktop"]);
 var BRIDGE_TARGETS = /* @__PURE__ */ new Set([
@@ -40,8 +124,27 @@ var BUDDY_TRANSITIONS = {
 function canTransition(from, to) {
   return BUDDY_TRANSITIONS[from].includes(to);
 }
+
+// src/index.ts
+var SLO_THRESHOLDS = {
+  captureUploadSuccessRate: { min: 0.99 },
+  tenantAttachDeniedRate: { max: 0.01 },
+  adminPromotionLatencyP95Ms: { max: 2e3 },
+  bridgeUptimePerVisitorMedian: { min: 0.99 }
+};
 export {
   BUDDY_TRANSITIONS,
+  SLO_THRESHOLDS,
+  WIDGET_AVATAR_LOTTIE_PROXY_PATH,
+  WIDGET_AVATAR_PROXY_PATH,
+  buildWidgetConfigResponse,
   canTransition,
-  isBridgeEnvelope
+  getAvatarStateAnimations,
+  isAvatarMode,
+  isAvatarMotion,
+  isAvatarPresetId,
+  isBridgeEnvelope,
+  isWidgetAvatarProxyUrl,
+  parseWidgetAvatar,
+  resolveRendererAvatarOptions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kibee/contracts",
-  "version": "0.2.0",
+  "version": "0.8.0",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -11,12 +11,17 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "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"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }