@wippy-fe/types-global-proxy 0.0.64 → 0.0.66

package/index.d.ts

@@ -58,7 +58,7 @@ interface HostComponentPanelDef extends HostPanelBase {
     tagName: string;
 }
 /**
- * Built-in panel ids shipped by gen-2-chat. The `@HOST/` prefix marks
+ * Built-in panel ids shipped by the Wippy Web Host. The `@HOST/` prefix marks
  * them as framework-owned so consumers can later plug in their own
  * `kind: 'builtin'` ids without colliding (and so the declaration
  * shows ownership at a glance).
@@ -348,100 +348,110 @@ type ApiRoutesOverride = {
     };
 };
 
-var chat = {
-	emptyState: {
-		title: "No chat session selected",
-		description: "Please select a session from the dropdown above or start a new conversation.",
-		goToHome: "Go to Home Page",
-		loadingAgents: "Loading agents...",
-		selectAgent: "Select Agent",
-		startChat: "Start Chat",
-		startChatError: "Failed to start chat",
-		noAgents: "No agents available. Please contact your administrator.",
-		dropFiles: "Drop files here to upload"
-	},
-	contextMenu: {
-		copyConversation: "Copy conversation",
-		copySelection: "Copy selection",
-		copySessionLink: "Copy session link",
-		copySessionJson: "Copy session JSON (debug)",
-		copied: "Copied",
-		copiedDetail: "Copied to clipboard",
-		copyFailed: "Copy failed",
-		copyFailedDetail: "Could not copy to clipboard",
-		nothingToCopy: "Nothing to copy yet"
-	}
-};
-var customPage = {
-	loading: {
-		title: "Loading page content..."
-	},
-	error: {
-		title: "Failed to load page content"
-	}
-};
-var home = {
-	loading: "Application is Loading",
-	error: {
-		title: "Error Loading Application"
-	},
-	noHomePage: {
-		title: "No Home Page Detected",
-		message: "Probably backend configuration is malformed"
-	}
-};
-var app = {
-	title: "Wippy App",
-	appName: "Wippy",
-	icon: "wippy:logo"
-};
-var login = {
-	error: {
-		title: "Session Token Expired",
-		description: "Your session has expired or is no longer valid. Please close this window and log in again to continue."
-	}
-};
-var logout = {
-	title: "Logout",
-	description: "Logging out..."
-};
-var keeper = {
-	controls: {
-		newChat: "New Chat",
-		searchAgents: "Search agents...",
-		undo: "Undo",
-		redo: "Redo",
-		download: "Registry To File System",
-		upload: "File System To Registry",
-		codeAssistant: "Wippy Code Assistant",
-		syncControls: "Sync Controls",
-		confirmUpload: {
-			title: "Confirm Upload",
-			message: "Do you wish to upload file system changes to registry? This will overwrite current state",
-			cancel: "Cancel",
-			upload: "Upload",
-			cancelled: {
-				title: "Upload cancelled",
-				message: "The upload operation was cancelled"
-			}
-		}
-	},
-	version: {
-		label: "Version:",
-		tooltip: "Version {{version}}"
-	}
-};
-var textRS = {
-	chat: chat,
-	customPage: customPage,
-	home: home,
-	app: app,
-	login: login,
-	logout: logout,
-	keeper: keeper
+declare const defaultLNG: "en";
+declare const defaultNS: "text";
+declare const resources: {
+    readonly en: {
+        readonly text: {
+            chat: {
+                emptyState: {
+                    title: string;
+                    description: string;
+                    goToHome: string;
+                    loadingAgents: string;
+                    selectAgent: string;
+                    startChat: string;
+                    startChatError: string;
+                    noAgents: string;
+                    dropFiles: string;
+                };
+                contextMenu: {
+                    copyConversation: string;
+                    copySelection: string;
+                    copySessionLink: string;
+                    copySessionJson: string;
+                    copied: string;
+                    copiedDetail: string;
+                    copyFailed: string;
+                    copyFailedDetail: string;
+                    nothingToCopy: string;
+                };
+            };
+            customPage: {
+                loading: {
+                    title: string;
+                };
+                error: {
+                    title: string;
+                };
+            };
+            home: {
+                loading: string;
+                error: {
+                    title: string;
+                };
+                noHomePage: {
+                    title: string;
+                    message: string;
+                };
+            };
+            app: {
+                title: string;
+                appName: string;
+                icon: string;
+            };
+            login: {
+                error: {
+                    title: string;
+                    description: string;
+                };
+            };
+            logout: {
+                title: string;
+                description: string;
+            };
+            keeper: {
+                controls: {
+                    newChat: string;
+                    searchAgents: string;
+                    undo: string;
+                    redo: string;
+                    download: string;
+                    upload: string;
+                    codeAssistant: string;
+                    syncControls: string;
+                    confirmUpload: {
+                        title: string;
+                        message: string;
+                        cancel: string;
+                        upload: string;
+                        cancelled: {
+                            title: string;
+                            message: string;
+                        };
+                    };
+                };
+                version: {
+                    label: string;
+                    tooltip: string;
+                };
+            };
+        };
+        readonly feature: {
+            session: {
+                type: string;
+            };
+            history: string;
+            env: {
+                APP_API_URL: string;
+                APP_AUTH_API_URL: string;
+                APP_WEBSOCKET_URL: string;
+            };
+        };
+        readonly css: {};
+    };
 };
-
-type I18NTextTypes = typeof textRS;
+type I18NTextTypes = (typeof resources)[typeof defaultLNG][typeof defaultNS];
 
 interface IconDef {
     body: string;
@@ -759,6 +769,128 @@ interface SanitizeOptions {
     extraTags?: Record<string, string[]>;
 }
 
+/** An error for one question. A form-level error that names an unknown question also has `field`. */
+interface ArtifactFormFieldError {
+    code: string;
+    message: string;
+    field?: string;
+}
+declare const ARTIFACT_STATE_ERROR_BRAND: unique symbol;
+/**
+ * Rejection type of `artifactState()` calls. Prefer `isArtifactStateError()`:
+ * each proxy bundle carries its own copy of this class, so `instanceof` fails
+ * for an error thrown by another bundle.
+ */
+declare class ArtifactStateError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly errors?: Record<string, ArtifactFormFieldError[]>;
+    readonly formErrors?: ArtifactFormFieldError[];
+    readonly [ARTIFACT_STATE_ERROR_BRAND] = true;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        errors?: Record<string, ArtifactFormFieldError[]>;
+        formErrors?: ArtifactFormFieldError[];
+        cause?: unknown;
+    });
+}
+
+interface ArtifactFormFieldOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+interface ArtifactFormField {
+    id: string;
+    type: 'choice';
+    label: string;
+    description?: string;
+    required: boolean;
+    options: ArtifactFormFieldOption[];
+    multiple: boolean;
+    allow_other: boolean;
+}
+interface ArtifactFormDefinition {
+    title: string;
+    description?: string;
+    submit_label?: string;
+    /** The text of the user's chat message once the form is answered. The form never shows it. */
+    answered_message?: string;
+    fields: ArtifactFormField[];
+}
+/**
+ * One answer to a choice: a listed option, a listed option with the user's
+ * note, or text the user wrote instead of an option. A stored answer with a
+ * note always has `note`, and a submitted one may leave it out.
+ */
+type ArtifactFormChoiceAnswer = string | {
+    value: string;
+    note?: string;
+} | {
+    other: string;
+};
+/** The answer to one field. A `multiple` field takes a list of choices. */
+type ArtifactFormAnswerValue = ArtifactFormChoiceAnswer | ArtifactFormChoiceAnswer[];
+type ArtifactFormAnswers = Record<string, ArtifactFormAnswerValue>;
+/**
+ * Where an accepted answer is on its way to the agent.
+ *
+ * - `pending`: the session has not taken the answer yet.
+ * - `running`: the session took it and the agent is working on it.
+ * - `complete`: the agent replied after the answer.
+ * - `interrupted`: the turn was stopped, or failed, before a reply.
+ */
+type ArtifactFormDelivery = 'pending' | 'running' | 'complete' | 'interrupted';
+/** GET `artifacts.state` response body. */
+interface ArtifactFormState {
+    form_version: number;
+    artifact_id: string;
+    session_id: string;
+    status: 'active' | 'idle';
+    /** Only for an `active` form: another user message came after the form was created. */
+    stale: boolean;
+    late: boolean;
+    content_version: number;
+    definition: ArtifactFormDefinition;
+    data: ArtifactFormAnswers | null;
+    submitted_at: string | null;
+    answer_message_id: string | null;
+    /** `null` until the form is answered. */
+    delivery: ArtifactFormDelivery | null;
+}
+/** POST `artifacts.state` request body. */
+interface ArtifactFormSubmitEnvelope {
+    /** The `form_version` of the state the answers belong to. */
+    form_version: number;
+    request_id: string;
+    /**
+     * The `content_version` the form was loaded at. The server answers 409
+     * `version_conflict` when it has changed since. Without it the server skips
+     * that check.
+     */
+    expected_content_version?: number;
+    answers: ArtifactFormAnswers;
+}
+/** POST `artifacts.state` success (200) response body. */
+interface ArtifactFormSubmitResult {
+    success: true;
+    artifact_id: string;
+    request_id: string;
+    answer_message_id: string;
+    content_version: number;
+    status: 'idle';
+    late: boolean;
+    /** `pending` for a new answer. An exact replay reports the current delivery. */
+    delivery: ArtifactFormDelivery;
+    /** `true` when this was an exact replay of an earlier request (same `request_id` and answers). */
+    replayed: boolean;
+}
+interface ArtifactStateClient {
+    get: () => Promise<ArtifactFormState>;
+    submit: (envelope: ArtifactFormSubmitEnvelope) => Promise<ArtifactFormSubmitResult>;
+}
+
 interface AttentionInspectionApi {
     subscribe: (options: AttentionSubscriptionOptions, listener: (notification: AttentionNotification) => void) => AttentionSubscription;
     getCursor: (scope?: AttentionInspectionScope) => Promise<AttentionInspectionResult>;
@@ -965,7 +1097,8 @@ interface Artifact {
     type: ArtifactType;
     /** The content of the artifact, which can be HTML, Markdown, or JSON with wippy specific package.json info */
     content_type: 'text/html' | 'text/markdown' | 'application/json';
-    content_version?: string;
+    /** Revision number. Set it through {@link normalizeArtifactFields}, so a legacy numeric string becomes a number. */
+    content_version?: number;
     status: ArtifactStatus;
 }
 
@@ -1064,6 +1197,8 @@ declare enum WsMessageType {
     CONTENT = "content",
     /** Contains content of the message to append to current one */
     CHUNK = "chunk",
+    /** Reasoning text that a thinking model streams before its reply. The chat does not show it. */
+    THINKING = "thinking",
     /** User message with contents */
     USER = "received",
     /** Response started, can create a message placeholder */
@@ -1165,11 +1300,22 @@ interface WsMessageDataChunk extends WsMessageDataBase {
     type: WsMessageType.CHUNK;
     content: string;
 }
+/** Reasoning text that a thinking model streams before its reply. */
+interface WsMessageDataThinking extends WsMessageDataBase {
+    type: WsMessageType.THINKING;
+    content?: string;
+}
 interface WsMessageDataContent extends WsMessageDataBase {
     type: WsMessageType.CONTENT;
     content: string;
     message_id: MessageUUID;
     file_uuids?: string[];
+    /**
+     * The message's own timestamp (RFC3339), matching `messages.date` in the
+     * REST history — i.e. when the reply was produced, not when its turn
+     * started. Optional: older backends, and any other event type, omit it.
+     */
+    date?: string;
 }
 interface WsMessageDataUser extends WsMessageDataBase {
     type: WsMessageType.USER;
@@ -1238,6 +1384,10 @@ interface WsMessageDataToolError extends WsMessageDataBase {
     type: WsMessageType.TOOL_ERROR | WsMessageType.FUNCTION_ERROR;
     function_name: string;
     artifact_id?: string;
+    message_id?: string;
+    call_id?: string;
+    /** Set to cancelled when Stop, a failed turn, a handoff or a command bus failure cancelled the call. */
+    outcome?: 'cancelled';
 }
 interface WsMessageDataError extends WsMessageDataBase {
     type: WsMessageType.ERROR;
@@ -1246,7 +1396,7 @@ interface WsMessageDataError extends WsMessageDataBase {
 }
 interface WsMessage_SessionMessage extends WsMessageBase {
     topic: WsTopicTypes['SessionMessage'];
-    data: (WsMessageDataUser | WsMessageDataContent | WsMessageDataChunk | WsMessageDataDelegation | WsMessageDataToolCall | WsMessageDataError | WsMessageDataInvalidate | WsMessageDataStarted | WsMessageDataToolSuccess | WsMessageDataArtifact | WsMessageDataToolError | WsMessageDataUpdate) & {
+    data: (WsMessageDataUser | WsMessageDataContent | WsMessageDataChunk | WsMessageDataThinking | WsMessageDataDelegation | WsMessageDataToolCall | WsMessageDataError | WsMessageDataInvalidate | WsMessageDataStarted | WsMessageDataToolSuccess | WsMessageDataArtifact | WsMessageDataToolError | WsMessageDataUpdate) & {
         request_id?: string;
     };
 }
@@ -1488,7 +1638,7 @@ interface LayoutApi {
     on: (channel: string, handler: (env: BroadcastEnvelope) => void) => () => void;
 }
 
-type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error' | '@layout-change' | '@layout-breakpoint' | '@theme' | '@config';
+type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error' | '@layout-change' | '@layout-breakpoint' | '@theme' | '@config' | '@reconnect';
 type Events = {
     /** Effective child config changed; the injected config is refreshed before this fires. */
     '@config': () => void;
@@ -1510,6 +1660,12 @@ type Events = {
     }) => void;
     /** Accepted theme mode changed in the resolved application config. */
     '@theme': (mode: 'auto' | 'light' | 'dark') => void;
+    /**
+     * The host's WebSocket reconnected after a genuine drop.
+     * No payload — anything that depends on live session/artifact state
+     * should refetch it. See iframe-proxy.md next to `@visibility`.
+     */
+    '@reconnect': () => void;
 } & {
     [K in string as K extends KnownTopics ? never : K]: (data: WsMessage) => void;
 };
@@ -1710,6 +1866,14 @@ interface ProxyApiInstance {
         get: () => Promise<FormState>;
         submit: (data: FormData | Record<string, unknown>) => Promise<FormResult>;
     };
+    /**
+     * Typed client for the session-forms artifact state route
+     * (`artifacts.state` = `/api/v1/artifact/{artifactId}/state`). Resolves
+     * route overrides fresh on every call and throws a real `ArtifactStateError`
+     * (HTTP status + code + field errors) instead of fabricating data on
+     * failure — see `iframe-proxy.md#artifact-state-forms`.
+     */
+    artifactState: (artifactId: string) => ArtifactStateClient;
     /**
      * Subscribe to events. Returns an unsubscribe function that MUST be called
      * on component unmount to prevent subscription leaks.
@@ -1749,6 +1913,29 @@ interface ProxyApiInstance {
      */
     sanitize: (html: string, opts?: SanitizeOptions) => string;
 }
+/** The `window.$W` global of a srcdoc iframe page. Each accessor resolves one member of the realm's `ProxyApiInstance`. */
+interface ProxyGlobalApi {
+    config: () => Promise<ChildAppConfig>;
+    instance: () => Promise<ProxyApiInstance>;
+    api: () => Promise<ProxyApiInstance['api']>;
+    attention: () => Promise<ProxyApiInstance['attention']>;
+    /** @deprecated Use `$W.api` instead */
+    form: () => Promise<ProxyApiInstance['api']>;
+    host: () => Promise<ProxyApiInstance['host']>;
+    /** @deprecated Use `$W.host` instead */
+    iframe: () => Promise<ProxyApiInstance['host']>;
+    on: () => Promise<ProxyApiInstance['on']>;
+    logger: () => Promise<ProxyApiInstance['logger']>;
+    state: () => Promise<ProxyApiInstance['state']>;
+    ws: () => Promise<ProxyApiInstance['ws']>;
+    loadWebComponent: () => Promise<ProxyApiInstance['loadWebComponent']>;
+    loadByTagName: () => Promise<ProxyApiInstance['loadByTagName']>;
+    sanitize: () => Promise<ProxyApiInstance['sanitize']>;
+    html: () => Promise<ProxyApiInstance['html']>;
+    artifactState: () => Promise<ProxyApiInstance['artifactState']>;
+    /** Same check as isArtifactStateError from @wippy-fe/proxy. */
+    isArtifactStateError: (value: unknown) => value is ArtifactStateError;
+}
 
 declare global {
     interface Window {
@@ -1798,25 +1985,7 @@ declare global {
          * @deprecated
          */
         initWippyApi: () => Promise<ProxyApiInstance>;
-        $W: {
-            config: () => Promise<ChildAppConfig>;
-            instance: () => Promise<ProxyApiInstance>;
-            api: () => Promise<ProxyApiInstance['api']>;
-            attention: () => Promise<ProxyApiInstance['attention']>;
-            /** @deprecated Use `$W.api` instead */
-            form: () => Promise<ProxyApiInstance['api']>;
-            host: () => Promise<ProxyApiInstance['host']>;
-            /** @deprecated Use `$W.host` instead */
-            iframe: () => Promise<ProxyApiInstance['host']>;
-            on: () => Promise<ProxyApiInstance['on']>;
-            logger: () => Promise<ProxyApiInstance['logger']>;
-            state: () => Promise<ProxyApiInstance['state']>;
-            ws: () => Promise<ProxyApiInstance['ws']>;
-            loadWebComponent: () => Promise<ProxyApiInstance['loadWebComponent']>;
-            loadByTagName: () => Promise<ProxyApiInstance['loadByTagName']>;
-            sanitize: () => Promise<ProxyApiInstance['sanitize']>;
-            html: () => Promise<ProxyApiInstance['html']>;
-        };
+        $W: ProxyGlobalApi;
         tailwind?: {
             config: Partial<typeof _default>;
         };
@@ -1826,8 +1995,7 @@ declare global {
 
 // Augment axios's request config so consumers can opt out of the proxy
 // api's default auth handling on a per-request basis. The proxy's createApi
-// reads `skipDefaultAuth` in both the request and response interceptors;
-// see `gen-2-chat:src/proxy/shared/api.ts` for the runtime semantics.
+// reads `skipDefaultAuth` in both the request and response interceptors.
 declare module 'axios' {
     interface AxiosRequestConfig {
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/types-global-proxy",
-  "version": "0.0.64",
+  "version": "0.0.66",
   "description": "Global type declarations for Wippy iframe proxy (window.getWippyApi, $W, etc.)",
   "license": "UNLICENSED",
   "types": "index.d.ts",