@serenity-star/sdk 2.4.4 → 2.5.1

package/dist/index.d.mts

@@ -62,17 +62,37 @@ type ProxyExecutionOptions = {
     useVision?: boolean;
 };
 
-/**
- * Options for configuring the Serenity client.
- */
-type SerenityClientOptions = {
-    /**
-     * The API key used for authenticating requests to the Serenity API.
-     */
+/** Context passed to the tokenProvider callback */
+type TokenProviderContext = {
+    publicKey: string;
+    /** The base URL of the Serenity API */
+    baseUrl: string;
+    /** The agent code this token is scoped to */
+    agentCode: string;
+};
+/** The tokenProvider function signature */
+type TokenProviderFn = (params: {
+    context: TokenProviderContext;
+}) => Promise<string>;
+/** Agent Client Credentials — scoped to a single agent */
+type AgentClientCredentials = {
+    /** The agent this credential is scoped to */
+    agentCode: string;
+    /** The public key issued for this agent */
+    publicKey: string;
+    /** Callback to obtain a client token from your backend */
+    tokenProvider: TokenProviderFn;
+};
+/** API Key auth mode — full access */
+type ApiKeyClientOptions = {
     apiKey: string;
-    /**
-     * The base URL of the Serenity API.
-     */
+    agentClientCredentials?: never;
+    baseUrl?: string;
+};
+/** Agent Client Credentials auth mode — scoped to one agent */
+type AgentClientCredentialsOptions = {
+    apiKey?: never;
+    agentClientCredentials: AgentClientCredentials;
     baseUrl?: string;
 };
 /**
@@ -646,15 +666,27 @@ type ConnectorStatusResult = {
     isConnected: boolean;
 };
 
+interface AuthProvider {
+    /** Returns the headers to attach to HTTP requests */
+    getHeaders(): Promise<Record<string, string>>;
+    /** Returns the WebSocket sub-protocols for authentication */
+    getWebSocketProtocols(): Promise<string[]>;
+    /**
+     * Handles a 401 Unauthorized response.
+     * Returns true if the token was refreshed and the request should be retried.
+     */
+    handleUnauthorized(response: Response): Promise<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 readonly authProvider;
     private ids;
-    constructor(baseUrl: string, apiKey: string);
+    constructor(baseUrl: string, authProvider: AuthProvider);
     /**
      * 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.
@@ -721,7 +753,7 @@ declare class VolatileKnowledgeManager {
 declare class Conversation extends EventEmitter<SSEStreamEvents> {
     #private;
     private agentCode;
-    private apiKey;
+    private authProvider;
     private baseUrl;
     private userIdentifier?;
     private agentVersion?;
@@ -752,6 +784,13 @@ declare class Conversation extends EventEmitter<SSEStreamEvents> {
     sendMessage(message: string, options?: MessageAdditionalInfo): Promise<AgentResult>;
     sendAudioMessage(audio: Blob, options?: MessageAdditionalInfo): Promise<AgentResult>;
     streamAudioMessage(audio: Blob, options?: MessageAdditionalInfo): Promise<AgentResult>;
+    /**
+     * Download an attached file from a conversation message.
+     *
+     * @param downloadUrl - Attachment download URL
+     * @returns The downloaded attachment as a Blob
+     */
+    downloadAttachment(downloadUrl: string): Promise<Blob>;
     /**
      * Stops the current streaming response, aborting the SSE connection.
      * If no stream is active, this method does nothing.
@@ -900,7 +939,7 @@ type RealtimeSessionEvents = {
 declare class RealtimeSession extends EventEmitter<RealtimeSessionEvents> {
     #private;
     private agentCode;
-    private apiKey;
+    private authProvider;
     private baseUrl;
     private inputParameters?;
     private userIdentifier?;
@@ -913,7 +952,7 @@ declare class RealtimeSession extends EventEmitter<RealtimeSessionEvents> {
     private localStream?;
     private dataChannel?;
     private socket?;
-    constructor(agentCode: string, apiKey: string, baseUrl: string, options?: AgentSetupOptions);
+    constructor(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: AgentSetupOptions);
     /**
      * Starts the real-time session.
      */
@@ -935,7 +974,7 @@ 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 authProvider: AuthProvider;
     protected readonly baseUrl: string;
     protected readonly options?: SystemAgentExecutionOptionsMap[T] | undefined;
     /**
@@ -953,7 +992,7 @@ declare abstract class SystemAgent<T extends keyof SystemAgentExecutionOptionsMa
     readonly volatileKnowledge: VolatileKnowledgeManager;
     private readonly fileManager;
     private connection;
-    protected constructor(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap[T] | undefined);
+    protected constructor(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap[T] | undefined);
     /**
      * Stops the current streaming response, aborting the SSE connection.
      * If no stream is active, this method does nothing.
@@ -984,8 +1023,8 @@ declare abstract class SystemAgent<T extends keyof SystemAgentExecutionOptionsMa
 
 declare class Activity extends SystemAgent<"activity"> {
     private constructor();
-    static create(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["activity"]): Activity;
-    static createAndExecute(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["activity"]): Promise<AgentResult>;
+    static create(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap["activity"]): Activity;
+    static createAndExecute(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap["activity"]): Promise<AgentResult>;
     protected createExecuteBody(stream: boolean): ExecuteBodyParams | {
         [key: string]: any;
     };
@@ -994,8 +1033,8 @@ declare class Activity extends SystemAgent<"activity"> {
 
 declare class ChatCompletion extends SystemAgent<"chat-completion"> {
     private constructor();
-    static create(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["chat-completion"]): ChatCompletion;
-    static createAndExecute(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["chat-completion"]): Promise<AgentResult>;
+    static create(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap["chat-completion"]): ChatCompletion;
+    static createAndExecute(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap["chat-completion"]): Promise<AgentResult>;
     protected createExecuteBody(stream: boolean): ExecuteBodyParams | {
         [key: string]: any;
     };
@@ -1006,8 +1045,8 @@ declare class ChatCompletion extends SystemAgent<"chat-completion"> {
 
 declare class Proxy extends SystemAgent<"proxy"> {
     private constructor();
-    static create(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["proxy"]): Proxy;
-    static createAndExecute(agentCode: string, apiKey: string, baseUrl: string, options?: SystemAgentExecutionOptionsMap["proxy"]): Promise<AgentResult>;
+    static create(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap["proxy"]): Proxy;
+    static createAndExecute(agentCode: string, authProvider: AuthProvider, baseUrl: string, options?: SystemAgentExecutionOptionsMap["proxy"]): Promise<AgentResult>;
     protected createExecuteBody(stream: boolean): ExecuteBodyParams | {
         [key: string]: any;
     };
@@ -1116,6 +1155,17 @@ type SystemAgentScope<T extends keyof SystemAgentExecutionOptionsMap, TCreateRet
      */
     create: (agentCode: string, options?: SystemAgentExecutionOptionsMap[T]) => TCreateReturn;
 };
+type ScopedConversationalAgentScope<T extends keyof ConversationalAgentExecutionOptionsMap> = {
+    createConversation: (options?: AgentSetupOptions) => Promise<Conversation>;
+    getInfo: (options?: AgentSetupOptions) => Promise<ConversationInfoResult | null>;
+    getConversationById: (conversationId: string, options?: {
+        showExecutorTaskLogs: boolean;
+    }) => Promise<ConversationRes>;
+};
+type ScopedSystemAgentScope<T extends keyof SystemAgentExecutionOptionsMap, TCreateReturn> = {
+    execute: (options?: SystemAgentExecutionOptionsMap[T]) => Promise<AgentResult>;
+    create: (options?: SystemAgentExecutionOptionsMap[T]) => TCreateReturn;
+};
 
 type AudioServiceScope = {
     /**
@@ -1142,210 +1192,53 @@ type AudioServiceScope = {
     transcribe: (file: File, options?: TranscribeAudioOptions) => Promise<TranscribeAudioResult>;
 };
 
-declare class SerenityClient {
-    private apiKey;
+type FullAgents = {
+    assistants: ConversationalAgentScope<"assistant">;
+    copilots: ConversationalAgentScope<"copilot">;
+    activities: SystemAgentScope<"activity", Activity>;
+    chatCompletions: SystemAgentScope<"chat-completion", ChatCompletion>;
+    proxies: SystemAgentScope<"proxy", Proxy>;
+};
+type FullServices = {
+    audio: AudioServiceScope;
+};
+type ScopedAgents = {
+    assistants: ScopedConversationalAgentScope<"assistant">;
+    copilots: ScopedConversationalAgentScope<"copilot">;
+    activities: ScopedSystemAgentScope<"activity", Activity>;
+    chatCompletions: ScopedSystemAgentScope<"chat-completion", ChatCompletion>;
+    proxies: ScopedSystemAgentScope<"proxy", Proxy>;
+};
+/** Full-access client returned when using API Key authentication */
+declare class FullSerenityClient {
     private baseUrl;
     /**
      * Interact with the different agents available in Serenity Star.
      * You can choose between assistants, copilots, activities, chat completions and proxies.
      */
-    readonly agents: {
-        /**
-         * Interact with Assistant agents available in Serenity Star.
-         * This allows you to create conversations and real-time sessions.
-         *
-         * ## Start a new conversation and send a message:
-         * ```typescript
-         * // Regular text conversation
-         * const conversation = await client.agents.assistants.createConversation("translator-assistant");
-         * const response = await conversation.sendMessage("The sun was beginning to set...");
-         * console.log(response.content);
-         *
-         * ```
-         *
-         * ## Stream message with SSE
-         * ```typescript
-         * const conversation = await client.agents.assistants
-         *   .createConversation("translator-assistant")
-         *   .on("start", () => console.log("Started"))
-         *   .on("content", (chunk) => console.log(chunk))
-         *   .on("error", (error) => console.error(error));
-         *
-         * await conversation.streamMessage("The sun was beginning to set...");
-         *
-         * ```
-         *
-         * ## Real-time voice conversation example:
-         * ```typescript
-         * const session = client.agents.assistants.createRealtimeSession("marketing-assistant")
-         *   .on("session.created", () => console.log("Session started"))
-         *   .on("speech.started", () => console.log("User started talking"))
-         *   .on("speech.stopped", () => console.log("User stopped talking"))
-         *   .on("response.done", (response) => console.log("Response:", response))
-         *   .on("session.stopped", () => console.log("Session stopped"));
-         *
-         * await session.start();
-         * // Later: session.stop();
-         * ```
-         */
-        assistants: ConversationalAgentScope<"assistant">;
-        /**
-         * Interact with Copilot agents available in Serenity Star.
-         * Similar to assistants but allows you to interact with the UI through callbacks.
-         *
-         * Text conversation example:
-         * ```typescript
-         * // Regular conversation
-         * const conversation = await client.agents.copilots.createConversation("app-copilot");
-         * const response = await conversation.sendMessage("How do I create a new support ticket?");
-         * console.log(response.content);
-         *
-         * // Streaming conversation
-         * const conversation = await client.agents.copilots
-         *   .createConversation("app-copilot")
-         *   .on("start", () => console.log("Started"))
-         *   .on("content", (chunk) => console.log(chunk))
-         *   .on("error", (error) => console.error(error));
-         *
-         * await conversation.streamMessage("How do I create a new support ticket?");
-         * ```
-         */
-        copilots: ConversationalAgentScope<"copilot">;
-        /**
-         * Interact with Activity agents available in Serenity Star.
-         * This allows you to execute activities.
-         * It supports streaming.
-         * Execute simple tasks based on the user input.
-         *
-         * ## Regular activity execution:
-         * ```typescript
-         * const response = await client.agents.activities.execute("marketing-campaign")
-         * console.log(response.content);
-         *
-         * // With parameters
-         * const response = await client.agents.activities.execute("cooking-activity", {
-         *   inputParameters: {
-         *     ingredientOne: "chicken",
-         *     ingredientTwo: "onion",
-         *     ingredientThree: "cream",
-         *   }
-         * });
-         * ```
-         *
-         * ## Stream activity with SSE:
-         * ```typescript
-         * const activity = client.agents.activities
-         *   .create("marketing-campaign")
-         *   .on("start", () => console.log("Started"))
-         *   .on("content", (chunk) => console.log(chunk))
-         *   .on("error", (error) => console.error(error));
-         *
-         * await activity.stream();
-         * ```
-         */
-        activities: SystemAgentScope<"activity", Activity>;
-        /**
-         * Interact with Chat Completion agents available in Serenity Star.
-         * This allows you to execute chat completions.
-         * It supports streaming.
-         * Chat completions allows you to fully control the conversation and generate completions.
-         *
-         * ## Regular chat completion:
-         * ```typescript
-         * const response = await client.agents.chatCompletions.execute("Health-Coach", {
-         *   message: "Hello!"
-         * });
-         * console.log(response.content);
-         * ```
-         *
-         * ## Stream chat completion with SSE:
-         * ```typescript
-         * const chatCompletion = client.agents.chatCompletions
-         *   .create("Health-Coach", {
-         *     message: "Hello!"
-         *   })
-         *   .on("start", () => console.log("Started"))
-         *   .on("content", (chunk) => console.log(chunk))
-         *   .on("error", (error) => console.error(error));
-         *
-         * await chatCompletion.stream();
-         * ```
-         */
-        chatCompletions: SystemAgentScope<"chat-completion", ChatCompletion>;
-        /**
-         * Interact with Proxy agents available in Serenity Star.
-         * This allows you to execute proxies.
-         * It supports streaming.
-         * Proxy agents allows you to define a set of parameters dynamically for each request
-         *
-         * ## Regular proxy execution:
-         * ```typescript
-         * const response = await client.agents.proxies.execute("proxy-agent", {
-         *   model: "gpt-4o-mini-2024-07-18",
-         *   messages: [
-         *     {
-         *       role: "system",
-         *       content: "You are a helpful assistant. Always use short and concise responses"
-         *     },
-         *     { role: "user", content: "What is artificial intelligence?" }
-         *   ],
-         *   temperature: 1,
-         *   max_tokens: 250
-         * });
-         * console.log(response.content);
-         * ```
-         *
-         * ## Stream proxy with SSE:
-         * ```typescript
-         * const proxy = client.agents.proxies
-         *   .create("proxy-agent", {
-         *     model: "gpt-4o-mini-2024-07-18",
-         *     messages: [
-         *     {
-         *       role: "system",
-         *       content: "You are a helpful assistant. Always use short and concise responses"
-         *     },
-         *       { role: "user", content: "What is artificial intelligence?" }
-         *     ],
-         *     temperature: 1,
-         *     max_tokens: 250
-         *   })
-         *   .on("start", () => console.log("Started"))
-         *   .on("content", (chunk) => console.log(chunk))
-         *   .on("error", (error) => console.error(error));
-         *
-         * await proxy.stream();
-         * ```
-         */
-        proxies: SystemAgentScope<"proxy", Proxy>;
-    };
+    readonly agents: FullAgents;
     /**
      * 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);
+    readonly services: FullServices;
+    constructor(options: ApiKeyClientOptions);
+}
+/** Agent-scoped client returned when using Agent Client Credentials authentication */
+declare class ScopedSerenityClient {
+    private baseUrl;
+    /**
+     * Interact with the agent scoped to this client.
+     * Operations do not require an agentCode parameter — it is baked in.
+     */
+    readonly agents: ScopedAgents;
+    constructor(options: AgentClientCredentialsOptions);
+}
+interface SerenityClientConstructor {
+    new (options: ApiKeyClientOptions): FullSerenityClient;
+    new (options: AgentClientCredentialsOptions): ScopedSerenityClient;
 }
+declare const SerenityClient: SerenityClientConstructor;
 
 declare class ExternalErrorHelper {
     static determineErrorType(error: unknown): {
@@ -1357,4 +1250,4 @@ declare class ExternalErrorHelper {
     private static isBaseErrorBody;
 }
 
-export { type AgentResult, type AttachedVolatileKnowledgeRes, 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 };
+export { type AgentClientCredentials, type AgentResult, type AttachedVolatileKnowledgeRes, type AuthProvider, type BaseErrorBody, type ChatWidgetRes, type ConnectorStatusResult, Conversation, type ConversationInfoResult, type ConversationRes, ExternalErrorHelper as ErrorHelper, type FileError, type FileUploadRes, type FullAgents, FullSerenityClient, type FullServices, type GetConnectorStatusOptions, type Message, type PendingAction, type RateLimitErrorBody, RealtimeSession, type RemoveFeedbackOptions, type RemoveFeedbackResult, type ScopedAgents, ScopedSerenityClient, SerenityClient, type SubmitFeedbackOptions, type SubmitFeedbackResult, type TokenProviderContext, type TokenProviderFn, type TranscribeAudioOptions, type TranscribeAudioResult, type ValidationErrorBody, VolatileKnowledgeManager, type VolatileKnowledgeUploadOptions, type VolatileKnowledgeUploadRes };