@amaster.ai/client 1.0.0-alpha.1

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@amaster.ai/client",
+  "version": "1.0.0-alpha.1",
+  "description": "Unified API client for Amaster platform - All services in one package",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./types/index.d.ts"
+      ],
+      "auth": [
+        "./types/auth/index.d.ts"
+      ],
+      "auth/*": [
+        "./types/auth/*.d.ts"
+      ],
+      "entity": [
+        "./types/entity.d.ts"
+      ],
+      "bpm": [
+        "./types/bpm.d.ts"
+      ],
+      "workflow": [
+        "./types/workflow.d.ts"
+      ],
+      "asr": [
+        "./types/asr.d.ts"
+      ],
+      "copilot": [
+        "./types/copilot.d.ts"
+      ],
+      "function": [
+        "./types/function.d.ts"
+      ],
+      "tts": [
+        "./types/tts.d.ts"
+      ],
+      "s3": [
+        "./types/s3.d.ts"
+      ],
+      "common": [
+        "./types/common.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md"
+  ],
+  "keywords": [
+    "amaster",
+    "client",
+    "sdk",
+    "unified-api",
+    "typescript"
+  ],
+  "author": "Amaster Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@amaster.ai/asr-client": "1.0.0-alpha.1",
+    "@amaster.ai/bpm-client": "1.0.0-alpha.1",
+    "@amaster.ai/copilot-client": "1.0.0-alpha.1",
+    "@amaster.ai/auth-client": "1.0.0-alpha.1",
+    "@amaster.ai/http-client": "1.0.0-alpha.1",
+    "@amaster.ai/function-client": "1.0.0-alpha.1",
+    "@amaster.ai/entity-client": "1.0.0-alpha.1",
+    "@amaster.ai/tts-client": "1.0.0-alpha.1",
+    "@amaster.ai/workflow-client": "1.0.0-alpha.1",
+    "@amaster.ai/s3-client": "1.0.0-alpha.1"
+  },
+  "peerDependencies": {
+    "axios": "^1.11.0"
+  },
+  "devDependencies": {
+    "@a2a-js/sdk": "^0.3.7",
+    "@vitest/ui": "^1.0.0",
+    "axios": "^1.11.0",
+    "axios-mock-adapter": "^1.22.0",
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.2",
+    "vitest": "^1.0.0"
+  },
+  "scripts": {
+    "build": "./scripts/build.sh",
+    "build:types": "tsc --emitDeclarationOnly --outDir types-generated",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist types-generated *.tsbuildinfo",
+    "type-check": "tsc --noEmit",
+    "validate-types": "tsc --noEmit --project tsconfig.types.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/types/__tests__/type-checks.test-d.ts

@@ -0,0 +1,163 @@
+/**
+ * Type-level tests for @amaster.ai/client
+ * 
+ * These tests verify type inference and type safety at compile time.
+ * They ensure that the type definitions work correctly with TypeScript.
+ */
+
+import { describe, it, expectTypeOf } from 'vitest';
+import type {
+  AmasterClient,
+  AmasterClientOptions,
+  ClientResult,
+  ClientError,
+  EntityListResponse,
+  LoginParams,
+  User,
+  Task,
+  ProcessInstance,
+} from '../index';
+
+describe('Type Tests', () => {
+  describe('ClientResult', () => {
+    it('should have correct structure', () => {
+      type Result = ClientResult<{ id: number; name: string }>;
+      
+      expectTypeOf<Result>().toMatchTypeOf<{
+        data: { id: number; name: string } | null;
+        error: ClientError | null;
+        status: number;
+        success: boolean;
+      }>();
+    });
+
+    it('should infer data type correctly', () => {
+      type UserResult = ClientResult<User>;
+      
+      expectTypeOf<UserResult['data']>().toEqualTypeOf<User | null>();
+    });
+
+    it('should have success field', () => {
+      type Result = ClientResult<unknown>;
+      
+      expectTypeOf<Result['success']>().toEqualTypeOf<boolean>();
+    });
+  });
+
+  describe('ClientError', () => {
+    it('should have all required fields', () => {
+      expectTypeOf<ClientError>().toMatchTypeOf<{
+        status: number;
+        message: string;
+        code?: string;
+        details?: unknown;
+        timestamp?: string;
+      }>();
+    });
+  });
+
+  describe('EntityListResponse', () => {
+    it('should infer item type correctly', () => {
+      type UserListResponse = EntityListResponse<{ id: number; name: string }>;
+      
+      expectTypeOf<UserListResponse['items']>().toEqualTypeOf<Array<{ id: number; name: string }>>();
+    });
+
+    it('should have pagination fields', () => {
+      type Response = EntityListResponse<unknown>;
+      
+      expectTypeOf<Response>().toMatchTypeOf<{
+        items: unknown[];
+        total: number;
+        page?: number;
+        perPage?: number;
+      }>();
+    });
+  });
+
+  describe('AmasterClient', () => {
+    it('should have all service modules', () => {
+      expectTypeOf<AmasterClient>().toHaveProperty('auth');
+      expectTypeOf<AmasterClient>().toHaveProperty('entity');
+      expectTypeOf<AmasterClient>().toHaveProperty('bpm');
+      expectTypeOf<AmasterClient>().toHaveProperty('workflow');
+      expectTypeOf<AmasterClient>().toHaveProperty('asr');
+      expectTypeOf<AmasterClient>().toHaveProperty('copilot');
+      expectTypeOf<AmasterClient>().toHaveProperty('function');
+      expectTypeOf<AmasterClient>().toHaveProperty('tts');
+      expectTypeOf<AmasterClient>().toHaveProperty('s3');
+    });
+
+    it('should have utility methods', () => {
+      expectTypeOf<AmasterClient>().toHaveProperty('isAuthenticated');
+      expectTypeOf<AmasterClient>().toHaveProperty('getAccessToken');
+      expectTypeOf<AmasterClient>().toHaveProperty('setAccessToken');
+      expectTypeOf<AmasterClient>().toHaveProperty('clearAuth');
+    });
+  });
+
+  describe('LoginParams', () => {
+    it('should accept email login', () => {
+      const params: LoginParams = {
+        email: 'user@example.com',
+        password: 'password123'
+      };
+      
+      expectTypeOf(params).toMatchTypeOf<LoginParams>();
+    });
+
+    it('should accept username login', () => {
+      const params: LoginParams = {
+        username: 'johndoe',
+        password: 'password123'
+      };
+      
+      expectTypeOf(params).toMatchTypeOf<LoginParams>();
+    });
+
+    it('should accept phone login', () => {
+      const params: LoginParams = {
+        phone: '+1234567890',
+        password: 'password123'
+      };
+      
+      expectTypeOf(params).toMatchTypeOf<LoginParams>();
+    });
+  });
+
+  describe('Generic Type Inference', () => {
+    it('should infer entity list result type', () => {
+      type User = { id: number; name: string; email: string };
+      type Result = ClientResult<EntityListResponse<User>>;
+      
+      // If success, data.items should be User[]
+      expectTypeOf<NonNullable<Result['data']>['items']>().toEqualTypeOf<User[]>();
+    });
+
+    it('should infer entity get result type', () => {
+      type Product = { id: number; title: string; price: number };
+      type Result = ClientResult<Product>;
+      
+      expectTypeOf<NonNullable<Result['data']>>().toEqualTypeOf<Product>();
+    });
+  });
+
+  describe('BPM Types', () => {
+    it('should have correct Task structure', () => {
+      expectTypeOf<Task>().toMatchTypeOf<{
+        id: string;
+        name: string;
+        assignee: string | null;
+        processInstanceId: string;
+      }>();
+    });
+
+    it('should have correct ProcessInstance structure', () => {
+      expectTypeOf<ProcessInstance>().toMatchTypeOf<{
+        id: string;
+        definitionId?: string;
+        businessKey?: string;
+      }>();
+    });
+  });
+});

package/types/asr.d.ts

@@ -0,0 +1,237 @@
+/**
+ * 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
+ * ```typescript
+ * 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);
+ *   },
+ * });
+ *
+ * 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 "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;
+
+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;
+}
+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

@@ -0,0 +1,105 @@
+/**
+ *  * Verification code-based authentication including:
+ * - Email verification code login
+ * - SMS verification code login
+ * - Send verification code
+ * - Captcha verification
+ * 
+ * @module auth/code-auth
+ */
+
+import type { ClientResult } from '../common';
+import type { LoginResponse, SuccessResponse } from './password-auth';
+
+// ==================== Parameters ====================
+
+/**
+ * Verification code login type
+ */
+export type CodeLoginType = 'email' | 'phone';
+
+/**
+ * Verification code login parameters
+ *
+ */
+export interface CodeLoginParams {
+  /** Login method (optional, auto-detected) */
+  loginType?: CodeLoginType;
+  
+  /** Email (required if using email code) */
+  email?: string;
+  
+  /** Phone (required if using phone code) */
+  phone?: string;
+  
+  /** Verification code received via email/SMS */
+  code: string;
+}
+
+/**
+ * Send verification code parameters
+ */
+export interface SendCodeParams {
+  /** Delivery method */
+  type: 'email' | 'phone';
+  
+  /** Email address (required if type='email') */
+  email?: string;
+  
+  /** Phone number (required if type='phone') */
+  phone?: string;
+}
+
+/**
+ * Captcha response data
+ */
+export interface CaptchaResponse {
+  /** Unique captcha identifier */
+  captchaId: string;
+  
+  /** Base64 encoded captcha image */
+  captchaImage: string;
+}
+
+// ==================== API ====================
+
+/**
+ * Verification Code Authentication API
+ * 
+ * Methods for code-based authentication and verification.
+ */
+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>>;
+
+  /**
+   * Send verification code
+   * 
+   * Sends a verification code to the specified email or phone.
+   * Used for code login or account verification.
+   * 
+   * @param params - Email or phone to send code to
+   * @returns Success status
+   *
+   */
+  sendCode(params: SendCodeParams): Promise<ClientResult<SuccessResponse>>;
+
+  /**
+   * Get captcha image
+   * 
+   * Retrieves a captcha challenge for verification.
+   * Used during registration or sensitive operations.
+   * 
+   * @returns Captcha ID and image (base64)
+   *
+   */
+  getCaptcha(): Promise<ClientResult<CaptchaResponse>>;
+}