@amaster.ai/client 1.0.0-alpha.1

package/types/http.d.ts

@@ -0,0 +1,95 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+
+type ClientError = {
+    message: string;
+    status?: number;
+    code?: string;
+    details?: unknown;
+};
+type ClientResult<T> = {
+    data: T | null;
+    error: ClientError | null;
+    status: number;
+};
+type RequestConfig = AxiosRequestConfig & {
+    url: string;
+    method: NonNullable<AxiosRequestConfig["method"]> | string;
+};
+type AdapterResponse = {
+    status: number;
+    data: unknown;
+    headers?: unknown;
+};
+type HttpAdapter = (_config: RequestConfig) => Promise<AdapterResponse>;
+type HttpClientOptions = {
+    /**
+     * HTTP adapter to use:
+     * - undefined: auto-detect (taro if mini-program APIs exist, otherwise axios)
+     * - "taro": force mini-program request (wx/tt/my/...) or global Taro.request
+     * - "axios": force axios
+     * - AxiosInstance: use provided axios instance
+     * - function: custom adapter
+     */
+    adapter?: "taro" | "axios" | AxiosInstance | HttpAdapter;
+    /**
+     * Base URL to prefix when `config.url` is relative (e.g. "/api/...").
+     *
+     * If not provided:
+     * - Taro/mini-program: auto-reads from process.env.TARO_APP_API_BASE_URL or process.env.VITE_API_BASE_URL
+     * - H5/Browser: no baseURL (expects dev proxy or absolute URLs)
+     */
+    baseURL?: string;
+    /** Default headers merged into each request */
+    headers?: Record<string, string>;
+    /**
+     * Custom response transform function to extract/modify data from backend response
+     * If not provided, uses default transform logic for { status: 0/1, data: {...} }
+     *
+     * Similar to axios's transformResponse option
+     *
+     * @example
+     * ```typescript
+     * // For backend that returns: { statusCode: 200, data: {...} }
+     * const client = createHttpClient({
+     *   transformResponse: (response) => {
+     *     if (response && typeof response === 'object' && 'data' in response) {
+     *       return response.data;
+     *     }
+     *     return response;
+     *   }
+     * });
+     * ```
+     */
+    transformResponse?: <T>(responseData: unknown) => T;
+    /**
+     * Whether to log errors to console (default: true)
+     * Set to false to disable automatic error logging
+     */
+    logErrors?: boolean;
+};
+type HttpClient = {
+    request<T>(_config: RequestConfig): Promise<ClientResult<T>>;
+};
+/**
+ * Create an HTTP client instance
+ *
+ * @param axiosInstance - Optional axios instance to use (defaults to a basic axios instance)
+ * @returns HttpClient with request method
+ *
+ * @example
+ * ```typescript
+ * import axios from "axios";
+ * import { createHttpClient } from "@amaster.ai/http-client";
+ *
+ * const instance = axios.create({ baseURL: "https://api.example.com" });
+ * const client = createHttpClient(instance);
+ *
+ * const result = await client.request({
+ *   url: "/users",
+ *   method: "get",
+ * });
+ * ```
+ */
+declare function createHttpClient(axiosInstanceOrOptions?: AxiosInstance | HttpClientOptions): HttpClient;
+
+export { type AdapterResponse, type ClientError, type ClientResult, type HttpAdapter, type HttpClient, type HttpClientOptions, type RequestConfig, createHttpClient };

package/types/index.d.ts

@@ -0,0 +1,338 @@
+/**
+ *  * A Supabase-inspired unified client for the Amaster platform.
+ *
+ * ## Features
+ * - Single client instance for all services (auth, entity, bpm, workflow)
+ * - Automatic token management and refresh
+ * - Auto-attach authentication to all requests
+ * - Centralized error handling
+ *
+ * ## Quick Start
+ * ```typescript
+ * import { createClient } from '@amaster.ai/client';
+ *
+ * const client = createClient({
+ *   baseURL: 'https://api.amaster.ai',
+ *   onUnauthorized: () => window.location.href = '/login'
+ * });
+ *
+ * // Login
+ * await client.auth.login({ email, password });
+ *
+ * // All subsequent requests automatically include auth token
+ * await client.entity.list('default', 'users');
+ * await client.bpm.startProcess('approval', {});
+ * ```
+ *
+ * ## Module Documentation
+ * For detailed API documentation, see individual module type definitions:
+ * - **Authentication**: {@link ./auth/index.d.ts} (split into user, password-auth, code-auth, oauth, permissions, profile)
+ * - **Entity Operations**: {@link ./entity.d.ts}
+ * - **BPM (Business Process)**: {@link ./bpm.d.ts}
+ * - **Workflow Execution**: {@link ./workflow.d.ts}
+ *
+ * ## AI-Friendly Type Structure
+ * This package provides modular type definitions optimized for AI tools and large language models.
+ * Types are split into focused modules that can be loaded on-demand:
+ *
+ * **Authentication Types** (70-88% token savings):
+ * - `@amaster.ai/client/auth/user` - User types (100 lines)
+ * - `@amaster.ai/client/auth/password-auth` - Login/register (200 lines)
+ * - `@amaster.ai/client/auth/code-auth` - Verification code (150 lines)
+ * - `@amaster.ai/client/auth/oauth` - OAuth providers (120 lines)
+ * - `@amaster.ai/client/auth/permissions` - Permission helpers (80 lines)
+ * - `@amaster.ai/client/auth/profile` - Profile management (100 lines)
+ * */
+
+import type { AuthClientAPI } from "./auth/index";
+import type { EntityClientAPI } from "./entity";
+import type { BpmClientAPI } from "./bpm";
+import type { WorkflowClientAPI } from "./workflow";
+import type { ASRClientConfig, ASRClient, ASRHttpClientConfig, ASRHttpClient } from "./asr";
+import type { CopilotClientAPI } from "./copilot";
+import type { FunctionClientAPI } from "./function";
+import type { TTSClientAPI } from "./tts";
+import type { S3ClientAPI } from "./s3";
+import type { HttpClient } from "./http";
+
+/**
+ * Configuration options for creating an Amaster client
+ *
+ */
+export interface AmasterClientOptions {
+  /**
+   * Base URL for the Amaster API
+   *
+   */
+  baseURL: string;
+
+  /**
+   * Optional custom headers to include in ALL requests
+   *
+   * These headers will be merged with authentication headers.
+   * Useful for tenant IDs, API keys, or application metadata.
+   *
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Callback triggered when a 401 Unauthorized response is received
+   *
+   * Use this to redirect to login page or show authentication modal.
+   * This callback is invoked BEFORE the request promise rejects.
+   *
+   */
+  onUnauthorized?: () => void;
+
+  /**
+   * Callback triggered when the access token expires
+   *
+   * Note: Token refresh is handled automatically by the client.
+   * This callback is for additional actions like logging or analytics.
+   *
+   */
+  onTokenExpired?: () => void;
+
+  /**
+   * Enable automatic token refresh (default: true)
+   *
+   * When enabled, tokens are automatically refreshed before expiry.
+   *
+   * @default true
+   */
+  autoRefresh?: boolean;
+
+  /**
+   * Token refresh threshold in seconds (default: 300)
+   *
+   * Tokens will be refreshed this many seconds before expiry.
+   * For example, if set to 300 (5 minutes), a token expiring at
+   * 10:00:00 will be refreshed at 9:55:00.
+   *
+   * @default 300
+   */
+  refreshThreshold?: number;
+
+  /**
+   * Auto-handle OAuth callback on page load (default: true)
+   *
+   * Automatically detects and processes `#access_token` in URL hash,
+   * then clears the hash for security. Set to `false` to manually
+   * call `client.auth.handleOAuthCallback()`.
+   *
+   * @default true
+   */
+  autoHandleOAuthCallback?: boolean;
+}
+
+/**
+ * Unified Amaster Client interface
+ *
+ * This is the main client object returned by `createClient()`.
+ * It provides access to all Amaster services through a unified interface.
+ *
+ * ## Core Modules
+ * - {@link auth} - Authentication and user management
+ * - {@link entity} - CRUD operations for entities
+ * - {@link bpm} - Business process management
+ * - {@link workflow} - Workflow execution
+ *
+ * ## Token Management
+ * - {@link isAuthenticated} - Check if user is authenticated
+ * - {@link getAccessToken} - Get current access token
+ * - {@link setAccessToken} - Set access token manually
+ * - {@link clearAuth} - Clear all authentication state
+ *
+ */
+export interface AmasterClient {
+  /**
+   * Authentication module
+   *
+   * Provides methods for user authentication, registration, and management.
+   *
+   * For detailed documentation, see {@link ./auth.d.ts}
+   *
+   */
+  auth: AuthClientAPI;
+
+  /**
+   * Entity CRUD operations module
+   *
+   * Provides methods for creating, reading, updating, and deleting entities.
+   *
+   * For detailed documentation, see {@link ./entity.d.ts}
+   *
+   */
+  entity: EntityClientAPI;
+
+  /**
+   * Business Process Management (BPM) module
+   *
+   * Provides methods for managing BPMN processes and tasks.
+   *
+   * For detailed documentation, see {@link ./bpm.d.ts}
+   *
+   */
+  bpm: BpmClientAPI;
+
+  /**
+   * Workflow execution module
+   *
+   * Provides methods for executing Dify-style workflows.
+   *
+   * For detailed documentation, see {@link ./workflow.d.ts}
+   *
+   */
+  workflow: WorkflowClientAPI;
+
+  /**
+   * ASR (Automatic Speech Recognition) module
+   *
+   * Provides methods for real-time speech-to-text conversion via WebSocket.
+   *
+   * For detailed documentation, see {@link ./asr.d.ts}
+   */
+  asr: (config: ASRClientConfig) => ASRClient;
+
+  /**
+   * ASR HTTP module
+   *
+   * Provides methods for speech-to-text conversion via HTTP API.
+   *
+   * For detailed documentation, see
+   */
+  asrHttp: (config: ASRHttpClientConfig) => ASRHttpClient;
+
+  /**
+   * Copilot AI Assistant module
+   *
+   * Provides methods for interactive AI conversations with a2a streaming.
+   *
+   * For detailed documentation, see {@link ./copilot.d.ts}
+   *
+   */
+  copilot: CopilotClientAPI;
+
+  /**
+   * Serverless Function module
+   *
+   * Provides methods for invoking serverless functions.
+   *
+   * For detailed documentation, see {@link ./function.d.ts}
+   */
+  function: FunctionClientAPI;
+
+  /**
+   * TTS (Text-to-Speech) module
+   *
+   * Provides methods for real-time text-to-speech conversion via WebSocket.
+   *
+   * For detailed documentation, see {@link ./tts.d.ts}
+   */
+  tts: TTSClientAPI;
+
+  /**
+   * S3 Storage module
+   *
+   * Provides methods for file upload, download, and management.
+   *
+   * For detailed documentation, see {@link ./s3.d.ts}
+   */
+  s3: S3ClientAPI;
+
+  /**
+   * HTTP client instance used for all requests
+   *
+   * This is the underlying HTTP client that handles all API requests.
+   * It automatically includes authentication headers and base URL.
+   * You can use this client to make custom requests to the Amaster API
+   * or your own backend while still benefiting from automatic token management.
+     * For example:
+   * ```typescript
+   * const response = await client.http.request({
+   *   url: '/api/custom-endpoint',
+   *   method: 'POST',
+   *   data: { key: 'value' }
+   * });
+   * console.log(response.data);
+   * ```
+     * Note: The `http` client is an instance of the same HTTP client used internally by the Amaster client.
+   * It automatically includes the base URL and authentication headers configured in `createClient()`.
+   */
+  http: HttpClient;
+
+  /**
+   * Check if the user is currently authenticated
+   *
+   * @returns `true` if a valid access token exists, `false` otherwise
+   *
+   */
+  isAuthenticated(): boolean;
+
+  /**
+   * Get the current access token
+   *
+   * @returns The access token string, or `null` if not authenticated
+   *
+   */
+  getAccessToken(): string | null;
+
+  /**
+   * Manually set the access token
+   *
+   * Useful when you have a token from another source (e.g., SSO, OAuth).
+   * After setting the token, all requests will use it automatically.
+   *
+   * @param token - The JWT access token to set
+   *
+   */
+  setAccessToken(token: string): void;
+
+  /**
+   * Clear all authentication state
+   *
+   * This removes:
+   * - Access token
+   * - User information
+   * - Auto-refresh timers
+   *
+   * After calling this, `isAuthenticated()` will return `false`
+   * and all requests will be unauthenticated.
+   *
+   */
+  clearAuth(): void;
+}
+
+/**
+ * Factory function to create a unified Amaster client
+ *
+ * This is the main entry point for using the Amaster client library.
+ * It returns a client instance that provides access to all Amaster services.
+ *
+ * @param options - Configuration options for the client
+ * @returns A configured Amaster client instance
+ *
+ */
+export declare function createClient(options: AmasterClientOptions): AmasterClient;
+
+// Re-export shared common types
+export type { ClientResult } from "./common";
+
+// Re-export main client interfaces
+export type { AuthClientAPI } from "./auth";
+export type { EntityClientAPI } from "./entity";
+export type { BpmClientAPI } from "./bpm";
+export type { WorkflowClientAPI } from "./workflow";
+export type { ASRClient, ASRClientConfig, ASRHttpClient, ASRHttpClientConfig } from "./asr";
+export type { CopilotClientAPI } from "./copilot";
+export type { FunctionClientAPI } from "./function";
+export type { TTSClientAPI } from "./tts";
+export type { S3ClientAPI } from "./s3";
+export type { HttpClient } from "./http";
+
+// For detailed types, import directly from submodules:
+// import type { LoginParams, User } from '@amaster.ai/client/auth'
+// import type { EntityQueryParams } from '@amaster.ai/client/entity'
+// import type { Task, ProcessInstance } from '@amaster.ai/client/bpm'
+// import type { WorkflowRunRequest } from '@amaster.ai/client/workflow'
+// import type { ServerToClientMessage } from '@amaster.ai/client/copilot'

package/types/s3.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 
+ * @module s3
+ */
+
+import type { ClientResult } from './common';
+
+// ==================== Response Types ====================
+
+/**
+ * Upload response data
+ *
+ */
+export interface UploadRes {
+  /** File key in storage */
+  key: string;
+  /** Full access URL */
+  url: string;
+}
+
+/**
+ * File metadata
+ *
+ */
+export interface S3Metadata {
+  contentType?: string;
+  contentLength?: number;
+  lastModified?: string;
+  [key: string]: any;
+}
+
+// ==================== S3 Client API ====================
+
+/**
+ * S3 Storage Client API
+ * 
+ * Provides methods for uploading, downloading, and managing files in object storage.
+ * 
+ * @since 1.0.0
+ */
+export interface S3ClientAPI {
+  /**
+   * Download a file
+   * 
+   * @param filename - The name/key of the file to download
+   * @returns Blob data of the file
+   * 
+   * @example
+   * const result = await client.s3.download('documents/report.pdf');
+   * if (result.success) {
+   *   const blob = result.data;
+   *   const url = URL.createObjectURL(blob);
+   *   window.open(url);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  download(filename: string): Promise<ClientResult<Blob>>;
+
+  /**
+   * Get metadata for a file
+   * 
+   * @param key - The key of the file
+   * @returns File metadata
+   * 
+   * @example
+   * const result = await client.s3.getMetadata('images/photo.jpg');
+   * if (result.success) {
+   *   console.log('Size:', result.data.contentLength);
+   *   console.log('Type:', result.data.contentType);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  getMetadata(key: string): Promise<ClientResult<S3Metadata>>;
+
+  /**
+   * Upload a file
+   * 
+   * @param file - The file to upload (File or Blob)
+   * @returns Upload result containing key and URL
+   * 
+   * @example
+   * const fileInput = document.querySelector('input[type="file"]');
+   * const file = fileInput.files[0];
+   * 
+   * const result = await client.s3.upload(file);
+   * if (result.success) {
+   *   console.log('File uploaded:', result.data.url);
+   *   console.log('File key:', result.data.key);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  upload(file: File | Blob): Promise<ClientResult<UploadRes>>;
+}

package/types/tts.d.ts

@@ -0,0 +1,88 @@
+/**
+ *  * Real-time text-to-speech synthesis using WebSocket connection.
+ * 
+ * @module tts
+ */
+
+/**
+ * TTS Client Configuration
+ *
+ */
+export interface TTSClientConfig {
+  
+  /** Voice name, default 'Cherry' */
+  voice?: string;
+  
+  /** Auto play audio, default true */
+  autoPlay?: boolean;
+  
+  /** Audio format, default 'pcm' */
+  audioFormat?: "pcm" | "mp3" | "wav" | "opus";
+  
+  /** Sample rate, default 24000 */
+  sampleRate?: number;
+  
+  /** Called when connection is ready */
+  onReady?: () => void;
+  
+  /** Called when audio playback starts */
+  onAudioStart?: () => void;
+  
+  /** Called when audio playback ends */
+  onAudioEnd?: () => void;
+  
+  /** 
+   * Called on each audio chunk received
+   * @param chunks - Array of base64-encoded audio chunks
+   */
+  onAudioChunk?: (chunks: string[]) => void;
+  
+  /** Called on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * TTS (Text-to-Speech) Client API
+ * 
+ * Provides real-time text-to-speech synthesis via WebSocket.
+ * 
+ * @since 1.0.0
+ */
+export interface TTSClientAPI {
+  /**
+   * Connect to TTS service
+   * 
+   * Establishes WebSocket connection to the text-to-speech service.
+   * 
+   * @returns Promise that resolves when connected
+   *
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Synthesize speech from text
+   * 
+   * Converts text to speech and plays it (if autoPlay is enabled).
+   * 
+   * @param text - Text to synthesize
+   * @returns Promise that resolves when synthesis starts
+   *
+   */
+  speak(text: string): Promise<void>;
+
+  /**
+   * Play audio from chunks
+   * 
+   * Manually plays audio chunks when autoPlay is disabled.
+   *
+   */
+  play(): void;
+
+  /**
+   * Close connection
+   * 
+   * Closes the WebSocket connection and releases resources.
+   *
+   */
+  close(): void;
+}