perso-interactive-sdk-web 1.2.2 → 1.3.1

package/dist/server/index.d.ts

@@ -1,56 +1,10 @@
-type CreateSessionIdBody = {
-    using_stf_webrtc: boolean;
-    model_style: string;
-    prompt: string;
-    document?: string;
-    background_image?: string;
-    mcp_servers?: Array<string>;
-    padding_left?: number;
-    padding_top?: number;
-    padding_height?: number;
-    llm_type?: string;
-    tts_type?: string;
-    stt_type?: string;
-};
-/**
- * Requests a new session creation ID by POSTing the desired runtime options to
- * the Perso backend (`/api/v1/session/`).
- * @param apiServer Perso API server URL.
- * @param apiKey API key used for authentication.
- * @param params {
- *   using_stf_webrtc: boolean;
- *   llm_type?: string;
- *   tts_type?: string;
- *   stt_type?: string;
- *   model_style: string;
- *   prompt: string;
- *   document?: string;
- *   background_image?: string;
- *   mcp_servers?: Array<string>;
- *   padding_left?: number;
- *   padding_top?: number;
- *   padding_height?: number;
- * }
- * @returns Session ID returned by the server.
- */
-declare const createSessionId: (apiServer: string, apiKey: string, params: CreateSessionIdBody) => Promise<string>;
-/**
- * Retrieves the intro message for a specific prompt.
- * @param apiServer Perso API server URL.
- * @param apiKey API key used for authentication.
- * @param promptId The prompt ID to fetch intro message for.
- * @returns The intro message string.
- */
-declare const getIntroMessage: (apiServer: string, apiKey: string, promptId: string) => Promise<string>;
-
-declare class ApiError extends Error {
-    errorCode: number;
-    code: string;
-    detail: string;
-    attr?: string | undefined;
-    constructor(errorCode: number, code: string, detail: string, attr?: string | undefined);
+declare enum SessionCapabilityName {
+    LLM = "LLM",
+    TTS = "TTS",
+    STT = "STT",
+    STF_ONPREMISE = "STF_ONPREMISE",
+    STF_WEBRTC = "STF_WEBRTC"
 }
-
 declare enum SessionEvent {
     SESSION_START = "SESSION_START",
     SESSION_DURING = "SESSION_DURING",
@@ -61,6 +15,11 @@ declare enum SessionEvent {
     SESSION_STT = "SESSION_STT",
     SESSION_LLM = "SESSION_LLM"
 }
+interface TextNormalizationDownload {
+    config_id: string;
+    config_name: string;
+    file_url: string;
+}
 declare class PersoUtil {
     /**
      * @param apiServer Perso Interactive API Server
@@ -134,9 +93,11 @@ declare class PersoUtil {
      *   "audio": string
      * }
      */
-    static makeTTS(apiServer: string, { sessionId, text }: {
+    static makeTTS(apiServer: string, { sessionId, text, locale, output_format }: {
         sessionId: string;
         text: string;
+        locale?: string;
+        output_format?: string;
     }): Promise<{
         audio: string;
     }>;
@@ -186,6 +147,49 @@ declare class PersoUtil {
      *   }
      * ]
      */
+    /**
+     * @param apiServer Perso Interactive API Server
+     * @param apiKey Perso Interactive API Key
+     * @returns JSON
+     * [
+     *   {
+     *     "textnormalizationconfig_id": string,
+     *     "name": string,
+     *     "created_at": string
+     *   }
+     * ]
+     */
+    static getTextNormalizations(apiServer: string, apiKey: string): Promise<any>;
+    /**
+     * Downloads the ruleset data file for a Text Normalization Config.
+     * Returns a pre-signed Blob Storage URL for the CSV file.
+     * The client can download the file directly from this URL and leverage Azure Blob Storage ETag for caching.
+     * @param apiServer Perso Interactive API Server
+     * @param apiKey Perso Interactive API Key
+     * @param configId Text Normalization Config ID
+     * @returns JSON
+     * {
+     *   "config_id": string,
+     *   "config_name": string,
+     *   "file_url": string
+     * }
+     */
+    static downloadTextNormalization(apiServer: string, apiKey: string, configId: string): Promise<TextNormalizationDownload>;
+    /**
+     * Retrieves the list of session templates.
+     * @param apiServer Perso Interactive API Server
+     * @param apiKey Perso Interactive API Key
+     * @returns Array of SessionTemplate objects
+     */
+    static getSessionTemplates(apiServer: string, apiKey: string): Promise<SessionTemplate[]>;
+    /**
+     * Retrieves a single session template by ID.
+     * @param apiServer Perso Interactive API Server
+     * @param apiKey Perso Interactive API Key
+     * @param sessionTemplateId Session Template ID
+     * @returns SessionTemplate object
+     */
+    static getSessionTemplate(apiServer: string, apiKey: string, sessionTemplateId: string): Promise<SessionTemplate>;
     static getMcpServers(apiServer: string, apiKey: string): Promise<any>;
     /**
      * @param apiServer Perso Interactive API Server
@@ -290,4 +294,182 @@ declare class PersoUtil {
     static parseJson(response: Response): Promise<any>;
 }
 
-export { ApiError, PersoUtil as PersoUtilServer, createSessionId, getIntroMessage };
+interface Prompt {
+    prompt_id: string;
+    name: string;
+    description?: string;
+    system_prompt: string;
+    require_document?: boolean;
+    intro_message?: string;
+}
+interface SessionCapability {
+    name: SessionCapabilityName;
+    description?: string | null;
+}
+interface Document {
+    document_id: string;
+    title: string;
+    file: string;
+    description?: string;
+    search_count?: number;
+    ef_search?: number | null;
+    processed: boolean;
+    processed_v2: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface LLMType {
+    name: string;
+    service?: string;
+}
+interface TTSType {
+    name: string;
+    streamable?: boolean;
+    service: string;
+    model?: string | null;
+    voice?: string | null;
+    voice_settings?: unknown | null;
+    style?: string | null;
+    voice_extra_data?: unknown | null;
+}
+interface STTType {
+    name: string;
+    service: string;
+    options?: unknown | null;
+}
+interface TextNormalizationConfig {
+    textnormalizationconfig_id: string;
+    name: string;
+    created_at: string;
+}
+interface ModelStyleConfig {
+    modelstyleconfig_id: string;
+    key: string;
+    value: string;
+}
+interface AIHumanModelFile {
+    name: string;
+    file?: string | null;
+}
+interface ModelStyle {
+    name: string;
+    model: string;
+    model_file?: string | null;
+    model_files: AIHumanModelFile[];
+    style: string;
+    file?: string | null;
+    platform_type?: string;
+    configs: ModelStyleConfig[];
+}
+interface BackgroundImage {
+    backgroundimage_id: string;
+    title: string;
+    image: string;
+    created_at: string;
+}
+interface MCPServer {
+    mcpserver_id: string;
+    name: string;
+    description?: string;
+    url: string;
+    transport_protocol?: string;
+    server_timeout_sec?: number;
+    extra_data?: unknown | null;
+}
+interface SessionTemplate {
+    sessiontemplate_id: string;
+    name: string;
+    description: string | null;
+    prompt: Prompt;
+    capability: SessionCapability[];
+    document: Document | null;
+    llm_type: LLMType;
+    tts_type: TTSType;
+    stt_type: STTType;
+    text_normalization_config: TextNormalizationConfig | null;
+    text_normalization_locale: string | null;
+    model_style: ModelStyle;
+    background_image: BackgroundImage | null;
+    agent: string | null;
+    padding_left: number | null;
+    padding_top: number | null;
+    padding_height: number | null;
+    extra_data: unknown | null;
+    mcp_servers: MCPServer[];
+    created_at: string;
+    last_used_at: string | null;
+}
+
+type CreateSessionIdBody = {
+    using_stf_webrtc: boolean;
+    model_style: string;
+    prompt: string;
+    document?: string;
+    background_image?: string;
+    mcp_servers?: Array<string>;
+    padding_left?: number;
+    padding_top?: number;
+    padding_height?: number;
+    llm_type?: string;
+    tts_type?: string;
+    stt_type?: string;
+    text_normalization_config?: string;
+    text_normalization_locale?: string | null;
+};
+/**
+ * Requests a new session creation ID by POSTing the desired runtime options to
+ * the Perso backend (`/api/v1/session/`).
+ *
+ * @overload Creates a session from a SessionTemplate ID. Internally calls
+ * `getSessionTemplate` to resolve the template and maps it to the request body.
+ * @param apiServer Perso API server URL.
+ * @param apiKey API key used for authentication.
+ * @param sessionTemplateId SessionTemplate ID to resolve configuration from.
+ * @returns Session ID returned by the server.
+ * @throws {Error} If the template's `model_style.platform_type` is not `"webrtc"`.
+ * @throws {ApiError} If the template ID is invalid or API call fails.
+ */
+declare function createSessionId(apiServer: string, apiKey: string, sessionTemplateId: string): Promise<string>;
+/**
+ * @overload Creates a session from explicit runtime options.
+ * @param apiServer Perso API server URL.
+ * @param apiKey API key used for authentication.
+ * @param params Runtime options for the session.
+ * @returns Session ID returned by the server.
+ */
+declare function createSessionId(apiServer: string, apiKey: string, params: CreateSessionIdBody): Promise<string>;
+/**
+ * Retrieves the intro message for a specific prompt.
+ * @param apiServer Perso API server URL.
+ * @param apiKey API key used for authentication.
+ * @param promptId The prompt ID to fetch intro message for.
+ * @returns The intro message string.
+ */
+/**
+ * Retrieves the list of session templates.
+ * @param apiServer Perso API server URL.
+ * @param apiKey API key used for authentication.
+ * @returns {Promise<SessionTemplate[]>} Array of available session templates.
+ */
+declare function getSessionTemplates(apiServer: string, apiKey: string): Promise<SessionTemplate[]>;
+/**
+ * Retrieves a single session template by ID.
+ * @param apiServer Perso API server URL.
+ * @param apiKey API key used for authentication.
+ * @param sessionTemplateId Session Template ID.
+ * @returns {Promise<SessionTemplate>} The matching session template.
+ * @throws {ApiError} If the template ID is invalid or API call fails.
+ */
+declare function getSessionTemplate(apiServer: string, apiKey: string, sessionTemplateId: string): Promise<SessionTemplate>;
+declare const getIntroMessage: (apiServer: string, apiKey: string, promptId: string) => Promise<string>;
+
+declare class ApiError extends Error {
+    errorCode: number;
+    code: string;
+    detail: string;
+    attr?: string | undefined;
+    constructor(errorCode: number, code: string, detail: string, attr?: string | undefined);
+}
+
+export { ApiError, PersoUtil as PersoUtilServer, createSessionId, getIntroMessage, getSessionTemplate, getSessionTemplates };
+export type { SessionTemplate };

package/dist/server/index.js

@@ -1 +1 @@
-class t extends Error{errorCode;code;detail;attr;constructor(t,e,s,a){let i;i=null!=a?`${t}:${a}_${s}`:`${t}:${s}`,super(i),this.errorCode=t,this.code=e,this.detail=s,this.attr=a}}var e,s;!function(t){t.LLM="LLM",t.TTS="TTS",t.STT="STT",t.STF_ONPREMISE="STF_ONPREMISE",t.STF_WEBRTC="STF_WEBRTC"}(e||(e={})),function(t){t.SESSION_START="SESSION_START",t.SESSION_DURING="SESSION_DURING",t.SESSION_LOG="SESSION_LOG",t.SESSION_END="SESSION_END",t.SESSION_ERROR="SESSION_ERROR",t.SESSION_TTS="SESSION_TTS",t.SESSION_STT="SESSION_STT",t.SESSION_LLM="SESSION_LLM"}(s||(s={}));class a{static async getLLMs(t,e){const s=fetch(`${t}/api/v1/settings/llm_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getModelStyles(t,e){const s=fetch(`${t}/api/v1/settings/modelstyle/?platform_type=webrtc`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getBackgroundImages(t,e){const s=fetch(`${t}/api/v1/background_image/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getTTSs(t,e){const s=fetch(`${t}/api/v1/settings/tts_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getSTTs(t,e){const s=fetch(`${t}/api/v1/settings/stt_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async makeTTS(t,{sessionId:e,text:s}){const a=await fetch(`${t}/api/v1/session/${e}/tts/`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({text:s})});return await this.parseJson(a)}static async getPrompts(t,e){const s=fetch(`${t}/api/v1/prompt/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getDocuments(t,e){const s=fetch(`${t}/api/v1/document/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getMcpServers(t,e){const s=fetch(`${t}/api/v1/settings/mcp_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getSessionInfo(t,e){const s=fetch(`${t}/api/v1/session/${e}/`,{method:"GET"}),a=await s;return await this.parseJson(a)}static async sessionEvent(t,e,s){const a=await fetch(`${t}/api/v1/session/${e}/event/create/`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({detail:"",event:s})});await this.parseJson(a)}static async makeSTT(t,e,s,a){const i=new FormData;i.append("audio",s),a&&i.append("language",a);const r=await fetch(`${t}/api/v1/session/${e}/stt/`,{method:"POST",body:i});return await this.parseJson(r)}static async makeLLM(e,s,a,i){const r=await fetch(`${e}/api/v1/session/${s}/llm/v2/`,{body:JSON.stringify(a),headers:{"Content-Type":"application/json"},method:"POST",signal:i});if(!r.ok){const e=await r.json(),s=e.errors?.[0]??{code:"UNKNOWN_ERROR",detail:`Server returned status ${r.status} with no error details`,attr:null};throw new t(r.status,s.code,s.detail,s.attr)}return r.body.getReader()}static async getIceServers(t,e){const s=await fetch(`${t}/api/v1/session/${e}/ice-servers/`,{method:"GET"});return(await this.parseJson(s)).ice_servers}static async exchangeSDP(t,e,s){const a=await fetch(`${t}/api/v1/session/${e}/exchange/`,{body:JSON.stringify({client_sdp:s}),headers:{"Content-Type":"application/json"},method:"POST"});return(await this.parseJson(a)).server_sdp}static async parseJson(e){const s=await e.json();if(e.ok)return s;{const a=s.errors?.[0]??{code:"UNKNOWN_ERROR",detail:`Server returned status ${e.status} with no error details`,attr:null};throw new t(e.status,a.code,a.detail,a.attr)}}}const i=async(t,e,s)=>{const i={capability:[],...s};s.using_stf_webrtc&&i.capability.push("STF_WEBRTC"),s?.llm_type&&(i.capability.push("LLM"),i.llm_type=s.llm_type),s?.tts_type&&(i.capability.push("TTS"),i.tts_type=s.tts_type),s?.stt_type&&(i.capability.push("STT"),i.stt_type=s.stt_type);const r=await fetch(`${t}/api/v1/session/`,{body:JSON.stringify(i),headers:{"PersoLive-APIKey":e,"Content-Type":"application/json"},method:"POST"});return(await a.parseJson(r)).session_id},r=async(e,s,i)=>{try{const t=(await a.getPrompts(e,s)).find(t=>t.prompt_id===i);if(!t)throw new Error(`Prompt (${i}) not found`,{cause:404});return t.intro_message}catch(e){if(e instanceof t)throw new Error(e.detail,{cause:e.errorCode??500});throw e}};export{t as ApiError,a as PersoUtilServer,i as createSessionId,r as getIntroMessage};
+class t extends Error{errorCode;code;detail;attr;constructor(t,e,s,a){let i;i=null!=a?`${t}:${a}_${s}`:`${t}:${s}`,super(i),this.errorCode=t,this.code=e,this.detail=s,this.attr=a}}var e,s;!function(t){t.LLM="LLM",t.TTS="TTS",t.STT="STT",t.STF_ONPREMISE="STF_ONPREMISE",t.STF_WEBRTC="STF_WEBRTC"}(e||(e={})),function(t){t.SESSION_START="SESSION_START",t.SESSION_DURING="SESSION_DURING",t.SESSION_LOG="SESSION_LOG",t.SESSION_END="SESSION_END",t.SESSION_ERROR="SESSION_ERROR",t.SESSION_TTS="SESSION_TTS",t.SESSION_STT="SESSION_STT",t.SESSION_LLM="SESSION_LLM"}(s||(s={}));class a{static async getLLMs(t,e){const s=fetch(`${t}/api/v1/settings/llm_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getModelStyles(t,e){const s=fetch(`${t}/api/v1/settings/modelstyle/?platform_type=webrtc`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getBackgroundImages(t,e){const s=fetch(`${t}/api/v1/background_image/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getTTSs(t,e){const s=fetch(`${t}/api/v1/settings/tts_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getSTTs(t,e){const s=fetch(`${t}/api/v1/settings/stt_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async makeTTS(t,{sessionId:e,text:s,locale:a,output_format:i}){const o={text:s};a&&(o.locale=a),i&&(o.output_format=i);const n=await fetch(`${t}/api/v1/session/${e}/tts/`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(o)});return await this.parseJson(n)}static async getPrompts(t,e){const s=fetch(`${t}/api/v1/prompt/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getDocuments(t,e){const s=fetch(`${t}/api/v1/document/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getTextNormalizations(t,e){const s=fetch(`${t}/api/v1/settings/text_normalization_config/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async downloadTextNormalization(t,e,s){const a=await fetch(`${t}/api/v1/settings/text_normalization_config/${s}/download/`,{headers:{"PersoLive-APIKey":e},method:"GET"});return await this.parseJson(a)}static async getSessionTemplates(t,e){const s=await fetch(`${t}/api/v1/session_template/`,{headers:{"PersoLive-APIKey":e},method:"GET"});return await this.parseJson(s)}static async getSessionTemplate(t,e,s){const a=await fetch(`${t}/api/v1/session_template/${s}/`,{headers:{"PersoLive-APIKey":e},method:"GET"});return await this.parseJson(a)}static async getMcpServers(t,e){const s=fetch(`${t}/api/v1/settings/mcp_type/`,{headers:{"PersoLive-APIKey":e},method:"GET"}),a=await s;return await this.parseJson(a)}static async getSessionInfo(t,e){const s=fetch(`${t}/api/v1/session/${e}/`,{method:"GET"}),a=await s;return await this.parseJson(a)}static async sessionEvent(t,e,s){const a=await fetch(`${t}/api/v1/session/${e}/event/create/`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({detail:"",event:s})});await this.parseJson(a)}static async makeSTT(t,e,s,a){const i=new FormData;i.append("audio",s),a&&i.append("language",a);const o=await fetch(`${t}/api/v1/session/${e}/stt/`,{method:"POST",body:i});return await this.parseJson(o)}static async makeLLM(e,s,a,i){const o=await fetch(`${e}/api/v1/session/${s}/llm/v2/`,{body:JSON.stringify(a),headers:{"Content-Type":"application/json"},method:"POST",signal:i});if(!o.ok){const e=await o.json(),s=e.errors?.[0]??{code:"UNKNOWN_ERROR",detail:`Server returned status ${o.status} with no error details`,attr:null};throw new t(o.status,s.code,s.detail,s.attr)}return o.body.getReader()}static async getIceServers(t,e){const s=await fetch(`${t}/api/v1/session/${e}/ice-servers/`,{method:"GET"});return(await this.parseJson(s)).ice_servers}static async exchangeSDP(t,e,s){const a=await fetch(`${t}/api/v1/session/${e}/exchange/`,{body:JSON.stringify({client_sdp:s}),headers:{"Content-Type":"application/json"},method:"POST"});return(await this.parseJson(a)).server_sdp}static async parseJson(e){const s=await e.json();if(e.ok)return s;{const a=s.errors?.[0]??{code:"UNKNOWN_ERROR",detail:`Server returned status ${e.status} with no error details`,attr:null};throw new t(e.status,a.code,a.detail,a.attr)}}}async function i(t,s,i){let o;if("string"==typeof i){const n=await a.getSessionTemplate(t,s,i);if("webrtc"!==n.model_style.platform_type)throw new Error(`SessionTemplate "${i}" uses platform_type "${n.model_style.platform_type}", but only "webrtc" is supported`);o=function(t){const s=e=>t.capability.some(t=>t.name===e);return{using_stf_webrtc:s(e.STF_WEBRTC),model_style:t.model_style.name,prompt:t.prompt.prompt_id,document:t.document?.document_id,background_image:t.background_image?.backgroundimage_id,mcp_servers:t.mcp_servers.length?t.mcp_servers.map(t=>t.mcpserver_id):void 0,llm_type:s(e.LLM)?t.llm_type.name:void 0,tts_type:s(e.TTS)?t.tts_type.name:void 0,stt_type:s(e.STT)?t.stt_type.name:void 0,text_normalization_config:t.text_normalization_config?.textnormalizationconfig_id,text_normalization_locale:t.text_normalization_locale,padding_left:t.padding_left??void 0,padding_top:t.padding_top??void 0,padding_height:t.padding_height??void 0}}(n)}else o=i;const n={capability:[],...o};o.using_stf_webrtc&&n.capability.push("STF_WEBRTC"),o?.llm_type&&(n.capability.push("LLM"),n.llm_type=o.llm_type),o?.tts_type&&(n.capability.push("TTS"),n.tts_type=o.tts_type),o?.stt_type&&(n.capability.push("STT"),n.stt_type=o.stt_type);const r=await fetch(`${t}/api/v1/session/`,{body:JSON.stringify(n),headers:{"PersoLive-APIKey":s,"Content-Type":"application/json"},method:"POST"});return(await a.parseJson(r)).session_id}async function o(t,e){return await a.getSessionTemplates(t,e)}async function n(t,e,s){return await a.getSessionTemplate(t,e,s)}const r=async(e,s,i)=>{try{const t=(await a.getPrompts(e,s)).find(t=>t.prompt_id===i);if(!t)throw new Error(`Prompt (${i}) not found`,{cause:404});return t.intro_message}catch(e){if(e instanceof t)throw new Error(e.detail,{cause:e.errorCode??500});throw e}};export{t as ApiError,a as PersoUtilServer,i as createSessionId,r as getIntroMessage,n as getSessionTemplate,o as getSessionTemplates};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "perso-interactive-sdk-web",
-	"version": "1.2.2",
+	"version": "1.3.1",
 	"description": "Perso Interactive Web SDK - WebRTC-based real-time interactive AI avatar sessions",
 	"type": "module",
 	"private": false,