@amaster.ai/client 1.1.0-beta.0

package/types/entity.d.ts

@@ -0,0 +1,710 @@
+/**
+ * ============================================================================
+ * 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
+ */
+
+import type { ClientResult } from './common';
+
+// ==================== Filter Types ====================
+
+/**
+ * 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)
+  | '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
+
+/**
+ * Advanced filter operators for condition builder
+ * 
+ * @example
+ * ```typescript
+ * {
+ *   op: 'equal',
+ *   left: { field: 'status' },
+ *   right: 'active'
+ * }
+ * ```
+ */
+export type AdvancedFilterOperator =
+  | 'equal'
+  | 'not_equal'
+  | 'less'
+  | 'less_or_equal'
+  | 'greater'
+  | 'greater_or_equal'
+  | 'like'
+  | 'not_like'
+  | 'starts_with'
+  | 'ends_with'
+  | 'between'
+  | 'is_empty'
+  | 'is_not_empty'
+  | 'select_any_in'
+  | 'select_not_any_in';
+
+/**
+ * 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;
+  left: {
+    /** Field name, supports dot notation for relations (e.g., 'user.email') */
+    field: string;
+  };
+  right?: string | number | boolean | Date | null | string[] | number[];
+}
+
+/**
+ * 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';
+  children: Array<FilterGroup | FilterItem>;
+}
+
+/**
+ * Keywords search configuration
+ * 
+ * @example
+ * Search in specific fields:
+ * ```typescript
+ * {
+ *   fields: ['name', 'description'],
+ *   value: 'search term'
+ * }
+ * ```
+ */
+export interface KeywordsSearch {
+  /** Fields to search in */
+  fields: string[];
+  /** Search value */
+  value: string;
+}
+
+/**
+ * Between filter value
+ * 
+ * @example
+ * ```typescript
+ * {
+ *   'created_at[bt]': {
+ *     from: '2024-01-01',
+ *     to: '2024-12-31'
+ *   }
+ * }
+ * ```
+ */
+export interface BetweenValue {
+  from?: string | number | Date;
+  to?: string | number | Date;
+}
+
+// ==================== Query Parameters ====================
+
+/**
+ * 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 ====================
+  
+  /** 
+   * Page number (1-based)
+   * @default 1
+   */
+  page?: number;
+  
+  /** 
+   * Items per page
+   * @default 20
+   */
+  perPage?: number;
+  
+  /** 
+   * Maximum items to return (alternative to perPage)
+   */
+  limit?: number;
+  
+  /** 
+   * Number of items to skip (alternative to page)
+   */
+  offset?: number;
+
+  // ==================== Sorting ====================
+  
+  /** 
+   * Field to sort by
+   * @example 'created_at'
+   */
+  orderBy?: string;
+  
+  /** 
+   * Sort direction
+   * @default 'asc'
+   */
+  orderDir?: 'asc' | 'desc';
+
+  /** 
+   * Multiple sort orders (comma-separated)
+   * Format: "field1:asc,field2:desc"
+   * @example 'priority:desc,created_at:asc'
+   */
+  __orders?: string;
+
+  // ==================== Search ====================
+  
+  /** 
+   * 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;
+
+  // ==================== Relations & Fields ====================
+  
+  /** 
+   * 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[];
+
+  // ==================== Filters ====================
+  
+  /** 
+   * 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;
+}
+
+// ==================== Response Types ====================
+
+/**
+ * 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 */
+  items: T[];
+  /** Total count of entities (for pagination) */
+  total: number;
+  /** Current page number */
+  page?: number;
+  /** Items per page */
+  perPage?: number;
+}
+
+// ==================== Entity Client API ====================
+
+/**
+ * Entity CRUD Operations Client API
+ * 
+ * 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);
+ * ```
+ */
+export interface EntityClientAPI {
+  /**
+   * List entities with pagination, filtering, and sorting
+   * 
+   * @template T - The entity type
+   * @param source - Data source name (e.g., 'default', 'app-123')
+   * @param entity - Entity name (table name)
+   * @param params - Query parameters
+   * @returns List of entities with pagination info
+   * 
+   * @example
+   * Basic list:
+   * ```typescript
+   * const result = await client.entity.list('default', 'users');
+   * console.log(result.data.items); // User array
+   * console.log(result.data.total); // Total count
+   * ```
+   * 
+   * @example
+   * With pagination and sorting:
+   * ```typescript
+   * const result = await client.entity.list('default', 'users', {
+   *   page: 2,
+   *   perPage: 50,
+   *   orderBy: 'createdAt',
+   *   orderDir: 'desc'
+   * });
+   * ```
+   * 
+   * @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' }
+   * });
+   * ```
+   * 
+   * @example
+   * With full-text search:
+   * ```typescript
+   * const result = await client.entity.list('default', 'products', {
+   *   __keywords: {
+   *     fields: ['name', 'description'],
+   *     value: 'laptop'
+   *   }
+   * });
+   * ```
+   * 
+   * @example
+   * With relations:
+   * ```typescript
+   * const result = await client.entity.list('default', 'orders', {
+   *   __relations: ['user', 'items'],
+   *   __fields: ['id', 'total', 'user.name', 'items.product']
+   * });
+   * ```
+   */
+  list<T = Record<string, unknown>>(
+    source: string,
+    entity: string,
+    params?: EntityQueryParams
+  ): Promise<ClientResult<EntityListResponse<T>>>;
+
+  /**
+   * Get a single entity by ID
+   * 
+   * @template T - The entity type
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param id - Entity ID
+   * @returns The entity data
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.entity.get('default', 'users', 123);
+   * if (result.data) {
+   *   console.log('User:', result.data);
+   * }
+   * ```
+   * 
+   * @example
+   * With type safety:
+   * ```typescript
+   * interface User {
+   *   id: number;
+   *   name: string;
+   *   email: string;
+   * }
+   * 
+   * const result = await client.entity.get<User>('default', 'users', 123);
+   * const user: User = result.data;
+   * ```
+   */
+  get<T = Record<string, unknown>>(
+    source: string,
+    entity: string,
+    id: string | number
+  ): Promise<ClientResult<T>>;
+
+  /**
+   * Create a new entity
+   * 
+   * @template T - The entity type
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param data - Entity data to create
+   * @returns The created entity
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.entity.create('default', 'users', {
+   *   name: 'John Doe',
+   *   email: 'john@example.com',
+   *   role: 'user'
+   * });
+   * 
+   * if (result.data) {
+   *   console.log('Created user 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
+   * ```
+   */
+  create<T = Record<string, unknown>>(
+    source: string,
+    entity: string,
+    data: Record<string, unknown>
+  ): Promise<ClientResult<T>>;
+
+  /**
+   * Update an existing entity
+   * 
+   * @template T - The entity type
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param id - Entity ID to update
+   * @param data - Fields to update
+   * @returns The updated entity
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.entity.update('default', 'users', 123, {
+   *   name: 'Jane Doe',
+   *   email: 'jane@example.com'
+   * });
+   * ```
+   * 
+   * @example
+   * Partial update:
+   * ```typescript
+   * // Only update the status field
+   * await client.entity.update('default', 'orders', 456, {
+   *   status: 'completed'
+   * });
+   * ```
+   */
+  update<T = Record<string, unknown>>(
+    source: string,
+    entity: string,
+    id: string | number,
+    data: Record<string, unknown>
+  ): Promise<ClientResult<T>>;
+
+  /**
+   * Delete an entity by ID
+   * 
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param id - Entity ID to delete
+   * @returns null on success
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.entity.delete('default', 'users', 123);
+   * if (result.error === null) {
+   *   console.log('User deleted successfully');
+   * }
+   * ```
+   * 
+   * @example
+   * With confirmation:
+   * ```typescript
+   * if (confirm('Are you sure?')) {
+   *   await client.entity.delete('default', 'users', userId);
+   * }
+   * ```
+   */
+  delete(
+    source: string,
+    entity: string,
+    id: string | number
+  ): Promise<ClientResult<null>>;
+
+  /**
+   * Get options for select/dropdown fields
+   * 
+   * @template T - The option type
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param fields - Fields to include in options
+   * @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' }, ...]
+   * 
+   * // Use in select element
+   * result.data.forEach(user => {
+   *   const option = document.createElement('option');
+   *   option.value = user.id;
+   *   option.text = user.name;
+   *   selectElement.appendChild(option);
+   * });
+   * ```
+   */
+  options<T = Record<string, unknown>>(
+    source: string,
+    entity: string,
+    fields?: string[]
+  ): Promise<ClientResult<T[]>>;
+
+  /**
+   * Bulk update multiple entities
+   * 
+   * @template T - The response type
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param items - Array of entities to update (each must have an id)
+   * @returns Update result
+   * 
+   * @example
+   * ```typescript
+   * await client.entity.bulkUpdate('default', 'tasks', [
+   *   { id: 1, status: 'completed' },
+   *   { id: 2, status: 'completed' },
+   *   { id: 3, status: 'in_progress' }
+   * ]);
+   * ```
+   */
+  bulkUpdate<T = Record<string, unknown>>(
+    source: string,
+    entity: string,
+    items: Array<Record<string, unknown> & { id: string | number }>
+  ): Promise<ClientResult<T>>;
+
+  /**
+   * Bulk delete multiple entities
+   * 
+   * @param source - Data source name
+   * @param entity - Entity name
+   * @param ids - Array of entity IDs to delete
+   * @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);
+   * }
+   * ```
+   */
+  bulkDelete(
+    source: string,
+    entity: string,
+    ids: Array<string | number>
+  ): Promise<ClientResult<null>>;
+}