type CreateSessionIdBody = { using_stf_webrtc: boolean; model_style: string; prompt: string; document?: string; background_image?: string; mcp_servers?: Array; 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; stt_text_normalization_config?: string; stt_text_normalization_locale?: string | null; }; type CreateSessionIdObjectOptions = { apiKey: string; params: CreateSessionIdBody; apiServer?: string; } | { apiKey: string; sessionTemplateId: string; apiServer?: string; }; /** @overload Object-form. Uses DEFAULT_API_SERVER when apiServer is omitted. */ declare function createSessionId(options: CreateSessionIdObjectOptions): Promise; /** @overload Positional form — SessionTemplate ID. */ declare function createSessionId(apiServer: string, apiKey: string, sessionTemplateId: string): Promise; /** @overload Positional form — explicit params. */ declare function createSessionId(apiServer: string, apiKey: string, params: CreateSessionIdBody): Promise; type GetIntroMessageObjectOptions = { apiKey: string; promptId: string; apiServer?: string; }; /** @overload Object-form. Uses DEFAULT_API_SERVER when apiServer is omitted. */ declare function getIntroMessage(options: GetIntroMessageObjectOptions): Promise; /** @overload Positional form. */ declare function getIntroMessage(apiServer: string, apiKey: string, promptId: string): Promise; 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; } /** * Response from POST /api/v1/session/{session_id}/stt/. * * The wire payload includes additional fields (e.g., `locale`, * `normalized_text`) that the SDK intentionally does not expose. */ interface STTResponse { text: string; } 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; stt_text_normalization_config?: TextNormalizationConfig | null; stt_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; } 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", SESSION_LOG = "SESSION_LOG", SESSION_END = "SESSION_END", SESSION_ERROR = "SESSION_ERROR", SESSION_TTS = "SESSION_TTS", 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 * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "name": string * } * ] */ static getLLMs(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "name": string, * "model": string, * "style": string * } * ] */ static getModelStyles(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "backgroundimage_id": string, * "title": string, * "image": string * "created_at": string // ex) "2024-05-02T09:05:55.395Z" * } * ] */ static getBackgroundImages(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "name": string, * "service": string, * "speaker": string * } * ] */ static getTTSs(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "name": string, * "service": string * } * ] */ static getSTTs(apiServer: string, apiKey: string): Promise; /** * Sends text to the TTS API and returns Base64-encoded audio. * @param apiServer Perso Interactive API Server * @param params Session ID and text to synthesize. * @returns JSON with Base64 audio string. * { * "audio": string * } */ static makeTTS(apiServer: string, { sessionId, text, locale, output_format }: { sessionId: string; text: string; locale?: string; output_format?: string; }): Promise<{ audio: string; }>; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "name": string, * "description": string, * "prompt_id": string, * "system_prompt": string, * "require_document": boolean, * "intro_message": string * } * ] */ static getPrompts(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "document_id": string, * "title": string, * "description": string, * "search_count": number, * "processed": boolean, * "created_at": string, // ex) "2024-05-02T09:05:55.395Z", * "updated_at": string // ex) "2024-05-02T09:05:55.395Z" * } * ] */ static getDocuments(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * [ * { * "mcpserver_id": string, * "name": string, * "url": string, * "description": string * } * ] */ /** * @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; /** * 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; /** * 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; /** * 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; static getMcpServers(apiServer: string, apiKey: string): Promise; /** * @param apiServer Perso Interactive API Server * @param apiKey Perso Interactive API Key * @returns JSON * { * "session_id": string, * "client_sdp": string, * "server_sdp": string, * "prompt": { * "name": string, * "description": string, * "prompt_id": string, * "system_prompt": string, * "require_document": boolean, * "intro_message": string * }, * "document": string, * "llm_type": { * "name": string * }, * "model_style": { * "name": string, * "model": string, * "model_file": string, * "style": string, * "file": string * }, * "tts_type": { * "name": string, * "service": string, * "model": string, * "voice": string, * "style": string, * "voice_extra_data": string * }, * "ice_servers": Array, * "status": string, // "CREATED", "EXCHANGED", "IN_PROGRESS", "TERMINATED" * "termination_reason": string, // "GRACEFUL_TERMINATION", "SESSION_EXPIRED_BEFORE_CONNECTION", "SESSION_LOST_AFTER_CONNECTION", "SESSION_MISC_ERROR", "MAX_ACTIVE_SESSION_QUOTA_EXCEEDED", "MAX_MIN_PER_SESSION_QUOTA_EXCEEDED", "TOTAL_MIN_PER_MONTH_QUOTA_EXCEEDED" * "duration_sec": number, * "created_at": string, // ex) "2024-05-02T09:05:55.395Z" * "padding_left": number, * "padding_top": number, * "padding_height": number, * "background_image": { * "backgroundimage_id": string, * "title": string, * "image": string, * "created_at": string // ex) "2024-05-02T09:05:55.395Z" * }, * "extra_data": string, * "capability": Array<{ * "name": string, // "LLM" | "TTS" | "STT" | "STF_ONPREMISE" | "STF_WEBRTC" * "description": string * }> * } */ static getSessionInfo(apiServer: string, sessionId: string): Promise; static sessionEvent(apiServer: string, sessionId: string, sessionEvent: SessionEvent, detail?: string): Promise; /** * Sends audio data to the STT API endpoint for speech-to-text conversion. * @param apiServer Perso Interactive API Server * @param sessionId Session ID for the current session * @param audioFile Audio file (WAV format) * @param language Optional language code (e.g., 'ko', 'en') * @returns STTResponse with only the transcribed text. * * The server returns additional fields (e.g., `locale`, `normalized_text`) * which are intentionally not exposed by the SDK. */ static makeSTT(apiServer: string, sessionId: string, audioFile: File, language?: string): Promise; /** * Initiates an LLM streaming request and returns the response body reader. * @param apiServer Perso Interactive API Server * @param sessionId Session ID for the current session * @param body Request body containing messages and tools * @param signal Optional AbortSignal to cancel the request * @returns ReadableStreamDefaultReader for SSE streaming response * @throws ApiError when response is not ok */ static makeLLM(apiServer: string, sessionId: string, body: { messages: Array; tools: Array; }, signal?: AbortSignal): Promise>; /** * Fetches ICE server configuration for WebRTC peer connection setup. * @param apiServer Perso Interactive API Server * @param sessionId Session ID * @returns Array of RTCIceServer configurations. */ static getIceServers(apiServer: string, sessionId: string): Promise>; /** * Exchanges the client SDP offer with the server and returns the server SDP answer. * @param apiServer Perso Interactive API Server * @param sessionId Session ID * @param offer Client SDP offer from RTCPeerConnection.createOffer(). * @returns Server SDP answer to set as remote description. */ static exchangeSDP(apiServer: string, sessionId: string, offer: RTCSessionDescriptionInit): Promise; static parseJson(response: Response): Promise; } type ApiKeyOptions = { apiKey: string; apiServer?: string; }; /** * Retrieves the list of available LLM providers from the API. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getLLMs(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getLLMs(apiServer: string, apiKey: string): ReturnType; /** * Retrieves available TTS providers. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getTTSs(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getTTSs(apiServer: string, apiKey: string): ReturnType; /** * Retrieves available STT providers. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getSTTs(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getSTTs(apiServer: string, apiKey: string): ReturnType; /** * Fetches avatar model styles. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getModelStyles(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getModelStyles(apiServer: string, apiKey: string): ReturnType; /** * Fetches preset background images. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getBackgroundImages(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getBackgroundImages(apiServer: string, apiKey: string): ReturnType; /** * Returns predefined prompt templates. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getPrompts(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getPrompts(apiServer: string, apiKey: string): ReturnType; /** * Returns supporting document metadata usable by the session. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getDocuments(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getDocuments(apiServer: string, apiKey: string): ReturnType; /** * Lists MCP server identifiers configured for the tenant. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getMcpServers(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getMcpServers(apiServer: string, apiKey: string): ReturnType; /** * Retrieves available text normalization options. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getTextNormalizations(options: ApiKeyOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getTextNormalizations(apiServer: string, apiKey: string): ReturnType; type GetTextNormalizationOptions = { apiKey: string; configId: string; apiServer?: string; }; /** * Downloads the ruleset data file for a Text Normalization Config. * Returns a pre-signed Blob Storage URL for the CSV file. * * @param options.apiKey API key used for authentication. * @param options.configId Identifier of the Text Normalization Config to download. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getTextNormalization(options: GetTextNormalizationOptions): Promise; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. * @param configId Identifier of the Text Normalization Config to download. */ declare function getTextNormalization(apiServer: string, apiKey: string, configId: string): Promise; /** * Retrieves the list of session templates. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getSessionTemplates(options: ApiKeyOptions): Promise; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getSessionTemplates(apiServer: string, apiKey: string): Promise; type GetSessionTemplateOptions = { apiKey: string; sessionTemplateId: string; apiServer?: string; }; /** * Retrieves a single session template by ID. * * @param options.apiKey API key used for authentication. * @param options.sessionTemplateId Identifier of the session template to fetch. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getSessionTemplate(options: GetSessionTemplateOptions): Promise; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. * @param sessionTemplateId Identifier of the session template to fetch. */ declare function getSessionTemplate(apiServer: string, apiKey: string, sessionTemplateId: string): Promise; type AllSettings = { llms: Awaited>; ttsTypes: Awaited>; sttTypes: Awaited>; modelStyles: Awaited>; backgroundImages: Awaited>; prompts: Awaited>; documents: Awaited>; mcpServers: Awaited>; textNormalizations: Awaited> | []; }; /** * Convenience helper that fetches every dropdown-friendly resource needed to * build a Perso session configuration screen in one call chain. * * @param options.apiKey API key used for authentication. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getAllSettings(options: ApiKeyOptions): Promise; /** * @param apiServer Perso API server URL. * @param apiKey API key used for authentication. */ declare function getAllSettings(apiServer: string, apiKey: string): Promise; type MakeTTSParams = { sessionId: string; text: string; locale?: string; output_format?: string; }; type MakeTTSOptions = MakeTTSParams & { apiServer?: string; }; /** * Sends text to the TTS API and returns Base64-encoded audio. * * @param options.sessionId Identifier of the active session. * @param options.text Text to synthesize. * @param options.locale Optional locale override for the TTS voice. * @param options.output_format Optional output audio format. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function makeTTS(options: MakeTTSOptions): Promise<{ audio: string; }>; /** * @param apiServer Perso API server URL. * @param params TTS request parameters (`sessionId`, `text`, optional `locale`, `output_format`). */ declare function makeTTS(apiServer: string, params: MakeTTSParams): Promise<{ audio: string; }>; type GetSessionInfoOptions = { sessionId: string; apiServer?: string; }; /** * Retrieves metadata for an existing session. * * @param options.sessionId Identifier of the session to look up. * @param options.apiServer Perso API server URL. Defaults to `https://platform.perso.ai`. */ declare function getSessionInfo(options: GetSessionInfoOptions): ReturnType; /** * @param apiServer Perso API server URL. * @param sessionId Identifier of the session to look up. */ declare function getSessionInfo(apiServer: string, sessionId: string): ReturnType; declare const DEFAULT_API_SERVER = "https://platform.perso.ai"; declare class ApiError extends Error { errorCode: number; code: string; detail: string; attr?: string | undefined; constructor(errorCode: number, code: string, detail: string, attr?: string | undefined); } /** * Domain error thrown by `createSessionId()` (and the `getSessionTemplate` * path) when the underlying API returns an `ApiError`. The raw * `errorCode`, `code`, `detail`, and `attr` fields are preserved as-is — * callers inspect them to decide how to react (e.g. treat * `code === 'invalid'` with a "not found" detail as feature-unavailable * per LIV-1681). * * Extends `ApiError`, so existing `instanceof ApiError` branches keep * working. */ declare class SessionCreationError extends ApiError { constructor(source: ApiError); } /** * Session creation failed because a referenced resource does not exist. * Triggered when the server returns `code === 'does_not_exist'` — for * example, a `prompt_id` that has been deleted or never existed. The * `attr` field, when present, identifies which input field referenced * the missing resource (e.g. `'prompt'`). */ declare class DoesNotExistError extends SessionCreationError { constructor(source: ApiError); } /** * Session creation failed because a referenced resource is not assigned * to the caller's organization. Triggered when the server returns * `code === 'not_in_organization'` — for example, an LLM/TTS/STT type * that exists in the platform catalog but is not enabled for this * organization. The `attr` field, when present, identifies which input * field referenced the unavailable resource. */ declare class NotInOrganizationError extends SessionCreationError { constructor(source: ApiError); } export { ApiError, DEFAULT_API_SERVER, DoesNotExistError, NotInOrganizationError, PersoUtil as PersoUtilServer, SessionCreationError, createSessionId, getAllSettings, getBackgroundImages, getDocuments, getIntroMessage, getLLMs, getMcpServers, getModelStyles, getPrompts, getSTTs, getSessionInfo, getSessionTemplate, getSessionTemplates, getTTSs, getTextNormalization, getTextNormalizations, makeTTS }; export type { ApiKeyOptions, GetSessionInfoOptions, GetSessionTemplateOptions, GetTextNormalizationOptions, MakeTTSOptions, STTResponse, SessionTemplate };