@illalabs/sdk 0.3.3-canary.ae6ff112 → 0.4.0-canary.1a04c18e

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.
Files changed (122) hide show
  1. package/README.md +68 -9
  2. package/dist/src/chat/Chat.d.ts +36 -4
  3. package/dist/src/chat/Chat.d.ts.map +1 -1
  4. package/dist/src/chat/Chat.js +129 -11
  5. package/dist/src/chat/Chat.js.map +1 -1
  6. package/dist/src/chat/errors/ChatInvalidMultiplePromptsKind.d.ts +22 -0
  7. package/dist/src/chat/errors/ChatInvalidMultiplePromptsKind.d.ts.map +1 -0
  8. package/dist/src/chat/errors/ChatInvalidMultiplePromptsKind.js +31 -0
  9. package/dist/src/chat/errors/ChatInvalidMultiplePromptsKind.js.map +1 -0
  10. package/dist/src/chat/errors/ChatInvalidPromptSnapshot.d.ts +19 -0
  11. package/dist/src/chat/errors/ChatInvalidPromptSnapshot.d.ts.map +1 -0
  12. package/dist/src/chat/errors/ChatInvalidPromptSnapshot.js +28 -0
  13. package/dist/src/chat/errors/ChatInvalidPromptSnapshot.js.map +1 -0
  14. package/dist/src/chat/errors/ChatInvalidSinglePromptKind.d.ts +22 -0
  15. package/dist/src/chat/errors/ChatInvalidSinglePromptKind.d.ts.map +1 -0
  16. package/dist/src/chat/errors/ChatInvalidSinglePromptKind.js +31 -0
  17. package/dist/src/chat/errors/ChatInvalidSinglePromptKind.js.map +1 -0
  18. package/dist/src/chat/errors/index.d.ts +3 -0
  19. package/dist/src/chat/errors/index.d.ts.map +1 -1
  20. package/dist/src/chat/errors/index.js +3 -0
  21. package/dist/src/chat/errors/index.js.map +1 -1
  22. package/dist/src/chat/utils/prompt.d.ts +3 -0
  23. package/dist/src/chat/utils/prompt.d.ts.map +1 -0
  24. package/dist/src/chat/utils/prompt.js +5 -0
  25. package/dist/src/chat/utils/prompt.js.map +1 -0
  26. package/dist/src/context/ContextManager.d.ts +2 -0
  27. package/dist/src/context/ContextManager.d.ts.map +1 -1
  28. package/dist/src/context/ContextManager.js +8 -1
  29. package/dist/src/context/ContextManager.js.map +1 -1
  30. package/dist/src/errors/SdkEmptyToolsResultsError.d.ts +19 -0
  31. package/dist/src/errors/SdkEmptyToolsResultsError.d.ts.map +1 -0
  32. package/dist/src/errors/SdkEmptyToolsResultsError.js +28 -0
  33. package/dist/src/errors/SdkEmptyToolsResultsError.js.map +1 -0
  34. package/dist/src/interfaces/chat.interface.d.ts +55 -3
  35. package/dist/src/interfaces/chat.interface.d.ts.map +1 -1
  36. package/dist/src/interfaces/contextManager.interface.d.ts +7 -1
  37. package/dist/src/interfaces/contextManager.interface.d.ts.map +1 -1
  38. package/dist/src/interfaces/coreApiProvider.interface.d.ts +13 -1
  39. package/dist/src/interfaces/coreApiProvider.interface.d.ts.map +1 -1
  40. package/dist/src/interfaces/index.d.ts +1 -1
  41. package/dist/src/interfaces/index.d.ts.map +1 -1
  42. package/dist/src/internal.d.ts +1 -0
  43. package/dist/src/internal.d.ts.map +1 -1
  44. package/dist/src/internal.js +1 -0
  45. package/dist/src/internal.js.map +1 -1
  46. package/dist/src/prompt/Prompt.d.ts +2 -10
  47. package/dist/src/prompt/Prompt.d.ts.map +1 -1
  48. package/dist/src/prompt/Prompt.js +9 -22
  49. package/dist/src/prompt/Prompt.js.map +1 -1
  50. package/dist/src/prompt/index.d.ts +1 -1
  51. package/dist/src/prompt/index.d.ts.map +1 -1
  52. package/dist/src/prompt/types.d.ts +7 -9
  53. package/dist/src/prompt/types.d.ts.map +1 -1
  54. package/dist/src/prompt/utils/cloneToolResult.d.ts +6 -6
  55. package/dist/src/prompt/utils/cloneToolResult.d.ts.map +1 -1
  56. package/dist/src/prompt/utils/cloneToolResult.js +11 -16
  57. package/dist/src/prompt/utils/cloneToolResult.js.map +1 -1
  58. package/dist/src/prompt/utils/index.d.ts +1 -3
  59. package/dist/src/prompt/utils/index.d.ts.map +1 -1
  60. package/dist/src/prompt/utils/index.js +1 -3
  61. package/dist/src/prompt/utils/index.js.map +1 -1
  62. package/dist/src/providers/coreApiProvider/CoreApiProvider.d.ts +40 -1
  63. package/dist/src/providers/coreApiProvider/CoreApiProvider.d.ts.map +1 -1
  64. package/dist/src/providers/coreApiProvider/CoreApiProvider.js +124 -2
  65. package/dist/src/providers/coreApiProvider/CoreApiProvider.js.map +1 -1
  66. package/dist/src/providers/coreApiProvider/index.d.ts +1 -1
  67. package/dist/src/providers/coreApiProvider/index.d.ts.map +1 -1
  68. package/dist/src/providers/coreApiProvider/types.d.ts +44 -0
  69. package/dist/src/providers/coreApiProvider/types.d.ts.map +1 -1
  70. package/dist/src/sdk.d.ts +311 -25
  71. package/dist/src/sdk.d.ts.map +1 -1
  72. package/dist/src/sdk.js +365 -26
  73. package/dist/src/sdk.js.map +1 -1
  74. package/dist/src/streaming/errors/SSEParse.d.ts +15 -0
  75. package/dist/src/streaming/errors/SSEParse.d.ts.map +1 -0
  76. package/dist/src/streaming/errors/SSEParse.js +23 -0
  77. package/dist/src/streaming/errors/SSEParse.js.map +1 -0
  78. package/dist/src/streaming/errors/StreamingHttpError.d.ts +18 -0
  79. package/dist/src/streaming/errors/StreamingHttpError.d.ts.map +1 -0
  80. package/dist/src/streaming/errors/StreamingHttpError.js +27 -0
  81. package/dist/src/streaming/errors/StreamingHttpError.js.map +1 -0
  82. package/dist/src/streaming/errors/StreamingResponseBodyNull.d.ts +13 -0
  83. package/dist/src/streaming/errors/StreamingResponseBodyNull.d.ts.map +1 -0
  84. package/dist/src/streaming/errors/StreamingResponseBodyNull.js +21 -0
  85. package/dist/src/streaming/errors/StreamingResponseBodyNull.js.map +1 -0
  86. package/dist/src/streaming/errors/StreamingServerError.d.ts +23 -0
  87. package/dist/src/streaming/errors/StreamingServerError.d.ts.map +1 -0
  88. package/dist/src/streaming/errors/StreamingServerError.js +33 -0
  89. package/dist/src/streaming/errors/StreamingServerError.js.map +1 -0
  90. package/dist/src/streaming/errors/index.d.ts +5 -0
  91. package/dist/src/streaming/errors/index.d.ts.map +1 -0
  92. package/dist/src/streaming/errors/index.js +5 -0
  93. package/dist/src/streaming/errors/index.js.map +1 -0
  94. package/dist/src/streaming/index.d.ts +4 -0
  95. package/dist/src/streaming/index.d.ts.map +1 -0
  96. package/dist/src/streaming/index.js +3 -0
  97. package/dist/src/streaming/index.js.map +1 -0
  98. package/dist/src/streaming/parseSSE.d.ts +23 -0
  99. package/dist/src/streaming/parseSSE.d.ts.map +1 -0
  100. package/dist/src/streaming/parseSSE.js +152 -0
  101. package/dist/src/streaming/parseSSE.js.map +1 -0
  102. package/dist/src/streaming/types.d.ts +6 -0
  103. package/dist/src/streaming/types.d.ts.map +1 -0
  104. package/dist/src/streaming/types.js +6 -0
  105. package/dist/src/streaming/types.js.map +1 -0
  106. package/dist/src/telemetry/TelemetryClient.d.ts +140 -0
  107. package/dist/src/telemetry/TelemetryClient.d.ts.map +1 -0
  108. package/dist/src/telemetry/TelemetryClient.js +225 -0
  109. package/dist/src/telemetry/TelemetryClient.js.map +1 -0
  110. package/dist/src/telemetry/index.d.ts +2 -0
  111. package/dist/src/telemetry/index.d.ts.map +1 -0
  112. package/dist/src/telemetry/index.js +2 -0
  113. package/dist/src/telemetry/index.js.map +1 -0
  114. package/package.json +3 -5
  115. package/dist/src/prompt/utils/normalizeTextPrompt.d.ts +0 -14
  116. package/dist/src/prompt/utils/normalizeTextPrompt.d.ts.map +0 -1
  117. package/dist/src/prompt/utils/normalizeTextPrompt.js +0 -22
  118. package/dist/src/prompt/utils/normalizeTextPrompt.js.map +0 -1
  119. package/dist/src/prompt/utils/normalizeToolResult.d.ts +0 -14
  120. package/dist/src/prompt/utils/normalizeToolResult.d.ts.map +0 -1
  121. package/dist/src/prompt/utils/normalizeToolResult.js +0 -27
  122. package/dist/src/prompt/utils/normalizeToolResult.js.map +0 -1
package/dist/src/sdk.d.ts CHANGED
@@ -1,15 +1,23 @@
1
- import type { MessageHistoryType, ModelContext, PersonalityContext, ToolResultType, UserContext } from "@illalabs/interfaces";
2
- import type { CacheEntryOptions, ChatContextSnapshot, ContextManagerOptions, ICache, IContextManager, SendMessageResult } from "./internal.js";
3
- import { Chat, ContextManager } from "./internal.js";
1
+ import type { CoreApiChatErrorResponse, IllaToolErrorJSON, IllaToolOutcomeJSON, MessageHistoryType, ModelContext, PendingToolCallType, PersonalityContext, UserContext } from "@illalabs/interfaces";
2
+ import type { AsyncCheckerEvents, AsyncToolCheckerCheckParams, AwaitableActionDescriptor, AwaitActionResult, CacheEntryOptions, ChatContextSnapshot, ContextManagerOptions, CoreApiProviderConfig, CoreApiProviderRoutes, EventSubscription, HttpClientFactory, ICache, IContextManager, PollingConfig, SendMessageResult, SendMessageStreamingOptions } from "./internal.js";
3
+ import { Chat, ContextManager, Prompt } from "./internal.js";
4
4
  /**
5
5
  * Configuration options for initializing the IllaSDK.
6
6
  *
7
7
  * @property apiKey - Your ILLA API key for authentication
8
8
  * @property baseURL - Optional custom base URL for the ILLA API (defaults to production API)
9
+ * @property timeout - Optional request timeout in milliseconds
10
+ * @property headers - Optional additional headers to send with requests
11
+ * @property httpClientFactory - Optional custom HTTP client factory
12
+ * @property routes - Optional custom routes configuration
9
13
  */
10
14
  type illaSDKConfig = {
11
15
  apiKey: string;
12
16
  baseURL?: string;
17
+ timeout?: number;
18
+ headers?: Record<string, string>;
19
+ httpClientFactory?: HttpClientFactory;
20
+ routes?: CoreApiProviderRoutes;
13
21
  };
14
22
  /**
15
23
  * Optional configuration for the IllaSDK instance.
@@ -55,6 +63,29 @@ type SendMessageContext = {
55
63
  chatId?: never;
56
64
  userContext: UserContext;
57
65
  };
66
+ /**
67
+ * Options for sending a message via the SDK.
68
+ *
69
+ * @property signal - Abort signal used to cancel the request
70
+ * @property onRequestId - Callback invoked with the requestId after the request is initiated,
71
+ * enabling real-time telemetry streaming
72
+ */
73
+ type SdkSendMessageOptions = {
74
+ signal?: AbortSignal;
75
+ onRequestId?: (requestId: string) => void;
76
+ };
77
+ /**
78
+ * Metadata extracted from a SendMessageResult response.
79
+ * Provides detailed information about the response including errors, pending tools, and tool errors.
80
+ */
81
+ type ResponseMetadata = {
82
+ isError: boolean;
83
+ text?: string;
84
+ messages?: MessageHistoryType;
85
+ pendingTools?: ReadonlyArray<PendingToolCallType>;
86
+ toolErrors?: ReadonlyArray<IllaToolErrorJSON>;
87
+ error?: CoreApiChatErrorResponse;
88
+ };
58
89
  /**
59
90
  * Error raised when attempting to interact with a chat that doesn't exist.
60
91
  *
@@ -195,15 +226,16 @@ declare class IllaSDK {
195
226
  * If a chatId is provided, the message will be sent to the existing chat.
196
227
  * If a chatId is not provided, a new chat will be created with the provided userContext.
197
228
  *
198
- * @param msg - The message text to send
229
+ * @param msg - The message to send (can be a string or Prompt object)
199
230
  * @param context - Context containing either chatId for existing chat or userContext for new chat
231
+ * @param chatOptions - Optional chat configuration when creating a new chat
200
232
  * @returns {Promise<SendMessageResult>} The AI's response including chat ID, response text, and any pending tools
201
233
  *
202
234
  * @example
203
235
  * ```typescript
204
236
  * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
205
237
  *
206
- * // Start a new conversation
238
+ * // Start a new conversation with a string
207
239
  * const result1 = await sdk.sendMessage(
208
240
  * "What can you help me with?",
209
241
  * { userContext: { address: "0x1234..." } }
@@ -211,19 +243,73 @@ declare class IllaSDK {
211
243
  * console.log(result1.response.text);
212
244
  * console.log("Chat ID:", result1.chatId);
213
245
  *
214
- * // Continue the conversation using the chat ID
215
- * const result2 = await sdk.sendMessage(
216
- * "I want to swap 1 ETH for USDC on Base",
217
- * { chatId: result1.chatId }
218
- * );
246
+ * // Continue the conversation with a Prompt object
247
+ * const prompt = new Prompt({ text: "I want to swap 1 ETH for USDC on Base" });
248
+ * const result2 = await sdk.sendMessage(prompt, { chatId: result1.chatId });
219
249
  *
220
250
  * // Check if there are tools to execute
221
251
  * if (result2.response.pendingTools && result2.response.pendingTools.length > 0) {
222
252
  * console.log("Tool to execute:", result2.response.pendingTools[0]);
223
253
  * }
254
+ *
255
+ * // With telemetry callback for real-time events
256
+ * const result3 = await sdk.sendMessage(
257
+ * "Show me my balance",
258
+ * { chatId: result1.chatId },
259
+ * undefined,
260
+ * {
261
+ * onRequestId: (requestId) => {
262
+ * // Connect to telemetry stream
263
+ * telemetryClient.connect(requestId);
264
+ * }
265
+ * }
266
+ * );
224
267
  * ```
225
268
  */
226
- sendMessage(msg: string, context: SendMessageContext): Promise<SendMessageResult>;
269
+ sendMessage(msg: string | Prompt, context: SendMessageContext, chatOptions?: Omit<ChatOptions, "userContext">, options?: SdkSendMessageOptions): Promise<SendMessageResult>;
270
+ /**
271
+ * Sends a message with streaming response via SSE.
272
+ *
273
+ * Instead of waiting for the full response, this method streams telemetry events
274
+ * in real-time as they occur during orchestration. The final result is delivered
275
+ * through the `onComplete` callback.
276
+ *
277
+ * This eliminates the need for a separate telemetry subscription - events and
278
+ * the result are delivered through a single HTTP connection.
279
+ *
280
+ * @param msg - The message to send (can be a string or Prompt object)
281
+ * @param context - Context containing either chatId for existing chat or userContext for new chat
282
+ * @param options - Streaming options with event callbacks
283
+ * @param chatOptions - Optional chat configuration when creating a new chat
284
+ * @returns {Promise<void>} A promise that resolves when the stream ends
285
+ *
286
+ * @example
287
+ * ```typescript
288
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
289
+ *
290
+ * await sdk.sendMessageStreaming(
291
+ * "What can you help me with?",
292
+ * { userContext: { address: "0x1234..." } },
293
+ * {
294
+ * onEvent: (event) => console.log('Event:', event.type),
295
+ * onComplete: (result) => {
296
+ * console.log('Response:', result.text);
297
+ * console.log('Pending tools:', result.pendingTools?.length ?? 0);
298
+ * },
299
+ * onError: (error) => console.error('Error:', error),
300
+ * }
301
+ * );
302
+ * ```
303
+ */
304
+ sendMessageStreaming(msg: string | Prompt, context: SendMessageContext, options?: SendMessageStreamingOptions, chatOptions?: Omit<ChatOptions, "userContext">): Promise<void>;
305
+ /**
306
+ * Gets an existing chat or creates a new one if it doesn't exist.
307
+ *
308
+ * @param context - Context containing either chatId for existing chat or userContext for new chat
309
+ * @param chatOptions - Optional chat configuration when creating a new chat
310
+ * @returns {Chat} The chat instance
311
+ */
312
+ private getOrCreateChat;
227
313
  /**
228
314
  * Sends the result of a tool execution back to the AI. This method is used to complete
229
315
  * the tool execution loop when the AI requests a tool to be executed.
@@ -231,10 +317,12 @@ declare class IllaSDK {
231
317
  * @param chatId - The ID of the chat to send the tool result to
232
318
  * @param toolResult - The result of the tool execution
233
319
  * @returns {Promise<SendMessageResult>} The AI's response after processing the tool result
234
- * @throws {Error} If the chat with the specified chatId is not found
320
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
235
321
  *
236
322
  * @example
237
323
  * ```typescript
324
+ * import { IllaToolOutcome, IllaToolError } from '@illalabs/interfaces';
325
+ *
238
326
  * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
239
327
  *
240
328
  * // Start a conversation that will request a tool execution
@@ -247,23 +335,26 @@ declare class IllaSDK {
247
335
  * if (result1.response.pendingTools && result1.response.pendingTools.length > 0) {
248
336
  * const tool = result1.response.pendingTools[0];
249
337
  *
250
- * // Execute the tool (e.g., send a transaction)
251
- * const executionResult = await executeTool(tool);
252
- *
253
- * // Send the result back to the ILLA
254
- * const toolResult: ToolResultType = {
255
- * toolCallId: tool.toolCallId,
256
- * toolName: tool.toolName,
257
- * result?: executionResult,
258
- * error?: executionResult.error,
259
- * };
338
+ * // Execute the tool and create the outcome
339
+ * let toolResult: IllaToolOutcome<unknown>;
340
+ * try {
341
+ * const executionResult = await executeTool(tool);
342
+ * toolResult = IllaToolOutcome.success(tool.toolCallId, tool.toolName, executionResult);
343
+ * } catch (error) {
344
+ * toolResult = IllaToolOutcome.error(
345
+ * tool.toolCallId,
346
+ * tool.toolName,
347
+ * IllaToolError.execution(tool.toolCallId, tool.toolName, error.message)
348
+ * );
349
+ * }
260
350
  *
261
- * const result2 = await sdk.sendToolResult(result1.chatId, toolResult);
351
+ * // Send the result back to ILLA
352
+ * const result2 = await sdk.sendToolResult(result1.chatId, toolResult.toJSON());
262
353
  * console.log(result2.response.text); // ILLA's response after processing the tool result
263
354
  * }
264
355
  * ```
265
356
  */
266
- sendToolResult(chatId: string, toolResult: ToolResultType): Promise<SendMessageResult>;
357
+ sendToolResult(chatId: string, toolResult: IllaToolOutcomeJSON): Promise<SendMessageResult>;
267
358
  /**
268
359
  * Gets the messages for a given chat ID.
269
360
  *
@@ -272,6 +363,198 @@ declare class IllaSDK {
272
363
  * @throws {ChatNotFound} If the chat with the specified chatId is not found
273
364
  */
274
365
  getMessages(chatId: string): Promise<MessageHistoryType>;
366
+ /**
367
+ * Appends messages to an existing chat's message history.
368
+ *
369
+ * @param chatId - The ID of the chat to append messages to
370
+ * @param messages - The messages to append to the chat history
371
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
372
+ *
373
+ * @example
374
+ * ```typescript
375
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
376
+ *
377
+ * // Append synthetic messages for testing or prompting
378
+ * await sdk.appendMessages(chatId, [
379
+ * { role: "user", content: "Previous context..." },
380
+ * { role: "assistant", content: "Understood..." }
381
+ * ]);
382
+ * ```
383
+ */
384
+ appendMessages(chatId: string, messages: MessageHistoryType): Promise<void>;
385
+ /**
386
+ * Clears the message history for a chat while keeping the chat instance.
387
+ *
388
+ * @param chatId - The ID of the chat to clear
389
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
390
+ *
391
+ * @example
392
+ * ```typescript
393
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
394
+ *
395
+ * // Clear chat history to start fresh
396
+ * await sdk.clearContext(chatId);
397
+ * ```
398
+ */
399
+ clearContext(chatId: string): Promise<void>;
400
+ /**
401
+ * Deletes a chat and removes all associated data.
402
+ *
403
+ * @param chatId - The ID of the chat to delete
404
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
405
+ *
406
+ * @example
407
+ * ```typescript
408
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
409
+ *
410
+ * // Clean up chat when done
411
+ * await sdk.deleteChat(chatId);
412
+ * ```
413
+ */
414
+ deleteChat(chatId: string): Promise<void>;
415
+ /**
416
+ * Sends multiple tool results back to the AI in a single request.
417
+ * This method is used when multiple tools need to be executed and their results
418
+ * sent back together.
419
+ *
420
+ * @param chatId - The ID of the chat to send the tool results to
421
+ * @param toolResults - Array of tool execution results
422
+ * @param options - Optional parameters including AbortSignal
423
+ * @returns {Promise<SendMessageResult>} The AI's response after processing all tool results
424
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
425
+ *
426
+ * @example
427
+ * ```typescript
428
+ * import { IllaToolOutcome, IllaToolError } from '@illalabs/interfaces';
429
+ *
430
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
431
+ *
432
+ * // Execute multiple tools and send results together
433
+ * const toolResults = pendingTools.map(tool => {
434
+ * try {
435
+ * const result = executeToolSync(tool);
436
+ * return IllaToolOutcome.success(tool.toolCallId, tool.toolName, result);
437
+ * } catch (error) {
438
+ * return IllaToolOutcome.error(
439
+ * tool.toolCallId,
440
+ * tool.toolName,
441
+ * IllaToolError.execution(tool.toolCallId, tool.toolName, error.message)
442
+ * );
443
+ * }
444
+ * });
445
+ *
446
+ * const response = await sdk.sendToolResults(chatId, toolResults.map(r => r.toJSON()));
447
+ * ```
448
+ */
449
+ sendToolResults(chatId: string, toolResults: IllaToolOutcomeJSON[]): Promise<SendMessageResult>;
450
+ /**
451
+ * Subscribes to status updates for a long-running tool execution.
452
+ *
453
+ * @param params - Parameters identifying the tool execution to monitor
454
+ * @param callbacks - Event handlers for status changes and errors
455
+ * @param config - Optional polling configuration
456
+ * @returns {EventSubscription} Subscription handle to cancel monitoring
457
+ *
458
+ * @example
459
+ * ```typescript
460
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
461
+ *
462
+ * const subscription = sdk.subscribeToToolStatus(
463
+ * { toolName: "swap", protocol: "li.fi", args: txHash },
464
+ * {
465
+ * onStatusChange: (event) => console.log("Status:", event.status),
466
+ * onError: (error) => console.error("Error:", error)
467
+ * },
468
+ * { interval: 2000, maxDuration: 300, maxRetries: 3 }
469
+ * );
470
+ *
471
+ * // Later, cancel the subscription
472
+ * subscription.unsubscribe();
473
+ * ```
474
+ */
475
+ subscribeToToolStatus<TPayload = unknown, TError = unknown>(params: AsyncToolCheckerCheckParams, callbacks: AsyncCheckerEvents<TPayload, TError>, config?: Partial<PollingConfig>): EventSubscription;
476
+ /**
477
+ * Awaits the completion of a long-running action triggered by a chat.
478
+ *
479
+ * @param chatId - The ID of the chat that triggered the action
480
+ * @param descriptor - Descriptor identifying the action to track
481
+ * @returns {Promise<AwaitActionResult>} The final status of the action
482
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
483
+ *
484
+ * @example
485
+ * ```typescript
486
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
487
+ *
488
+ * const result = await sdk.awaitAction(chatId, {
489
+ * toolName: "swap",
490
+ * protocol: "li.fi",
491
+ * args: { txHash: "0x..." }
492
+ * });
493
+ *
494
+ * if (result.isError) {
495
+ * console.error("Action failed:", result.error);
496
+ * } else {
497
+ * console.log("Action completed:", result.response);
498
+ * }
499
+ * ```
500
+ */
501
+ awaitAction(chatId: string, descriptor: AwaitableActionDescriptor): Promise<AwaitActionResult>;
502
+ /**
503
+ * Gets the underlying Chat instance for advanced operations.
504
+ *
505
+ * @param chatId - The ID of the chat to retrieve
506
+ * @returns {Chat} The Chat instance
507
+ * @throws {ChatNotFound} If the chat with the specified chatId is not found
508
+ *
509
+ * @example
510
+ * ```typescript
511
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
512
+ *
513
+ * const chat = sdk.getChat(chatId);
514
+ * // Now you can use advanced Chat methods directly
515
+ * const context = await chat.getContext();
516
+ * ```
517
+ */
518
+ getChat(chatId: string): Chat;
519
+ /**
520
+ * Gets all active chat IDs as an array.
521
+ * Alias for the chatIds getter property.
522
+ *
523
+ * @returns {string[]} Array of active chat IDs
524
+ *
525
+ * @example
526
+ * ```typescript
527
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
528
+ *
529
+ * const ids = sdk.getChatIds();
530
+ * console.log("Active chats:", ids);
531
+ * ```
532
+ */
533
+ getChatIds(): string[];
534
+ /**
535
+ * Helper method to extract detailed response metadata from a SendMessageResult.
536
+ * Provides access to incompleteTools, toolErrors, and other response details.
537
+ *
538
+ * @param result - The SendMessageResult to extract metadata from
539
+ * @returns {ResponseMetadata} Extracted response metadata
540
+ *
541
+ * @example
542
+ * ```typescript
543
+ * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
544
+ *
545
+ * const result = await sdk.sendMessage("Hello", { chatId });
546
+ * const metadata = sdk.getResponseMetadata(result);
547
+ *
548
+ * if (metadata.incompleteTools?.length > 0) {
549
+ * console.log("Incomplete tools:", metadata.incompleteTools);
550
+ * }
551
+ * if (metadata.toolErrors?.length > 0) {
552
+ * console.log("Tool errors:", metadata.toolErrors);
553
+ * }
554
+ * ```
555
+ */
556
+ getResponseMetadata(result: SendMessageResult): ResponseMetadata;
557
+ private isSuccessResponse;
275
558
  }
276
559
  /**
277
560
  * Exports the public API of the SDK.
@@ -286,5 +569,8 @@ export { ContextManager } from "./context/index.js";
286
569
  export { AsyncToolChecker } from "./asyncToolChecker/index.js";
287
570
  export { CoreApiProvider } from "./providers/index.js";
288
571
  export { UserContextMissing } from "./chat/errors/index.js";
289
- export type { illaSDKConfig, ChatContextSnapshot, CacheEntryOptions, ICache, IContextManager, SendMessageContext, };
572
+ export { TelemetryClient, TelemetryStreamFailed, type TelemetryClientConfig, type TelemetryStreamState, } from "./telemetry/index.js";
573
+ export { parseSSEStream, SSEParse, StreamingHttpError, StreamingResponseBodyNull, StreamingServerError, type ErrorStreamEvent, type ResultStreamEvent, type SSEStreamEndEvent, type SSEStreamEvent, type StreamEventType, type TelemetryStreamEvent, } from "./streaming/index.js";
574
+ export type { illaSDKConfig, illaSDKOptions, ChatOptions, ChatContextSnapshot, CacheEntryOptions, ICache, IContextManager, SendMessageContext, SendMessageResult, SendMessageStreamingOptions, SdkSendMessageOptions, ResponseMetadata, AsyncCheckerEvents, AsyncToolCheckerCheckParams, AwaitableActionDescriptor, AwaitActionResult, CoreApiProviderConfig, CoreApiProviderRoutes, EventSubscription, HttpClientFactory, PollingConfig, ContextManagerOptions, };
575
+ export type { MessageHistoryType, IllaToolOutcomeJSON, IllaToolErrorJSON, UserContext, ModelContext, PersonalityContext, CoreApiChatErrorResponse, CoreApiChatSuccessResponse, PendingToolCallType, TelemetryEvent, TelemetryEventType, OrchestratorPhase, OrchestratorObserver, BaseTelemetryEvent, ToolResultStatus, TelemetryEnabledResponse, } from "@illalabs/interfaces";
290
576
  //# sourceMappingURL=sdk.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/sdk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,WAAW,EACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EACR,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,MAAM,EACN,eAAe,EACf,iBAAiB,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEH,IAAI,EACJ,cAAc,EAKjB,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,KAAK,aAAa,GAAG;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,KAAK,cAAc,GACb;IACI,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,cAAc,CAAC,EAAE,KAAK,CAAC;CAC1B,GACD;IACI,cAAc,EAAE,eAAe,CAAC;IAChC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,qBAAqB,CAAC,EAAE,KAAK,CAAC;CACjC,CAAC;AAER;;;;;GAKG;AACH,KAAK,WAAW,GAAG;IACf,WAAW,EAAE,WAAW,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,KAAK,kBAAkB,GACjB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnD;;;;;GAKG;AACH,cAAM,YAAa,SAAQ,KAAK;IAC5B;;OAEG;IACH,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B;;;;;OAKG;gBACgB,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAK5D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAM,OAAO;IACT,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,cAAc,CAAkB;IAExC,OAAO,CAAC,KAAK,CAAgC;IAE7C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;gBACS,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,cAAc;IAkB3D;;;;;;;;;;;;;;;OAeG;IACH,IAAW,OAAO,IAAI,MAAM,EAAE,CAE7B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACW,uBAAuB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,qBAAqB,GAC/B,cAAc;IAIjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI;IAiB9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACI,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAYxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACU,cAAc,CACvB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,cAAc,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAO7B;;;;;;OAMG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAOxE;AAED;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EACR,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,MAAM,EACN,eAAe,EACf,kBAAkB,GACrB,CAAC"}
1
+ {"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/sdk.ts"],"names":[],"mappings":"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"}