@serenity-star/sdk 1.0.3 → 2.1.0

package/dist/index.d.mts

@@ -76,9 +76,9 @@ type SerenityClientOptions = {
     baseUrl?: string;
 };
 /**
- * Base options for executing any type of agent.
- */
-type AgentExecutionOptions = {
+ * Base options for setting up an agent.
+*/
+type AgentSetupOptions = {
     /**
      * Optional identifier for the user initiating the execution.
      */
@@ -92,20 +92,20 @@ type AgentExecutionOptions = {
      */
     channel?: string;
     /**
-     * Optional array of volatile knowledge IDs to include in the execution context.
+     * Optional key-value pairs of input parameters specific to the agent.
      */
-    volatileKnowledgeIds?: string[];
+    inputParameters?: {
+        [key: string]: any;
+    };
 };
 /**
- * Extends AgentExecutionOptions to include input parameters for agents that support them.
+ * Base options for executing any type of agent.
  */
-type AgentExecutionOptionsWithParameters = AgentExecutionOptions & {
+type AgentExecutionOptions = AgentSetupOptions & {
     /**
-     * Optional key-value pairs of input parameters specific to the agent.
+     * Optional array of volatile knowledge IDs to include in the execution context.
      */
-    inputParameters?: {
-        [key: string]: any;
-    };
+    volatileKnowledgeIds?: string[];
 };
 /**
  * Maps agent types to their specific execution options for conversational agents.
@@ -114,8 +114,8 @@ type AgentExecutionOptionsWithParameters = AgentExecutionOptions & {
  * Both assistant and copilot agents support input parameters in addition to base execution options.
  */
 type ConversationalAgentExecutionOptionsMap = {
-    "assistant": AgentExecutionOptionsWithParameters;
-    "copilot": AgentExecutionOptionsWithParameters;
+    "assistant": AgentSetupOptions;
+    "copilot": AgentSetupOptions;
 };
 /**
  * Maps agent types to their specific execution options for system agents.
@@ -125,9 +125,8 @@ type ConversationalAgentExecutionOptionsMap = {
  * - Proxy agents have specific proxy execution options
  */
 type SystemAgentExecutionOptionsMap = {
-    "activity": AgentExecutionOptionsWithParameters;
-    "plan": AgentExecutionOptionsWithParameters;
-    "chat-completion": AgentExecutionOptionsWithParameters & {
+    "activity": AgentExecutionOptions;
+    "chat-completion": AgentExecutionOptions & {
         /** The single message content for the chat completion */
         message: string;
         /** Optional array of message objects representing the conversation history */
@@ -142,13 +141,15 @@ type AgentResult = {
     content: string;
     instance_id: string;
     json_content?: any;
-    meta_analysis?: MetaAnalysisRes;
-    completion_usage?: CompletionUsageRes;
+    meta_analysis?: MetaAnalysisRes$1;
+    completion_usage?: CompletionUsageRes$1;
     time_to_first_token?: number;
-    executor_task_logs?: ExecutorTaskLogsRes;
+    executor_task_logs?: ExecutorTaskLogsRes$1;
     action_results?: {
-        [key: string]: PluginExecutionResult;
+        [key: string]: PluginExecutionResult$1;
     };
+    agent_message_id?: string;
+    user_message_id?: string;
 };
 /**
  * Represents the events that can occur during a realtime session.
@@ -210,7 +211,7 @@ type ExecuteBodyParams = Array<{
     Key: string;
     Value: any;
 }>;
-type MetaAnalysisRes = {
+type MetaAnalysisRes$1 = {
     [key: string]: any;
 } & {
     policy_compliance?: {
@@ -258,23 +259,370 @@ type MetaAnalysisRes = {
         topic_area?: string;
     };
 };
-type CompletionUsageRes = {
+type CompletionUsageRes$1 = {
     completion_tokens: number;
     prompt_tokens: number;
     total_tokens: number;
 };
-type ExecutorTaskLogsRes = {
+type ExecutorTaskLogsRes$1 = {
     description: string;
     duration: number;
 }[];
-type SpeechGenerationResult = {
+type SpeechGenerationResult$1 = {
     content: string;
     finish_reason?: string;
     usage?: {
         [key: string]: any;
     };
 };
+type PluginExecutionResult$1 = SpeechGenerationResult$1;
+type BaseErrorBody = {
+    message: string;
+    statusCode: number;
+};
+type ValidationErrorBody = BaseErrorBody & {
+    errors: {
+        [key: string]: string;
+    };
+};
+type RateLimitErrorBody = BaseErrorBody & {
+    retryAfter: number;
+};
+
+type MessageAdditionalInfo = {
+    inputParameters?: {
+        [key: string]: any;
+    };
+    volatileKnowledgeIds?: string[];
+};
+type ConversationInfoResult = {
+    agent: {
+        isRealtime: boolean;
+        version: number;
+        visionEnabled: boolean;
+        imageId: string;
+    };
+    conversation: {
+        initialMessage: string;
+        starters: string[];
+    };
+    channel?: ChatWidgetRes;
+};
+type ChatWidgetRes = {
+    expanded: boolean;
+    opened: boolean;
+    showExpandButton: boolean;
+    allowUpload: boolean;
+    allowAudioRecording: boolean;
+    storeConversation: boolean;
+    stream: boolean;
+    extractPageContent: boolean;
+    showSystemLogo: boolean;
+    userIdentifier: string;
+    logoURL: string;
+    mode: string;
+    engagementMessage: EngagementMessageRes;
+    locale: LocaleRes;
+    theme: ThemeRes;
+    enableFeedbackRecollection: boolean;
+};
+type EngagementMessageRes = {
+    enabled: boolean;
+    message: string;
+    showAfter: number;
+};
+type LocaleRes = {
+    uploadFileErrorMessage: string;
+    uploadFilesErrorMessage: string;
+    chatErrorMessage: string;
+    chatInitConversationErrorMessage: string;
+    headerTitle: string;
+    finalizedMessage: string;
+    limitExceededMessage: string;
+    waitUntilMessage: string;
+    remainingMessage: string;
+    inputPlaceholder: string;
+    internalLinkMessage: string;
+    newChatBtnMessage: string;
+    exceededMaxNumberOfFilesMessage: string;
+    exceededMaxFileStatusChecksMessage: string;
+    closedConversationMessage: string;
+};
+type ThemeRes = {
+    header: HeaderThemeRes;
+    fabButton: FabButtonThemeRes;
+    sendButton: SendButtonThemeRes;
+    engagementMessage: EngagementMessageThemeRes;
+    conversationStarters: ConversationStartersThemeRes;
+    scrollToBottomIndicator: ScrollToBottomIndicatorThemeRes;
+    uploadFileBtn: UploadFileBtnThemeRes;
+    messageBubble: MessageBubbleThemeRes;
+};
+type HeaderThemeRes = {
+    bgColor: string;
+    textColor: string;
+    resetChatBtn: ResetChatBtnThemeRes;
+    minimizeBtn: MinimizeBtnThemeRes;
+};
+type FabButtonThemeRes = {
+    bgColor: string;
+    iconStrokeColor: string;
+    buttonSize: number;
+    iconSize: number;
+};
+type SendButtonThemeRes = {
+    bgColor: string;
+    iconStrokeColor: string;
+};
+type EngagementMessageThemeRes = {
+    bgColor: string;
+    textColor: string;
+};
+type ConversationStartersThemeRes = {
+    bgColor: string;
+    textColor: string;
+    containerBgColor: string;
+    initialMessageBgColor: string;
+    initialMessageTextColor: string;
+};
+type ScrollToBottomIndicatorThemeRes = {
+    bgColor: string;
+    iconStrokeColor: string;
+};
+type UploadFileBtnThemeRes = {
+    iconStrokeColor: string;
+};
+type MessageBubbleThemeRes = {
+    user: UserThemeRes;
+    assistant: AssistantThemeRes;
+};
+type ResetChatBtnThemeRes = {
+    bgColor: string;
+    hoverBgColor: string;
+    textColor: string;
+};
+type MinimizeBtnThemeRes = {
+    iconStrokeColor: string;
+};
+type UserThemeRes = {
+    bgColor: string;
+    textColor: string;
+};
+type AssistantThemeRes = {
+    bgColor: string;
+    textColor: string;
+};
+type ConversationRes = {
+    startDate: string;
+    endDate: string;
+    id: string;
+    messages: Message[];
+    name: string;
+    userIdentifier?: string;
+    useVision?: boolean;
+    conversationStarters?: string[];
+    open?: boolean;
+};
+type Message = ({
+    sender: "user";
+} | {
+    sender: "bot";
+    conversationStarters?: string[];
+}) & {
+    id: string;
+    created_at: Date;
+    type: "text" | "image" | "error" | "info";
+    value: string;
+    attachments?: VolatileKnowledgeUploadRes[] | AttachedVolatileKnowledge[];
+    meta_analysis?: MetaAnalysisRes;
+    completion_usage?: CompletionUsageRes;
+    time_to_first_token?: number;
+    executor_task_logs?: ExecutorTaskLogsRes;
+    attached_volatile_knowledges?: AttachedVolatileKnowledge[];
+    action_results?: {
+        [key: string]: PluginExecutionResult;
+    };
+};
 type PluginExecutionResult = SpeechGenerationResult;
+type SpeechGenerationResult = {
+    content: string;
+    finish_reason?: string;
+    usage?: object;
+};
+type VolatileKnowledgeUploadRes = {
+    id: string;
+    expirationDate: string;
+    status: string;
+    fileName: string;
+    fileSize: number;
+};
+type AttachedVolatileKnowledge = {
+    id: string;
+    expirationDate: string;
+    fileId: string;
+    fileName: string;
+    fileSize: number;
+    downloadUrl: string;
+};
+type CompletionUsageRes = {
+    completion_tokens: number;
+    prompt_tokens: number;
+    total_tokens: number;
+};
+type ExecutorTaskLogsRes = {
+    description: string;
+    duration: number;
+}[];
+type MetaAnalysisRes = {
+    [key: string]: any;
+} & {
+    policy_compliance?: {
+        compliance_score?: number;
+        explanation?: string;
+        policy_violations?: {
+            source_id?: string;
+            source_document_name: string;
+            chunk_id?: string;
+            section_number?: string;
+            section?: string;
+            policy?: string;
+            policy_name: string;
+            policy_id?: string;
+        }[];
+    };
+    pii_release_risk?: {
+        risk_score?: number;
+        explanation?: string;
+    };
+    ethics?: {
+        score?: number;
+        explanation?: string;
+        avoid_topics?: {
+            topic: string;
+            reason: string;
+        }[];
+    };
+    deception_estimation?: {
+        deception_score?: number;
+        explanation?: string;
+    };
+    cybersecurity_threat?: {
+        threat_assessment?: number;
+        explanation?: string;
+    };
+    social_content_risk?: {
+        risk_score?: number;
+        explanation?: string;
+    };
+    conversation_analysis?: {
+        emotion_value_estimate?: number;
+        predicted_next_goal?: string;
+        attended_to_features?: string[];
+        topic_area?: string;
+    };
+    guardrails_compliance?: {
+        explanation?: string;
+        investment_score?: number;
+        legal_score?: number;
+        medical_score?: number;
+        tax_score?: number;
+    };
+};
+type SubmitFeedbackOptions = {
+    /**
+     * The ID of the agent message to provide feedback for
+     */
+    agentMessageId: string;
+    /**
+     * The feedback value - true for positive, false for negative
+     */
+    feedback: boolean;
+};
+type SubmitFeedbackResult = {
+    /**
+     * Indicates if the feedback was successfully submitted
+     */
+    success: boolean;
+};
+type RemoveFeedbackOptions = {
+    /**
+     * The ID of the agent message to remove feedback from
+     */
+    agentMessageId: string;
+};
+type RemoveFeedbackResult = {
+    /**
+     * Indicates if the feedback was successfully removed
+     */
+    success: boolean;
+};
+
+declare class Conversation extends EventEmitter<SSEStreamEvents> {
+    #private;
+    private agentCode;
+    private apiKey;
+    private baseUrl;
+    private userIdentifier?;
+    private agentVersion?;
+    private channel?;
+    private inputParameters?;
+    conversationId?: string;
+    info: ConversationInfoResult | null;
+    private constructor();
+    private static create;
+    private static createWithoutInfo;
+    streamMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    sendMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    getConversationById(id: string, options?: {
+        showExecutorTaskLogs: boolean;
+    }): Promise<ConversationRes>;
+    getInfo(): Promise<ConversationInfoResult>;
+    /**
+     * Submit feedback for an agent message in the conversation.
+     *
+     * @param options - The feedback options including the agent message ID and feedback value
+     * @returns A promise that resolves to the feedback submission result
+     * @throws Error if the conversation ID is not set or if the request fails
+     *
+     * @example
+     * ```typescript
+     * const conversation = await client.agents.assistants.createConversation("agent-code");
+     * const response = await conversation.sendMessage("Hello!");
+     *
+     * // Submit positive feedback
+     * await conversation.submitFeedback({
+     *   agentMessageId: response.agent_message_id!,
+     *   feedback: true
+     * });
+     * ```
+     */
+    submitFeedback(options: SubmitFeedbackOptions): Promise<SubmitFeedbackResult>;
+    /**
+     * Remove feedback for an agent message in the conversation.
+     *
+     * @param options - The feedback options including the agent message ID
+     * @returns A promise that resolves to the feedback removal result
+     * @throws Error if the conversation ID is not set or if the request fails
+     *
+     * @example
+     * ```typescript
+     * const conversation = await client.agents.assistants.createConversation("agent-code");
+     * const response = await conversation.sendMessage("Hello!");
+     *
+     * // Submit feedback first
+     * await conversation.submitFeedback({
+     *   agentMessageId: response.agent_message_id!,
+     *   feedback: true
+     * });
+     *
+     * // Remove feedback
+     * await conversation.removeFeedback({
+     *   agentMessageId: response.agent_message_id!
+     * });
+     * ```
+     */
+    removeFeedback(options: RemoveFeedbackOptions): Promise<RemoveFeedbackResult>;
+}
 
 /**
  * Events that can be emitted by a realtime session.
@@ -351,7 +699,7 @@ declare class RealtimeSession extends EventEmitter<RealtimeSessionEvents> {
     private localStream?;
     private dataChannel?;
     private socket?;
-    constructor(agentCode: string, apiKey: string, baseUrl: string, options?: AgentExecutionOptionsWithParameters);
+    constructor(agentCode: string, apiKey: string, baseUrl: string, options?: AgentSetupOptions);
     /**
      * Starts the real-time session.
      */
@@ -370,29 +718,6 @@ declare class RealtimeSession extends EventEmitter<RealtimeSessionEvents> {
     unmuteMicrophone(): void;
 }
 
-type MessageOptions = {
-    inputParameters?: {
-        [key: string]: any;
-    };
-    volatileKnowledgeIds?: string[];
-};
-
-declare class Conversation extends EventEmitter<SSEStreamEvents> {
-    #private;
-    private agentCode;
-    private apiKey;
-    private baseUrl;
-    private inputParameters?;
-    private userIdentifier?;
-    private agentVersion?;
-    private channel?;
-    conversationId?: string;
-    private constructor();
-    private static create;
-    streamMessage(message: string, options?: MessageOptions): Promise<AgentResult>;
-    sendMessage(message: string, options?: MessageOptions): Promise<AgentResult>;
-}
-
 declare abstract class SystemAgent<T extends keyof SystemAgentExecutionOptionsMap> extends EventEmitter<SSEStreamEvents> {
     protected readonly agentCode: string;
     protected readonly apiKey: string;
@@ -431,16 +756,6 @@ declare class ChatCompletion extends SystemAgent<"chat-completion"> {
     private appendInputParametersIfNeeded;
 }
 
-declare class Plan extends SystemAgent<"plan"> {
-    private constructor();
-    static create(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["plan"]): Plan;
-    static createAndExecute(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["plan"]): Promise<AgentResult>;
-    protected createExecuteBody(stream: boolean): ExecuteBodyParams | {
-        [key: string]: any;
-    };
-    private appendInputParametersIfNeeded;
-}
-
 declare class Proxy extends SystemAgent<"proxy"> {
     private constructor();
     static create(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["proxy"]): Proxy;
@@ -477,7 +792,7 @@ type ConversationalAgentScope<T extends keyof ConversationalAgentExecutionOption
      * @param options - Additional options for the conversation
      * @returns A Promise that resolves to a Conversation instance
      */
-    createConversation: (agentCode: string, options?: ConversationalAgentExecutionOptionsMap[T]) => Promise<Conversation>;
+    createConversation: (agentCode: string, options?: AgentSetupOptions) => Promise<Conversation>;
     /**
      * Create a real-time session with an agent.
      * This allows for voice interactions and real-time responses.
@@ -501,6 +816,10 @@ type ConversationalAgentScope<T extends keyof ConversationalAgentExecutionOption
      * @returns A RealtimeSession instance
      */
     createRealtimeSession: (agentCode: string, options?: ConversationalAgentExecutionOptionsMap[T]) => RealtimeSession;
+    getInfoByCode: (agentCode: string, options?: AgentSetupOptions) => Promise<ConversationInfoResult> | null;
+    getConversationById: (agentCode: string, conversationId: string, options?: {
+        showExecutorTaskLogs: boolean;
+    }) => Promise<ConversationRes>;
 };
 type SystemAgentScope<T extends keyof SystemAgentExecutionOptionsMap, TCreateReturn> = {
     /**
@@ -555,7 +874,7 @@ declare class SerenityClient {
     private baseUrl;
     /**
      * Interact with the different agents available in Serenity Star.
-     * You can choose between assistants, copilots, activities, chat completions, proxies, and plans.
+     * You can choose between assistants, copilots, activities, chat completions and proxies.
      */
     readonly agents: {
         /**
@@ -726,32 +1045,18 @@ declare class SerenityClient {
          * ```
          */
         proxies: SystemAgentScope<"proxy", Proxy>;
-        /**
-         * Interact with Plan agents available in Serenity Star.
-         * This allows you to execute plans.
-         * It supports streaming.
-         * Plan agents are capable of building an execution plan based on the user input and execute it.
-         *
-         * ## Regular plan execution:
-         * ```typescript
-         * const response = await client.agents.plans.execute("event-planner");
-         * console.log(response.content);
-         * ```
-         *
-         * ## Stream plan with SSE:
-         * ```typescript
-         * const plan = client.agents.plans
-         *   .create("event-planner")
-         *   .on("start", () => console.log("Started"))
-         *   .on("content", (chunk) => console.log(chunk))
-         *   .on("error", (error) => console.error(error));
-         *
-         * await plan.stream();
-         * ```
-         */
-        plans: SystemAgentScope<"plan", Plan>;
     };
     constructor(options: SerenityClientOptions);
 }
 
-export { type AgentResult, RealtimeSession, SerenityClient };
+declare class ExternalErrorHelper {
+    static determineErrorType(error: unknown): {
+        type: "RateLimitError" | "ValidationError" | "BaseError" | "UnknownError";
+        error: RateLimitErrorBody | ValidationErrorBody | BaseErrorBody | unknown;
+    };
+    private static isRateLimitErrorBody;
+    private static isValidationErrorBody;
+    private static isBaseErrorBody;
+}
+
+export { type AgentResult, type BaseErrorBody, type ChatWidgetRes, Conversation, type ConversationInfoResult, type ConversationRes, ExternalErrorHelper as ErrorHelper, type Message, type RateLimitErrorBody, RealtimeSession, type RemoveFeedbackOptions, type RemoveFeedbackResult, SerenityClient, type SubmitFeedbackOptions, type SubmitFeedbackResult, type ValidationErrorBody };