@amaster.ai/client 1.1.0-beta.7 → 1.1.0-beta.71

package/types/entity.d.ts

@@ -1,32 +1,4 @@
 /**
- * ============================================================================
- * Entity Module - Type Definitions
- * ============================================================================
- * 
- * This module provides CRUD operations for entities in the Amaster platform.
- * 
- * ## Key Features
- * - List entities with pagination, sorting, and filtering
- * - Get single entity by ID
- * - Create, update, and delete entities
- * - Advanced filtering with AND/OR conditions
- * - Full-text search across multiple fields
- * - Relation loading (eager loading)
- * - Field selection (only fetch specific fields)
- * - Bulk operations
- * 
- * ## Filter Operators
- * - `eq` (default): Equal
- * - `ne`: Not equal
- * - `gt`: Greater than
- * - `ge`: Greater or equal
- * - `lt`: Less than
- * - `le`: Less or equal
- * - `like`: Fuzzy match (auto wraps with %)
- * - `sw`: Starts with
- * - `ew`: Ends with
- * - `bt`: Between (requires {from, to})
- * - `in`: In array
  * 
  * @module entity
  */
@@ -39,16 +11,7 @@ import type { ClientResult } from './common';
  * Simple filter operators for query string format
  * 
  * Usage: `{ 'field[op]': value }`
- * 
- * @example
- * ```typescript
- * {
- *   'status[eq]': 'active',
- *   'price[gt]': 100,
- *   'name[like]': 'test',
- *   'id[in]': [1, 2, 3]
- * }
- * ```
+ *
  */
 export type FilterOperator =
   | 'eq'    // Equal (default if no operator specified)
@@ -65,15 +28,7 @@ export type FilterOperator =
 
 /**
  * Advanced filter operators for condition builder
- * 
- * @example
- * ```typescript
- * {
- *   op: 'equal',
- *   left: { field: 'status' },
- *   right: 'active'
- * }
- * ```
+ *
  */
 export type AdvancedFilterOperator =
   | 'equal'
@@ -94,26 +49,7 @@ export type AdvancedFilterOperator =
 
 /**
  * Advanced filter item (single condition)
- * 
- * @example
- * Single condition:
- * ```typescript
- * {
- *   op: 'equal',
- *   left: { field: 'status' },
- *   right: 'active'
- * }
- * ```
- * 
- * @example
- * Relation field:
- * ```typescript
- * {
- *   op: 'equal',
- *   left: { field: 'user.email' },
- *   right: 'test@example.com'
- * }
- * ```
+ *
  */
 export interface FilterItem {
   op: AdvancedFilterOperator;
@@ -126,35 +62,7 @@ export interface FilterItem {
 
 /**
  * Advanced filter group (supports AND/OR with nesting)
- * 
- * @example
- * (status = 'active') AND (priority > 5 OR assignee IS NOT NULL):
- * ```typescript
- * {
- *   conjunction: 'and',
- *   children: [
- *     {
- *       op: 'equal',
- *       left: { field: 'status' },
- *       right: 'active'
- *     },
- *     {
- *       conjunction: 'or',
- *       children: [
- *         {
- *           op: 'greater',
- *           left: { field: 'priority' },
- *           right: 5
- *         },
- *         {
- *           op: 'is_not_empty',
- *           left: { field: 'assignee' }
- *         }
- *       ]
- *     }
- *   ]
- * }
- * ```
+ *
  */
 export interface FilterGroup {
   conjunction: 'and' | 'or';
@@ -163,15 +71,7 @@ export interface FilterGroup {
 
 /**
  * Keywords search configuration
- * 
- * @example
- * Search in specific fields:
- * ```typescript
- * {
- *   fields: ['name', 'description'],
- *   value: 'search term'
- * }
- * ```
+ *
  */
 export interface KeywordsSearch {
   /** Fields to search in */
@@ -182,16 +82,7 @@ export interface KeywordsSearch {
 
 /**
  * Between filter value
- * 
- * @example
- * ```typescript
- * {
- *   'created_at[bt]': {
- *     from: '2024-01-01',
- *     to: '2024-12-31'
- *   }
- * }
- * ```
+ *
  */
 export interface BetweenValue {
   from?: string | number | Date;
@@ -204,67 +95,7 @@ export interface BetweenValue {
  * Entity query parameters
  * 
  * Supports pagination, sorting, filtering, searching, and relation loading.
- * 
- * @example
- * Basic pagination and sorting:
- * ```typescript
- * {
- *   page: 1,
- *   perPage: 20,
- *   orderBy: 'created_at',
- *   orderDir: 'desc'
- * }
- * ```
- * 
- * @example
- * Simple field filter:
- * ```typescript
- * {
- *   status: 'active',
- *   'price[gt]': 100,
- *   'name[like]': 'test'
- * }
- * ```
- * 
- * @example
- * Keywords search:
- * ```typescript
- * {
- *   __keywords: {
- *     fields: ['name', 'description'],
- *     value: 'search term'
- *   }
- * }
- * ```
- * 
- * @example
- * Load relations and select fields:
- * ```typescript
- * {
- *   __relations: ['user', 'category'],
- *   __fields: ['id', 'name', 'status', 'user.email']
- * }
- * ```
- * 
- * @example
- * Advanced filter with AND/OR:
- * ```typescript
- * {
- *   __filter: {
- *     conjunction: 'and',
- *     children: [
- *       { op: 'equal', left: { field: 'status' }, right: 'active' },
- *       {
- *         conjunction: 'or',
- *         children: [
- *           { op: 'greater', left: { field: 'priority' }, right: 5 },
- *           { op: 'is_not_empty', left: { field: 'assignee' } }
- *         ]
- *       }
- *     ]
- *   }
- * }
- * ```
+ *
  */
 export interface EntityQueryParams {
   // ==================== Pagination ====================
@@ -295,7 +126,6 @@ export interface EntityQueryParams {
   
   /** 
    * Field to sort by
-   * @example 'created_at'
    */
   orderBy?: string;
   
@@ -308,7 +138,6 @@ export interface EntityQueryParams {
   /** 
    * Multiple sort orders (comma-separated)
    * Format: "field1:asc,field2:desc"
-   * @example 'priority:desc,created_at:asc'
    */
   __orders?: string;
 
@@ -318,9 +147,7 @@ export interface EntityQueryParams {
    * Keywords search
    * - String: search all searchable fields (backend determines)
    * - Object: search specific fields
-   * 
-   * @example '__keywords=search'
-   * @example { __keywords: { fields: ['name', 'description'], value: 'keyword' } }
+   *
    */
   __keywords?: string | KeywordsSearch;
 
@@ -328,13 +155,11 @@ export interface EntityQueryParams {
   
   /** 
    * Relations to load (eager loading)
-   * @example ['user', 'category', 'tags']
    */
   __relations?: string[];
 
   /** 
    * Fields to select (only return these fields)
-   * @example ['id', 'name', 'status', 'user.email']
    */
   __fields?: string[];
 
@@ -342,13 +167,11 @@ export interface EntityQueryParams {
   
   /** 
    * Advanced filter (condition builder with AND/OR)
-   * @example { conjunction: 'and', children: [...] }
    */
   __filter?: FilterGroup;
 
   /** 
    * Simple filters using field=value or field[op]=value
-   * @example { status: 'active', 'price[gt]': 100 }
    */
   [key: string]: unknown;
 }
@@ -359,19 +182,7 @@ export interface EntityQueryParams {
  * Entity list response
  * 
  * @template T - The entity type
- * 
- * @example
- * ```typescript
- * interface User {
- *   id: number;
- *   name: string;
- *   email: string;
- * }
- * 
- * const result = await client.entity.list<User>('default', 'users');
- * const users: User[] = result.data.items;
- * const total: number = result.data.total;
- * ```
+ *
  */
 export interface EntityListResponse<T = Record<string, unknown>> {
   /** Array of entities */
@@ -391,36 +202,7 @@ export interface EntityListResponse<T = Record<string, unknown>> {
  * 
  * Provides methods for creating, reading, updating, and deleting entities.
  * 
- * @example
- * Complete CRUD operations:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // 1. List entities
- * const list = await client.entity.list('default', 'users', {
- *   page: 1,
- *   perPage: 20,
- *   orderBy: 'createdAt',
- *   orderDir: 'desc'
- * });
- * 
- * // 2. Get single entity
- * const user = await client.entity.get('default', 'users', 1);
- * 
- * // 3. Create entity
- * const newUser = await client.entity.create('default', 'users', {
- *   name: 'John Doe',
- *   email: 'john@example.com'
- * });
- * 
- * // 4. Update entity
- * const updated = await client.entity.update('default', 'users', 1, {
- *   name: 'Jane Doe'
- * });
- * 
- * // 5. Delete entity
- * await client.entity.delete('default', 'users', 1);
- * ```
+ * @since 1.0.0
  */
 export interface EntityClientAPI {
   /**
@@ -433,53 +215,39 @@ export interface EntityClientAPI {
    * @returns List of entities with pagination info
    * 
    * @example
-   * Basic list:
-   * ```typescript
+   * // Basic usage
    * const result = await client.entity.list('default', 'users');
-   * console.log(result.data.items); // User array
-   * console.log(result.data.total); // Total count
-   * ```
+   * console.log('Users:', result.data.items);
    * 
    * @example
-   * With pagination and sorting:
-   * ```typescript
+   * // With pagination
    * const result = await client.entity.list('default', 'users', {
-   *   page: 2,
-   *   perPage: 50,
-   *   orderBy: 'createdAt',
-   *   orderDir: 'desc'
+   *   page: 1,
+   *   perPage: 20
    * });
-   * ```
    * 
    * @example
-   * With filtering:
-   * ```typescript
-   * const result = await client.entity.list('default', 'orders', {
-   *   status: 'pending',
-   *   'amount[gt]': 1000,
-   *   'created_at[bt]': { from: '2024-01-01', to: '2024-12-31' }
+   * // With filters and sorting
+   * const result = await client.entity.list('default', 'users', {
+   *   page: 1,
+   *   perPage: 20,
+   *   orderBy: 'createdAt',
+   *   orderDir: 'desc',
+   *   'status[eq]': 'active',
+   *   'age[gt]': 18
    * });
-   * ```
    * 
    * @example
-   * With full-text search:
-   * ```typescript
-   * const result = await client.entity.list('default', 'products', {
-   *   __keywords: {
-   *     fields: ['name', 'description'],
-   *     value: 'laptop'
-   *   }
-   * });
-   * ```
+   * // With type safety
+   * type User = { id: number; name: string; email: string };
+   * const result = await client.entity.list<User>('default', 'users');
+   * if (result.success) {
+   *   result.data.items.forEach(user => {
+   *     console.log(user.name); // Type-safe
+   *   });
+   * }
    * 
-   * @example
-   * With relations:
-   * ```typescript
-   * const result = await client.entity.list('default', 'orders', {
-   *   __relations: ['user', 'items'],
-   *   __fields: ['id', 'total', 'user.name', 'items.product']
-   * });
-   * ```
+   * @since 1.0.0
    */
   list<T = Record<string, unknown>>(
     source: string,
@@ -497,25 +265,17 @@ export interface EntityClientAPI {
    * @returns The entity data
    * 
    * @example
-   * ```typescript
    * const result = await client.entity.get('default', 'users', 123);
-   * if (result.data) {
+   * if (result.success) {
    *   console.log('User:', result.data);
    * }
-   * ```
    * 
    * @example
-   * With type safety:
-   * ```typescript
-   * interface User {
-   *   id: number;
-   *   name: string;
-   *   email: string;
-   * }
-   * 
+   * // With type safety
+   * type User = { id: number; name: string };
    * const result = await client.entity.get<User>('default', 'users', 123);
-   * const user: User = result.data;
-   * ```
+   * 
+   * @since 1.0.0
    */
   get<T = Record<string, unknown>>(
     source: string,
@@ -533,28 +293,17 @@ export interface EntityClientAPI {
    * @returns The created entity
    * 
    * @example
-   * ```typescript
    * const result = await client.entity.create('default', 'users', {
    *   name: 'John Doe',
    *   email: 'john@example.com',
-   *   role: 'user'
+   *   status: 'active'
    * });
    * 
-   * if (result.data) {
-   *   console.log('Created user ID:', result.data.id);
+   * if (result.success) {
+   *   console.log('Created user with ID:', result.data.id);
    * }
-   * ```
    * 
-   * @example
-   * With Date handling:
-   * ```typescript
-   * await client.entity.create('default', 'events', {
-   *   title: 'Meeting',
-   *   startTime: new Date('2026-02-07T10:00:00Z'),
-   *   endTime: new Date('2026-02-07T11:00:00Z')
-   * });
-   * // Dates are automatically converted to backend format
-   * ```
+   * @since 1.0.0
    */
   create<T = Record<string, unknown>>(
     source: string,
@@ -573,21 +322,16 @@ export interface EntityClientAPI {
    * @returns The updated entity
    * 
    * @example
-   * ```typescript
    * const result = await client.entity.update('default', 'users', 123, {
    *   name: 'Jane Doe',
-   *   email: 'jane@example.com'
+   *   status: 'inactive'
    * });
-   * ```
    * 
-   * @example
-   * Partial update:
-   * ```typescript
-   * // Only update the status field
-   * await client.entity.update('default', 'orders', 456, {
-   *   status: 'completed'
-   * });
-   * ```
+   * if (result.success) {
+   *   console.log('Updated:', result.data);
+   * }
+   * 
+   * @since 1.0.0
    */
   update<T = Record<string, unknown>>(
     source: string,
@@ -605,20 +349,12 @@ export interface EntityClientAPI {
    * @returns null on success
    * 
    * @example
-   * ```typescript
    * const result = await client.entity.delete('default', 'users', 123);
-   * if (result.error === null) {
-   *   console.log('User deleted successfully');
+   * if (result.success) {
+   *   console.log('User deleted');
    * }
-   * ```
    * 
-   * @example
-   * With confirmation:
-   * ```typescript
-   * if (confirm('Are you sure?')) {
-   *   await client.entity.delete('default', 'users', userId);
-   * }
-   * ```
+   * @since 1.0.0
    */
   delete(
     source: string,
@@ -636,19 +372,12 @@ export interface EntityClientAPI {
    * @returns Array of option objects
    * 
    * @example
-   * Get user options for dropdown:
-   * ```typescript
    * const result = await client.entity.options('default', 'users', ['id', 'name']);
-   * // Returns: [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }, ...]
+   * if (result.success) {
+   *   result.data.forEach(opt => console.log(opt.name));
+   * }
    * 
-   * // Use in select element
-   * result.data.forEach(user => {
-   *   const option = document.createElement('option');
-   *   option.value = user.id;
-   *   option.text = user.name;
-   *   selectElement.appendChild(option);
-   * });
-   * ```
+   * @since 1.0.0
    */
   options<T = Record<string, unknown>>(
     source: string,
@@ -666,13 +395,13 @@ export interface EntityClientAPI {
    * @returns Update result
    * 
    * @example
-   * ```typescript
-   * await client.entity.bulkUpdate('default', 'tasks', [
-   *   { id: 1, status: 'completed' },
-   *   { id: 2, status: 'completed' },
-   *   { id: 3, status: 'in_progress' }
+   * const result = await client.entity.bulkUpdate('default', 'users', [
+   *   { id: 1, status: 'active' },
+   *   { id: 2, status: 'inactive' },
+   *   { id: 3, status: 'active' }
    * ]);
-   * ```
+   * 
+   * @since 1.0.0
    */
   bulkUpdate<T = Record<string, unknown>>(
     source: string,
@@ -689,18 +418,12 @@ export interface EntityClientAPI {
    * @returns null on success
    * 
    * @example
-   * ```typescript
-   * await client.entity.bulkDelete('default', 'users', [1, 2, 3, 4, 5]);
-   * ```
-   * 
-   * @example
-   * Delete selected items:
-   * ```typescript
-   * const selectedIds = [123, 456, 789];
-   * if (confirm(`Delete ${selectedIds.length} items?`)) {
-   *   await client.entity.bulkDelete('default', 'items', selectedIds);
+   * const result = await client.entity.bulkDelete('default', 'users', [1, 2, 3]);
+   * if (result.success) {
+   *   console.log('3 users deleted');
    * }
-   * ```
+   * 
+   * @since 1.0.0
    */
   bulkDelete(
     source: string,