@wippy-fe/types-global-proxy 0.0.16 → 0.0.18

package/README.md

@@ -0,0 +1,39 @@
+# @wippy-fe/types-global-proxy
+
+TypeScript ambient declarations for the Wippy iframe proxy globals.
+
+## Installation
+
+```bash
+npm install -D @wippy-fe/types-global-proxy
+```
+
+## What it declares
+
+- `window.getWippyApi()` — returns `Promise<ProxyApiInstance>`
+- `window.$W.*` — lazy async accessors for `config`, `api`, `host`, `on`, `state`, `ws`, `loadWebComponent`
+- `window.__WIPPY_APP_CONFIG__` — `AppConfig`
+- `window.__WIPPY_APP_API__` — `ProxyApiInstance`
+- `window.__WIPPY_PROXY_CONFIG__` — `ProxyConfig`
+
+## Exported types
+
+`ProxyApiInstance`, `AppConfig`, `AppFeatures`, `AppCustomization`, `StateApi`, `ProxyWsApi`, `WsMessage`, `WsCommand`, `Artifact`, `PageApi`, `UploadApi`, `ApiRoutes`, and all WebSocket message/topic types.
+
+## Usage
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@wippy-fe/types-global-proxy"]
+  }
+}
+```
+
+Or use a triple-slash reference:
+
+```typescript
+/// <reference types="@wippy-fe/types-global-proxy" />
+```

package/index.d.ts

@@ -4,6 +4,284 @@ import { ConfirmationOptions } from 'primevue/confirmationoptions';
 import { ToastMessageOptions } from 'primevue/toast';
 import * as tailwindcss_types_config from 'tailwindcss/types/config';
 
+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"
+	}
+};
+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
+};
+
+type I18NTextTypes = typeof textRS;
+
+/**
+ * All API route templates, grouped by domain.
+ * Dynamic path segments use `{paramName}` placeholders (OpenAPI-style).
+ * Each leaf value is a flat, fully-formed route — no concatenation needed at call site.
+ *
+ * Internally, routes use `@/…` shorthand that resolves against the group's `@prefix`.
+ * Resolution happens once inside `getApiRoutes()`, so consumers always receive clean strings.
+ *
+ * Base URL resolution:
+ * - HTTP routes: `getEnv().APP_API_URL` + route  (handled by axios baseURL)
+ * - WebSocket:   `getEnv().APP_WEBSOCKET_URL` + `getApiRoutes().ws.join`  (composed in ws/client.ts)
+ */
+interface ApiRoutes {
+    agents: {
+        list: string;
+        details: string;
+        byName: string;
+    };
+    sessions: {
+        list: string;
+        get: string;
+        messages: string;
+    };
+    models: {
+        list: string;
+        byName: string;
+    };
+    uploads: {
+        list: string;
+        get: string;
+        create: string;
+    };
+    artifacts: {
+        get: string;
+        content: string;
+        state: string;
+        baseUrl: string;
+    };
+    pages: {
+        list: string;
+        get: string;
+        content: string;
+        baseUrl: string;
+    };
+    registry: {
+        namespaces: string;
+        entries: string;
+        entry: string;
+        entryCreate: string;
+        entryEditors: string;
+        versions: string;
+        versionApply: string;
+    };
+    keeperSync: {
+        state: string;
+        download: string;
+        upload: string;
+        undo: string;
+        redo: string;
+    };
+    components: {
+        list: string;
+    };
+    tools: {
+        byName: string;
+    };
+    ws: {
+        join: string;
+    };
+}
+/**
+ * Override type for `AppConfig.feature.apiRoutes`.
+ *
+ * Each group is optional and partially overridable.
+ * Set `@prefix` to rebase all `@/…` routes in that group at once,
+ * or override individual routes with absolute paths.
+ */
+type ApiRoutesOverride = {
+    [K in keyof ApiRoutes]?: Partial<ApiRoutes[K]> & {
+        '@prefix'?: string;
+    };
+};
+
+interface IconDef {
+    body: string;
+    width: number;
+    height: number;
+}
+interface CssVariablesMap {
+    [key: string]: string | Record<string, string> | undefined;
+    '@dark'?: Record<string, string>;
+    '@light'?: Record<string, string>;
+}
+interface AppAuthConfig {
+    token: string;
+    expiresAt: string;
+}
+interface ThemingScope {
+    cssVariables?: CssVariablesMap;
+    customCSS?: string;
+    /** @deprecated Use `iconSets` instead */
+    icons?: Record<string, IconDef>;
+    /** Named icon collections. Each key is an Iconify prefix. */
+    iconSets?: Record<string, Record<string, IconDef>>;
+}
+interface HostThemingScope extends ThemingScope {
+    i18n?: Partial<I18NTextTypes>;
+}
+interface ChildrenThemingScope {
+    cssVariables?: CssVariablesMap;
+    customCSS?: string;
+}
+interface AppCustomization {
+    customCSS?: string;
+    cssVariables?: CssVariablesMap;
+    i18n?: Partial<I18NTextTypes>;
+    /** @deprecated Use `iconSets` instead. Icons registered under the 'custom' prefix. */
+    icons?: Record<string, IconDef>;
+    /** Named icon collections. Each key is an Iconify prefix, value is a map of icon name → definition. */
+    iconSets?: Record<string, Record<string, IconDef>>;
+}
+interface HostConfig {
+    showAdmin?: boolean;
+    allowSelectModel?: boolean;
+    startNavOpen?: boolean;
+    hideNavBar?: boolean;
+    disableRightPanel?: boolean;
+    hideSessionSelector?: boolean;
+    additionalNavItems?: Array<PageApi.Page>;
+    chat?: {
+        convertPasteToFile?: {
+            enabled: boolean;
+            minFileSize: number;
+            allowHtml: boolean;
+        };
+    };
+    apiRoutes?: ApiRoutesOverride;
+    stateCache?: {
+        maxPages?: number;
+        maxSizePerPage?: number;
+    };
+    allowAdditionalTags?: Record<string, string[]>;
+    session?: {
+        type: 'non-persistent' | 'cookie';
+    };
+    history?: 'browser' | 'hash';
+}
+interface AppContext {
+    resourceId: string;
+    resourceType: 'page' | 'artifact';
+    route?: string;
+    parentResourceId?: string;
+    nestingDepth?: number;
+    layoutPanelId?: string;
+    layoutId?: string;
+    extensions?: Record<string, unknown>;
+}
+interface AppEnv {
+    APP_API_URL: string;
+    APP_AUTH_API_URL: string;
+    APP_WEBSOCKET_URL: string;
+}
+interface AppConfig {
+    $schema: string;
+    auth: AppAuthConfig;
+    env: AppEnv;
+    axiosDefaults?: Partial<AxiosDefaults>;
+    routePrefix?: string;
+    theming: {
+        global?: ThemingScope;
+        host?: HostThemingScope;
+        children?: ChildrenThemingScope;
+    };
+    hostConfig: HostConfig;
+    context: AppContext;
+}
+interface ChildAppConfig {
+    $schema: string;
+    auth: AppAuthConfig;
+    env: AppEnv;
+    axiosDefaults?: Partial<AxiosDefaults>;
+    routePrefix?: string;
+    apiRoutes?: ApiRoutesOverride;
+    customization: AppCustomization;
+    context: AppContext;
+    configOverrides?: AppConfigOverrides;
+}
+interface AppConfigOverrides {
+    customization?: Partial<AppCustomization>;
+    axiosDefaults?: Partial<AxiosDefaults>;
+    routePrefix?: string;
+    apiRoutes?: ApiRoutesOverride;
+}
+
 declare namespace PageApi {
     interface Page {
         icon: string;
@@ -23,6 +301,8 @@ declare namespace PageApi {
         content_version?: string;
         /** The content of the page artifact, which can be HTML, Markdown, or JSON with wippy specific package.json info */
         content_type?: 'text/html' | 'text/markdown' | 'application/json';
+        /** Per-page config overrides — merged into AppConfig before CSS injection. Populated from registry entry config_overrides. */
+        configOverrides?: AppConfigOverrides;
     }
     interface PagesResponse {
         count: number;
@@ -402,6 +682,57 @@ interface WsMessage_Upload extends WsMessageBase {
 }
 type WsMessage = WsMessage_Welcome | WsMessage_Pages | WsMessage_Page | WsMessage_SessionMessage | WsMessage_Session | WsMessage_SessionClosed | WsMessage_Error | WsMessage_Artifact | WsMessage_SessionOpen | WsMessage_Action | WsMessage_Registry | WsMessage_RegistryEntry | WsMessage_Upload;
 
+interface BaseWsCommand {
+    type: string;
+    /**
+     * If used, WsService will await a response with the same request_id
+     */
+    request_id?: string;
+}
+interface SessionOpenCommand extends BaseWsCommand {
+    type: 'session_open';
+    session_id?: string;
+    start_token?: string;
+}
+interface SessionCloseCommand extends BaseWsCommand {
+    type: 'session_close';
+    session_id: string;
+}
+interface SessionMessageCommand extends BaseWsCommand {
+    type: 'session_message';
+    session_id: string;
+    message_id: string;
+    data: {
+        text: string;
+        file_uuids?: string[];
+    };
+}
+interface SessionCommandCommand extends BaseWsCommand {
+    type: 'session_command';
+    session_id: string;
+    data: StopCommand | ModelCommand | OtherCommand | AgentCommand;
+}
+interface StopCommand {
+    command: 'stop';
+}
+interface ModelCommand {
+    command: 'model';
+    name: string;
+}
+interface AgentCommand {
+    command: 'agent';
+    name: string;
+}
+interface ExternalEventCommand extends BaseWsCommand {
+    type: string;
+    data: Record<string, unknown>;
+}
+interface OtherCommand {
+    command: string;
+    [key: string]: unknown;
+}
+type WsCommand = SessionOpenCommand | SessionCloseCommand | SessionMessageCommand | SessionCommandCommand | ExternalEventCommand;
+
 type KnownTopics = '@history' | '@visibility' | '@message' | '@state-error';
 type Events = {
     /** Emitted when pages are updated */
@@ -431,283 +762,25 @@ interface StateApi {
     getAll: (options?: StateApiOptions) => Promise<Record<string, unknown>>;
 }
 
-var session = {
-	type: "non-persistent"
-};
-var history = "browser";
-var env = {
-	APP_API_URL: "",
-	APP_AUTH_API_URL: "",
-	APP_WEBSOCKET_URL: ""
-};
-var featureRS = {
-	session: session,
-	history: history,
-	env: env
-};
-
-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"
-	}
-};
-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
-};
-
-type I18NFeatureTypes = typeof featureRS;
-type I18NTextTypes = typeof textRS;
-
-/**
- * All API route templates, grouped by domain.
- * Dynamic path segments use `{paramName}` placeholders (OpenAPI-style).
- * Each leaf value is a flat, fully-formed route — no concatenation needed at call site.
- *
- * Internally, routes use `@/…` shorthand that resolves against the group's `@prefix`.
- * Resolution happens once inside `getApiRoutes()`, so consumers always receive clean strings.
- *
- * Base URL resolution:
- * - HTTP routes: `getEnv().APP_API_URL` + route  (handled by axios baseURL)
- * - WebSocket:   `getEnv().APP_WEBSOCKET_URL` + `getApiRoutes().ws.join`  (composed in ws/client.ts)
- */
-interface ApiRoutes {
-    agents: {
-        list: string;
-        details: string;
-        byName: string;
-    };
-    sessions: {
-        list: string;
-        get: string;
-        messages: string;
-    };
-    models: {
-        list: string;
-        byName: string;
-    };
-    uploads: {
-        list: string;
-        get: string;
-        create: string;
-    };
-    artifacts: {
-        get: string;
-        content: string;
-        state: string;
-        baseUrl: string;
-    };
-    pages: {
-        list: string;
-        get: string;
-        content: string;
-        baseUrl: string;
-    };
-    registry: {
-        namespaces: string;
-        entries: string;
-        entry: string;
-        entryCreate: string;
-        entryEditors: string;
-        versions: string;
-        versionApply: string;
-    };
-    keeperSync: {
-        state: string;
-        download: string;
-        upload: string;
-        undo: string;
-        redo: string;
-    };
-    components: {
-        list: string;
-    };
-    tools: {
-        byName: string;
-    };
-    ws: {
-        join: string;
-    };
-}
-/**
- * Override type for `AppConfig.feature.apiRoutes`.
- *
- * Each group is optional and partially overridable.
- * Set `@prefix` to rebase all `@/…` routes in that group at once,
- * or override individual routes with absolute paths.
- */
-type ApiRoutesOverride = {
-    [K in keyof ApiRoutes]?: Partial<ApiRoutes[K]> & {
-        '@prefix'?: string;
-    };
-};
-
-interface AppFeatures extends I18NFeatureTypes {
-    /**
-     * If to remember auth details or not
-     */
-    session: {
-        type: 'non-persistent' | 'cookie';
-    };
-    history: 'browser' | 'hash';
-    env: {
-        APP_API_URL: string;
-        APP_AUTH_API_URL: string;
-        APP_WEBSOCKET_URL: string;
-    };
-    axiosDefaults?: Partial<AxiosDefaults>;
-    routePrefix?: string;
-    showAdmin?: boolean;
-    allowSelectModel?: boolean;
-    startNavOpen?: boolean;
-    hideNavBar?: boolean;
-    disableRightPanel?: boolean;
-    /**
-     * Hide the session selector dropdown in chat views
-     * @default false
-     */
-    hideSessionSelector?: boolean;
-    additionalNavItems?: Array<PageApi.Page>;
-    chat?: {
-        convertPasteToFile?: {
-            enabled: boolean;
-            minFileSize: number;
-            allowHtml: boolean;
-        };
-    };
-    apiRoutes?: ApiRoutesOverride;
-    /**
-     * Additional HTML tags to whitelist in the sanitizer.
-     * Map of tag name to allowed attribute names.
-     * 'class' is always implicitly allowed for every tag.
-     */
-    allowAdditionalTags?: Record<string, string[]>;
+interface ProxyWsApi {
     /**
-     * LRU cache configuration for child iframe state preservation.
-     * @default { maxPages: 50, maxSizePerPage: 2097152 }
+     * Send a raw WebSocket command through the host's WebSocket connection.
+     * Fire-and-forget — responses arrive via `on()` event subscriptions.
      */
-    stateCache?: {
-        /** Maximum number of page/artifact state buckets to keep. @default 50 */
-        maxPages?: number;
-        /** Maximum JSON-serialized size per page in bytes. @default 2097152 (2 MB) */
-        maxSizePerPage?: number;
-    };
-}
-interface AppAuthConfig {
-    token: string;
-    expiresAt: string;
-}
-interface CssVariablesMap {
-    [key: string]: string | Record<string, string> | undefined;
-    '@dark'?: Record<string, string>;
-    '@light'?: Record<string, string>;
-}
-interface AppCustomization {
-    customCSS?: string;
-    cssVariables?: CssVariablesMap;
-    i18n?: Partial<I18NTextTypes>;
-    icons?: Record<string, {
-        body: string;
-        width: number;
-        height: number;
-    }>;
-}
-interface AppConfig {
-    artifactId?: string;
+    send: (command: WsCommand) => void;
     /**
-     * Starting app or artifact/page path
+     * Send a WebSocket command and wait for the server's response.
+     * The command is sent with a `request_id`; the promise resolves when the server echoes it back.
+     * Times out after 30 seconds.
      */
-    path?: string;
+    sendWithResponse: (command: WsCommand) => Promise<WsMessage>;
     /**
-     * App features like history mode, session type, etc.
+     * Convenience method to send a session command (stop, model, agent, etc.)
      */
-    feature?: AppFeatures;
-    /**
-     * Auth configuration
-     */
-    auth: AppAuthConfig;
-    /**
-     * App customization like i18n texts, css variables, custom css, etc.
-     */
-    customization?: AppCustomization;
-    externalEvents?: {
-        enabled: boolean;
-        wsType: string;
-        allowedOrigins: string[];
-        allowedTypes: string[];
-    };
+    sendCommand: (sessionId: string, data: {
+        command: string;
+        [key: string]: unknown;
+    }) => void;
 }
 
 interface FormState {
@@ -721,7 +794,7 @@ interface FormResult {
 }
 type LimitedConfirmationOptions = Omit<ConfirmationOptions, 'target' | 'appendTo' | 'onShow' | 'onHide'>;
 interface ProxyApiInstance {
-    config: AppConfig;
+    config: ChildAppConfig;
     /** @deprecated, use `host` instead */
     iframe: {
         toast: (message: ToastMessageOptions) => void;
@@ -769,6 +842,7 @@ interface ProxyApiInstance {
     };
     on: ReturnType<typeof createEvents>;
     state: StateApi;
+    ws: ProxyWsApi;
     loadWebComponent: (componentId: string, tagName?: string) => Promise<void>;
 }
 
@@ -795,13 +869,15 @@ interface ProxyConfig {
 
 declare const GLOBAL_CONFIG_VAR: "__WIPPY_APP_CONFIG__";
 declare const GLOBAL_PROXY_CONFIG_VAR: "__WIPPY_PROXY_CONFIG__";
+declare const GLOBAL_CONFIG_OVERRIDES_VAR: "__WIPPY_CONFIG_OVERRIDES__";
 declare const GLOBAL_API_PROVIDER: "__WIPPY_APP_API__";
 declare const GLOBAL_WEB_COMPONENT_CACHE: "__WIPPY_WEB_COMPONENT_CACHE__";
 declare global {
     interface Window {
-        [GLOBAL_CONFIG_VAR]: AppConfig;
+        [GLOBAL_CONFIG_VAR]: AppConfig | ChildAppConfig;
         [GLOBAL_API_PROVIDER]: ProxyApiInstance;
         [GLOBAL_PROXY_CONFIG_VAR]?: ProxyConfig;
+        [GLOBAL_CONFIG_OVERRIDES_VAR]?: AppConfigOverrides;
         [GLOBAL_WEB_COMPONENT_CACHE]: Record<string, {
             usedAt: number;
             data: string;
@@ -845,7 +921,7 @@ declare global {
          */
         initWippyApi: () => Promise<ProxyApiInstance>;
         $W: {
-            config: () => Promise<AppConfig>;
+            config: () => Promise<ChildAppConfig>;
             instance: () => Promise<ProxyApiInstance>;
             api: () => Promise<ProxyApiInstance['api']>;
             /** @deprecated Use `$W.api` instead */
@@ -855,6 +931,7 @@ declare global {
             iframe: () => Promise<ProxyApiInstance['host']>;
             on: () => Promise<ProxyApiInstance['on']>;
             state: () => Promise<ProxyApiInstance['state']>;
+            ws: () => Promise<ProxyApiInstance['ws']>;
             loadWebComponent: () => Promise<ProxyApiInstance['loadWebComponent']>;
         };
         tailwind?: {

package/package.json

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