@amaster.ai/client 1.0.0-alpha.2 → 1.0.0-beta.72

package/types/asr.d.ts

@@ -1,3 +1,4 @@
+import type{ HttpClient } from "./http";
 /**
  * ASR Realtime WebSocket Client for Qwen-ASR Realtime API
  *
@@ -6,6 +7,8 @@
  *
  * @example
  * ```typescript
+ * import { createClient } from "@amaster.ai/client";
+ * export const client = createClient({});
  * const asrClient = client.asr({
  *   language: "zh",
  *   enableVAD: true,
@@ -27,211 +30,298 @@
  * 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 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;
+  event_id: string;
+  type: ClientEventType | ServerEventType;
 }
 export interface SessionUpdateEvent extends BaseEvent {
-    type: "session.update";
-    session: SessionConfig;
+  type: "session.update";
+  session: SessionConfig;
 }
 export interface InputAudioBufferAppendEvent extends BaseEvent {
-    type: "input_audio_buffer.append";
-    audio: string;
+  type: "input_audio_buffer.append";
+  audio: string;
 }
 export interface InputAudioBufferCommitEvent extends BaseEvent {
-    type: "input_audio_buffer.commit";
+  type: "input_audio_buffer.commit";
 }
 export interface SessionFinishEvent extends BaseEvent {
-    type: "session.finish";
+  type: "session.finish";
 }
-type ClientEvent = SessionUpdateEvent | InputAudioBufferAppendEvent | InputAudioBufferCommitEvent | SessionFinishEvent;
+type ClientEvent =
+  | SessionUpdateEvent
+  | InputAudioBufferAppendEvent
+  | InputAudioBufferCommitEvent
+  | SessionFinishEvent;
 export interface SessionCreatedEvent extends BaseEvent {
-    type: "session.created";
-    session: {
-        id: string;
-    };
+  type: "session.created";
+  session: {
+    id: string;
+  };
 }
 export interface SessionUpdatedEvent extends BaseEvent {
-    type: "session.updated";
-    session: SessionConfig;
+  type: "session.updated";
+  session: SessionConfig;
 }
 export interface SpeechStartedEvent extends BaseEvent {
-    type: "input_audio_buffer.speech_started";
+  type: "input_audio_buffer.speech_started";
 }
 export interface SpeechStoppedEvent extends BaseEvent {
-    type: "input_audio_buffer.speech_stopped";
+  type: "input_audio_buffer.speech_stopped";
 }
 export interface InputAudioBufferCommittedEvent extends BaseEvent {
-    type: "input_audio_buffer.committed";
+  type: "input_audio_buffer.committed";
 }
 export interface TranscriptionTextEvent extends BaseEvent {
-    type: "conversation.item.input_audio_transcription.text";
-    text?: string;
-    stash?: string;
-    transcript?: string;
+  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;
+  type: "conversation.item.input_audio_transcription.completed";
+  text?: string;
+  transcript?: string;
 }
 export interface SessionFinishedEvent extends BaseEvent {
-    type: "session.finished";
+  type: "session.finished";
 }
 export interface ErrorEvent extends BaseEvent {
-    type: "error";
-    error: {
-        message: string;
-        code?: string;
-    };
+  type: "error";
+  error: {
+    message: string;
+    code?: string;
+  };
 }
-export type ServerEvent = SessionCreatedEvent | SessionUpdatedEvent | SpeechStartedEvent | SpeechStoppedEvent | InputAudioBufferCommittedEvent | TranscriptionTextEvent | TranscriptionCompletedEvent | SessionFinishedEvent | ErrorEvent;
+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;
+  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;
+  language?: ASRLanguage;
 }
 export interface SessionConfig {
-    input_audio_format?: "pcm" | "opus";
-    sample_rate?: 16000 | 8000;
-    input_audio_transcription?: InputAudioTranscriptionConfig;
-    turn_detection?: TurnDetectionConfig | null;
+  input_audio_format?: "pcm" | "opus";
+  sample_rate?: 16000 | 8000;
+  input_audio_transcription?: InputAudioTranscriptionConfig;
+  turn_detection?: TurnDetectionConfig | null;
 }
 export interface ASRClientConfig {
-    /**
-     * 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 (VAD mode only)
-     */
-    onSpeechStart?: () => void;
-    /**
-     * Called when speech stops (VAD mode only)
-     */
-    onSpeechEnd?: () => void;
-    /**
-     * Called on transcript result
-     * @param text - Transcribed text
-     * @param isFinal - Whether this is the final result
-     */
-    onTranscript?: (text: string, isFinal: boolean) => void;
-    /**
-     * 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 close
-     */
-    onClose?: () => void;
+  /**
+   * 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 (VAD mode only)
+   */
+  onSpeechStart?: () => void;
+  /**
+   * Called when speech stops (VAD mode only)
+   */
+  onSpeechEnd?: () => void;
+  /**
+   * Called on transcript result
+   * @param text - Transcribed text
+   * @param isFinal - Whether this is the final result
+   */
+  onTranscript?: (text: string, isFinal: boolean) => void;
+  /**
+   * 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 close
+   */
+  onClose?: () => void;
 }
 export interface ASRClient {
-    /** Connect to ASR service and establish session */
-    connect(): Promise<void>;
-    /** Start recording from microphone */
-    startRecording(): Promise<void>;
-    /**
-     * Stop recording
-     * @description In non-VAD mode, this triggers recognition by sending input_audio_buffer.commit
-     */
-    stopRecording(): Promise<void>;
-    /**
-     * Close connection gracefully
-     * @description Sends session.finish and waits for session.finished before closing
-     */
-    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;
+  /** Connect to ASR service and establish session */
+  connect(): Promise<void>;
+  /** Start recording from microphone */
+  startRecording(): Promise<void>;
+  /**
+   * Stop recording
+   * @description In non-VAD mode, this triggers recognition by sending input_audio_buffer.commit
+   */
+  stopRecording(): Promise<void>;
+  /**
+   * Close connection gracefully
+   * @description Sends session.finish and waits for session.finished before closing
+   */
+  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 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;
+  /**
+   * 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 */
-    getAccessToken?(): string | null;
-    /** 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;
+  /** 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>;
-}
+  /** 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

@@ -71,14 +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
    *
    */
-  codeLogin(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
+  loginWithCode(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
 
   /**
    * Send verification code

package/types/auth/index.d.ts

@@ -98,6 +98,33 @@ export interface AuthClientAPI
    */
   refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
 
+  // ==================== Event Handling ====================
+
+  /**
+   * Subscribe to authentication events
+   * 
+   * Available events:
+   * - `login` - Fired after successful login, receives User object
+   * - `logout` - Fired after logout
+   * - `tokenExpired` - Fired when access token expires
+   * - `tokenRefreshed` - Fired after token refresh, receives new token
+   * - `unauthorized` - Fired on 401 response
+   * 
+   * @param event - Event name to subscribe to
+   * @param handler - Callback function
+   *
+   */
+  on(event: "login" | "logout" | "tokenExpired" | "tokenRefreshed" | "unauthorized", handler: (...args: unknown[]) => void): void;
+
+  /**
+   * Unsubscribe from authentication events
+   * 
+   * @param event - Event name to unsubscribe from
+   * @param handler - The same callback function that was passed to `on()`
+   *
+   */
+  off(event: "login" | "logout" | "tokenExpired" | "tokenRefreshed" | "unauthorized", handler: (...args: unknown[]) => void): void;
+
   // ==================== Permission Checks ====================
   
   /**

package/types/auth/user.d.ts

@@ -12,7 +12,7 @@
  * 
  * Roles and permissions are returned as simple string arrays for efficient client-side use:
  * - `roles`: ["admin", "user", "manager"]
- * - `permissions`: ["user:read", "user:write", "order:read"]
+ * - `permissions`: ["user.read", "user.write", "order.read"]
  *
  */
 export interface User {
@@ -61,7 +61,7 @@ export interface User {
   
   /** 
    * Permission names granted to user
-   * Format: "resource:action"
+   * Format: "resource.action"
    */
   permissions: string[];