@stina/extension-api 0.7.1 → 0.8.1

package/dist/{types-Brv9O9NY.d.cts → types-Cr8eCJ0G.d.cts}

@@ -1,3 +1,207 @@
+/** Base interface for dynamically rendered extension components. */
+interface ExtensionComponentData {
+    component: string;
+    [key: string]: unknown;
+}
+/**
+ * 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" }]
+ * }
+ * ```
+ */
+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.
+ */
+type ExtensionComponentChildren = ExtensionComponentData[] | ExtensionComponentIterator;
+/**
+ * Action call with parameters.
+ * Used for component events like onClick, onChange, etc.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "deleteTodo",
+ *   "params": { "todoId": "$todo.id" }
+ * }
+ * ```
+ */
+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.
+ */
+type ExtensionActionRef = string | ExtensionActionCall;
+/**
+ * Data source definition for fetching data via an action.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "getProjects",
+ *   "params": { "includeArchived": false },
+ *   "refreshOn": ["project.changed"]
+ * }
+ * ```
+ */
+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": [...] }
+ *   }
+ * }
+ * ```
+ */
+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. */
+interface HeaderProps extends ExtensionComponentData {
+    component: 'Header';
+    level: number;
+    title: string;
+    description?: string | string[];
+    icon?: string;
+}
+/** The extension API properties for the Label component. */
+interface LabelProps extends ExtensionComponentData {
+    component: 'Label';
+    text: string;
+}
+/** The extension API properties for the paragraph component. */
+interface ParagraphProps extends ExtensionComponentData {
+    component: 'Paragraph';
+    text: string;
+}
+/** The extension API properties for the Button component. */
+interface ButtonProps extends ExtensionComponentData {
+    component: 'Button';
+    text: string;
+    onClickAction: ExtensionActionRef;
+}
+/** The extension API properties for the TextInput component. */
+interface TextInputProps extends ExtensionComponentData {
+    component: 'TextInput';
+    label: string;
+    placeholder?: string;
+    value?: string;
+    onChangeAction: ExtensionActionRef;
+}
+/** The extension API properties for the Select component. */
+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. */
+interface VerticalStackProps extends ExtensionComponentData {
+    component: 'VerticalStack';
+    gap?: number;
+    children: ExtensionComponentChildren;
+}
+/** The extension API properties for the HorizontalStack component. */
+interface HorizontalStackProps extends ExtensionComponentData {
+    component: 'HorizontalStack';
+    gap?: number;
+    children: ExtensionComponentChildren;
+}
+/** The extension API properties for the Grid component. */
+interface GridProps extends ExtensionComponentData {
+    component: 'Grid';
+    columns: number;
+    gap?: number;
+    children: ExtensionComponentChildren;
+}
+/** The extension API properties for the Divider component. */
+interface DividerProps extends ExtensionComponentData {
+    component: 'Divider';
+}
+/** The extension API properties for the Icon component. */
+interface IconProps extends ExtensionComponentData {
+    component: 'Icon';
+    name: string;
+    title?: string;
+}
+/** Button type for IconButton. */
+type IconButtonType = 'normal' | 'primary' | 'danger' | 'accent';
+/** The extension API properties for the IconButton component. */
+interface IconButtonProps extends ExtensionComponentData {
+    component: 'IconButton';
+    icon: string;
+    tooltip: string;
+    active?: boolean;
+    disabled?: boolean;
+    type?: IconButtonType;
+    onClickAction: ExtensionActionRef;
+}
+/** Action button definition for Panel component. */
+interface PanelAction {
+    icon: string;
+    tooltip: string;
+    action: ExtensionActionRef;
+    type?: IconButtonType;
+}
+/** The extension API properties for the Panel component. */
+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. */
+interface ToggleProps extends ExtensionComponentData {
+    component: 'Toggle';
+    label?: string;
+    description?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    onChangeAction: ExtensionActionRef;
+}
+
 /**
  * Extension manifest format (manifest.json)
  */
@@ -41,6 +245,8 @@ interface ExtensionContributions {
     settings?: SettingDefinition[];
     /** Tool settings views for UI */
     toolSettings?: ToolSettingsViewDefinition[];
+    /** Right panel contributions */
+    panels?: PanelDefinition[];
     /** AI providers */
     providers?: ProviderDefinition[];
     /** Tools for Stina to use */
@@ -69,6 +275,22 @@ interface SettingDefinition {
         value: string;
         label: string;
     }[];
+    /** For select type: load options from tool */
+    optionsToolId?: string;
+    /** Params for options tool */
+    optionsParams?: Record<string, unknown>;
+    /** Mapping for options tool response */
+    optionsMapping?: SettingOptionsMapping;
+    /** Tool ID for creating a new option */
+    createToolId?: string;
+    /** Label for create action */
+    createLabel?: string;
+    /** Fields for create form */
+    createFields?: SettingDefinition[];
+    /** Static params always sent to create tool */
+    createParams?: Record<string, unknown>;
+    /** Mapping for create tool response */
+    createMapping?: SettingCreateMapping;
     /** Validation rules */
     validation?: {
         required?: boolean;
@@ -77,6 +299,28 @@ interface SettingDefinition {
         pattern?: string;
     };
 }
+/**
+ * Mapping for select field options from tool response
+ */
+interface SettingOptionsMapping {
+    /** Key for items array in tool result data */
+    itemsKey: string;
+    /** Key for option value */
+    valueKey: string;
+    /** Key for option label */
+    labelKey: string;
+    /** Optional key for description */
+    descriptionKey?: string;
+}
+/**
+ * Mapping for create tool response
+ */
+interface SettingCreateMapping {
+    /** Key for result data object */
+    resultKey?: string;
+    /** Key for option value (defaults to "id") */
+    valueKey: string;
+}
 /**
  * Tool settings view definition (UI schema)
  */
@@ -138,6 +382,52 @@ interface ToolSettingsListMapping {
     /** Key for secondary label */
     secondaryKey?: string;
 }
+/**
+ * Panel definition for right panel views
+ */
+interface PanelDefinition {
+    /** Unique panel ID within the extension */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Icon name (from huge-icons) */
+    icon?: string;
+    /** Panel view schema */
+    view: PanelView;
+}
+/**
+ * Panel view schema (declarative)
+ */
+type PanelView = PanelComponentView | PanelUnknownView;
+interface PanelUnknownView {
+    /** View kind */
+    kind: string;
+    /** Additional view configuration */
+    [key: string]: unknown;
+}
+/**
+ * Action-based data source for declarative panels.
+ * Uses actions (not tools) to fetch data.
+ */
+interface PanelActionDataSource {
+    /** Action ID 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[];
+}
+/**
+ * Component-based panel view using the declarative DSL.
+ * Data is fetched via actions, content is rendered via ExtensionComponent.
+ */
+interface PanelComponentView {
+    kind: 'component';
+    /** Data sources available in the panel. Keys become variable names (e.g., "$projects"). */
+    data?: Record<string, PanelActionDataSource>;
+    /** Root component to render */
+    content: ExtensionComponentData;
+}
 /**
  * Provider definition (metadata only, implementation in code)
  */
@@ -262,7 +552,7 @@ type StoragePermission = 'database.own' | 'storage.local';
 /** User data permissions */
 type UserDataPermission = 'user.profile.read' | 'user.location.read' | 'chat.history.read' | 'chat.current.read';
 /** Capability permissions */
-type CapabilityPermission = 'provider.register' | 'tools.register' | 'settings.register' | 'commands.register';
+type CapabilityPermission = 'provider.register' | 'tools.register' | 'actions.register' | 'settings.register' | 'commands.register' | 'panels.register' | 'events.emit' | 'scheduler.register' | 'chat.message.write';
 /** System permissions */
 type SystemPermission = 'files.read' | 'files.write' | 'clipboard.read' | 'clipboard.write';
 /**
@@ -289,6 +579,16 @@ interface ExtensionContext {
     readonly providers?: ProvidersAPI;
     /** Tool registration (if permitted) */
     readonly tools?: ToolsAPI;
+    /** Action registration (if permitted) */
+    readonly actions?: ActionsAPI;
+    /** Event emission (if permitted) */
+    readonly events?: EventsAPI;
+    /** Scheduler access (if permitted) */
+    readonly scheduler?: SchedulerAPI;
+    /** User data access (if permitted) */
+    readonly user?: UserAPI;
+    /** Chat access (if permitted) */
+    readonly chat?: ChatAPI;
     /** Database access (if permitted) */
     readonly database?: DatabaseAPI;
     /** Local storage (if permitted) */
@@ -344,6 +644,93 @@ interface ToolsAPI {
      */
     register(tool: Tool): Disposable;
 }
+/**
+ * Actions API for registering UI actions
+ */
+interface ActionsAPI {
+    /**
+     * Register an action that UI components can invoke
+     */
+    register(action: Action): Disposable;
+}
+/**
+ * Events API for notifying the host
+ */
+interface EventsAPI {
+    /**
+     * Emit a named event with optional payload
+     */
+    emit(name: string, payload?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Scheduler schedule types
+ */
+type SchedulerSchedule = {
+    type: 'at';
+    at: string;
+} | {
+    type: 'cron';
+    cron: string;
+    timezone?: string;
+} | {
+    type: 'interval';
+    everyMs: number;
+};
+/**
+ * Scheduler job request
+ */
+interface SchedulerJobRequest {
+    id: string;
+    schedule: SchedulerSchedule;
+    payload?: Record<string, unknown>;
+    misfire?: 'run_once' | 'skip';
+}
+/**
+ * Scheduler fire payload
+ */
+interface SchedulerFirePayload {
+    id: string;
+    payload?: Record<string, unknown>;
+    scheduledFor: string;
+    firedAt: string;
+    delayMs: number;
+}
+/**
+ * Scheduler API for registering jobs
+ */
+interface SchedulerAPI {
+    schedule(job: SchedulerJobRequest): Promise<void>;
+    cancel(jobId: string): Promise<void>;
+    onFire(callback: (payload: SchedulerFirePayload) => void): Disposable;
+}
+/**
+ * User profile data
+ */
+interface UserProfile {
+    firstName?: string;
+    nickname?: string;
+    language?: string;
+    timezone?: string;
+}
+/**
+ * User API for profile access
+ */
+interface UserAPI {
+    getProfile(): Promise<UserProfile>;
+}
+/**
+ * Chat instruction message
+ */
+interface ChatInstructionMessage {
+    text: string;
+    conversationId?: string;
+}
+/**
+ * Chat API for appending instructions
+ */
+interface ChatAPI {
+    appendInstruction(message: ChatInstructionMessage): Promise<void>;
+}
 /**
  * Database API for extension-specific tables
  */
@@ -523,6 +910,30 @@ interface ToolResult {
     /** Error message if failed */
     error?: string;
 }
+/**
+ * Action implementation for UI interactions.
+ * Actions are invoked by UI components, not by Stina (AI).
+ */
+interface Action {
+    /** Action ID (unique within the extension) */
+    id: string;
+    /**
+     * Execute the action
+     * @param params Parameters from the UI component (with $-values already resolved)
+     */
+    execute(params: Record<string, unknown>): Promise<ActionResult>;
+}
+/**
+ * Action execution result
+ */
+interface ActionResult {
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Result data (returned to UI) */
+    data?: unknown;
+    /** Error message if failed */
+    error?: string;
+}
 /**
  * Extension entry point interface
  */
@@ -537,4 +948,4 @@ interface ExtensionModule {
     deactivate?(): void | Promise<void>;
 }
 
-export type { DatabaseAPI as A, StorageAPI as B, ChatMessage as C, Disposable as D, ExtensionManifest as E, AIProvider as F, GetModelsOptions as G, ToolCall as H, Tool as I, ExtensionModule as J, LogAPI as L, ModelInfo as M, NetworkPermission as N, Platform as P, StreamEvent as S, ToolResult as T, UserDataPermission as U, ChatOptions as a, ExtensionContributions as b, SettingDefinition as c, ToolSettingsViewDefinition as d, ToolSettingsView as e, ToolSettingsListView as f, ToolSettingsListMapping as g, ProviderDefinition as h, PromptContribution as i, PromptSection as j, ToolDefinition as k, CommandDefinition as l, ProviderConfigSchema as m, ProviderConfigProperty as n, ProviderConfigPropertyType as o, ProviderConfigSelectOption as p, ProviderConfigValidation as q, Permission as r, StoragePermission as s, CapabilityPermission as t, SystemPermission as u, ExtensionContext as v, NetworkAPI as w, SettingsAPI as x, ProvidersAPI as y, ToolsAPI as z };
+export type { ChatInstructionMessage as $, ActionResult as A, StoragePermission as B, ChatMessage as C, CapabilityPermission as D, ExtensionManifest as E, SystemPermission as F, GetModelsOptions as G, ExtensionContext as H, Disposable as I, NetworkAPI as J, SettingsAPI as K, ProvidersAPI as L, ModelInfo as M, NetworkPermission as N, ToolsAPI as O, Platform as P, ActionsAPI as Q, EventsAPI as R, SchedulerFirePayload as S, ToolResult as T, UserDataPermission as U, SchedulerAPI as V, SchedulerJobRequest as W, SchedulerSchedule as X, UserAPI as Y, UserProfile as Z, ChatAPI as _, ChatOptions as a, DatabaseAPI as a0, StorageAPI as a1, LogAPI as a2, AIProvider as a3, ToolCall as a4, Tool as a5, Action as a6, ExtensionModule as a7, ExtensionComponentData as a8, ExtensionComponentIterator as a9, ExtensionComponentChildren as aa, ExtensionActionCall as ab, ExtensionActionRef as ac, ExtensionDataSource as ad, ExtensionPanelDefinition as ae, HeaderProps as af, LabelProps as ag, ParagraphProps as ah, ButtonProps as ai, TextInputProps as aj, SelectProps as ak, VerticalStackProps as al, HorizontalStackProps as am, GridProps as an, DividerProps as ao, IconProps as ap, IconButtonType as aq, IconButtonProps as ar, PanelAction as as, PanelProps as at, ToggleProps as au, StreamEvent as b, ExtensionContributions as c, SettingDefinition as d, SettingOptionsMapping as e, SettingCreateMapping as f, ToolSettingsViewDefinition as g, ToolSettingsView as h, ToolSettingsListView as i, ToolSettingsListMapping as j, PanelDefinition as k, PanelView as l, PanelComponentView as m, PanelActionDataSource as n, PanelUnknownView as o, ProviderDefinition as p, PromptContribution as q, PromptSection as r, ToolDefinition as s, CommandDefinition as t, ProviderConfigSchema as u, ProviderConfigProperty as v, ProviderConfigPropertyType as w, ProviderConfigSelectOption as x, ProviderConfigValidation as y, Permission as z };