@meetopenbot/plugin-sdk 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # OpenBot Plugin SDK
2
2
 
3
- The official SDK for building plugins for [OpenBot](https://meetopenbot.com). This SDK provides the types and helpers needed to create plugins that can handle events, interact with storage, and render UI widgets within the OpenBot ecosystem.
3
+ The official SDK for building plugins for [OpenBot](https://meetopenbot.com). This SDK provides the types and helpers needed to create plugins that act as **agent runtimes**—handling events, interacting with storage, and rendering UI widgets within the OpenBot ecosystem.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,28 +8,30 @@ The official SDK for building plugins for [OpenBot](https://meetopenbot.com). Th
8
8
  npm install @meetopenbot/plugin-sdk
9
9
  ```
10
10
 
11
+ OpenBot plugins **must** be **ESM** (ECMAScript modules): `import` / `export` in the plugin entry, with a package configured as a module (for example `"type": "module"` in `package.json`, or an `.mjs` entry). CommonJS (`require`) is not supported.
12
+
11
13
  ## How it Works
12
14
 
13
- OpenBot plugins operate on an event-driven architecture powered by [Melony](https://github.com/meetopenbot/melony). Plugin authors work with the OpenBot SDK types and helpers; you do not need to import Melony types in your plugin code.
15
+ OpenBot plugins operate as the **agent runtime** on an event-driven architecture powered by [Melony](https://github.com/meetopenbot/melony).
14
16
 
15
17
  1. **Registration**: The host loads your plugin and calls the `factory` function with a `PluginContext`.
16
- 2. **Subscription**: Your `factory` function uses the `PluginBuilder` to subscribe to specific events (for example, `agent:invoke`).
17
- 3. **Processing**: When an event occurs, your handler is called. You can perform logic, interact with `storage`, or call external APIs.
18
- 4. **Publication**: Your handler can emit new events back to the bus (for example, `agent:output` or `client:ui:widget`) to communicate with the user or other plugins.
18
+ 2. **Subscription**: Your `factory` function uses the `PluginBuilder` to subscribe to the full event surface (e.g., `agent:invoke`).
19
+ 3. **Processing**: When a user sends a message, `agent:invoke` is dispatched. Your plugin runs its loop, performs logic, interacts with `storage`, or calls external APIs.
20
+ 4. **Communication**: Your plugin emits events back to the bus (e.g., `agent:output` or `client:ui:widget`) to communicate with the user or the parent agent.
19
21
 
20
22
  ## Core Concepts
21
23
 
22
24
  ### Plugin
23
25
 
24
- A plugin is defined by the `Plugin` or `PluginModule` interface. Use `definePlugin` to get full OpenBot typing without annotating Melony types yourself.
26
+ A plugin is defined by the `Plugin` or `PluginModule` interface. Use `definePlugin` to get full OpenBot typing.
25
27
 
26
28
  ```typescript
27
29
  import { definePlugin } from '@meetopenbot/plugin-sdk';
28
30
 
29
31
  export default definePlugin({
30
- id: 'my-plugin',
31
- name: 'My Plugin',
32
- description: 'A simple example plugin',
32
+ id: 'my-agent',
33
+ name: 'My Agent',
34
+ description: 'A custom AI agent',
33
35
  configSchema: {
34
36
  type: 'object',
35
37
  properties: {
@@ -37,66 +39,61 @@ export default definePlugin({
37
39
  },
38
40
  required: ['apiKey'],
39
41
  },
40
- toolDefinitions: {
41
- get_weather: {
42
- description: 'Get the current weather',
43
- inputSchema: {
44
- type: 'object',
45
- properties: {
46
- location: { type: 'string' },
47
- },
48
- },
49
- },
50
- },
51
42
  factory: (context) => (builder) => {
52
43
  builder.on('agent:invoke', async function* (event) {
53
- // Handle events here
44
+ // Handle agent logic here
54
45
  });
55
46
  },
56
47
  });
57
48
  ```
58
49
 
59
- For community plugins published as npm packages, omit `id` and export a `PluginModule`. The host assigns `id` from the package name.
50
+ ### Events
60
51
 
61
- You can also type a plugin object explicitly with `Plugin` or `PluginModule` if you prefer. The `factory` function returns a `PluginFactory`, which registers handlers on the `PluginBuilder` and receives `PluginHandlerContext` in event handlers.
52
+ Plugins communicate via an event bus. Core events include:
62
53
 
63
- ### Configuration & Tools
54
+ - `agent:invoke`: Dispatched when a user sends a message to the agent.
55
+ - `agent:output`: Emitted by the plugin to send messages back to the user or feedback final results to a parent agent.
56
+ - `client:ui:widget`: Used to render interactive UI widgets (forms, choices, etc.) in the client.
57
+ - `client:ui:widget:response`: Dispatched when a user interacts with a widget (e.g., submits a form or clicks a choice).
58
+ - `action:<toolName>`: Dispatched when a tool call is requested.
59
+ - `action:<toolName>:result`: Emitted when a tool handler finishes. Must include `data.output: string` to be fed back to the model.
64
60
 
65
- - **`configSchema`**: Defines the configuration options for your plugin. The host uses this to validate the configuration provided in `AGENT.md`.
66
- - **`toolDefinitions`**: Defines the tools your plugin provides. Other plugins (like a runtime plugin) can use these definitions to call your plugin's tools.
61
+ ### Output and Communication
67
62
 
68
- ### Events
63
+ OpenBot is oriented toward **complete messages**. Use the `agentOutput` helper to emit full step text or final results.
69
64
 
70
- Plugins communicate via an event bus. Common event types include:
65
+ - **Multiple Outputs**: A single plugin can emit multiple `agent:output` events during a single turn to show progress.
66
+ - **Parent Communication**: The **latest `agentOutput`** is the primary way to communicate with a parent agent and provide the final results of the agent's execution.
71
67
 
72
- - `agent:invoke`: Dispatched when a user sends a message to the agent.
73
- - `agent:output`: Emitted by the agent to send a message back to the user.
74
- - `client:ui:widget`: Used to render a UI widget in the client.
75
- - `action:<toolName>`: Dispatched when a runtime requests a tool call.
76
- - `action:<toolName>:result`: Emitted when a tool handler finishes.
68
+ ### Implementation Strategies
69
+
70
+ OpenBot plugins are designed for **AI agent behavior**, not just thin translation layers. You can implement this behavior in two primary ways:
71
+
72
+ 1. **Third-Party Agent Harness**: If your target platform provides a full agent stack (built-in tools, context management, and reasoning), you can wrap it directly. Examples include **Claude Code**, **Codex**, or other "full agent" SDKs. You connect their internal lifecycle to OpenBot via this SDK's events.
73
+ 2. **Custom Agentic Logic**: If the third-party provider only offers a regular API, SDK, or CLI without agentic intelligence, it is recommended to use the [**Vercel AI SDK**](https://sdk.vercel.ai/docs) to build the agent loop. This allows you to add the necessary "intelligence" and tool-calling capabilities on top of the raw integration.
77
74
 
78
75
  ### Storage
79
76
 
80
- The `PluginContext` provides access to the `storage` interface, allowing plugins to interact with:
77
+ The `PluginContext` provides access to the `storage` interface for interacting with:
81
78
 
82
79
  - **Channels & Threads**: Manage conversation contexts.
83
- - **Agents**: Access and update agent details.
84
80
  - **Variables**: Store configuration or secrets.
85
- - **Files**: Read and list files in the channel's workspace.
81
+ - **Files**: Read and list files in the workspace.
86
82
  - **Memories**: Store and retrieve long-term memory records.
87
83
 
88
84
  ### UI Widgets
89
85
 
90
- Plugins can render interactive UI widgets using the `uiWidget` helper. Supported widget types include:
86
+ Plugins can render interactive UI widgets using the `uiWidget` helper and handle user interactions by subscribing to `client:ui:widget:response`:
91
87
 
92
88
  - `message`: Simple text message with optional actions.
93
89
  - `choice`: A set of buttons for the user to choose from.
94
- - `form`: A form with various field types (text, number, select, etc.).
90
+ - `form`: A form with various field types.
95
91
  - `list`: A list of items with status indicators.
92
+ - `media`: Images, video, audio, or files.
96
93
 
97
- ## Example: Hello World Plugin
94
+ ## Example: Hello World Agent
98
95
 
99
- This plugin responds to any message with "Hello, World!".
96
+ This agent responds to any message with "Hello, World!".
100
97
 
101
98
  ```typescript
102
99
  import { definePlugin, shouldHandleInvoke, agentOutput } from '@meetopenbot/plugin-sdk';
@@ -122,7 +119,6 @@ export default definePlugin({
122
119
  ## API Reference
123
120
 
124
121
  - [Plugin & Context](./src/plugin.ts)
125
- - [Runtime Types](./src/runtime.ts)
126
122
  - [Events & State](./src/events.ts)
127
123
  - [Storage Interface](./src/storage.ts)
128
124
  - [UI Widget Specs](./src/ui.ts)
package/dist/events.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { AgentDetails, ChannelDetails, ThreadDetails } from './storage.js';
2
- import type { UIWidgetSpec } from './ui.js';
2
+ import type { RenderUIWidgetData } from './ui.js';
3
3
  export type EventMeta = {
4
4
  agentId?: string;
5
5
  threadId?: string;
@@ -30,7 +30,7 @@ export type AgentOutputEvent = BaseEvent & {
30
30
  };
31
31
  export type UIWidgetEvent = BaseEvent & {
32
32
  type: 'client:ui:widget';
33
- data: UIWidgetSpec;
33
+ data: RenderUIWidgetData;
34
34
  meta: EventMeta & {
35
35
  agentId: string;
36
36
  };
@@ -1 +1 @@
1
- {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG;IACzC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE;QACJ,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;QACvC,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG;IACzC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,IAAI,EAAE,SAAS,GAAG;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG;IACtC,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,SAAS,GAAG;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG;IAC9C,IAAI,EAAE,2BAA2B,CAAC;IAClC,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;CACH,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,eAAe,CAAC,KAAK,GAAG,OAAO,IAAI,SAAS,GAAG;IACzD,IAAI,EAAE,UAAU,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,eAAe,CAAC,KAAK,GAAG,OAAO,IAAI,SAAS,GAAG;IACzD,IAAI,EAAE,UAAU,MAAM,SAAS,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,qBAAqB,GACrB,eAAe,GACf,eAAe,CAAC;AAEpB,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,CAAC,SAAS,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACxC"}
1
+ {"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
package/dist/helpers.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { AgentInvokeEvent, AgentOutputEvent, EventMeta, ToolResultEvent, UIWidgetEvent } from './events.js';
2
- import type { UIWidgetSpec } from './ui.js';
2
+ import type { RenderUIWidgetData } from './ui.js';
3
3
  /** Return true when this agent should handle an `agent:invoke` event. */
4
4
  export declare function shouldHandleInvoke(event: AgentInvokeEvent, agentId: string): boolean;
5
5
  /** Build an `agent:output` event. */
@@ -16,7 +16,7 @@ export declare function toolResult<TData>(toolName: string, request: {
16
16
  /** Build a `client:ui:widget` event. */
17
17
  export declare function uiWidget(args: {
18
18
  agentId: string;
19
- widget: UIWidgetSpec;
19
+ widget: RenderUIWidgetData;
20
20
  threadId?: string;
21
21
  meta?: EventMeta;
22
22
  }): UIWidgetEvent;
@@ -1 +1 @@
1
- {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,gBAAgB,CAUnB;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC7B,IAAI,EAAE,KAAK,GACV,eAAe,CAAC,KAAK,CAAC,CAMxB;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,aAAa,CAUhB;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EACrD,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC5B,KAAK,EAAE,CAAC,GACP,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAS1B"}
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAG,MAAM,SAAS,CAAC;AAEnD,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,gBAAgB,CAUnB;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC7B,IAAI,EAAE,KAAK,GACV,eAAe,CAAC,KAAK,CAAC,CAMxB;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,aAAa,CAUhB;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EACrD,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC5B,KAAK,EAAE,CAAC,GACP,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAS1B"}
package/dist/ui.d.ts CHANGED
@@ -8,7 +8,7 @@ export type UIWidgetAction = {
8
8
  export type UIWidgetField = {
9
9
  id: string;
10
10
  label: string;
11
- type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date';
11
+ type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'password';
12
12
  description?: string;
13
13
  placeholder?: string;
14
14
  required?: boolean;
@@ -22,37 +22,61 @@ export type UIWidgetListItem = {
22
22
  id: string;
23
23
  label: string;
24
24
  description?: string;
25
+ /** URL for a thumbnail or an icon name */
26
+ image?: string;
27
+ /** Optional badge text (e.g., "New", "Sale", "10") */
28
+ badge?: string;
29
+ /** Actions specific to this list item */
30
+ actions?: UIWidgetAction[];
25
31
  status?: 'pending' | 'in_progress' | 'done' | 'error' | 'cancelled';
26
32
  metadata?: Record<string, unknown>;
27
33
  };
34
+ export type UIMediaItem = {
35
+ type: 'image' | 'video' | 'audio' | 'file';
36
+ url: string;
37
+ title?: string;
38
+ alt?: string;
39
+ thumbnailUrl?: string;
40
+ metadata?: Record<string, unknown>;
41
+ };
28
42
  export type UIWidgetBase = {
29
43
  widgetId: string;
30
44
  title?: string;
31
45
  description?: string;
32
- body?: string;
46
+ /** Optional hero media for the widget */
47
+ media?: UIMediaItem;
48
+ /** Optional actions for the widget */
49
+ actions?: UIWidgetAction[];
33
50
  state?: 'open' | 'submitted' | 'cancelled' | 'error';
51
+ display?: 'expanded' | 'collapsed';
52
+ size?: 'small' | 'medium' | 'large' | 'full';
34
53
  metadata?: Record<string, unknown>;
54
+ variant: "default" | "basic";
35
55
  };
36
56
  export type UIMessageWidget = UIWidgetBase & {
37
57
  kind: 'message';
38
- actions?: UIWidgetAction[];
58
+ body?: string;
39
59
  };
40
60
  export type UIChoiceWidget = UIWidgetBase & {
41
61
  kind: 'choice';
62
+ /** Choice widgets require at least one action */
42
63
  actions: UIWidgetAction[];
43
64
  };
44
65
  export type UIFormWidget = UIWidgetBase & {
45
66
  kind: 'form';
46
67
  fields: UIWidgetField[];
47
68
  submitLabel?: string;
48
- actions?: UIWidgetAction[];
49
69
  };
50
70
  export type UIListWidget = UIWidgetBase & {
51
71
  kind: 'list';
52
72
  items: UIWidgetListItem[];
53
- actions?: UIWidgetAction[];
54
73
  };
55
- export type UIWidgetSpec = UIMessageWidget | UIChoiceWidget | UIFormWidget | UIListWidget;
74
+ export type UIMediaWidget = UIWidgetBase & {
75
+ kind: 'media';
76
+ items: UIMediaItem[];
77
+ layout?: 'single' | 'grid' | 'carousel';
78
+ };
79
+ export type UIWidgetSpec = UIMessageWidget | UIChoiceWidget | UIFormWidget | UIListWidget | UIMediaWidget;
56
80
  export type RenderUIWidgetData = (Omit<UIMessageWidget, 'widgetId'> & {
57
81
  widgetId?: string;
58
82
  }) | (Omit<UIChoiceWidget, 'widgetId'> & {
@@ -61,11 +85,7 @@ export type RenderUIWidgetData = (Omit<UIMessageWidget, 'widgetId'> & {
61
85
  widgetId?: string;
62
86
  }) | (Omit<UIListWidget, 'widgetId'> & {
63
87
  widgetId?: string;
64
- }) | {
65
- kind: 'approval' | 'todo_list';
88
+ }) | (Omit<UIMediaWidget, 'widgetId'> & {
66
89
  widgetId?: string;
67
- title?: string;
68
- props?: Record<string, unknown>;
69
- metadata?: Record<string, unknown>;
70
- };
90
+ });
71
91
  //# sourceMappingURL=ui.d.ts.map
package/dist/ui.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@meetopenbot/plugin-sdk",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "Types and helpers for building OpenBot plugins on the event bus.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",