@amaster.ai/client 1.1.0-beta.0

package/types/index.d.ts

@@ -0,0 +1,487 @@
+/**
+ * ============================================================================
+ * @amaster.ai/client - Unified API Client
+ * ============================================================================
+ * 
+ * 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.d.ts}
+ * - **Entity Operations**: {@link ./entity.d.ts}
+ * - **BPM (Business Process)**: {@link ./bpm.d.ts}
+ * - **Workflow Execution**: {@link ./workflow.d.ts}
+ * 
+ * @packageDocumentation
+ */
+
+import type { AuthClientAPI } from './auth';
+import type { EntityClientAPI } from './entity';
+import type { BpmClientAPI } from './bpm';
+import type { WorkflowClientAPI } from './workflow';
+
+/**
+ * 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;
+
+  /**
+   * 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.
+   * 
+   * @example
+   * ```typescript
+   * {
+   *   'X-Tenant-ID': 'tenant-123',
+   *   'X-App-Version': '1.0.0',
+   *   'X-Custom-Header': 'custom-value'
+   * }
+   * ```
+   */
+  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.
+   * 
+   * @example
+   * Redirect to login page:
+   * ```typescript
+   * onUnauthorized: () => {
+   *   window.location.href = '/login';
+   * }
+   * ```
+   * 
+   * @example
+   * Show modal:
+   * ```typescript
+   * onUnauthorized: () => {
+   *   showLoginModal();
+   * }
+   * ```
+   */
+  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.
+   * 
+   * @example
+   * ```typescript
+   * onTokenExpired: () => {
+   *   console.log('Token expired, auto-refreshing...');
+   *   analytics.track('token_expired');
+   * }
+   * ```
+   */
+  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;
+}
+
+/**
+ * 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
+ * 
+ * @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 {
+  /**
+   * Authentication module
+   * 
+   * 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;
+
+  /**
+   * Entity CRUD operations module
+   * 
+   * 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;
+
+  /**
+   * Business Process Management (BPM) module
+   * 
+   * 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;
+
+  /**
+   * Workflow execution module
+   * 
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * 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
+   * 
+   * @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;
+
+  /**
+   * 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.
+   * 
+   * @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;
+}
+
+/**
+ * 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
+ * 
+ * @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;
+
+// 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';
+
+// 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'