@amaster.ai/client 1.1.0-beta.7 → 1.1.0-beta.71

package/types/asr.d.ts

@@ -1,192 +1,327 @@
+import type{ HttpClient } from "./http";
 /**
- * ============================================================================
- * ASR (Automatic Speech Recognition) - Type Definitions
- * ============================================================================
- * 
- * Real-time speech recognition using WebSocket connection.
- * 
- * @module asr
- */
-
-/**
- * ASR Client Configuration
- * 
+ * ASR Realtime WebSocket Client for Qwen-ASR Realtime API
+ *
+ * WebSocket-based real-time speech recognition for streaming transcription.
+ * Follows the Qwen-ASR Realtime API protocol with proper event handling.
+ *
  * @example
- * Configure ASR with custom voice settings:
  * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Reconfigure ASR client
- * client.asr = createASRClient({
- *   audioFormat: 'pcm16',
- *   sampleRate: 16000,
- *   onTranscript: (text, isFinal) => {
- *     console.log(isFinal ? `Final: ${text}` : `Interim: ${text}`);
+ * import { createClient } from "@amaster.ai/client";
+ * export const client = createClient({});
+ * const asrClient = client.asr({
+ *   language: "zh",
+ *   enableVAD: true,
+ *   onReady() {
+ *     console.log("ASR connected");
+ *   },
+ *   onTranscript(text, isFinal) {
+ *     console.log(isFinal ? "[Final]" : "[Interim]", text);
+ *   },
+ *   onError(err) {
+ *     console.error("ASR error:", err);
  *   },
- *   onError: (error) => console.error('ASR Error:', error)
  * });
+ *
+ * await asrClient.connect();
+ * await asrClient.startRecording();
+ * // ... stop ...
+ * await asrClient.stopRecording();
+ * await asrClient.close();
  * ```
  */
+export type ASRLanguage =
+  | "zh"
+  | "yue"
+  | "en"
+  | "ja"
+  | "de"
+  | "ko"
+  | "ru"
+  | "fr"
+  | "pt"
+  | "ar"
+  | "it"
+  | "es"
+  | "hi"
+  | "id"
+  | "th"
+  | "tr"
+  | "uk"
+  | "vi"
+  | "cs"
+  | "da"
+  | "fil"
+  | "fi"
+  | "is"
+  | "ms"
+  | "no"
+  | "pl"
+  | "sv";
+export type ClientEventType =
+  | "session.update"
+  | "input_audio_buffer.append"
+  | "input_audio_buffer.commit"
+  | "session.finish";
+export type ServerEventType =
+  | "session.created"
+  | "session.updated"
+  | "input_audio_buffer.speech_started"
+  | "input_audio_buffer.speech_stopped"
+  | "input_audio_buffer.committed"
+  | "conversation.item.input_audio_transcription.text"
+  | "conversation.item.input_audio_transcription.completed"
+  | "session.finished"
+  | "error";
+export interface BaseEvent {
+  event_id: string;
+  type: ClientEventType | ServerEventType;
+}
+export interface SessionUpdateEvent extends BaseEvent {
+  type: "session.update";
+  session: SessionConfig;
+}
+export interface InputAudioBufferAppendEvent extends BaseEvent {
+  type: "input_audio_buffer.append";
+  audio: string;
+}
+export interface InputAudioBufferCommitEvent extends BaseEvent {
+  type: "input_audio_buffer.commit";
+}
+export interface SessionFinishEvent extends BaseEvent {
+  type: "session.finish";
+}
+type ClientEvent =
+  | SessionUpdateEvent
+  | InputAudioBufferAppendEvent
+  | InputAudioBufferCommitEvent
+  | SessionFinishEvent;
+export interface SessionCreatedEvent extends BaseEvent {
+  type: "session.created";
+  session: {
+    id: string;
+  };
+}
+export interface SessionUpdatedEvent extends BaseEvent {
+  type: "session.updated";
+  session: SessionConfig;
+}
+export interface SpeechStartedEvent extends BaseEvent {
+  type: "input_audio_buffer.speech_started";
+}
+export interface SpeechStoppedEvent extends BaseEvent {
+  type: "input_audio_buffer.speech_stopped";
+}
+export interface InputAudioBufferCommittedEvent extends BaseEvent {
+  type: "input_audio_buffer.committed";
+}
+export interface TranscriptionTextEvent extends BaseEvent {
+  type: "conversation.item.input_audio_transcription.text";
+  text?: string;
+  stash?: string;
+  transcript?: string;
+}
+export interface TranscriptionCompletedEvent extends BaseEvent {
+  type: "conversation.item.input_audio_transcription.completed";
+  text?: string;
+  transcript?: string;
+}
+export interface SessionFinishedEvent extends BaseEvent {
+  type: "session.finished";
+}
+export interface ErrorEvent extends BaseEvent {
+  type: "error";
+  error: {
+    message: string;
+    code?: string;
+  };
+}
+export type ServerEvent =
+  | SessionCreatedEvent
+  | SessionUpdatedEvent
+  | SpeechStartedEvent
+  | SpeechStoppedEvent
+  | InputAudioBufferCommittedEvent
+  | TranscriptionTextEvent
+  | TranscriptionCompletedEvent
+  | SessionFinishedEvent
+  | ErrorEvent;
+export interface TurnDetectionConfig {
+  type: "server_vad";
+  /** VAD检测阈值，推荐设为 0.0，默认值 0.2，范围 [-1, 1] */
+  threshold?: number;
+  /** VAD断句检测阈值(ms)，推荐设为 400，默认值 800，范围 [200, 6000] */
+  silence_duration_ms?: number;
+}
+export interface InputAudioTranscriptionConfig {
+  language?: ASRLanguage;
+}
+export interface SessionConfig {
+  input_audio_format?: "pcm" | "opus";
+  sample_rate?: 16000 | 8000;
+  input_audio_transcription?: InputAudioTranscriptionConfig;
+  turn_detection?: TurnDetectionConfig | null;
+}
 export interface ASRClientConfig {
-  /** Audio format, default 'pcm16' */
-  audioFormat?: "pcm16" | "g711a" | "g711u";
-  
-  /** Sample rate, default 16000 */
-  sampleRate?: number;
-  
-  /** Called when connection is ready */
+  /**
+   * Audio format
+   * @default "pcm"
+   */
+  audioFormat?: "pcm" | "opus";
+  /**
+   * Sample rate in Hz
+   * @default 16000
+   * @description 支持 16000 和 8000。设置为 8000 时，服务端会先升采样到16000Hz再进行识别，可能引入微小延迟。
+   */
+  sampleRate?: 16000 | 8000;
+  /**
+   * Audio source language
+   * @default "zh"
+   * @description 支持多种语言，包括 zh（中文）、yue（粤语）、en（英文）、ja（日语）等
+   */
+  language?: ASRLanguage;
+  /**
+   * Enable VAD (Voice Activity Detection) mode
+   * @default true
+   * @description true = VAD模式（服务端自动检测语音开始/结束），false = Manual模式（客户端手动控制）
+   */
+  enableVAD?: boolean;
+  /**
+   * VAD detection threshold
+   * @default 0.2
+   * @description 推荐设为 0.0。取值范围 [-1, 1]。较低的阈值会提高 VAD 的灵敏度。
+   */
+  vadThreshold?: number;
+  /**
+   * VAD silence duration threshold in milliseconds
+   * @default 800
+   * @description 推荐设为 400。取值范围 [200, 6000]。静音持续时长超过该阈值将被认为是语句结束。
+   */
+  vadSilenceDurationMs?: number;
+  /**
+   * Get access token for WebSocket authentication
+   */
+  getAccessToken?: () => string | null;
+  /**
+   * Called when connection is ready (session.created received and session.update sent)
+   */
   onReady?: () => void;
-  
-  /** Called when speech is detected */
+  /**
+   * Called when speech is detected (VAD mode only)
+   */
   onSpeechStart?: () => void;
-  
-  /** Called when speech stops */
+  /**
+   * Called when speech stops (VAD mode only)
+   */
   onSpeechEnd?: () => void;
-  
-  /** 
+  /**
    * Called on transcript result
-   * @param text - Recognized text
+   * @param text - Transcribed text
    * @param isFinal - Whether this is the final result
    */
   onTranscript?: (text: string, isFinal: boolean) => void;
-  
-  /** Called on error */
+  /**
+   * Called when audio buffer is committed (non-VAD mode only)
+   */
+  onAudioBufferCommitted?: () => void;
+  /**
+   * Called when session is finished
+   */
+  onSessionFinished?: () => void;
+  /**
+   * Called on error
+   */
   onError?: (error: Error) => void;
-  
-  /** Called on connection close */
+  /**
+   * Called on close
+   */
   onClose?: () => void;
-  
-  /** WebSocket path override */
-  path?: string;
 }
-
-/**
- * ASR Client API
- * 
- * Real-time speech recognition client using WebSocket.
- * 
- * @example
- * Basic usage:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Configure callbacks
- * client.asr = createASRClient({
- *   onTranscript: (text, isFinal) => {
- *     if (isFinal) {
- *       console.log('Final transcript:', text);
- *     } else {
- *       console.log('Interim transcript:', text);
- *     }
- *   }
- * });
- * 
- * // Connect and start recording
- * await client.asr.connect();
- * await client.asr.startRecording();
- * 
- * // Stop recording
- * client.asr.stopRecording();
- * 
- * // Close connection
- * client.asr.close();
- * ```
- * 
- * @example
- * With error handling:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * client.asr = createASRClient({
- *   onReady: () => console.log('ASR ready'),
- *   onSpeechStart: () => console.log('Speech detected'),
- *   onSpeechEnd: () => console.log('Speech ended'),
- *   onTranscript: (text, isFinal) => {
- *     console.log(isFinal ? `[FINAL] ${text}` : `[INTERIM] ${text}`);
- *   },
- *   onError: (error) => {
- *     console.error('ASR Error:', error.message);
- *   },
- *   onClose: () => {
- *     console.log('ASR connection closed');
- *   }
- * });
- * 
- * try {
- *   await client.asr.connect();
- *   await client.asr.startRecording();
- * } catch (error) {
- *   console.error('Failed to start ASR:', error);
- * }
- * ```
- */
 export interface ASRClient {
+  /** Connect to ASR service and establish session */
+  connect(): Promise<void>;
+  /** Start recording from microphone */
+  startRecording(): Promise<void>;
   /**
-   * Connect to ASR service
-   * 
-   * Establishes WebSocket connection to the speech recognition service.
-   * 
-   * @returns Promise that resolves when connected
-   * 
-   * @example
-   * ```typescript
-   * await client.asr.connect();
-   * console.log('Connected to ASR service');
-   * ```
+   * Stop recording
+   * @description In non-VAD mode, this triggers recognition by sending input_audio_buffer.commit
    */
-  connect(): Promise<void>;
-
+  stopRecording(): Promise<void>;
   /**
-   * Start recording from microphone
-   * 
-   * Begins capturing audio from the user's microphone and sends it to the ASR service.
-   * Requires microphone permission from the user.
-   * 
-   * @returns Promise that resolves when recording starts
-   * 
-   * @example
-   * ```typescript
-   * // Request microphone permission and start recording
-   * try {
-   *   await client.asr.startRecording();
-   *   console.log('Recording started');
-   * } catch (error) {
-   *   if (error.name === 'NotAllowedError') {
-   *     console.error('Microphone permission denied');
-   *   }
-   * }
-   * ```
+   * Close connection gracefully
+   * @description Sends session.finish and waits for session.finished before closing
    */
-  startRecording(): Promise<void>;
+  close(): Promise<void>;
+  /**
+   * Check if currently recording
+   */
+  isRecording(): boolean;
+  /**
+   * Check if connected to server
+   */
+  isConnected(): boolean;
+}
+declare const _default$1: (
+  authConfig: Pick<ASRClientConfig, "getAccessToken">
+) => (config: ASRClientConfig) => ASRClient;
 
+export interface Recorder {
+  /** Start recording */
+  start(): Promise<void>;
   /**
-   * Stop recording
-   * 
-   * Stops capturing audio from the microphone but keeps the WebSocket connection open.
-   * 
-   * @example
-   * ```typescript
-   * // Stop recording after 10 seconds
-   * await client.asr.startRecording();
-   * setTimeout(() => {
-   *   client.asr.stopRecording();
-   *   console.log('Recording stopped');
-   * }, 10000);
-   * ```
-   */
-  stopRecording(): void;
+   * Stop recording and get base64-encoded WAV audio data. You can use this data to call the ASR API.
+   *
+   * @returns Base64-encoded WAV audio data
+   */
+  stop(): Promise<void>;
+}
 
+export interface RecorderOptions {
+  /** Called when recording starts */
+  onStart?: () => void;
   /**
-   * Close connection
-   * 
-   * Closes the WebSocket connection and releases resources.
-   * 
-   * @example
-   * ```typescript
-   * // Cleanup when done
-   * client.asr.stopRecording();
-   * client.asr.close();
-   * ```
-   */
-  close(): void;
+   * Called when recording stops, with base64-encoded WAV audio data. You can use this data to call the ASR API.
+   *
+   * @param base64 - Base64-encoded WAV audio data
+   * @returns void
+   */
+  onStop?: (base64: string) => void;
+  onError?: (error: Error) => void;
+}
+
+export type ASRHttpStatus = "idle" | "recording" | "recognizing";
+
+export interface ASRHttpClientConfig {
+  /** Get access token */
+  http?: HttpClient;
+  /** Get access token */
+  getAccessToken?(): string | null;
+  /** Create custom recorder */
+  createRecorder?(options?: RecorderOptions): Promise<Recorder>;
+  /** Language, default 'zh' */
+  language?: string;
+  /** Sample rate, default 16000 */
+  sampleRate?: number;
+  /** Called when recording starts */
+  onRecordingStart?: () => void;
+  /** Called when recording stops */
+  onRecordingStop?: () => void;
+  /** Called with recognition result */
+  onResult?: (text: string) => void;
+  /** Called on error */
+  onError?: (error: Error) => void;
+  /** Called when status changes */
+  onStatusChange?: (status: ASRHttpStatus) => void;
+}
+export interface ASRHttpClient {
+  /** Start recording (press-to-talk) */
+  startRecording(): Promise<void>;
+  /** Stop recording and get result */
+  stopRecording(): Promise<string>;
+  /** Record for specific duration then recognize */
+  recordAndRecognize(durationMs: number): Promise<string>;
+  /** Recognize audio file (File or Blob) */
+  recognizeFile(file: File | Blob): Promise<string>;
+  /** Recognize audio from URL */
+  recognizeUrl(audioUrl: string): Promise<string>;
 }

package/types/auth/code-auth.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * Verification Code Authentication - Type Definitions
- * ============================================================================
- * 
- * Verification code-based authentication including:
+ *  * Verification code-based authentication including:
  * - Email verification code login
  * - SMS verification code login
  * - Send verification code
@@ -24,46 +20,7 @@ export type CodeLoginType = 'email' | 'phone';
 
 /**
  * Verification code login parameters
- * 
- * @example
- * Email code login:
- * ```typescript
- * // 1. Send verification code
- * await client.auth.sendCode({
- *   type: 'email',
- *   email: 'user@example.com'
- * });
- * 
- * // 2. User receives code via email: "123456"
- * 
- * // 3. Login with code
- * const result = await client.auth.codeLogin({
- *   email: 'user@example.com',
- *   code: '123456'
- * });
- * 
- * if (result.data) {
- *   console.log('Logged in successfully!');
- * }
- * ```
- * 
- * @example
- * Phone code login:
- * ```typescript
- * // 1. Send SMS code
- * await client.auth.sendCode({
- *   type: 'phone',
- *   phone: '+86-13800138000'
- * });
- * 
- * // 2. User receives SMS: "654321"
- * 
- * // 3. Login with code
- * await client.auth.codeLogin({
- *   phone: '+86-13800138000',
- *   code: '654321'
- * });
- * ```
+ *
  */
 export interface CodeLoginParams {
   /** Login method (optional, auto-detected) */
@@ -114,52 +71,14 @@ export interface CaptchaResponse {
 export interface CodeAuthAPI {
   /**
    * Login with verification code
-   * 
+   *
    * Authenticates using a verification code sent to email or phone.
-   * 
+   *
    * @param params - Email/phone and verification code
    * @returns User info and access token
-   * 
-   * @example
-   * Complete code login flow:
-   * ```typescript
-   * // 1. Send verification code
-   * await client.auth.sendCode({
-   *   type: 'email',
-   *   email: 'user@example.com'
-   * });
-   * 
-   * // 2. User receives code: "123456"
-   * 
-   * // 3. Login with code
-   * const result = await client.auth.codeLogin({
-   *   email: 'user@example.com',
-   *   code: '123456'
-   * });
-   * 
-   * if (result.data) {
-   *   console.log('Logged in successfully!');
-   * }
-   * ```
-   * 
-   * @example
-   * SMS code login with error handling:
-   * ```typescript
-   * const result = await client.auth.codeLogin({
-   *   phone: '+86-13800138000',
-   *   code: userInputCode
-   * });
-   * 
-   * if (result.error) {
-   *   if (result.status === 400) {
-   *     console.error('Invalid or expired code');
-   *   } else {
-   *     console.error('Login failed:', result.error.message);
-   *   }
-   * }
-   * ```
+   *
    */
-  codeLogin(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
+  loginWithCode(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
 
   /**
    * Send verification code
@@ -169,43 +88,7 @@ export interface CodeAuthAPI {
    * 
    * @param params - Email or phone to send code to
    * @returns Success status
-   * 
-   * @example
-   * Send email verification code:
-   * ```typescript
-   * const result = await client.auth.sendCode({
-   *   type: 'email',
-   *   email: 'user@example.com'
-   * });
-   * 
-   * if (result.data?.success) {
-   *   console.log('Code sent to email');
-   *   showCodeInputForm();
-   * }
-   * ```
-   * 
-   * @example
-   * Send SMS verification code:
-   * ```typescript
-   * await client.auth.sendCode({
-   *   type: 'phone',
-   *   phone: '+86-13800138000'
-   * });
-   * console.log('SMS sent');
-   * ```
-   * 
-   * @example
-   * With rate limiting handling:
-   * ```typescript
-   * const result = await client.auth.sendCode({
-   *   type: 'email',
-   *   email: 'user@example.com'
-   * });
-   * 
-   * if (result.status === 429) {
-   *   console.error('Too many requests. Please try again later.');
-   * }
-   * ```
+   *
    */
   sendCode(params: SendCodeParams): Promise<ClientResult<SuccessResponse>>;
 
@@ -216,39 +99,7 @@ export interface CodeAuthAPI {
    * Used during registration or sensitive operations.
    * 
    * @returns Captcha ID and image (base64)
-   * 
-   * @example
-   * Display captcha to user:
-   * ```typescript
-   * const result = await client.auth.getCaptcha();
-   * if (result.data) {
-   *   // Display image to user
-   *   const img = document.createElement('img');
-   *   img.src = result.data.captchaImage;
-   *   document.body.appendChild(img);
-   *   
-   *   // Save captchaId for later verification
-   *   const captchaId = result.data.captchaId;
-   * }
-   * ```
-   * 
-   * @example
-   * Use with registration:
-   * ```typescript
-   * // 1. Get captcha
-   * const captchaResult = await client.auth.getCaptcha();
-   * showCaptchaImage(captchaResult.data.captchaImage);
-   * 
-   * // 2. Get user input
-   * const userInput = await promptUserForCaptcha();
-   * 
-   * // 3. Register with captcha
-   * await client.auth.register({
-   *   email: 'user@example.com',
-   *   password: 'Password@123',
-   *   captcha: `${captchaResult.data.captchaId}:${userInput}`
-   * });
-   * ```
+   *
    */
   getCaptcha(): Promise<ClientResult<CaptchaResponse>>;
 }