@xpert-ai/chatkit-types 0.3.13 → 0.4.1

package/dist/index.d.ts

@@ -1097,10 +1097,21 @@ export declare type Icon = {
     size?: IconSize;
 };
 
+export declare type IconDefinition = {
+    type: IconType;
+    value: string;
+    color?: string;
+    size?: number;
+    alt?: string;
+    style?: Record<string, string>;
+};
+
 export declare type IconName = 'agent' | 'analytics' | 'atom' | 'batch' | 'bolt' | 'book-open' | 'book-closed' | 'bug' | 'calendar' | 'chart' | 'circle-question' | 'compass' | 'cube' | 'globe' | 'keys' | 'lab' | 'images' | 'lifesaver' | 'lightbulb' | 'map-pin' | 'name' | 'notebook' | 'notebook-pencil' | 'page-blank' | 'profile' | 'profile-card' | 'search' | 'sparkle' | 'sparkle-double' | 'square-code' | 'square-image' | 'square-text' | 'suitcase' | 'write' | 'write-alt' | 'write-alt2';
 
 declare type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
 
+export declare type IconType = 'image' | 'svg' | 'font' | 'emoji' | 'lottie';
+
 declare type Image_2 = {
     type: 'Image';
     key?: string;
@@ -1772,6 +1783,53 @@ export declare type Title = {
 
 declare type TitleSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl';
 
+/**
+ * CSP domains declared by an MCP App resource. The backend validates and
+ * normalizes these values before ChatKit applies them to the iframe response.
+ */
+export declare type TMcpAppCsp = {
+    connectDomains?: string[];
+    resourceDomains?: string[];
+    frameDomains?: string[];
+    baseUriDomains?: string[];
+};
+
+/**
+ * Permission grant value for browser features requested by an MCP App resource.
+ * A boolean is enough for simple allow/deny cases; object values preserve
+ * future protocol details without forcing ChatKit message migrations.
+ */
+export declare type TMcpAppPermissionGrant = boolean | Record<string, unknown>;
+
+/**
+ * Browser feature permissions requested by an MCP App resource. ChatKit should
+ * keep deny-by-default behavior and only translate supported grants to iframe
+ * `allow` attributes.
+ */
+export declare type TMcpAppPermissions = {
+    camera?: TMcpAppPermissionGrant;
+    microphone?: TMcpAppPermissionGrant;
+    geolocation?: TMcpAppPermissionGrant;
+    clipboardWrite?: TMcpAppPermissionGrant;
+};
+
+export declare type TMcpAppToolResult = {
+    content: TMcpAppToolResultContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+};
+
+export declare type TMcpAppToolResultContentBlock = Record<string, unknown> & {
+    type: string;
+};
+
+/**
+ * Declares who may use an MCP tool. `model` exposes the tool to the LLM;
+ * `app` allows the rendered MCP App iframe to call it through the host bridge.
+ */
+export declare type TMcpAppVisibility = 'model' | 'app';
+
 /**
  * Defines the data type of the sub-message of `component` type in the message `content` {@link MessageContentComplex}
  */
@@ -1791,6 +1849,68 @@ export declare type TMessageComponentIframe = {
     };
 };
 
+/**
+ * MCP App data embedded as a ChatKit component message.
+ */
+export declare type TMessageComponentMcpApp = TMessageComponent<TMessageComponentMcpAppData>;
+
+/**
+ * Safe metadata needed to render an MCP App message. Chat history stores this
+ * descriptor and the initial tool input/result only; the app HTML is fetched
+ * from the backend app instance using `appInstanceId`.
+ */
+export declare type TMessageComponentMcpAppData = {
+    /** Component discriminator used by ChatKit renderers. */
+    type: 'McpApp';
+    /** Short-lived host-side instance that scopes resource and bridge access. */
+    appInstanceId: string;
+    /** Signed host token used to revive and authorize this app instance. */
+    appInstanceToken?: string;
+    /** MCP resource URI, normally `ui://...`, used to load the app HTML. */
+    resourceUri: string;
+    /** Tool that produced this app surface. */
+    toolName: string;
+    /** Provider/model tool-call id associated with the triggering call. */
+    toolCallId?: string;
+    /** Xpert toolset id used for authorization and MCP client lookup. */
+    toolsetId?: string;
+    /** MCP server name within a multi-server toolset. */
+    serverName?: string;
+    /** Xpert execution id that produced this message component. */
+    executionId?: string;
+    /** Display title shown by the ChatKit shell around the app. */
+    title?: LocalizedText;
+    /** Optional display description shown by the ChatKit shell around the app. */
+    description?: LocalizedText;
+    /** Optional display icon shown by the ChatKit shell around the app. */
+    icon?: IconDefinition;
+    /** Resource-level content security policy metadata. */
+    csp?: TMcpAppCsp;
+    /** Resource-level browser permission metadata. */
+    permissions?: TMcpAppPermissions;
+    /** Optional dedicated origin requested by the resource; may be ignored by v1 hosts. */
+    domain?: string;
+    /** Resource hint for whether the host should render a visible border. */
+    prefersBorder?: boolean;
+    /** Original tool input sent to the MCP App via `ui/notifications/tool-input`. */
+    toolInput?: Record<string, unknown>;
+    /**
+     * Standardized initial CallToolResult used to replay MCP App history without
+     * re-running the originating tool. Raw app HTML is never persisted here.
+     */
+    toolResult?: TMcpAppToolResult;
+    /** Serialized byte size of the initial tool result when known. */
+    toolResultSize?: number;
+    /** True when the initial tool result was too large to inline in chat history. */
+    toolResultTruncated?: boolean;
+    /** Visibility declared by the originating MCP tool. */
+    visibility?: TMcpAppVisibility[];
+    /** Current lifecycle status of the tool/app message. */
+    status?: 'running' | 'success' | 'fail';
+    /** Human-readable error captured while creating or rendering the app. */
+    error?: string;
+};
+
 export declare type TMessageComponentStep<T = unknown> = {
     type: ChatMessageStepCategory;
     toolset: string;
@@ -1869,6 +1989,12 @@ export declare type TMessageContentComponent<T extends object = object> = {
     runId?: string;
 };
 
+/**
+ * MCP App component item in a LangChain-compatible complex message content
+ * array.
+ */
+export declare type TMessageContentMcpApp = TMessageContentComponent<TMessageComponentMcpAppData>;
+
 export declare type TMessageContentMemory = {
     id?: string;
     agentKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/chatkit-types",
-  "version": "0.3.13",
+  "version": "0.4.1",
   "description": "Type definitions for the ChatKit.",
   "sideEffects": false,
   "type": "module",