@roomle/web-sdk-types 5.1.0-typestest.1 → 8.0.0-alpha.1

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
@@ -5,13 +5,19 @@ TypeScript declarations of the [Roomle](https://www.roomle.com/en) Web SDK, with
5
5
  Use this package when you only need the types, for example in a shared type package or in a library that talks to the SDK through an iframe. If your code runs the SDK, install [`@roomle/web-sdk`](https://www.npmjs.com/package/@roomle/web-sdk) instead: it ships the same declarations.
6
6
 
7
7
  ```bash
8
- npm install --save-dev @roomle/web-sdk-types
8
+ npm install @roomle/web-sdk-types
9
9
  ```
10
10
 
11
+ Install it as a regular dependency if you publish a library whose declaration files import these types; otherwise your consumers cannot resolve them. In an application that only type-checks its own code, `--save-dev` is enough.
12
+
11
13
  ```ts
12
14
  import type { RoomleConfigurator } from '@roomle/web-sdk-types';
13
15
  ```
14
16
 
17
+ Always use `import type`. This package contains no JavaScript, so importing an enum or a class as a value compiles but fails when you bundle or run your code. Values come from `@roomle/web-sdk`.
18
+
19
+ Type against one of the two packages in a project, not both. `@roomle/web-sdk` and `@roomle/web-sdk-types` each ship their own copy of the declarations, and TypeScript treats classes and types that use a `const enum` from the two copies as different types. An object typed by one package cannot be passed to a function typed by the other.
20
+
15
21
  The version always matches the `@roomle/web-sdk` release it was built from.
16
22
 
17
23
  For release notes, see the [CHANGELOG](https://docs.roomle.com/rubens/changelogs/changelog-1).
@@ -0,0 +1,203 @@
1
+ import { LanguageModelV4 } from '@ai-sdk/provider';
2
+ import { SharedV4ProviderOptions } from '@ai-sdk/provider';
3
+
4
+ /** The input schema of a tool as a Standard Schema with its JSON Schema. */
5
+ export declare interface AgentMcpInputSchema {
6
+ '~standard': {
7
+ version: 1;
8
+ vendor: string;
9
+ validate: (value: unknown) => {
10
+ value: unknown;
11
+ };
12
+ jsonSchema: {
13
+ input: (options: {
14
+ target: string;
15
+ }) => Record<string, unknown>;
16
+ output: (options: {
17
+ target: string;
18
+ }) => Record<string, unknown>;
19
+ };
20
+ };
21
+ }
22
+
23
+ /** What the model gets of a tool result, as `@ai-sdk/mcp` hands it to the AI SDK. */
24
+ export declare interface AgentMcpModelOutput {
25
+ type: 'content';
26
+ value: Array<{
27
+ type: 'text';
28
+ text: string;
29
+ } | {
30
+ type: 'file';
31
+ mediaType: string;
32
+ data: {
33
+ type: 'data';
34
+ data: string;
35
+ };
36
+ }>;
37
+ }
38
+
39
+ /** A tool of the HI MCP tool set, in the shape of an AI SDK dynamic tool. */
40
+ export declare interface AgentMcpTool {
41
+ type: 'dynamic';
42
+ annotations?: AgentToolDefinition['annotations'];
43
+ description: string;
44
+ inputSchema: AgentMcpInputSchema;
45
+ execute: (input: unknown) => Promise<McpToolResult>;
46
+ toModelOutput: (options: {
47
+ output: McpToolResult;
48
+ }) => AgentMcpModelOutput;
49
+ }
50
+
51
+ /** The HI MCP tools by name, the tool set an AI SDK `streamText` takes. */
52
+ export declare type AgentMcpTools = Record<string, AgentMcpTool>;
53
+
54
+ /** A tool of the agent tools as an MCP server lists it in `tools/list`: its input schema is a JSON Schema. */
55
+ export declare interface AgentToolDefinition {
56
+ name: string;
57
+ description: string;
58
+ inputSchema: Record<string, unknown>;
59
+ annotations?: {
60
+ readOnlyHint?: boolean;
61
+ destructiveHint?: boolean;
62
+ idempotentHint?: boolean;
63
+ openWorldHint?: boolean;
64
+ };
65
+ }
66
+
67
+ export declare interface ConfiguratorAgentApi {
68
+ getConfiguratorAgentTools(): Promise<AgentToolDefinition[]>;
69
+ callConfiguratorAgentTool(name: string, input: unknown): Promise<McpToolResult>;
70
+ getConfiguratorAgentPrompts(): Promise<{
71
+ systemPrompt: string;
72
+ imagePrompt: string;
73
+ /**
74
+ * The root component of the product whose context the system prompt holds; absent while a
75
+ * definition of the product could not be read, so that the prompts are read again.
76
+ */
77
+ rootComponentId?: string;
78
+ }>;
79
+ }
80
+
81
+ export declare const createAgentMcpTools: (definitions: AgentToolDefinition[], call: (name: string, input: unknown) => Promise<McpToolResult>, vendor: string) => AgentMcpTools;
82
+
83
+ /** Runs a browser agent with the tools and prompts supplied by its SDK domain. */
84
+ export declare const createAssistant: (config: PlanningAssistantConfig, signal: AbortSignal, output: (part: PlanningAssistantOutput) => unknown, setupDomain: () => Promise<{
85
+ prompts: {
86
+ systemPrompt: string;
87
+ imagePrompt: string;
88
+ };
89
+ tools: AgentMcpTools;
90
+ }>, turnPolicy?: {
91
+ timeoutMs: number;
92
+ recovery: (tools: AgentMcpTools) => {
93
+ tools: AgentMcpTools;
94
+ summary(): string;
95
+ };
96
+ }) => Promise<(prompt: PlanningAssistantPrompt) => Promise<void>>;
97
+
98
+ /**
99
+ * Records tool execution independently of whether the model finishes its
100
+ * step, so an interrupted reply can say what the tools changed.
101
+ */
102
+ export declare const createChatRecovery: (tools: AgentMcpTools, domain?: {
103
+ subject: string;
104
+ readTools: ReadonlySet<string>;
105
+ }) => {
106
+ tools: AgentMcpTools;
107
+ summary: () => string;
108
+ };
109
+
110
+ /** The AI SDK language model of the config and the provider options `streamText` takes with it. */
111
+ export declare const loadChatModel: ({ provider, model, apiKey, baseUrl, headers, chatCompletions, responses, storedResponses, reasoningEffort, }: PlanningAssistantConfig, observeRequest?: (body: string) => Promise<void>) => Promise<{
112
+ languageModel: LanguageModelV4;
113
+ providerOptions?: SharedV4ProviderOptions;
114
+ }>;
115
+
116
+ /** The tool result as `@ai-sdk/mcp` passes it to the model: text parts and images as file parts. */
117
+ export declare const mcpToModelOutput: ({ output, }: {
118
+ output: McpToolResult;
119
+ }) => AgentMcpModelOutput;
120
+
121
+ /** The result of a tool as an MCP server answers `tools/call`. */
122
+ export declare interface McpToolResult {
123
+ content: Array<{
124
+ type: 'text';
125
+ text: string;
126
+ } | {
127
+ type: 'image';
128
+ data: string;
129
+ mimeType: string;
130
+ }>;
131
+ isError?: boolean;
132
+ }
133
+
134
+ /**
135
+ * The model of the AI Planning Assistant as a JSON object: everything
136
+ * `loadChatModel` and `startPlanningAssistant` need to reach it.
137
+ */
138
+ export declare interface PlanningAssistantConfig {
139
+ /** `azure` for a deployment on an Azure AI Foundry resource, `openai-compatible` for an endpoint that speaks OpenAI Chat Completions or, with `responses`, stateless OpenAI Responses (e.g. a model proxy), else the provider of the model. */
140
+ provider: 'azure' | 'openai' | 'openai-compatible' | 'mistral' | 'anthropic' | 'google';
141
+ /** The model id at the provider; for `azure` the name of the deployment, for `openai-compatible` the model name the endpoint expects. */
142
+ model: string;
143
+ /** The API key of the provider, required by every provider but `openai-compatible`; for `azure` the key of the Foundry resource. */
144
+ apiKey?: string;
145
+ /** `azure`: the OpenAI v1 endpoint of the Foundry resource, e.g. `https://<resource>.services.ai.azure.com/openai/v1`; `openai-compatible` (required): the base URL before `/chat/completions` (or `/responses`). */
146
+ baseUrl?: string;
147
+ /** `openai-compatible` only: headers sent with every model request, e.g. the authorization of a model proxy; without a key and without an Authorization header, no Authorization header is sent, so a same-origin page keeps the browser's authenticated session. */
148
+ headers?: Record<string, string>;
149
+ /** `azure` only: call the deployment through the Chat Completions API instead of the Responses API. */
150
+ chatCompletions?: boolean;
151
+ /** `openai-compatible` only: call `<baseUrl>/responses` instead of `<baseUrl>/chat/completions`, defaulting to stateless (`store: false`, the whole history in every request, the reasoning carried encrypted) unless `storedResponses` is true. */
152
+ responses?: boolean;
153
+ /** `openai-compatible` with `responses` only: store responses on the server (`store: true`) so supported runtimes can continue steps and follow-up turns by `previousResponseId`. */
154
+ storedResponses?: boolean;
155
+ /** `azure` only: the reasoning effort of the deployment; its default when unset. */
156
+ reasoningEffort?: string;
157
+ /** Azure Responses only: mark the library prefix for caching on a deployment verified to support explicit breakpoints. */
158
+ referenceCacheBreakpoint?: boolean;
159
+ /** Whether the model reads images: the window offers the image drop only then. */
160
+ readsImages: boolean;
161
+ /** HI planning assistant only: a Gemini key of the user's own for the decisions before a turn, sent with each decision request through the Roomle AI Gateway; without it the window's Roomle session pays, if any. */
162
+ decisionApiKey?: string;
163
+ }
164
+
165
+ /**
166
+ * One part of the output of the host's planning agent for the AI Planning Assistant window:
167
+ * - "text": a piece of the answer of the running turn, markdown, appended to the answer
168
+ * - "activity": what the agent does now, e.g. the tool it runs, shown in the status line
169
+ * - "error": the turn failed; the text replaces the answer of the turn and ends the turn
170
+ * - "done": the turn is complete; the input is free again
171
+ * - "availability": the input on or off, with the reason shown in the status line; off until the host enables it
172
+ * - "images": the image drop on or off; off until the host enables it
173
+ */
174
+ export declare type PlanningAssistantOutput = {
175
+ type: 'text';
176
+ text: string;
177
+ } | {
178
+ type: 'activity';
179
+ text: string;
180
+ } | {
181
+ type: 'error';
182
+ text: string;
183
+ statusCode?: number;
184
+ } | {
185
+ type: 'done';
186
+ } | {
187
+ type: 'availability';
188
+ available: boolean;
189
+ text?: string;
190
+ } | {
191
+ type: 'images';
192
+ enabled: boolean;
193
+ };
194
+
195
+ /** The message the user sends in the AI Planning Assistant window. */
196
+ export declare interface PlanningAssistantPrompt {
197
+ /** What the user typed, trimmed; empty when the user sends only an image. */
198
+ text: string;
199
+ /** The images of the message as JPEG data URLs: the long side at most 1568 px, EXIF rotation applied, transparent parts white. */
200
+ images: string[];
201
+ }
202
+
203
+ export { }