@wippy-fe/proxy

ESM proxy module for Wippy web components. Provides authenticated API access, host communication, event subscriptions, state persistence, and WebSocket send through the Wippy host.

Usage

import { api, host, on, state, ws } from '@wippy-fe/proxy'

// Authenticated HTTP requests
const response = await api.get('/api/v1/users')

// Host communication
host.startChat('my-token', { sidebar: true })
host.navigate('/some-page')
host.toast({ severity: 'success', summary: 'Done' })

// Real-time event subscriptions
on('session:*:message:*', (msg) => console.log(msg))
on('@visibility', (visible) => console.log('Visible:', visible))

// State persistence (survives iframe destruction)
await state.set('filters', { search: 'john' })
const filters = await state.get('filters')

// WebSocket commands
ws.send({ type: 'session_message', session_id: 'id', message_id: 'mid', data: { text: 'Hello' } })
ws.sendCommand('session-id', { command: 'stop' })
const result = await ws.sendWithResponse({ type: 'session_open', start_token: 'token' })

Exports

| Export | Type | Description | |--------|------|-------------| | api | AxiosInstance | Authenticated HTTP client | | host | ProxyHostApi | Host communication (chat, navigation, toasts, dialogs) | | on | EventSubscriber | Real-time event subscription (WebSocket topics, @history, @visibility) | | state | StateApi | Host-mediated key-value state persistence | | ws | ProxyWsApi | WebSocket send bridge (send, sendWithResponse, sendCommand) | | config | AppConfig | Application configuration | | loadWebComponent | Function | Dynamically load other web components | | define | Function | Auto-register web component from import meta URL | | hostCss | Object | URLs to host-provided CSS (fonts, theme, PrimeVue, markdown) | | loadCss | Function | Fetch CSS text from a URL | | tailwindConfig | Object | Shared Tailwind config preset | | addIcons | Function | Register custom Iconify icon collections |

Iframe variant

For srcdoc iframes, the proxy is injected as proxy.js (UMD) and accessed via window.getWippyApi() or window.$W.*. See iframe-proxy.md for the full reference.

TypeScript

Types are provided via index.d.mts. For iframe global declarations (window.getWippyApi, $W), install @wippy-fe/types-global-proxy as a dev dependency.