@amaster.ai/client 1.1.0-beta.30 → 1.1.0-beta.32

package/types/function.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * Function Invocation - Type Definitions
- * ============================================================================
- * 
- * Invoke serverless functions deployed on the Amaster platform.
+ *  * Invoke serverless functions deployed on the Amaster platform.
  * 
  * @module function
  */
@@ -15,67 +11,9 @@ import type { ClientResult } from './common';
  * 
  * Execute serverless functions with type-safe parameters and results.
  * 
- * @example
- * Basic function call:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Call a function
- * const result = await client.function.invoke('sendEmail', {
- *   to: 'user@example.com',
- *   subject: 'Hello',
- *   body: 'Welcome to Amaster!'
- * });
- * 
- * if (result.data) {
- *   console.log('Email sent successfully:', result.data);
- * }
- * ```
- * 
- * @example
- * With TypeScript generics:
- * ```typescript
- * interface SendEmailParams {
- *   to: string;
- *   subject: string;
- *   body: string;
- * }
- * 
- * interface SendEmailResult {
- *   messageId: string;
- *   status: 'sent' | 'queued';
- * }
- * 
- * const result = await client.function.invoke<SendEmailResult>(
- *   'sendEmail',
- *   {
- *     to: 'user@example.com',
- *     subject: 'Hello',
- *     body: 'Welcome!'
- *   }
- * );
- * 
- * if (result.data) {
- *   console.log('Message ID:', result.data.messageId);
- * }
- * ```
- * 
- * @example
- * Error handling:
- * ```typescript
- * const result = await client.function.invoke('processPayment', {
- *   amount: 100,
- *   currency: 'USD'
- * });
- * 
- * if (result.error) {
- *   console.error('Payment failed:', result.error.message);
- * } else {
- *   console.log('Payment processed:', result.data);
- * }
- * ```
+ * @since 1.0.0
  */
-export interface FunctionClient {
+export interface FunctionClientAPI {
   /**
    * Invoke a serverless function
    * 
@@ -84,32 +22,17 @@ export interface FunctionClient {
    * @returns Function execution result
    * 
    * @example
-   * Simple function call:
-   * ```typescript
-   * const result = await client.function.invoke('hello', {
-   *   name: 'World'
+   * const result = await client.function.invoke<{ message: string }>('sendEmail', {
+   *   to: 'user@example.com',
+   *   subject: 'Hello',
+   *   body: 'Welcome!'
    * });
    * 
-   * console.log(result.data); // { message: 'Hello, World!' }
-   * ```
-   * 
-   * @example
-   * Function without parameters:
-   * ```typescript
-   * const result = await client.function.invoke('getCurrentTime');
-   * console.log(result.data); // { timestamp: '2024-01-01T00:00:00Z' }
-   * ```
-   * 
-   * @example
-   * Complex data processing:
-   * ```typescript
-   * const result = await client.function.invoke('analyzeData', {
-   *   dataset: [1, 2, 3, 4, 5],
-   *   operation: 'average'
-   * });
+   * if (result.success) {
+   *   console.log(result.data.message);
+   * }
    * 
-   * console.log(result.data); // { result: 3, count: 5 }
-   * ```
+   * @since 1.0.0
    */
   invoke<T = unknown>(
     funcName: string,

package/types/index.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * @amaster.ai/client - Unified API Client
- * ============================================================================
- * 
- * A Supabase-inspired unified client for the Amaster platform.
+ *  * A Supabase-inspired unified client for the Amaster platform.
  * 
  * ## Features
  * - Single client instance for all services (auth, entity, bpm, workflow)
@@ -46,63 +42,26 @@
  * - `@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)
- * 
- * @packageDocumentation
- */
+ * */
 
 import type { AuthClientAPI } from './auth/index';
 import type { EntityClientAPI } from './entity';
 import type { BpmClientAPI } from './bpm';
 import type { WorkflowClientAPI } from './workflow';
-import type { ASRClient } from './asr';
-import type { CopilotA2UIClient } from './copilot';
-import type { FunctionClient } from './function';
-import type { TTSClient } from './tts';
+import type { ASRClientAPI } from './asr';
+import type { CopilotClientAPI } from './copilot';
+import type { FunctionClientAPI } from './function';
+import type { TTSClientAPI } from './tts';
+import type { S3ClientAPI } from './s3';
 
 /**
  * Configuration options for creating an Amaster client
- * 
- * @example
- * Basic configuration:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai'
- * });
- * ```
- * 
- * @example
- * With authentication callbacks:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   onUnauthorized: () => {
- *     console.log('User is not authenticated');
- *     window.location.href = '/login';
- *   },
- *   onTokenExpired: () => {
- *     console.log('Token expired, refreshing...');
- *   }
- * });
- * ```
- * 
- * @example
- * With custom headers:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   headers: {
- *     'X-Tenant-ID': 'tenant-123',
- *     'X-App-Version': '1.0.0'
- *   }
- * });
- * ```
+ *
  */
 export interface AmasterClientOptions {
   /**
    * Base URL for the Amaster API
-   * 
-   * @example 'https://api.amaster.ai'
-   * @example 'https://my-app.amaster.ai'
+   *
    */
   baseURL: string;
 
@@ -111,15 +70,7 @@ export interface AmasterClientOptions {
    * 
    * These headers will be merged with authentication headers.
    * Useful for tenant IDs, API keys, or application metadata.
-   * 
-   * @example
-   * ```typescript
-   * {
-   *   'X-Tenant-ID': 'tenant-123',
-   *   'X-App-Version': '1.0.0',
-   *   'X-Custom-Header': 'custom-value'
-   * }
-   * ```
+   *
    */
   headers?: Record<string, string>;
 
@@ -128,22 +79,7 @@ export interface AmasterClientOptions {
    * 
    * Use this to redirect to login page or show authentication modal.
    * This callback is invoked BEFORE the request promise rejects.
-   * 
-   * @example
-   * Redirect to login page:
-   * ```typescript
-   * onUnauthorized: () => {
-   *   window.location.href = '/login';
-   * }
-   * ```
-   * 
-   * @example
-   * Show modal:
-   * ```typescript
-   * onUnauthorized: () => {
-   *   showLoginModal();
-   * }
-   * ```
+   *
    */
   onUnauthorized?: () => void;
 
@@ -152,14 +88,7 @@ export interface AmasterClientOptions {
    * 
    * Note: Token refresh is handled automatically by the client.
    * This callback is for additional actions like logging or analytics.
-   * 
-   * @example
-   * ```typescript
-   * onTokenExpired: () => {
-   *   console.log('Token expired, auto-refreshing...');
-   *   analytics.track('token_expired');
-   * }
-   * ```
+   *
    */
   onTokenExpired?: () => void;
 
@@ -182,6 +111,17 @@ export interface AmasterClientOptions {
    * @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;
 }
 
 /**
@@ -201,32 +141,7 @@ export interface AmasterClientOptions {
  * - {@link getAccessToken} - Get current access token
  * - {@link setAccessToken} - Set access token manually
  * - {@link clearAuth} - Clear all authentication state
- * 
- * @example
- * Complete authentication flow:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // 1. Login
- * await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password123'
- * });
- * 
- * // 2. Check authentication
- * if (client.isAuthenticated()) {
- *   console.log('User is logged in');
- * }
- * 
- * // 3. Get current token
- * const token = client.getAccessToken();
- * 
- * // 4. Use any service (token automatically attached)
- * const users = await client.entity.list('default', 'users');
- * 
- * // 5. Logout
- * await client.auth.logout();
- * ```
+ *
  */
 export interface AmasterClient {
   /**
@@ -235,32 +150,7 @@ export interface AmasterClient {
    * Provides methods for user authentication, registration, and management.
    * 
    * For detailed documentation, see {@link ./auth.d.ts}
-   * 
-   * @example
-   * Login:
-   * ```typescript
-   * await client.auth.login({
-   *   email: 'user@example.com',
-   *   password: 'password123'
-   * });
-   * ```
-   * 
-   * @example
-   * Register:
-   * ```typescript
-   * await client.auth.register({
-   *   username: 'johndoe',
-   *   email: 'john@example.com',
-   *   password: 'Password@123'
-   * });
-   * ```
-   * 
-   * @example
-   * Get current user:
-   * ```typescript
-   * const result = await client.auth.getMe();
-   * console.log(result.data); // User object
-   * ```
+   *
    */
   auth: AuthClientAPI;
 
@@ -270,26 +160,7 @@ export interface AmasterClient {
    * Provides methods for creating, reading, updating, and deleting entities.
    * 
    * For detailed documentation, see {@link ./entity.d.ts}
-   * 
-   * @example
-   * List entities:
-   * ```typescript
-   * const result = await client.entity.list('default', 'users', {
-   *   page: 1,
-   *   perPage: 20,
-   *   orderBy: 'createdAt',
-   *   orderDir: 'desc'
-   * });
-   * ```
-   * 
-   * @example
-   * Create entity:
-   * ```typescript
-   * await client.entity.create('default', 'users', {
-   *   name: 'John Doe',
-   *   email: 'john@example.com'
-   * });
-   * ```
+   *
    */
   entity: EntityClientAPI;
 
@@ -299,24 +170,7 @@ export interface AmasterClient {
    * Provides methods for managing BPMN processes and tasks.
    * 
    * For detailed documentation, see {@link ./bpm.d.ts}
-   * 
-   * @example
-   * Start a process:
-   * ```typescript
-   * const result = await client.bpm.startProcess('approval', {
-   *   amount: { value: 1000, type: 'Long' },
-   *   requester: { value: 'user-123', type: 'String' }
-   * });
-   * ```
-   * 
-   * @example
-   * Get tasks:
-   * ```typescript
-   * const tasks = await client.bpm.getTasks({
-   *   assignee: 'user-123',
-   *   processDefinitionKey: 'approval'
-   * });
-   * ```
+   *
    */
   bpm: BpmClientAPI;
 
@@ -326,16 +180,7 @@ export interface AmasterClient {
    * Provides methods for executing Dify-style workflows.
    * 
    * For detailed documentation, see {@link ./workflow.d.ts}
-   * 
-   * @example
-   * Run a workflow:
-   * ```typescript
-   * const result = await client.workflow.run('data-analysis', {
-   *   input_data: 'sample data',
-   *   options: { format: 'json' }
-   * });
-   * console.log(result.data.outputs);
-   * ```
+   *
    */
   workflow: WorkflowClientAPI;
 
@@ -346,7 +191,7 @@ export interface AmasterClient {
    * 
    * For detailed documentation, see {@link ./asr.d.ts}
    */
-  asr: ASRClient;
+  asr: ASRClientAPI;
 
   /**
    * Copilot AI Assistant module
@@ -354,20 +199,9 @@ export interface AmasterClient {
    * Provides methods for interactive AI conversations with A2UI streaming.
    * 
    * For detailed documentation, see {@link ./copilot.d.ts}
-   * 
-   * @example
-   * Chat with AI:
-   * ```typescript
-   * const stream = client.copilot.chat([
-   *   { role: 'user', content: 'Hello' }
-   * ]);
-   * 
-   * for await (const messages of stream) {
-   *   // Process A2UI messages
-   * }
-   * ```
+   *
    */
-  copilot: CopilotA2UIClient;
+  copilot: CopilotClientAPI;
 
   /**
    * Serverless Function module
@@ -376,7 +210,7 @@ export interface AmasterClient {
    * 
    * For detailed documentation, see {@link ./function.d.ts}
    */
-  function: FunctionClient;
+  function: FunctionClientAPI;
 
   /**
    * TTS (Text-to-Speech) module
@@ -385,21 +219,22 @@ export interface AmasterClient {
    * 
    * For detailed documentation, see {@link ./tts.d.ts}
    */
-  tts: TTSClient;
+  tts: TTSClientAPI;
+
+  /**
+   * S3 Storage module
+   * 
+   * Provides methods for file upload, download, and management.
+   * 
+   * For detailed documentation, see {@link ./s3.d.ts}
+   */
+  s3: S3ClientAPI;
 
   /**
    * Check if the user is currently authenticated
    * 
    * @returns `true` if a valid access token exists, `false` otherwise
-   * 
-   * @example
-   * ```typescript
-   * if (client.isAuthenticated()) {
-   *   console.log('User is logged in');
-   * } else {
-   *   console.log('Please log in');
-   * }
-   * ```
+   *
    */
   isAuthenticated(): boolean;
 
@@ -407,23 +242,7 @@ export interface AmasterClient {
    * Get the current access token
    * 
    * @returns The access token string, or `null` if not authenticated
-   * 
-   * @example
-   * ```typescript
-   * const token = client.getAccessToken();
-   * if (token) {
-   *   console.log('Token:', token);
-   * }
-   * ```
-   * 
-   * @example
-   * Store token for later use:
-   * ```typescript
-   * const token = client.getAccessToken();
-   * if (token) {
-   *   localStorage.setItem('backup_token', token);
-   * }
-   * ```
+   *
    */
   getAccessToken(): string | null;
 
@@ -434,25 +253,7 @@ export interface AmasterClient {
    * After setting the token, all requests will use it automatically.
    * 
    * @param token - The JWT access token to set
-   * 
-   * @example
-   * Set token from OAuth:
-   * ```typescript
-   * const ssoToken = await getSSOToken();
-   * client.setAccessToken(ssoToken);
-   * 
-   * // Now all requests will use this token
-   * await client.entity.list('default', 'users');
-   * ```
-   * 
-   * @example
-   * Restore token from storage:
-   * ```typescript
-   * const savedToken = localStorage.getItem('auth_token');
-   * if (savedToken) {
-   *   client.setAccessToken(savedToken);
-   * }
-   * ```
+   *
    */
   setAccessToken(token: string): void;
 
@@ -466,21 +267,7 @@ export interface AmasterClient {
    * 
    * After calling this, `isAuthenticated()` will return `false`
    * and all requests will be unauthenticated.
-   * 
-   * @example
-   * ```typescript
-   * client.clearAuth();
-   * console.log(client.isAuthenticated()); // false
-   * console.log(client.getAccessToken());  // null
-   * ```
-   * 
-   * @example
-   * Logout without API call:
-   * ```typescript
-   * // If you want to clear local state without calling logout API
-   * client.clearAuth();
-   * window.location.href = '/login';
-   * ```
+   *
    */
   clearAuth(): void;
 }
@@ -493,45 +280,7 @@ export interface AmasterClient {
  * 
  * @param options - Configuration options for the client
  * @returns A configured Amaster client instance
- * 
- * @example
- * Basic usage:
- * ```typescript
- * import { createClient } from '@amaster.ai/client';
- * 
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai'
- * });
- * 
- * await client.auth.login({ email, password });
- * ```
- * 
- * @example
- * With callbacks:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   onUnauthorized: () => {
- *     console.log('Session expired');
- *     window.location.href = '/login';
- *   },
- *   onTokenExpired: () => {
- *     console.log('Token expired, refreshing...');
- *   }
- * });
- * ```
- * 
- * @example
- * With custom headers:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   headers: {
- *     'X-Tenant-ID': 'tenant-123',
- *     'X-App-Version': '1.0.0'
- *   }
- * });
- * ```
+ *
  */
 export declare function createClient(options: AmasterClientOptions): AmasterClient;
 
@@ -543,10 +292,11 @@ export type { AuthClientAPI } from './auth';
 export type { EntityClientAPI } from './entity';
 export type { BpmClientAPI } from './bpm';
 export type { WorkflowClientAPI } from './workflow';
-export type { ASRClient } from './asr';
-export type { CopilotA2UIClient } from './copilot';
-export type { FunctionClient } from './function';
-export type { TTSClient } from './tts';
+export type { ASRClientAPI } from './asr';
+export type { CopilotClientAPI } from './copilot';
+export type { FunctionClientAPI } from './function';
+export type { TTSClientAPI } from './tts';
+export type { S3ClientAPI } from './s3';
 
 // For detailed types, import directly from submodules:
 // import type { LoginParams, User } from '@amaster.ai/client/auth'