@aginies/webuikit 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -9,8 +9,13 @@ import { ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes, TextareaHTML
 interface AginiesConfig {
     /** Platform origin, e.g. `https://app.example.com`. No trailing slash. */
     baseUrl: string;
-    /** Activation token issued for the deployment. Without it nothing renders. */
-    token: string;
+    /** Activation token issued for the deployment. Without it nothing renders, unless `hosted`. */
+    token?: string;
+    /**
+     * The platform's own pages: the widget runs on the platform origin and activates
+     * without a token. Refused from any other origin.
+     */
+    hosted?: boolean;
     /** UI language. Defaults to the document language, then English. */
     locale?: 'tr' | 'en';
     /** Fetch implementation override (tests, SSR). */
@@ -67,6 +72,16 @@ interface ChatConfig {
         blockId: string;
         path?: string;
     }>;
+    /** What the platform can do with speech for this chat. */
+    voice?: {
+        stt: boolean;
+        tts: boolean;
+    };
+}
+interface Transcription {
+    transcript: string;
+    language?: string;
+    duration?: number;
 }
 interface ChatAuthRequired {
     authRequired: ChatConfig['authType'];
@@ -108,7 +123,8 @@ declare class AginiesError extends Error {
 }
 declare class AginiesClient {
     readonly baseUrl: string;
-    readonly token: string;
+    readonly token: string | null;
+    private readonly hosted;
     readonly locale: 'tr' | 'en';
     private readonly fetchImpl;
     private state;
@@ -143,6 +159,10 @@ declare class AginiesClient {
     private request;
     /** A raw request against the platform for endpoints the client does not wrap. */
     fetchRaw(path: string, init?: RequestInit): Promise<Response>;
+    /** Sends a recording to the platform's transcription model. */
+    transcribe(identifier: string, audio: Blob, filename?: string, language?: string): Promise<Transcription>;
+    /** Audio for a reply from the platform's synthesis endpoint. */
+    speak(identifier: string, text: string): Promise<Blob>;
     /** Hosted-chat configuration. Resolves to an auth requirement instead of throwing on 401. */
     getChat(identifier: string): Promise<ChatConfig | ChatAuthRequired>;
     /**
@@ -396,9 +416,14 @@ interface ChatWidgetProps {
     defaultOpen?: boolean;
     /** Theme for the widget subtree; `auto` follows the host page. */
     theme?: 'dark' | 'light' | 'auto';
+    /**
+     * Offer dictation and a hands-free voice conversation when the platform provides speech
+     * for this chat and the browser can record. Default true.
+     */
+    voice?: boolean;
     className?: string;
 }
-declare function ChatWidget({ identifier, mode, position, launcherLabel, defaultOpen, theme, className, }: ChatWidgetProps): react.JSX.Element | null;
+declare function ChatWidget({ identifier, mode, position, launcherLabel, defaultOpen, theme, voice, className, }: ChatWidgetProps): react.JSX.Element | null;
 
 /**
  * Small Markdown renderer for agent replies. It builds React elements directly, so nothing
@@ -410,6 +435,44 @@ declare function Markdown({ text, className }: {
     className?: string;
 }): react.JSX.Element;
 
+/**
+ * Voice for the chat widget: records the visitor with the browser's recorder, sends the
+ * clip to the platform (which runs its own transcription model) and plays replies back
+ * from the platform's synthesis endpoint. No third-party browser speech API is involved,
+ * so it behaves the same in every browser and the audio never leaves the platform.
+ */
+type VoiceState = 'idle' | 'listening' | 'transcribing' | 'speaking' | 'denied' | 'unsupported';
+interface UseVoiceOptions {
+    identifier: string;
+    /** Receives the transcript of a finished recording; empty recordings are dropped. */
+    onTranscript: (text: string) => void;
+    /** Language hint for transcription; omit for auto-detection. */
+    language?: string;
+    /** Stop recording after this much silence once speech was heard. */
+    silenceMs?: number;
+    /** Longest single recording. */
+    maxMs?: number;
+}
+interface VoiceControls {
+    state: VoiceState;
+    /** Last failure, cleared on the next successful action. */
+    error: string | null;
+    /** Whether this browser can record at all. */
+    supported: boolean;
+    /** Input level 0..1 while listening, for a meter. */
+    level: number;
+    startListening: () => Promise<void>;
+    /** Ends the recording and transcribes it. */
+    stopListening: () => void;
+    /** Ends the recording and discards it. */
+    cancelListening: () => void;
+    /** Plays a reply; resolves when playback ends or is stopped. */
+    speak: (text: string) => Promise<void>;
+    stopSpeaking: () => void;
+}
+declare function isVoiceSupported(): boolean;
+declare function useVoice({ identifier, onTranscript, language, silenceMs, maxMs, }: UseVoiceOptions): VoiceControls;
+
 /** Joins class names, dropping falsy entries. */
 declare function cx(...parts: Array<string | false | null | undefined>): string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -615,6 +678,68 @@ declare const STRINGS: {
             readonly en: "Sign in";
         };
     };
+    readonly voice: {
+        readonly talk: {
+            readonly tr: "Konuşmak için dokunun";
+            readonly en: "Tap to talk";
+        };
+        readonly stopTalking: {
+            readonly tr: "Bitirmek için dokunun";
+            readonly en: "Tap when done";
+        };
+        readonly dictate: {
+            readonly tr: "Sesle yaz";
+            readonly en: "Dictate";
+        };
+        readonly handsFree: {
+            readonly tr: "Sesli sohbet";
+            readonly en: "Voice conversation";
+        };
+        readonly exit: {
+            readonly tr: "Sesli sohbetten çık";
+            readonly en: "Leave voice conversation";
+        };
+        readonly listening: {
+            readonly tr: "Dinliyor";
+            readonly en: "Listening";
+        };
+        readonly transcribing: {
+            readonly tr: "Yazıya dökülüyor";
+            readonly en: "Transcribing";
+        };
+        readonly thinking: {
+            readonly tr: "Yanıt hazırlanıyor";
+            readonly en: "Working on it";
+        };
+        readonly speaking: {
+            readonly tr: "Konuşuyor";
+            readonly en: "Speaking";
+        };
+        readonly idle: {
+            readonly tr: "Hazır";
+            readonly en: "Ready";
+        };
+        readonly interrupt: {
+            readonly tr: "Sözünü kesmek için dokunun";
+            readonly en: "Tap to interrupt";
+        };
+        readonly micDenied: {
+            readonly tr: "Mikrofon izni verilmedi. Tarayıcı ayarlarından izin verin.";
+            readonly en: "Microphone access was denied. Allow it in your browser settings.";
+        };
+        readonly unsupported: {
+            readonly tr: "Bu tarayıcı ses kaydını desteklemiyor.";
+            readonly en: "This browser cannot record audio.";
+        };
+        readonly unavailable: {
+            readonly tr: "Ses özelliği bu sohbet için açık değil.";
+            readonly en: "Voice is not enabled for this chat.";
+        };
+        readonly error: {
+            readonly tr: "Ses işlenemedi. Lütfen tekrar deneyin.";
+            readonly en: "Voice could not be processed. Please try again.";
+        };
+    };
     readonly run: {
         readonly submit: {
             readonly tr: "Çalıştır";
@@ -962,4 +1087,4 @@ declare function runAgent(client: AginiesClient, workflowId: string, options: Ru
 /** Decodes an execute SSE body into run events. Exported for tests. */
 declare function parseRunSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<RunEvent>;
 
-export { ATTACHMENT_LIMITS, type ActivationConfig, type ActivationSession, type ActivationState, AgentRunner, type AgentRunnerProps, AginiesClient, type AginiesConfig, AginiesError, AginiesProvider, type AginiesProviderProps, ApprovalPanel, type ApprovalPanelProps, type ApprovalStatus, Button, type ButtonProps, type ChatAttachment, type ChatAuthRequired, type ChatConfig, type ChatFilePayload, type ChatMessage, type ChatStreamEvent, ChatWidget, type ChatWidgetProps, Chip, type CodeRequestResult, type CostBarItem, CostBars, type CostBarsProps, Eyebrow, Field, type HeatmapRow, Input, type Locale, Markdown, Panel, type PauseContext, type PausePoint, type PausedExecution, type ResumeField, type ResumeOutcome, type ResumeQueueEntry, type ResumeStatus, type RunEvent, type RunField, type RunOptions, type RunStatus, type RunStep, RunTimeline, type RunTimelineProps, type SendMessageInput, Spinner, Stat, type StatItem, StatTiles, type StructuredItem, type StructuredResponse, StructuredUI, SuccessHeatmap, type SuccessHeatmapProps, Tag, Textarea, type TimelineStep, buildSubmission, cx, fieldsOf, formatFieldValue, getClient, getPauseContext, getPausedExecution, init, initialValues, listPausedExecutions, outputOf, parseFieldValue, parseRunSSE, parseSSE, parseStructured, resumeExecution, runAgent, translator, useAgentRun, useAginies, useApproval, useChat, useModule };
+export { ATTACHMENT_LIMITS, type ActivationConfig, type ActivationSession, type ActivationState, AgentRunner, type AgentRunnerProps, AginiesClient, type AginiesConfig, AginiesError, AginiesProvider, type AginiesProviderProps, ApprovalPanel, type ApprovalPanelProps, type ApprovalStatus, Button, type ButtonProps, type ChatAttachment, type ChatAuthRequired, type ChatConfig, type ChatFilePayload, type ChatMessage, type ChatStreamEvent, ChatWidget, type ChatWidgetProps, Chip, type CodeRequestResult, type CostBarItem, CostBars, type CostBarsProps, Eyebrow, Field, type HeatmapRow, Input, type Locale, Markdown, Panel, type PauseContext, type PausePoint, type PausedExecution, type ResumeField, type ResumeOutcome, type ResumeQueueEntry, type ResumeStatus, type RunEvent, type RunField, type RunOptions, type RunStatus, type RunStep, RunTimeline, type RunTimelineProps, type SendMessageInput, Spinner, Stat, type StatItem, StatTiles, type StructuredItem, type StructuredResponse, StructuredUI, SuccessHeatmap, type SuccessHeatmapProps, Tag, Textarea, type TimelineStep, type Transcription, type UseVoiceOptions, type VoiceControls, type VoiceState, buildSubmission, cx, fieldsOf, formatFieldValue, getClient, getPauseContext, getPausedExecution, init, initialValues, isVoiceSupported, listPausedExecutions, outputOf, parseFieldValue, parseRunSSE, parseSSE, parseStructured, resumeExecution, runAgent, translator, useAgentRun, useAginies, useApproval, useChat, useModule, useVoice };

package/dist/index.d.ts

@@ -9,8 +9,13 @@ import { ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes, TextareaHTML
 interface AginiesConfig {
     /** Platform origin, e.g. `https://app.example.com`. No trailing slash. */
     baseUrl: string;
-    /** Activation token issued for the deployment. Without it nothing renders. */
-    token: string;
+    /** Activation token issued for the deployment. Without it nothing renders, unless `hosted`. */
+    token?: string;
+    /**
+     * The platform's own pages: the widget runs on the platform origin and activates
+     * without a token. Refused from any other origin.
+     */
+    hosted?: boolean;
     /** UI language. Defaults to the document language, then English. */
     locale?: 'tr' | 'en';
     /** Fetch implementation override (tests, SSR). */
@@ -67,6 +72,16 @@ interface ChatConfig {
         blockId: string;
         path?: string;
     }>;
+    /** What the platform can do with speech for this chat. */
+    voice?: {
+        stt: boolean;
+        tts: boolean;
+    };
+}
+interface Transcription {
+    transcript: string;
+    language?: string;
+    duration?: number;
 }
 interface ChatAuthRequired {
     authRequired: ChatConfig['authType'];
@@ -108,7 +123,8 @@ declare class AginiesError extends Error {
 }
 declare class AginiesClient {
     readonly baseUrl: string;
-    readonly token: string;
+    readonly token: string | null;
+    private readonly hosted;
     readonly locale: 'tr' | 'en';
     private readonly fetchImpl;
     private state;
@@ -143,6 +159,10 @@ declare class AginiesClient {
     private request;
     /** A raw request against the platform for endpoints the client does not wrap. */
     fetchRaw(path: string, init?: RequestInit): Promise<Response>;
+    /** Sends a recording to the platform's transcription model. */
+    transcribe(identifier: string, audio: Blob, filename?: string, language?: string): Promise<Transcription>;
+    /** Audio for a reply from the platform's synthesis endpoint. */
+    speak(identifier: string, text: string): Promise<Blob>;
     /** Hosted-chat configuration. Resolves to an auth requirement instead of throwing on 401. */
     getChat(identifier: string): Promise<ChatConfig | ChatAuthRequired>;
     /**
@@ -396,9 +416,14 @@ interface ChatWidgetProps {
     defaultOpen?: boolean;
     /** Theme for the widget subtree; `auto` follows the host page. */
     theme?: 'dark' | 'light' | 'auto';
+    /**
+     * Offer dictation and a hands-free voice conversation when the platform provides speech
+     * for this chat and the browser can record. Default true.
+     */
+    voice?: boolean;
     className?: string;
 }
-declare function ChatWidget({ identifier, mode, position, launcherLabel, defaultOpen, theme, className, }: ChatWidgetProps): react.JSX.Element | null;
+declare function ChatWidget({ identifier, mode, position, launcherLabel, defaultOpen, theme, voice, className, }: ChatWidgetProps): react.JSX.Element | null;
 
 /**
  * Small Markdown renderer for agent replies. It builds React elements directly, so nothing
@@ -410,6 +435,44 @@ declare function Markdown({ text, className }: {
     className?: string;
 }): react.JSX.Element;
 
+/**
+ * Voice for the chat widget: records the visitor with the browser's recorder, sends the
+ * clip to the platform (which runs its own transcription model) and plays replies back
+ * from the platform's synthesis endpoint. No third-party browser speech API is involved,
+ * so it behaves the same in every browser and the audio never leaves the platform.
+ */
+type VoiceState = 'idle' | 'listening' | 'transcribing' | 'speaking' | 'denied' | 'unsupported';
+interface UseVoiceOptions {
+    identifier: string;
+    /** Receives the transcript of a finished recording; empty recordings are dropped. */
+    onTranscript: (text: string) => void;
+    /** Language hint for transcription; omit for auto-detection. */
+    language?: string;
+    /** Stop recording after this much silence once speech was heard. */
+    silenceMs?: number;
+    /** Longest single recording. */
+    maxMs?: number;
+}
+interface VoiceControls {
+    state: VoiceState;
+    /** Last failure, cleared on the next successful action. */
+    error: string | null;
+    /** Whether this browser can record at all. */
+    supported: boolean;
+    /** Input level 0..1 while listening, for a meter. */
+    level: number;
+    startListening: () => Promise<void>;
+    /** Ends the recording and transcribes it. */
+    stopListening: () => void;
+    /** Ends the recording and discards it. */
+    cancelListening: () => void;
+    /** Plays a reply; resolves when playback ends or is stopped. */
+    speak: (text: string) => Promise<void>;
+    stopSpeaking: () => void;
+}
+declare function isVoiceSupported(): boolean;
+declare function useVoice({ identifier, onTranscript, language, silenceMs, maxMs, }: UseVoiceOptions): VoiceControls;
+
 /** Joins class names, dropping falsy entries. */
 declare function cx(...parts: Array<string | false | null | undefined>): string;
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -615,6 +678,68 @@ declare const STRINGS: {
             readonly en: "Sign in";
         };
     };
+    readonly voice: {
+        readonly talk: {
+            readonly tr: "Konuşmak için dokunun";
+            readonly en: "Tap to talk";
+        };
+        readonly stopTalking: {
+            readonly tr: "Bitirmek için dokunun";
+            readonly en: "Tap when done";
+        };
+        readonly dictate: {
+            readonly tr: "Sesle yaz";
+            readonly en: "Dictate";
+        };
+        readonly handsFree: {
+            readonly tr: "Sesli sohbet";
+            readonly en: "Voice conversation";
+        };
+        readonly exit: {
+            readonly tr: "Sesli sohbetten çık";
+            readonly en: "Leave voice conversation";
+        };
+        readonly listening: {
+            readonly tr: "Dinliyor";
+            readonly en: "Listening";
+        };
+        readonly transcribing: {
+            readonly tr: "Yazıya dökülüyor";
+            readonly en: "Transcribing";
+        };
+        readonly thinking: {
+            readonly tr: "Yanıt hazırlanıyor";
+            readonly en: "Working on it";
+        };
+        readonly speaking: {
+            readonly tr: "Konuşuyor";
+            readonly en: "Speaking";
+        };
+        readonly idle: {
+            readonly tr: "Hazır";
+            readonly en: "Ready";
+        };
+        readonly interrupt: {
+            readonly tr: "Sözünü kesmek için dokunun";
+            readonly en: "Tap to interrupt";
+        };
+        readonly micDenied: {
+            readonly tr: "Mikrofon izni verilmedi. Tarayıcı ayarlarından izin verin.";
+            readonly en: "Microphone access was denied. Allow it in your browser settings.";
+        };
+        readonly unsupported: {
+            readonly tr: "Bu tarayıcı ses kaydını desteklemiyor.";
+            readonly en: "This browser cannot record audio.";
+        };
+        readonly unavailable: {
+            readonly tr: "Ses özelliği bu sohbet için açık değil.";
+            readonly en: "Voice is not enabled for this chat.";
+        };
+        readonly error: {
+            readonly tr: "Ses işlenemedi. Lütfen tekrar deneyin.";
+            readonly en: "Voice could not be processed. Please try again.";
+        };
+    };
     readonly run: {
         readonly submit: {
             readonly tr: "Çalıştır";
@@ -962,4 +1087,4 @@ declare function runAgent(client: AginiesClient, workflowId: string, options: Ru
 /** Decodes an execute SSE body into run events. Exported for tests. */
 declare function parseRunSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<RunEvent>;
 
-export { ATTACHMENT_LIMITS, type ActivationConfig, type ActivationSession, type ActivationState, AgentRunner, type AgentRunnerProps, AginiesClient, type AginiesConfig, AginiesError, AginiesProvider, type AginiesProviderProps, ApprovalPanel, type ApprovalPanelProps, type ApprovalStatus, Button, type ButtonProps, type ChatAttachment, type ChatAuthRequired, type ChatConfig, type ChatFilePayload, type ChatMessage, type ChatStreamEvent, ChatWidget, type ChatWidgetProps, Chip, type CodeRequestResult, type CostBarItem, CostBars, type CostBarsProps, Eyebrow, Field, type HeatmapRow, Input, type Locale, Markdown, Panel, type PauseContext, type PausePoint, type PausedExecution, type ResumeField, type ResumeOutcome, type ResumeQueueEntry, type ResumeStatus, type RunEvent, type RunField, type RunOptions, type RunStatus, type RunStep, RunTimeline, type RunTimelineProps, type SendMessageInput, Spinner, Stat, type StatItem, StatTiles, type StructuredItem, type StructuredResponse, StructuredUI, SuccessHeatmap, type SuccessHeatmapProps, Tag, Textarea, type TimelineStep, buildSubmission, cx, fieldsOf, formatFieldValue, getClient, getPauseContext, getPausedExecution, init, initialValues, listPausedExecutions, outputOf, parseFieldValue, parseRunSSE, parseSSE, parseStructured, resumeExecution, runAgent, translator, useAgentRun, useAginies, useApproval, useChat, useModule };
+export { ATTACHMENT_LIMITS, type ActivationConfig, type ActivationSession, type ActivationState, AgentRunner, type AgentRunnerProps, AginiesClient, type AginiesConfig, AginiesError, AginiesProvider, type AginiesProviderProps, ApprovalPanel, type ApprovalPanelProps, type ApprovalStatus, Button, type ButtonProps, type ChatAttachment, type ChatAuthRequired, type ChatConfig, type ChatFilePayload, type ChatMessage, type ChatStreamEvent, ChatWidget, type ChatWidgetProps, Chip, type CodeRequestResult, type CostBarItem, CostBars, type CostBarsProps, Eyebrow, Field, type HeatmapRow, Input, type Locale, Markdown, Panel, type PauseContext, type PausePoint, type PausedExecution, type ResumeField, type ResumeOutcome, type ResumeQueueEntry, type ResumeStatus, type RunEvent, type RunField, type RunOptions, type RunStatus, type RunStep, RunTimeline, type RunTimelineProps, type SendMessageInput, Spinner, Stat, type StatItem, StatTiles, type StructuredItem, type StructuredResponse, StructuredUI, SuccessHeatmap, type SuccessHeatmapProps, Tag, Textarea, type TimelineStep, type Transcription, type UseVoiceOptions, type VoiceControls, type VoiceState, buildSubmission, cx, fieldsOf, formatFieldValue, getClient, getPauseContext, getPausedExecution, init, initialValues, isVoiceSupported, listPausedExecutions, outputOf, parseFieldValue, parseRunSSE, parseSSE, parseStructured, resumeExecution, runAgent, translator, useAgentRun, useAginies, useApproval, useChat, useModule, useVoice };