@amaster.ai/client 1.0.0-alpha.1

package/types/common.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Error information structure
+ * 
+ * @since 1.1.0
+ */
+export interface ClientError {
+  /**
+   * HTTP status code
+   */
+  status: number;
+  
+  /**
+   * Error message
+   */
+  message: string;
+  
+  /**
+   * Application-specific error code (e.g., 'INVALID_TOKEN', 'PERMISSION_DENIED')
+   * 
+   * @since 1.1.0
+   */
+  code?: string;
+  
+  /**
+   * Additional error details (optional)
+   */
+  details?: unknown;
+  
+  /**
+   * Error timestamp (ISO 8601 format)
+   * 
+   * @since 1.1.0
+   */
+  timestamp?: string;
+}
+
+/**
+ * Standard API response wrapper
+ * 
+ * All Amaster API methods return results wrapped in this structure for
+ * consistent error handling and type safety.
+ * 
+ * @template T - The type of the successful response data
+ * 
+ * @example
+ * // Success case
+ * const result = await client.entity.list('default', 'users');
+ * if (result.success) {
+ *   console.log('Data:', result.data);
+ * }
+ * 
+ * @example
+ * // Error case
+ * const result = await client.auth.login({ email, password });
+ * if (!result.success) {
+ *   console.error('Error:', result.error.message);
+ *   console.error('Code:', result.error.code);
+ * }
+ * 
+ * @since 1.0.0
+ */
+export interface ClientResult<T> {
+  /**
+   * Response data (null if error occurred)
+   */
+  data: T | null;
+  
+  /**
+   * Error information (null if successful)
+   */
+  error: ClientError | null;
+  
+  /**
+   * HTTP response status code
+   */
+  status: number;
+  
+  /**
+   * Convenience flag for checking if request was successful
+   * 
+   * Equivalent to `error === null`
+   * 
+   * @since 1.1.0
+   */
+  success: boolean;
+}
+
+/**
+ * HTTP request methods
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+/**
+ * Pagination parameters for list queries
+ */
+export interface PaginationParams {
+  /**
+   * Page number (1-based)
+   * @default 1
+   */
+  page?: number;
+  
+  /**
+   * Number of items per page
+   * @default 20
+   */
+  perPage?: number;
+}
+
+/**
+ * Paginated response structure
+ * 
+ * @template T - The type of items in the list
+ */
+export interface PaginatedResult<T> {
+  /**
+   * Array of items for current page
+   */
+  items: T[];
+  
+  /**
+   * Total number of items across all pages
+   */
+  total: number;
+  
+  /**
+   * Current page number (1-based)
+   */
+  page: number;
+  
+  /**
+   * Number of items per page
+   */
+  perPage: number;
+  
+  /**
+   * Total number of pages
+   */
+  totalPages?: number;
+}

package/types/copilot.d.ts

@@ -0,0 +1,49 @@
+import type { SendStreamingMessageResponse, CancelTaskResponse, GetTaskResponse } from '@a2a-js/sdk';
+import type { ClientResult } from './common';
+
+interface TextContent {
+    type: "text";
+    text: string;
+}
+interface ImageContent {
+    type: "image";
+    data?: string;
+    url?: string;
+    mimeType?: string;
+}
+interface FileContent {
+    type: "file";
+    data?: string;
+    url?: string;
+    mimeType?: string;
+    name?: string;
+}
+type MessageContent = TextContent | ImageContent | FileContent;
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string | MessageContent[];
+}
+interface ChatOptions {
+    taskId?: string;
+}
+type CopilotClientAPI = {
+    /**
+     * Stream messages from Copilot Agent.
+     *
+     * @example
+     * ```typescript
+     * import { createCopilotClient, Data } from "@amaster.ai/copilot-client";
+     *
+     * const client = createCopilotClient();
+     *
+     * for await (const response of client.chat([{ role: "user", content: "Hello" }])) {
+     *   // deal response
+     * }
+     * ```
+     */
+    chat(messages: ChatMessage[], options?: ChatOptions): AsyncGenerator<SendStreamingMessageResponse, void, unknown>;
+    cancelChat(taskId: string): Promise<ClientResult<CancelTaskResponse>>;
+    getChatStatus(taskId: string): Promise<ClientResult<GetTaskResponse>>;
+};
+
+export { type ChatMessage, type ChatOptions, type CopilotClientAPI, type FileContent, type ImageContent, type MessageContent, type TextContent };

package/types/entity.d.ts

@@ -0,0 +1,433 @@
+/**
+ * 
+ * @module entity
+ */
+
+import type { ClientResult } from './common';
+
+// ==================== Filter Types ====================
+
+/**
+ * Simple filter operators for query string format
+ * 
+ * Usage: `{ 'field[op]': value }`
+ *
+ */
+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
+ *
+ */
+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)
+ *
+ */
+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)
+ *
+ */
+export interface FilterGroup {
+  conjunction: 'and' | 'or';
+  children: Array<FilterGroup | FilterItem>;
+}
+
+/**
+ * Keywords search configuration
+ *
+ */
+export interface KeywordsSearch {
+  /** Fields to search in */
+  fields: string[];
+  /** Search value */
+  value: string;
+}
+
+/**
+ * Between filter value
+ *
+ */
+export interface BetweenValue {
+  from?: string | number | Date;
+  to?: string | number | Date;
+}
+
+// ==================== Query Parameters ====================
+
+/**
+ * Entity query parameters
+ * 
+ * Supports pagination, sorting, filtering, searching, and relation loading.
+ *
+ */
+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
+   */
+  orderBy?: string;
+  
+  /** 
+   * Sort direction
+   * @default 'asc'
+   */
+  orderDir?: 'asc' | 'desc';
+
+  /** 
+   * Multiple sort orders (comma-separated)
+   * Format: "field1:asc,field2:desc"
+   */
+  __orders?: string;
+
+  // ==================== Search ====================
+  
+  /** 
+   * Keywords search
+   * - String: search all searchable fields (backend determines)
+   * - Object: search specific fields
+   *
+   */
+  __keywords?: string | KeywordsSearch;
+
+  // ==================== Relations & Fields ====================
+  
+  /** 
+   * Relations to load (eager loading)
+   */
+  __relations?: string[];
+
+  /** 
+   * Fields to select (only return these fields)
+   */
+  __fields?: string[];
+
+  // ==================== Filters ====================
+  
+  /** 
+   * Advanced filter (condition builder with AND/OR)
+   */
+  __filter?: FilterGroup;
+
+  /** 
+   * Simple filters using field=value or field[op]=value
+   */
+  [key: string]: unknown;
+}
+
+// ==================== Response Types ====================
+
+/**
+ * Entity list response
+ * 
+ * @template T - The entity type
+ *
+ */
+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.
+ * 
+ * @since 1.0.0
+ */
+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 usage
+   * const result = await client.entity.list('default', 'users');
+   * console.log('Users:', result.data.items);
+   * 
+   * @example
+   * // With pagination
+   * const result = await client.entity.list('default', 'users', {
+   *   page: 1,
+   *   perPage: 20
+   * });
+   * 
+   * @example
+   * // 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 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
+   *   });
+   * }
+   * 
+   * @since 1.0.0
+   */
+  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
+   * const result = await client.entity.get('default', 'users', 123);
+   * if (result.success) {
+   *   console.log('User:', result.data);
+   * }
+   * 
+   * @example
+   * // With type safety
+   * type User = { id: number; name: string };
+   * const result = await client.entity.get<User>('default', 'users', 123);
+   * 
+   * @since 1.0.0
+   */
+  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
+   * const result = await client.entity.create('default', 'users', {
+   *   name: 'John Doe',
+   *   email: 'john@example.com',
+   *   status: 'active'
+   * });
+   * 
+   * if (result.success) {
+   *   console.log('Created user with ID:', result.data.id);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  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
+   * const result = await client.entity.update('default', 'users', 123, {
+   *   name: 'Jane Doe',
+   *   status: 'inactive'
+   * });
+   * 
+   * if (result.success) {
+   *   console.log('Updated:', result.data);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  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
+   * const result = await client.entity.delete('default', 'users', 123);
+   * if (result.success) {
+   *   console.log('User deleted');
+   * }
+   * 
+   * @since 1.0.0
+   */
+  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
+   * const result = await client.entity.options('default', 'users', ['id', 'name']);
+   * if (result.success) {
+   *   result.data.forEach(opt => console.log(opt.name));
+   * }
+   * 
+   * @since 1.0.0
+   */
+  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
+   * 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,
+    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
+   * 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,
+    entity: string,
+    ids: Array<string | number>
+  ): Promise<ClientResult<null>>;
+}

package/types/function.d.ts

@@ -0,0 +1,41 @@
+/**
+ *  * Invoke serverless functions deployed on the Amaster platform.
+ * 
+ * @module function
+ */
+
+import type { ClientResult } from './common';
+
+/**
+ * Function Client API
+ * 
+ * Execute serverless functions with type-safe parameters and results.
+ * 
+ * @since 1.0.0
+ */
+export interface FunctionClientAPI {
+  /**
+   * Invoke a serverless function
+   * 
+   * @param funcName - Function name (corresponds to directory in src/functions/)
+   * @param params - Function parameters (sent as JSON body)
+   * @returns Function execution result
+   * 
+   * @example
+   * const result = await client.function.invoke<{ message: string }>('sendEmail', {
+   *   to: 'user@example.com',
+   *   subject: 'Hello',
+   *   body: 'Welcome!'
+   * });
+   * 
+   * if (result.success) {
+   *   console.log(result.data.message);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  invoke<T = unknown>(
+    funcName: string,
+    params?: Record<string, unknown>
+  ): Promise<ClientResult<T>>;
+}