@stina/extension-api 0.7.1 → 0.8.1

package/src/runtime.ts

@@ -13,11 +13,21 @@ import type {
   SettingsAPI,
   ProvidersAPI,
   ToolsAPI,
+  ActionsAPI,
+  EventsAPI,
+  SchedulerAPI,
+  SchedulerJobRequest,
+  SchedulerFirePayload,
+  UserAPI,
+  UserProfile,
+  ChatAPI,
+  ChatInstructionMessage,
   DatabaseAPI,
   StorageAPI,
   LogAPI,
   AIProvider,
   Tool,
+  Action,
   ChatMessage,
   ChatOptions,
   GetModelsOptions,
@@ -81,7 +91,9 @@ let extensionContext: ExtensionContext | null = null
 const pendingRequests = new Map<string, PendingRequest>()
 const registeredProviders = new Map<string, AIProvider>()
 const registeredTools = new Map<string, Tool>()
+const registeredActions = new Map<string, Action>()
 const settingsCallbacks: Array<(key: string, value: unknown) => void> = []
+const schedulerCallbacks: Array<(payload: SchedulerFirePayload) => void> = []
 
 const REQUEST_TIMEOUT = 30000 // 30 seconds
 
@@ -136,6 +148,10 @@ async function handleHostMessage(message: HostToWorkerMessage): Promise<void> {
       handleSettingsChanged(message.payload.key, message.payload.value)
       break
 
+    case 'scheduler-fire':
+      handleSchedulerFire(message.payload)
+      break
+
     case 'provider-chat-request':
       await handleProviderChatRequest(message.id, message.payload)
       break
@@ -148,6 +164,10 @@ async function handleHostMessage(message: HostToWorkerMessage): Promise<void> {
       await handleToolExecuteRequest(message.id, message.payload)
       break
 
+    case 'action-execute-request':
+      await handleActionExecuteRequest(message.id, message.payload)
+      break
+
     case 'response':
       handleResponse(message.payload)
       break
@@ -218,7 +238,9 @@ async function handleDeactivate(): Promise<void> {
     extensionContext = null
     registeredProviders.clear()
     registeredTools.clear()
+    registeredActions.clear()
     settingsCallbacks.length = 0
+    schedulerCallbacks.length = 0
   }
 }
 
@@ -232,6 +254,16 @@ function handleSettingsChanged(key: string, value: unknown): void {
   }
 }
 
+function handleSchedulerFire(payload: SchedulerFirePayload): void {
+  for (const callback of schedulerCallbacks) {
+    try {
+      callback(payload)
+    } catch (error) {
+      console.error('Error in scheduler callback:', error)
+    }
+  }
+}
+
 // ============================================================================
 // Provider / Tool Requests
 // ============================================================================
@@ -373,6 +405,45 @@ async function handleToolExecuteRequest(
   }
 }
 
+async function handleActionExecuteRequest(
+  requestId: string,
+  payload: { actionId: string; params: Record<string, unknown> }
+): Promise<void> {
+  const action = registeredActions.get(payload.actionId)
+  if (!action) {
+    postMessage({
+      type: 'action-execute-response',
+      payload: {
+        requestId,
+        result: { success: false, error: `Action ${payload.actionId} not found` },
+        error: `Action ${payload.actionId} not found`,
+      },
+    })
+    return
+  }
+
+  try {
+    const result = await action.execute(payload.params)
+    postMessage({
+      type: 'action-execute-response',
+      payload: {
+        requestId,
+        result,
+      },
+    })
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    postMessage({
+      type: 'action-execute-response',
+      payload: {
+        requestId,
+        result: { success: false, error: errorMessage },
+        error: errorMessage,
+      },
+    })
+  }
+}
+
 // ============================================================================
 // Context Building
 // ============================================================================
@@ -490,6 +561,79 @@ function buildContext(
     ;(context as { tools: ToolsAPI }).tools = toolsApi
   }
 
+  // Add actions API if permitted
+  if (hasPermission('actions.register')) {
+    const actionsApi: ActionsAPI = {
+      register(action: Action): Disposable {
+        registeredActions.set(action.id, action)
+        postMessage({
+          type: 'action-registered',
+          payload: {
+            id: action.id,
+          },
+        })
+        return {
+          dispose: () => {
+            registeredActions.delete(action.id)
+          },
+        }
+      },
+    }
+    ;(context as { actions: ActionsAPI }).actions = actionsApi
+  }
+
+  // Add events API if permitted
+  if (hasPermission('events.emit')) {
+    const eventsApi: EventsAPI = {
+      async emit(name: string, payload?: Record<string, unknown>): Promise<void> {
+        await sendRequest<void>('events.emit', { name, payload })
+      },
+    }
+    ;(context as { events: EventsAPI }).events = eventsApi
+  }
+
+  // Add scheduler API if permitted
+  if (hasPermission('scheduler.register')) {
+    const schedulerApi: SchedulerAPI = {
+      async schedule(job: SchedulerJobRequest): Promise<void> {
+        await sendRequest<void>('scheduler.schedule', { job })
+      },
+      async cancel(jobId: string): Promise<void> {
+        await sendRequest<void>('scheduler.cancel', { jobId })
+      },
+      onFire(callback: (payload: SchedulerFirePayload) => void): Disposable {
+        schedulerCallbacks.push(callback)
+        return {
+          dispose: () => {
+            const index = schedulerCallbacks.indexOf(callback)
+            if (index >= 0) schedulerCallbacks.splice(index, 1)
+          },
+        }
+      },
+    }
+    ;(context as { scheduler: SchedulerAPI }).scheduler = schedulerApi
+  }
+
+  // Add user profile API if permitted
+  if (hasPermission('user.profile.read')) {
+    const userApi: UserAPI = {
+      async getProfile(): Promise<UserProfile> {
+        return sendRequest<UserProfile>('user.getProfile', {})
+      },
+    }
+    ;(context as { user: UserAPI }).user = userApi
+  }
+
+  // Add chat API if permitted
+  if (hasPermission('chat.message.write')) {
+    const chatApi: ChatAPI = {
+      async appendInstruction(message: ChatInstructionMessage): Promise<void> {
+        await sendRequest<void>('chat.appendInstruction', message)
+      },
+    }
+    ;(context as { chat: ChatAPI }).chat = chatApi
+  }
+
   // Add database API if permitted
   if (hasPermission('database.own')) {
     const databaseApi: DatabaseAPI = {
@@ -556,6 +700,8 @@ export type {
   ToolDefinition,
   ToolResult,
   ToolCall,
+  Action,
+  ActionResult,
   ModelInfo,
   ChatMessage,
   ChatOptions,

package/src/types.components.ts

@@ -0,0 +1,236 @@
+/** Base interface for dynamically rendered extension components. */
+export interface ExtensionComponentData {
+  component: string
+  [key: string]: unknown
+}
+
+// =============================================================================
+// Iteration & Children
+// =============================================================================
+
+/**
+ * Iterator for rendering a list of components from data.
+ * Used with layout components like VerticalStack, HorizontalStack, Grid.
+ *
+ * @example
+ * ```json
+ * {
+ *   "each": "$todos",
+ *   "as": "todo",
+ *   "items": [{ "component": "Label", "text": "$todo.title" }]
+ * }
+ * ```
+ */
+export interface ExtensionComponentIterator {
+  /** Data source to iterate over. Use "$name" for dynamic reference or inline array. */
+  each: string | unknown[]
+  /** Variable name for current item in scope */
+  as: string
+  /** Components to render for each item */
+  items: ExtensionComponentData[]
+}
+
+/**
+ * Children can be either a static array of components or an iterator.
+ */
+export type ExtensionComponentChildren =
+  | ExtensionComponentData[]
+  | ExtensionComponentIterator
+
+// =============================================================================
+// Actions
+// =============================================================================
+
+/**
+ * Action call with parameters.
+ * Used for component events like onClick, onChange, etc.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "deleteTodo",
+ *   "params": { "todoId": "$todo.id" }
+ * }
+ * ```
+ */
+export interface ExtensionActionCall {
+  /** Name of the registered action */
+  action: string
+  /** Parameters to pass. Values starting with "$" are resolved from scope. */
+  params?: Record<string, unknown>
+}
+
+/**
+ * Action reference - can be a simple string (action name) or full action call.
+ */
+export type ExtensionActionRef = string | ExtensionActionCall
+
+// =============================================================================
+// Data Sources & Panel Definition
+// =============================================================================
+
+/**
+ * Data source definition for fetching data via an action.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "getProjects",
+ *   "params": { "includeArchived": false },
+ *   "refreshOn": ["project.changed"]
+ * }
+ * ```
+ */
+export interface ExtensionDataSource {
+  /** Action to call for fetching data */
+  action: string
+  /** Parameters to pass to the action */
+  params?: Record<string, unknown>
+  /** Event names that should trigger a refresh of this data */
+  refreshOn?: string[]
+}
+
+/**
+ * Panel definition for extension-contributed panels.
+ *
+ * @example
+ * ```json
+ * {
+ *   "data": {
+ *     "projects": { "action": "getProjectsWithTodos", "refreshOn": ["todo.changed"] }
+ *   },
+ *   "content": {
+ *     "component": "VerticalStack",
+ *     "children": { "each": "$projects", "as": "project", "items": [...] }
+ *   }
+ * }
+ * ```
+ */
+export interface ExtensionPanelDefinition {
+  /** Data sources available in the panel. Keys become variable names (e.g., "$projects"). */
+  data?: Record<string, ExtensionDataSource>
+  /** Root component to render */
+  content: ExtensionComponentData
+}
+
+/** The extension API properties for the Header component. */
+export interface HeaderProps extends ExtensionComponentData {
+  component: 'Header'
+  level: number
+  title: string
+  description?: string | string[]
+  icon?: string
+}
+
+/** The extension API properties for the Label component. */
+export interface LabelProps extends ExtensionComponentData {
+  component: 'Label'
+  text: string
+}
+
+/** The extension API properties for the paragraph component. */
+export interface ParagraphProps extends ExtensionComponentData {
+  component: 'Paragraph'
+  text: string
+}
+
+/** The extension API properties for the Button component. */
+export interface ButtonProps extends ExtensionComponentData {
+  component: 'Button'
+  text: string
+  onClickAction: ExtensionActionRef
+}
+
+/** The extension API properties for the TextInput component. */
+export interface TextInputProps extends ExtensionComponentData {
+  component: 'TextInput'
+  label: string
+  placeholder?: string
+  value?: string
+  onChangeAction: ExtensionActionRef
+}
+
+/** The extension API properties for the Select component. */
+export interface SelectProps extends ExtensionComponentData {
+  component: 'Select'
+  label: string
+  options: Array<{ label: string; value: string }>
+  selectedValue?: string
+  onChangeAction: ExtensionActionRef
+}
+
+/** The extension API properties for the VerticalStack component. */
+export interface VerticalStackProps extends ExtensionComponentData {
+  component: 'VerticalStack'
+  gap?: number
+  children: ExtensionComponentChildren
+}
+
+/** The extension API properties for the HorizontalStack component. */
+export interface HorizontalStackProps extends ExtensionComponentData {
+  component: 'HorizontalStack'
+  gap?: number
+  children: ExtensionComponentChildren
+}
+
+/** The extension API properties for the Grid component. */
+export interface GridProps extends ExtensionComponentData {
+  component: 'Grid'
+  columns: number
+  gap?: number
+  children: ExtensionComponentChildren
+}
+
+/** The extension API properties for the Divider component. */
+export interface DividerProps extends ExtensionComponentData {
+  component: 'Divider'
+}
+
+/** The extension API properties for the Icon component. */
+export interface IconProps extends ExtensionComponentData {
+  component: 'Icon'
+  name: string
+  title?: string
+}
+
+/** Button type for IconButton. */
+export type IconButtonType = 'normal' | 'primary' | 'danger' | 'accent'
+
+/** The extension API properties for the IconButton component. */
+export interface IconButtonProps extends ExtensionComponentData {
+  component: 'IconButton'
+  icon: string
+  tooltip: string
+  active?: boolean
+  disabled?: boolean
+  type?: IconButtonType
+  onClickAction: ExtensionActionRef
+}
+
+/** Action button definition for Panel component. */
+export interface PanelAction {
+  icon: string
+  tooltip: string
+  action: ExtensionActionRef
+  type?: IconButtonType
+}
+
+/** The extension API properties for the Panel component. */
+export interface PanelProps extends ExtensionComponentData {
+  component: 'Panel'
+  title: string
+  description?: string | string[]
+  icon?: string
+  actions?: PanelAction[]
+  content?: ExtensionComponentData
+}
+
+/** The extension API properties for the Toggle component. */
+export interface ToggleProps extends ExtensionComponentData {
+  component: 'Toggle'
+  label?: string
+  description?: string
+  checked?: boolean
+  disabled?: boolean
+  onChangeAction: ExtensionActionRef
+}