@amaster.ai/client 1.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amaster Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,463 @@
+# @amaster.ai/client
+
+> Unified API client for the Amaster platform - Supabase-style developer experience
+
+[![npm version](https://img.shields.io/npm/v/@amaster.ai/client.svg)](https://www.npmjs.com/package/@amaster.ai/client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## 🤖 AI-Friendly Documentation
+
+This package is designed with AI tools (GitHub Copilot, Cursor, etc.) in mind:
+
+- **Modular Type Definitions**: API documentation split into focused modules
+- **Rich JSDoc**: Every method includes detailed descriptions and examples
+- **On-Demand Loading**: AI tools only load relevant type files when needed
+- **Type-Driven Learning**: Full TypeScript support helps AI understand API patterns
+
+### Type Documentation Structure
+
+```
+types/
+  ├── index.d.ts      # Main entry (lightweight)
+  ├── auth.d.ts       # Authentication API (login, register, etc.)
+  ├── entity.d.ts     # Entity CRUD operations
+  ├── bpm.d.ts        # Business Process Management
+  └── workflow.d.ts   # Workflow execution
+```
+
+Each module contains:
+- Complete method signatures
+- Parameter descriptions
+- Return type definitions
+- Multiple usage examples
+- Best practices
+
+## 🚀 Overview
+
+`@amaster.ai/client` is a unified JavaScript/TypeScript client that provides a simple, consistent interface to all Amaster platform services. Inspired by Supabase's elegant API design, it offers:
+
+✨ **Single client instance** for all services  
+🔐 **Automatic authentication** - tokens attached to all requests  
+🔄 **Token auto-refresh** - never worry about expiration  
+📦 **Type-safe** - Full TypeScript support with auto-completion  
+🎯 **Simple API** - Clean, consistent method naming  
+
+## 📦 Installation
+
+```bash
+# npm
+npm install @amaster.ai/client axios
+
+# pnpm
+pnpm add @amaster.ai/client axios
+
+# yarn
+yarn add @amaster.ai/client axios
+```
+
+## 🎯 Quick Start
+
+```typescript
+import { createClient } from '@amaster.ai/client';
+
+// 1. Create client instance
+const client = createClient({
+  baseURL: 'https://api.amaster.ai',
+  onUnauthorized: () => {
+    // Handle unauthorized (redirect to login, show modal, etc.)
+    window.location.href = '/login';
+  }
+});
+
+// 2. Login
+await client.auth.login({
+  email: 'user@example.com',
+  password: 'password123'
+});
+
+// 3. Use any service - auth token is automatically attached!
+const users = await client.entity.list('default', 'users');
+const tasks = await client.bpm.getMyTasks();
+const result = await client.workflow.execute('my-workflow', { input: {} });
+```
+
+## 🔑 Authentication
+
+### Login
+
+```typescript
+// Email/Password login
+const result = await client.auth.login({
+  email: 'user@example.com',
+  password: 'password123'
+});
+
+if (result.success) {
+  console.log('Logged in:', result.data.user);
+}
+```
+
+### Register
+
+```typescript
+const result = await client.auth.register({
+  username: 'johndoe',
+  email: 'john@example.com',
+  password: 'securePassword123'
+});
+```
+
+### Get Current User
+
+```typescript
+const result = await client.auth.getMe();
+if (result.success) {
+  console.log('Current user:', result.data);
+}
+```
+
+### Logout
+
+```typescript
+await client.auth.logout();
+```
+
+### Check Authentication Status
+
+```typescript
+if (client.isAuthenticated()) {
+  console.log('User is logged in');
+}
+```
+
+## 📊 Entity Operations (CRUD)
+
+Full CRUD operations for your data entities with type safety.
+
+### List Entities
+
+```typescript
+const result = await client.entity.list('default', 'users', {
+  page: 1,
+  perPage: 20,
+  orderBy: 'createdAt',
+  orderDir: 'desc',
+  // Filters
+  'status[eq]': 'active',
+  'age[gt]': 18
+});
+
+if (result.success) {
+  const { items, total, page, perPage } = result.data;
+  console.log(`Found ${total} users`);
+}
+```
+
+### Get Single Entity
+
+```typescript
+const result = await client.entity.get('default', 'users', 123);
+if (result.success) {
+  console.log('User:', result.data);
+}
+```
+
+### Create Entity
+
+```typescript
+const result = await client.entity.create('default', 'users', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  status: 'active'
+});
+```
+
+### Update Entity
+
+```typescript
+const result = await client.entity.update('default', 'users', 123, {
+  name: 'Jane Doe',
+  status: 'inactive'
+});
+```
+
+### Delete Entity
+
+```typescript
+await client.entity.delete('default', 'users', 123);
+```
+
+### Bulk Operations
+
+```typescript
+// Bulk update
+await client.entity.bulkUpdate('default', 'users', [
+  { id: 1, status: 'active' },
+  { id: 2, status: 'inactive' }
+]);
+
+// Bulk delete
+await client.entity.bulkDelete('default', 'users', [1, 2, 3]);
+```
+
+## 🔄 BPM (Business Process Management)
+
+Manage business processes powered by Camunda 7.
+
+### Start a Process
+
+```typescript
+const result = await client.bpm.startProcess({
+  processKey: 'approval-process',
+  businessKey: 'ORDER-12345',
+  variables: {
+    amount: 1000,
+    requester: 'john@example.com'
+  }
+});
+```
+
+### Get My Tasks
+
+```typescript
+const result = await client.bpm.getMyTasks({
+  page: 1,
+  perPage: 20,
+  sortBy: 'created',
+  sortOrder: 'desc'
+});
+
+if (result.success) {
+  console.log('Tasks:', result.data.items);
+}
+```
+
+### Complete a Task
+
+```typescript
+await client.bpm.completeTask('task-id', {
+  approved: true,
+  comments: 'Looks good!'
+});
+```
+
+### Claim a Task
+
+```typescript
+await client.bpm.claimTask('task-id');
+```
+
+## ⚡ Workflow Execution
+
+Execute workflows and automation flows.
+
+```typescript
+const result = await client.workflow.execute('data-processing-workflow', {
+  input: {
+    dataSource: 'users',
+    filters: { status: 'active' }
+  }
+});
+
+if (result.success) {
+  console.log('Workflow result:', result.data);
+}
+```
+
+## ⚙️ Configuration
+
+### Client Options
+
+```typescript
+interface AmasterClientOptions {
+  /** Base URL for the Amaster API */
+  baseURL: string;
+
+  /** Optional custom headers */
+  headers?: Record<string, string>;
+
+  /** Called when receiving 401 Unauthorized */
+  onUnauthorized?: () => void;
+
+  /** Called when token expires (before auto-refresh) */
+  onTokenExpired?: () => void;
+
+  /** Enable automatic token refresh (default: true) */
+  autoRefresh?: boolean;
+
+  /** Refresh threshold in seconds (default: 300) */
+  refreshThreshold?: number;
+}
+```
+
+### Example with All Options
+
+```typescript
+const client = createClient({
+  baseURL: 'https://api.amaster.ai',
+  
+  headers: {
+    'X-App-Version': '1.0.0'
+  },
+  
+  onUnauthorized: () => {
+    console.log('Session expired, redirecting to login...');
+    window.location.href = '/login';
+  },
+  
+  onTokenExpired: () => {
+    console.log('Token expired, will auto-refresh');
+  },
+  
+  autoRefresh: true,
+  refreshThreshold: 300 // Refresh 5 minutes before expiry
+});
+```
+
+## 🔧 Advanced Usage
+
+### Manual Token Management
+
+```typescript
+// Get current access token
+const token = client.getAccessToken();
+
+// Set token manually (useful for SSR or external auth)
+client.setAccessToken('your-jwt-token');
+
+// Clear all auth data
+client.clearAuth();
+```
+
+### Error Handling
+
+```typescript
+const result = await client.entity.list('default', 'users');
+
+if (result.success) {
+  // Success case
+  console.log('Data:', result.data);
+} else {
+  // Error case
+  console.error('Error:', result.error);
+  console.error('Status:', result.statusCode);
+}
+```
+
+## 🎨 Comparison with Individual Clients
+
+### Before (Using separate clients)
+
+```typescript
+import { createAuthClient } from '@amaster.ai/auth-client';
+import { createEntityClient } from '@amaster.ai/entity-client';
+import { createBpmClient } from '@amaster.ai/bpm-client';
+
+const authClient = createAuthClient({ baseURL });
+const entityClient = createEntityClient({ baseURL });
+const bpmClient = createBpmClient({ baseURL });
+
+// Need to manage tokens manually across clients
+await authClient.login({ email, password });
+const token = authClient.getAccessToken();
+
+// Pass token to other clients somehow...
+```
+
+### After (Using unified client)
+
+```typescript
+import { createClient } from '@amaster.ai/client';
+
+const client = createClient({ baseURL });
+
+// One client, automatic token management
+await client.auth.login({ email, password });
+await client.entity.list('default', 'users'); // Token automatically attached
+await client.bpm.getMyTasks(); // Token automatically attached
+```
+
+## 📖 API Reference
+
+### `client.auth`
+
+Full authentication API from `@amaster.ai/auth-client`:
+
+- `login(params)` - Email/password or code-based login
+- `register(params)` - User registration
+- `logout()` - User logout
+- `getMe()` - Get current user profile
+- `updateMe(params)` - Update current user
+- `changePassword(params)` - Change password
+- `refreshToken()` - Manually refresh token
+- `sendCode(params)` - Send verification code
+- `hasPermission(permission)` - Check user permission
+- `hasRole(role)` - Check user role
+
+### `client.entity`
+
+Full CRUD API from `@amaster.ai/entity-client`:
+
+- `list(source, entity, params?)` - List entities with pagination
+- `get(source, entity, id)` - Get single entity
+- `create(source, entity, data)` - Create new entity
+- `update(source, entity, id, data)` - Update entity
+- `delete(source, entity, id)` - Delete entity
+- `bulkUpdate(source, entity, items)` - Bulk update
+- `bulkDelete(source, entity, ids)` - Bulk delete
+- `options(source, entity, fields?)` - Get field options
+
+### `client.bpm`
+
+Full BPM API from `@amaster.ai/bpm-client`:
+
+- `startProcess(params)` - Start process instance
+- `getMyTasks(params?)` - Get current user's tasks
+- `completeTask(taskId, variables?)` - Complete a task
+- `claimTask(taskId)` - Claim a task
+- `unclaimTask(taskId)` - Unclaim a task
+- And more...
+
+### `client.workflow`
+
+Workflow execution API from `@amaster.ai/workflow-client`:
+
+- `execute(workflowId, params)` - Execute a workflow
+- `getStatus(executionId)` - Get execution status
+- And more...
+
+## 🔐 Token Management Flow
+
+```
+1. Login → Token stored automatically
+2. Request → Token attached to headers
+3. Response 401 → onUnauthorized() called
+4. Token near expiry → Auto-refresh (if enabled)
+5. Logout → Token cleared
+```
+
+## 🌐 Environment Support
+
+Works in:
+
+- ✅ Browser (modern)
+- ✅ Node.js (18+)
+- ✅ React / Vue / Angular
+- ✅ Next.js / Nuxt
+- ✅ React Native (with axios)
+
+## 📄 License
+
+MIT © Amaster Team
+
+## 🤝 Related Packages
+
+- `@amaster.ai/auth-client` - Authentication client
+- `@amaster.ai/entity-client` - Entity CRUD client
+- `@amaster.ai/bpm-client` - BPM client
+- `@amaster.ai/workflow-client` - Workflow client
+- `@amaster.ai/http-client` - HTTP client foundation
+
+## 💡 Inspiration
+
+API design inspired by [Supabase](https://supabase.com) - aiming for the same level of developer experience and simplicity.

package/dist/index.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+var authClient = require('@amaster.ai/auth-client');
+var entityClient = require('@amaster.ai/entity-client');
+var bpmClient = require('@amaster.ai/bpm-client');
+var workflowClient = require('@amaster.ai/workflow-client');
+var httpClient = require('@amaster.ai/http-client');
+
+// src/client.ts
+function createClient(options) {
+  const { baseURL, headers = {}, onUnauthorized, onTokenExpired } = options;
+  const baseHttpClient = httpClient.createHttpClient({
+    baseURL,
+    headers
+  });
+  const auth = authClient.createAuthClient({
+    baseURL,
+    headers,
+    onTokenExpired,
+    onUnauthorized
+  });
+  const createAuthenticatedHttpClient = () => {
+    return {
+      async request(config) {
+        const token = auth.getAccessToken();
+        const authHeaders = token ? { Authorization: `Bearer ${token}` } : {};
+        const mergedConfig = {
+          ...config,
+          headers: {
+            ...config.headers,
+            ...authHeaders
+          }
+        };
+        const result = await baseHttpClient.request(mergedConfig);
+        if (result.status === 401 && onUnauthorized) {
+          onUnauthorized();
+        }
+        return result;
+      }
+    };
+  };
+  const authenticatedHttpClient = createAuthenticatedHttpClient();
+  const entity = entityClient.createEntityClient(authenticatedHttpClient);
+  const bpm = bpmClient.createBpmClient(authenticatedHttpClient);
+  const workflow = workflowClient.createWorkflowClient(authenticatedHttpClient);
+  const client = {
+    auth,
+    entity,
+    bpm,
+    workflow,
+    // Expose token management methods from auth client
+    isAuthenticated: () => auth.isAuthenticated(),
+    getAccessToken: () => auth.getAccessToken(),
+    setAccessToken: (token) => auth.setAccessToken(token),
+    clearAuth: () => auth.clearAuth()
+  };
+  return client;
+}
+
+exports.createClient = createClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"names":["createHttpClient","createAuthClient","createEntityClient","createBpmClient","createWorkflowClient"],"mappings":";;;;;;;;;AAiFO,SAAS,aAAa,OAAA,EAA8C;AACzE,EAAA,MAAM,EAAE,OAAA,EAAS,OAAA,GAAU,EAAC,EAAG,cAAA,EAAgB,gBAAe,GAAI,OAAA;AAGlE,EAAA,MAAM,iBAAiBA,2BAAA,CAAiB;AAAA,IACtC,OAAA;AAAA,IACA;AAAA,GACD,CAAA;AAGD,EAAA,MAAM,OAAmBC,2BAAA,CAAiB;AAAA,IACxC,OAAA;AAAA,IACA,OAAA;AAAA,IACA,cAAA;AAAA,IACA;AAAA,GACD,CAAA;AAGD,EAAA,MAAM,gCAAgC,MAAkB;AACtD,IAAA,OAAO;AAAA,MACL,MAAM,QAAW,MAAA,EAAiD;AAEhE,QAAA,MAAM,KAAA,GAAQ,KAAK,cAAA,EAAe;AAGlC,QAAA,MAAM,WAAA,GAAc,QAAQ,EAAE,aAAA,EAAe,UAAU,KAAK,CAAA,CAAA,KAAO,EAAC;AACpE,QAAA,MAAM,YAAA,GAA8B;AAAA,UAClC,GAAG,MAAA;AAAA,UACH,OAAA,EAAS;AAAA,YACP,GAAG,MAAA,CAAO,OAAA;AAAA,YACV,GAAG;AAAA;AACL,SACF;AAGA,QAAA,MAAM,MAAA,GAAS,MAAM,cAAA,CAAe,OAAA,CAAW,YAAY,CAAA;AAG3D,QAAA,IAAI,MAAA,CAAO,MAAA,KAAW,GAAA,IAAO,cAAA,EAAgB;AAC3C,UAAA,cAAA,EAAe;AAAA,QACjB;AAEA,QAAA,OAAO,MAAA;AAAA,MACT;AAAA,KACF;AAAA,EACF,CAAA;AAGA,EAAA,MAAM,0BAA0B,6BAAA,EAA8B;AAG9D,EAAA,MAAM,MAAA,GAAuBC,gCAAmB,uBAAuB,CAAA;AACvE,EAAA,MAAM,GAAA,GAAiBC,0BAAgB,uBAAuB,CAAA;AAC9D,EAAA,MAAM,QAAA,GAA2BC,oCAAqB,uBAAuB,CAAA;AAG7E,EAAA,MAAM,MAAA,GAAwB;AAAA,IAC5B,IAAA;AAAA,IACA,MAAA;AAAA,IACA,GAAA;AAAA,IACA,QAAA;AAAA;AAAA,IAGA,eAAA,EAAiB,MAAM,IAAA,CAAK,eAAA,EAAgB;AAAA,IAC5C,cAAA,EAAgB,MAAM,IAAA,CAAK,cAAA,EAAe;AAAA,IAC1C,cAAA,EAAgB,CAAC,KAAA,KAAkB,IAAA,CAAK,eAAe,KAAK,CAAA;AAAA,IAC5D,SAAA,EAAW,MAAM,IAAA,CAAK,SAAA;AAAU,GAClC;AAEA,EAAA,OAAO,MAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * ============================================================================\n * @amaster.ai/client - Unified Amaster Client\n * ============================================================================\n * \n * Supabase-inspired unified API client for the Amaster platform\n * \n * Features:\n * - Single client instance for all services (auth, entity, bpm, workflow)\n * - Automatic token management and refresh\n * - Auto-attach authentication to all requests\n * - Centralized error handling\n * \n * @example\n * ```typescript\n * const client = createClient({\n *   baseURL: 'https://api.amaster.ai',\n *   onUnauthorized: () => window.location.href = '/login'\n * });\n * \n * // Login\n * await client.auth.login({ email, password });\n * \n * // All subsequent requests automatically include auth token\n * await client.entity.list('default', 'users');\n * await client.bpm.startProcess({ processKey: 'approval' });\n * ```\n */\n\nimport { createAuthClient, type AuthClient } from \"@amaster.ai/auth-client\";\nimport { createEntityClient, type EntityClient } from \"@amaster.ai/entity-client\";\nimport { createBpmClient, type BpmClient } from \"@amaster.ai/bpm-client\";\nimport { createWorkflowClient, type WorkflowClient } from \"@amaster.ai/workflow-client\";\nimport { createHttpClient, type HttpClient, type RequestConfig, type ClientResult } from \"@amaster.ai/http-client\";\nimport type { AmasterClient, AmasterClientOptions } from \"./types\";\n\n/**\n * Create a unified Amaster client instance\n * \n * This function creates a single client that provides access to all Amaster services:\n * - Authentication (login, register, logout)\n * - Entity CRUD operations\n * - BPM (Business Process Management)\n * - Workflow execution\n * \n * All sub-clients automatically share the same HTTP client and authentication state,\n * ensuring that tokens are consistently attached to all requests.\n * \n * @param options - Client configuration options\n * @returns A unified Amaster client instance\n * \n * @example\n * ```typescript\n * // Basic usage\n * const client = createClient({\n *   baseURL: 'https://api.amaster.ai'\n * });\n * \n * // With authentication callbacks\n * const client = createClient({\n *   baseURL: 'https://api.amaster.ai',\n *   onUnauthorized: () => {\n *     // Redirect to login or show auth modal\n *     window.location.href = '/login';\n *   },\n *   onTokenExpired: () => {\n *     console.log('Token expired, refreshing...');\n *   }\n * });\n * \n * // Login\n * await client.auth.login({\n *   email: 'user@example.com',\n *   password: 'password123'\n * });\n * \n * // Now all requests automatically include the auth token\n * const users = await client.entity.list('default', 'users');\n * const tasks = await client.bpm.getMyTasks();\n * ```\n */\nexport function createClient(options: AmasterClientOptions): AmasterClient {\n  const { baseURL, headers = {}, onUnauthorized, onTokenExpired } = options;\n\n  // Create the base HTTP client\n  const baseHttpClient = createHttpClient({\n    baseURL,\n    headers,\n  });\n\n  // Create the auth client first (it manages its own HTTP client internally)\n  const auth: AuthClient = createAuthClient({\n    baseURL,\n    headers,\n    onTokenExpired,\n    onUnauthorized,\n  });\n\n  // Create a wrapper HTTP client that automatically adds the auth token\n  const createAuthenticatedHttpClient = (): HttpClient => {\n    return {\n      async request<T>(config: RequestConfig): Promise<ClientResult<T>> {\n        // Get the current token from auth client\n        const token = auth.getAccessToken();\n        \n        // Merge Authorization header with existing headers\n        const authHeaders = token ? { Authorization: `Bearer ${token}` } : {};\n        const mergedConfig: RequestConfig = {\n          ...config,\n          headers: {\n            ...config.headers,\n            ...authHeaders,\n          },\n        };\n\n        // Make the request with the updated config\n        const result = await baseHttpClient.request<T>(mergedConfig);\n\n        // Handle 401 errors\n        if (result.status === 401 && onUnauthorized) {\n          onUnauthorized();\n        }\n\n        return result;\n      },\n    };\n  };\n\n  // Create the authenticated HTTP client\n  const authenticatedHttpClient = createAuthenticatedHttpClient();\n\n  // Create other clients using the authenticated HTTP client\n  const entity: EntityClient = createEntityClient(authenticatedHttpClient);\n  const bpm: BpmClient = createBpmClient(authenticatedHttpClient);\n  const workflow: WorkflowClient = createWorkflowClient(authenticatedHttpClient);\n\n  // Return unified client interface\n  const client: AmasterClient = {\n    auth,\n    entity,\n    bpm,\n    workflow,\n\n    // Expose token management methods from auth client\n    isAuthenticated: () => auth.isAuthenticated(),\n    getAccessToken: () => auth.getAccessToken(),\n    setAccessToken: (token: string) => auth.setAccessToken(token),\n    clearAuth: () => auth.clearAuth(),\n  };\n\n  return client;\n}\n"]}