@alxxsck/ai-assistant 1.2.0 → 1.4.0

package/dist/domain/command/CommandRuntime.d.ts

@@ -11,8 +11,7 @@ type InternalHandlers = {
 };
 export declare class CommandRuntime {
     private readonly onStatus?;
-    private readonly targets;
-    private readonly hostHandlers;
+    private readonly uiCommands;
     private readonly internalHandlers;
     private readonly internalHandlersReady;
     private resolveInternalHandlers;
@@ -28,21 +27,16 @@ export declare class CommandRuntime {
     destroy(): void;
     private executeOnce;
     private dispatch;
-    private executeTargetCommand;
     private executeHighlight;
     private executeShowCta;
-    private canOpenPage;
-    private canOpenModal;
     private requireTarget;
+    private requireEnvelopeTarget;
     private findTargetElement;
     private applyDefaultHighlight;
     private removeDefaultHighlight;
     private requireInternal;
     private requireString;
     private firstDefined;
-    private applyUrlFallback;
-    private targetUrl;
-    private assertTargetCode;
     private finish;
     private storageKey;
     private loadCompleted;

package/dist/domain/command/UiCommandService.d.ts

@@ -0,0 +1,24 @@
+import type { HostCommandHandlerName, HostCommandHandlers, UiCommandActionSnapshot, UiCommandTarget, UiTarget } from "./command.types";
+type NavigationCommandType = "open_page" | "open_modal";
+export declare class UiCommandService {
+    private readonly targets;
+    private readonly handlers;
+    constructor(targets?: Record<string, UiTarget>, handlers?: HostCommandHandlers);
+    registerTarget(code: string, target: UiTarget): () => void;
+    getTarget(code: string): UiTarget | undefined;
+    getHandler<K extends HostCommandHandlerName>(name: K): HostCommandHandlers[K];
+    registerHandler<K extends HostCommandHandlerName>(name: K, handler: NonNullable<HostCommandHandlers[K]>): () => void;
+    resolveAction(commandType: NavigationCommandType, payload: Readonly<Record<string, unknown>>, target?: UiCommandTarget): Readonly<UiCommandActionSnapshot>;
+    execute(commandType: NavigationCommandType, commandId: string, payload: Readonly<Record<string, unknown>>, target?: UiCommandTarget): Promise<void>;
+    executeAction(action: Readonly<UiCommandActionSnapshot>, commandId: string, payload: Readonly<Record<string, unknown>>): Promise<void>;
+    canExecute(action: Readonly<UiCommandActionSnapshot>): boolean;
+    private resolveCanonicalAction;
+    private resolveLegacyAction;
+    private assertLegacyTarget;
+    private targetUrl;
+    private applyUrlFallback;
+    private isSameOriginUrl;
+    private requireNonEmptyString;
+    private assertTargetCode;
+}
+export {};

package/dist/domain/command/command.errors.d.ts

@@ -0,0 +1,5 @@
+export declare class CommandExecutionError extends Error {
+    readonly code: string;
+    readonly status: "failed" | "unsupported";
+    constructor(code: string, status?: "failed" | "unsupported", options?: ErrorOptions);
+}

package/dist/domain/command/command.types.d.ts

@@ -14,18 +14,35 @@ export type CommandEnvelope = {
     sequence: number;
     occurredAt: string;
     data: {
+        contractVersion: number;
         commandId: string;
         scenarioRunId: string;
         interactionSessionId: string;
         commandType: string;
-        target?: {
-            id?: string;
-            code?: string;
-        };
+        target?: UiCommandTarget;
         payload: Record<string, unknown>;
         expiresAt: string | null;
     };
 };
+export type PageCommandTarget = {
+    id: string;
+    code: string;
+    kind: "page";
+    route: string;
+};
+export type ModalCommandTarget = {
+    id: string;
+    code: string;
+    kind: "modal";
+    modalName: string;
+};
+export type ElementCommandTarget = {
+    id: string;
+    code: string;
+    kind: "button" | "element" | "handler";
+    selector?: string;
+};
+export type UiCommandTarget = PageCommandTarget | ModalCommandTarget | ElementCommandTarget;
 export type UiTargetKind = "button" | "element" | "modal" | "page";
 export type UiTarget = {
     kind: UiTargetKind;
@@ -33,6 +50,8 @@ export type UiTarget = {
     selector?: string;
     /** Trusted route used by the built-in openPage fallback. */
     route?: string;
+    /** Legacy modal registry key used while commands do not contain a canonical target. */
+    modalName?: string;
     /** Explicit URL fallback. It may include query parameters such as lola_modal. */
     url?: string;
     /** Query parameters merged into url, route, or the current location. Null removes a key. */
@@ -49,6 +68,49 @@ export type HostCommandContext = {
     modalId?: string;
     modalCode?: string;
 };
+export type OpenPageContext = {
+    commandId: string;
+    pageCode: string;
+    route: string;
+    payload: Readonly<Record<string, unknown>>;
+    /** @deprecated Use pageCode. */
+    target: string;
+    /** @deprecated The command type is fixed for this callback. */
+    commandType: "open_page";
+    /** @deprecated Use route. */
+    url: string;
+    /** @deprecated Used only by legacy local target integrations. */
+    targetDefinition?: UiTarget;
+};
+export type OpenModalContext = {
+    commandId: string;
+    modalCode: string;
+    modalName: string;
+    payload: Readonly<Record<string, unknown>>;
+    /** @deprecated Use modalCode. */
+    target: string;
+    /** @deprecated The command type is fixed for this callback. */
+    commandType: "open_modal";
+    /** @deprecated Use modalCode. */
+    modalId: string;
+    /** @deprecated Used only by legacy URL-based modal integrations. */
+    url?: string;
+    /** @deprecated Used only by legacy local target integrations. */
+    targetDefinition?: UiTarget;
+};
+export type UiCommandActionSnapshot = {
+    kind: "page";
+    code: string;
+    route: string;
+    target?: PageCommandTarget;
+} | {
+    kind: "modal";
+    code: string;
+    modalName?: string;
+    url?: string;
+    selector?: string;
+    target?: ModalCommandTarget;
+};
 export type HighlightCommandContext = HostCommandContext & {
     active: boolean;
     element?: Element;
@@ -57,6 +119,8 @@ export type CtaCommandContext = Omit<HostCommandContext, "target"> & {
     label: string;
     action: "none" | "open_modal" | "open_page";
     target?: string;
+    /** Resolved once when SHOW_CTA arrives and reused unchanged after the click. */
+    uiAction?: Readonly<UiCommandActionSnapshot>;
 };
 export type StartVoiceConversationCommandContext = {
     commandId: string;
@@ -81,8 +145,8 @@ export type SpeakTextCommandContext = {
     channels: 1;
 };
 export type HostCommandHandlers = {
-    openPage?: (context: HostCommandContext) => void | Promise<void>;
-    openModal?: (context: HostCommandContext) => void | Promise<void>;
+    openPage?: (context: OpenPageContext) => void | Promise<void>;
+    openModal?: (context: OpenModalContext) => void | Promise<void>;
     highlight?: (context: HighlightCommandContext) => void | Promise<void>;
     showCta?: (context: CtaCommandContext) => void | Promise<void>;
 };

package/dist/index.types.d.ts

@@ -47,4 +47,4 @@ export declare class ChatWidgetInstance extends EventTarget {
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
 }
 export type { CustomerInteractionSession };
-export type { CommandAck, CommandAckStatus, CommandEnvelope, CommandEventDetail, CommandType, CtaCommandContext, HighlightCommandContext, HostCommandContext, HostCommandHandler, HostCommandHandlerName, HostCommandHandlers, SpeakTextCommandContext, StartVoiceConversationCommandContext, UiTarget, UiTargetKind, } from "./domain/command/command.types";
+export type { CommandAck, CommandAckStatus, CommandEnvelope, CommandEventDetail, CommandType, CtaCommandContext, HighlightCommandContext, HostCommandContext, HostCommandHandler, HostCommandHandlerName, HostCommandHandlers, ModalCommandTarget, OpenModalContext, OpenPageContext, PageCommandTarget, SpeakTextCommandContext, StartVoiceConversationCommandContext, UiCommandActionSnapshot, UiCommandTarget, UiTarget, UiTargetKind, } from "./domain/command/command.types";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alxxsck/ai-assistant",
   "private": false,
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Embeddable chat widget for communication with Bridge AI agent",
   "type": "module",
   "main": "dist/bridge-ai-chat-widget.es.js",