@serenity-star/sdk 2.2.1 → 2.4.0

package/dist/index.d.mts

@@ -291,12 +291,66 @@ type BaseErrorBody = {
 };
 type ValidationErrorBody = BaseErrorBody & {
     errors: {
-        [key: string]: string;
+        [key: string]: string | string[];
     };
 };
 type RateLimitErrorBody = BaseErrorBody & {
     retryAfter: number;
 };
+type FileError = {
+    file?: File;
+    error: Error;
+};
+type VolatileKnowledgeUploadRes = {
+    success: true;
+    id: string;
+    expirationDate: string;
+    status: string;
+    fileName: string;
+    fileSize: number;
+} | {
+    success: false;
+    error: FileError;
+};
+type VolatileKnowledgeUploadOptions = {
+    processEmbeddings?: boolean;
+    noExpiration?: boolean;
+    expirationDays?: number;
+    useVision?: boolean;
+    locale?: {
+        uploadFileErrorMessage?: string;
+    };
+};
+type TranscribeAudioOptions = {
+    modelId?: string;
+    prompt?: string;
+    userIdentifier?: string;
+};
+type TranscribeAudioResult = {
+    transcript: string;
+    metadata?: TranscriptionMetadata;
+    tokenUsage?: TranscriptionTokenUsage;
+    cost?: TranscriptionCost;
+};
+type TranscriptionMetadata = {
+    language?: string;
+    duration?: number;
+};
+type TranscriptionTokenUsage = {
+    completionTokens: number;
+    promptTokens: number;
+    totalTokens: number;
+};
+type TranscriptionCost = {
+    completion: number;
+    prompt: number;
+    total: number;
+    currency: string;
+};
+type FileUploadRes = {
+    id: string;
+    downloadUrl: string;
+};
 
 type MessageAdditionalInfo = {
     inputParameters?: {
@@ -309,6 +363,7 @@ type ConversationInfoResult = {
         isRealtime: boolean;
         version: number;
         visionEnabled: boolean;
+        audioInputEnabled: boolean;
         imageId: string;
     };
     conversation: {
@@ -458,13 +513,6 @@ type SpeechGenerationResult = {
     finish_reason?: string;
     usage?: object;
 };
-type VolatileKnowledgeUploadRes = {
-    id: string;
-    expirationDate: string;
-    status: string;
-    fileName: string;
-    fileSize: number;
-};
 type AttachedVolatileKnowledge = {
     id: string;
     expirationDate: string;
@@ -582,6 +630,78 @@ type ConnectorStatusResult = {
     isConnected: boolean;
 };
 
+/**
+ * Manages volatile knowledge files for agent instances.
+ * Provides methods to upload, remove, and clear files.
+ */
+declare class VolatileKnowledgeManager {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private ids;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Upload a file to be used as volatile knowledge in the next agent execution.
+     * The file will be automatically included in subsequent messages/executions until cleared.
+     *
+     * @param file - The file to upload
+     * @param options - Optional configuration for file processing
+     * @returns Upload result with file details or errors
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await conversation.volatileKnowledge.upload(file);
+     *
+     * if (uploadResult.success) {
+     *   console.log('File uploaded:', uploadResult.id);
+     * } else {
+     *   console.error('Upload failed:', uploadResult.error);
+     * }
+     * ```
+     */
+    upload(file: File, options?: VolatileKnowledgeUploadOptions): Promise<VolatileKnowledgeUploadRes>;
+    /**
+     * Remove a specific volatile knowledge file by its ID.
+     *
+     * @param fileId - The ID of the file to remove
+     * @returns True if the file was removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await conversation.volatileKnowledge.upload(file);
+     *
+     * if (uploadResult.success) {
+     *   // Remove the file from the queue
+     *   conversation.volatileKnowledge.removeById(uploadResult.id);
+     * }
+     * ```
+     */
+    removeById(fileId: string): boolean;
+    /**
+     * Clear all volatile knowledge files from the queue.
+     *
+     * @example
+     * ```typescript
+     * await conversation.volatileKnowledge.upload(file1);
+     * await conversation.volatileKnowledge.upload(file2);
+     *
+     * // Clear all files from the queue
+     * conversation.volatileKnowledge.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get all volatile knowledge file IDs currently in the queue.
+     * @internal
+     */
+    getIds(): string[];
+    /**
+     * Fetch details of a volatile knowledge file by its ID.
+     * @param fileId - The ID of the file to fetch
+     * @returns The file details or an error
+     */
+    getById(fileId: string): Promise<VolatileKnowledgeUploadRes>;
+}
+
 declare class Conversation extends EventEmitter<SSEStreamEvents> {
     #private;
     private agentCode;
@@ -593,11 +713,27 @@ declare class Conversation extends EventEmitter<SSEStreamEvents> {
     private inputParameters?;
     conversationId?: string;
     info: ConversationInfoResult | null;
+    /**
+     * Volatile knowledge manager for uploading and managing temporary files.
+     * Files uploaded through this manager will be included in the next message/execution.
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await conversation.volatileKnowledge.upload(file);
+     * if (uploadResult.success) {
+     *   console.log('File uploaded:', uploadResult.id);
+     * }
+     * ```
+     */
+    readonly volatileKnowledge: VolatileKnowledgeManager;
+    private readonly fileManager;
     private constructor();
     private static create;
     private static createWithoutInfo;
     streamMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
     sendMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    sendAudioMessage(audio: Blob, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    streamAudioMessage(audio: Blob, options?: MessageAdditionalInfo): Promise<AgentResult>;
     getConversationById(id: string, options?: {
         showExecutorTaskLogs: boolean;
     }): Promise<ConversationRes>;
@@ -765,14 +901,33 @@ declare class RealtimeSession extends EventEmitter<RealtimeSessionEvents> {
 }
 
 declare abstract class SystemAgent<T extends keyof SystemAgentExecutionOptionsMap> extends EventEmitter<SSEStreamEvents> {
+    #private;
     protected readonly agentCode: string;
     protected readonly apiKey: string;
     protected readonly baseUrl: string;
     protected readonly options?: SystemAgentExecutionOptionsMap[T] | undefined;
+    /**
+     * Volatile knowledge manager for uploading and managing temporary files.
+     * Files uploaded through this manager will be included in the next execution.
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await activity.volatileKnowledge.upload(file);
+     * if (uploadResult.success) {
+     *   console.log('File uploaded:', uploadResult.id);
+     * }
+     * ```
+     */
+    readonly volatileKnowledge: VolatileKnowledgeManager;
+    private readonly fileManager;
     protected constructor(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap[T] | undefined);
     stream(): Promise<AgentResult>;
+    streamWithAudio(audio: Blob): Promise<AgentResult>;
     protected execute(): Promise<AgentResult>;
-    protected createExecuteBody(stream: boolean): ExecuteBodyParams | {
+    executeWithAudio(audio: Blob): Promise<AgentResult>;
+    protected createExecuteBody(stream: boolean, audio?: {
+        fileId: string;
+    }): ExecuteBodyParams | {
         [key: string]: any;
     };
     protected appendUserIdentifierIfNeeded(body: ExecuteBodyParams): void;
@@ -915,6 +1070,31 @@ type SystemAgentScope<T extends keyof SystemAgentExecutionOptionsMap, TCreateRet
     create: (agentCode: string, options?: SystemAgentExecutionOptionsMap[T]) => TCreateReturn;
 };
 
+type AudioServiceScope = {
+    /**
+     * Transcribe an audio file using the Serenity API.
+     *
+     * @param file - The audio file to transcribe
+     * @param options - Optional configuration for transcription
+     * @returns Transcription result with transcript, metadata, token usage, and cost information
+     *
+     * @example
+     * ```typescript
+     * const result = await client.services.audio.transcribe(audioFile, {
+     *   modelId: '[YOUR_MODEL_ID]',
+     *   prompt: 'This is a conversation about AI',
+     *   userIdentifier: 'user123'
+     * });
+     *
+     * console.log('Transcript:', result.transcript);
+     * console.log('Duration:', result.metadata?.duration);
+     * console.log('Total tokens:', result.tokenUsage?.totalTokens);
+     * console.log('Cost:', result.cost?.total, result.cost?.currency);
+     * ```
+     */
+    transcribe: (file: File, options?: TranscribeAudioOptions) => Promise<TranscribeAudioResult>;
+};
+
 declare class SerenityClient {
     private apiKey;
     private baseUrl;
@@ -1092,6 +1272,31 @@ declare class SerenityClient {
          */
         proxies: SystemAgentScope<"proxy", Proxy>;
     };
+    /**
+     * Access various services provided by Serenity Star.
+     * Services include audio transcription and other utility features.
+     */
+    readonly services: {
+        /**
+         * Audio-related services including transcription.
+         *
+         * ## Transcribe an audio file:
+         * ```typescript
+         * const file = new File([audioBlob], "audio.mp3", { type: "audio/mpeg" });
+         * const result = await client.services.audio.transcribe(file, {
+         *   modelId: '[YOUR_MODEL_ID]',
+         *   prompt: 'This is a conversation about AI',
+         *   userIdentifier: 'user123'
+         * });
+         *
+         * console.log('Transcript:', result.transcript);
+         * console.log('Duration:', result.metadata?.duration);
+         * console.log('Total tokens:', result.tokenUsage?.totalTokens);
+         * console.log('Cost:', result.cost?.total, result.cost?.currency);
+         * ```
+         */
+        audio: AudioServiceScope;
+    };
     constructor(options: SerenityClientOptions);
 }
 
@@ -1105,4 +1310,4 @@ declare class ExternalErrorHelper {
     private static isBaseErrorBody;
 }
 
-export { type AgentResult, type BaseErrorBody, type ChatWidgetRes, type ConnectorStatusResult, Conversation, type ConversationInfoResult, type ConversationRes, ExternalErrorHelper as ErrorHelper, type GetConnectorStatusOptions, type Message, type PendingAction, type RateLimitErrorBody, RealtimeSession, type RemoveFeedbackOptions, type RemoveFeedbackResult, SerenityClient, type SubmitFeedbackOptions, type SubmitFeedbackResult, type ValidationErrorBody };
+export { type AgentResult, type BaseErrorBody, type ChatWidgetRes, type ConnectorStatusResult, Conversation, type ConversationInfoResult, type ConversationRes, ExternalErrorHelper as ErrorHelper, type FileError, type FileUploadRes, type GetConnectorStatusOptions, type Message, type PendingAction, type RateLimitErrorBody, RealtimeSession, type RemoveFeedbackOptions, type RemoveFeedbackResult, SerenityClient, type SubmitFeedbackOptions, type SubmitFeedbackResult, type TranscribeAudioOptions, type TranscribeAudioResult, type ValidationErrorBody, VolatileKnowledgeManager, type VolatileKnowledgeUploadOptions, type VolatileKnowledgeUploadRes };

package/dist/index.d.ts

@@ -291,12 +291,66 @@ type BaseErrorBody = {
 };
 type ValidationErrorBody = BaseErrorBody & {
     errors: {
-        [key: string]: string;
+        [key: string]: string | string[];
     };
 };
 type RateLimitErrorBody = BaseErrorBody & {
     retryAfter: number;
 };
+type FileError = {
+    file?: File;
+    error: Error;
+};
+type VolatileKnowledgeUploadRes = {
+    success: true;
+    id: string;
+    expirationDate: string;
+    status: string;
+    fileName: string;
+    fileSize: number;
+} | {
+    success: false;
+    error: FileError;
+};
+type VolatileKnowledgeUploadOptions = {
+    processEmbeddings?: boolean;
+    noExpiration?: boolean;
+    expirationDays?: number;
+    useVision?: boolean;
+    locale?: {
+        uploadFileErrorMessage?: string;
+    };
+};
+type TranscribeAudioOptions = {
+    modelId?: string;
+    prompt?: string;
+    userIdentifier?: string;
+};
+type TranscribeAudioResult = {
+    transcript: string;
+    metadata?: TranscriptionMetadata;
+    tokenUsage?: TranscriptionTokenUsage;
+    cost?: TranscriptionCost;
+};
+type TranscriptionMetadata = {
+    language?: string;
+    duration?: number;
+};
+type TranscriptionTokenUsage = {
+    completionTokens: number;
+    promptTokens: number;
+    totalTokens: number;
+};
+type TranscriptionCost = {
+    completion: number;
+    prompt: number;
+    total: number;
+    currency: string;
+};
+type FileUploadRes = {
+    id: string;
+    downloadUrl: string;
+};
 
 type MessageAdditionalInfo = {
     inputParameters?: {
@@ -309,6 +363,7 @@ type ConversationInfoResult = {
         isRealtime: boolean;
         version: number;
         visionEnabled: boolean;
+        audioInputEnabled: boolean;
         imageId: string;
     };
     conversation: {
@@ -458,13 +513,6 @@ type SpeechGenerationResult = {
     finish_reason?: string;
     usage?: object;
 };
-type VolatileKnowledgeUploadRes = {
-    id: string;
-    expirationDate: string;
-    status: string;
-    fileName: string;
-    fileSize: number;
-};
 type AttachedVolatileKnowledge = {
     id: string;
     expirationDate: string;
@@ -582,6 +630,78 @@ type ConnectorStatusResult = {
     isConnected: boolean;
 };
 
+/**
+ * Manages volatile knowledge files for agent instances.
+ * Provides methods to upload, remove, and clear files.
+ */
+declare class VolatileKnowledgeManager {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private ids;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Upload a file to be used as volatile knowledge in the next agent execution.
+     * The file will be automatically included in subsequent messages/executions until cleared.
+     *
+     * @param file - The file to upload
+     * @param options - Optional configuration for file processing
+     * @returns Upload result with file details or errors
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await conversation.volatileKnowledge.upload(file);
+     *
+     * if (uploadResult.success) {
+     *   console.log('File uploaded:', uploadResult.id);
+     * } else {
+     *   console.error('Upload failed:', uploadResult.error);
+     * }
+     * ```
+     */
+    upload(file: File, options?: VolatileKnowledgeUploadOptions): Promise<VolatileKnowledgeUploadRes>;
+    /**
+     * Remove a specific volatile knowledge file by its ID.
+     *
+     * @param fileId - The ID of the file to remove
+     * @returns True if the file was removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await conversation.volatileKnowledge.upload(file);
+     *
+     * if (uploadResult.success) {
+     *   // Remove the file from the queue
+     *   conversation.volatileKnowledge.removeById(uploadResult.id);
+     * }
+     * ```
+     */
+    removeById(fileId: string): boolean;
+    /**
+     * Clear all volatile knowledge files from the queue.
+     *
+     * @example
+     * ```typescript
+     * await conversation.volatileKnowledge.upload(file1);
+     * await conversation.volatileKnowledge.upload(file2);
+     *
+     * // Clear all files from the queue
+     * conversation.volatileKnowledge.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get all volatile knowledge file IDs currently in the queue.
+     * @internal
+     */
+    getIds(): string[];
+    /**
+     * Fetch details of a volatile knowledge file by its ID.
+     * @param fileId - The ID of the file to fetch
+     * @returns The file details or an error
+     */
+    getById(fileId: string): Promise<VolatileKnowledgeUploadRes>;
+}
+
 declare class Conversation extends EventEmitter<SSEStreamEvents> {
     #private;
     private agentCode;
@@ -593,11 +713,27 @@ declare class Conversation extends EventEmitter<SSEStreamEvents> {
     private inputParameters?;
     conversationId?: string;
     info: ConversationInfoResult | null;
+    /**
+     * Volatile knowledge manager for uploading and managing temporary files.
+     * Files uploaded through this manager will be included in the next message/execution.
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await conversation.volatileKnowledge.upload(file);
+     * if (uploadResult.success) {
+     *   console.log('File uploaded:', uploadResult.id);
+     * }
+     * ```
+     */
+    readonly volatileKnowledge: VolatileKnowledgeManager;
+    private readonly fileManager;
     private constructor();
     private static create;
     private static createWithoutInfo;
     streamMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
     sendMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    sendAudioMessage(audio: Blob, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    streamAudioMessage(audio: Blob, options?: MessageAdditionalInfo): Promise<AgentResult>;
     getConversationById(id: string, options?: {
         showExecutorTaskLogs: boolean;
     }): Promise<ConversationRes>;
@@ -765,14 +901,33 @@ declare class RealtimeSession extends EventEmitter<RealtimeSessionEvents> {
 }
 
 declare abstract class SystemAgent<T extends keyof SystemAgentExecutionOptionsMap> extends EventEmitter<SSEStreamEvents> {
+    #private;
     protected readonly agentCode: string;
     protected readonly apiKey: string;
     protected readonly baseUrl: string;
     protected readonly options?: SystemAgentExecutionOptionsMap[T] | undefined;
+    /**
+     * Volatile knowledge manager for uploading and managing temporary files.
+     * Files uploaded through this manager will be included in the next execution.
+     *
+     * @example
+     * ```typescript
+     * const uploadResult = await activity.volatileKnowledge.upload(file);
+     * if (uploadResult.success) {
+     *   console.log('File uploaded:', uploadResult.id);
+     * }
+     * ```
+     */
+    readonly volatileKnowledge: VolatileKnowledgeManager;
+    private readonly fileManager;
     protected constructor(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap[T] | undefined);
     stream(): Promise<AgentResult>;
+    streamWithAudio(audio: Blob): Promise<AgentResult>;
     protected execute(): Promise<AgentResult>;
-    protected createExecuteBody(stream: boolean): ExecuteBodyParams | {
+    executeWithAudio(audio: Blob): Promise<AgentResult>;
+    protected createExecuteBody(stream: boolean, audio?: {
+        fileId: string;
+    }): ExecuteBodyParams | {
         [key: string]: any;
     };
     protected appendUserIdentifierIfNeeded(body: ExecuteBodyParams): void;
@@ -915,6 +1070,31 @@ type SystemAgentScope<T extends keyof SystemAgentExecutionOptionsMap, TCreateRet
     create: (agentCode: string, options?: SystemAgentExecutionOptionsMap[T]) => TCreateReturn;
 };
 
+type AudioServiceScope = {
+    /**
+     * Transcribe an audio file using the Serenity API.
+     *
+     * @param file - The audio file to transcribe
+     * @param options - Optional configuration for transcription
+     * @returns Transcription result with transcript, metadata, token usage, and cost information
+     *
+     * @example
+     * ```typescript
+     * const result = await client.services.audio.transcribe(audioFile, {
+     *   modelId: '[YOUR_MODEL_ID]',
+     *   prompt: 'This is a conversation about AI',
+     *   userIdentifier: 'user123'
+     * });
+     *
+     * console.log('Transcript:', result.transcript);
+     * console.log('Duration:', result.metadata?.duration);
+     * console.log('Total tokens:', result.tokenUsage?.totalTokens);
+     * console.log('Cost:', result.cost?.total, result.cost?.currency);
+     * ```
+     */
+    transcribe: (file: File, options?: TranscribeAudioOptions) => Promise<TranscribeAudioResult>;
+};
+
 declare class SerenityClient {
     private apiKey;
     private baseUrl;
@@ -1092,6 +1272,31 @@ declare class SerenityClient {
          */
         proxies: SystemAgentScope<"proxy", Proxy>;
     };
+    /**
+     * Access various services provided by Serenity Star.
+     * Services include audio transcription and other utility features.
+     */
+    readonly services: {
+        /**
+         * Audio-related services including transcription.
+         *
+         * ## Transcribe an audio file:
+         * ```typescript
+         * const file = new File([audioBlob], "audio.mp3", { type: "audio/mpeg" });
+         * const result = await client.services.audio.transcribe(file, {
+         *   modelId: '[YOUR_MODEL_ID]',
+         *   prompt: 'This is a conversation about AI',
+         *   userIdentifier: 'user123'
+         * });
+         *
+         * console.log('Transcript:', result.transcript);
+         * console.log('Duration:', result.metadata?.duration);
+         * console.log('Total tokens:', result.tokenUsage?.totalTokens);
+         * console.log('Cost:', result.cost?.total, result.cost?.currency);
+         * ```
+         */
+        audio: AudioServiceScope;
+    };
     constructor(options: SerenityClientOptions);
 }
 
@@ -1105,4 +1310,4 @@ declare class ExternalErrorHelper {
     private static isBaseErrorBody;
 }
 
-export { type AgentResult, type BaseErrorBody, type ChatWidgetRes, type ConnectorStatusResult, Conversation, type ConversationInfoResult, type ConversationRes, ExternalErrorHelper as ErrorHelper, type GetConnectorStatusOptions, type Message, type PendingAction, type RateLimitErrorBody, RealtimeSession, type RemoveFeedbackOptions, type RemoveFeedbackResult, SerenityClient, type SubmitFeedbackOptions, type SubmitFeedbackResult, type ValidationErrorBody };
+export { type AgentResult, type BaseErrorBody, type ChatWidgetRes, type ConnectorStatusResult, Conversation, type ConversationInfoResult, type ConversationRes, ExternalErrorHelper as ErrorHelper, type FileError, type FileUploadRes, type GetConnectorStatusOptions, type Message, type PendingAction, type RateLimitErrorBody, RealtimeSession, type RemoveFeedbackOptions, type RemoveFeedbackResult, SerenityClient, type SubmitFeedbackOptions, type SubmitFeedbackResult, type TranscribeAudioOptions, type TranscribeAudioResult, type ValidationErrorBody, VolatileKnowledgeManager, type VolatileKnowledgeUploadOptions, type VolatileKnowledgeUploadRes };