@amaster.ai/entity-client 1.0.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,305 @@
+# @amaster.ai/entity-client
+
+Type-safe CRUD client for entity data management with automatic date handling and advanced filtering.
+
+## Features
+
+- 🔐 Type-safe CRUD operations
+- 📅 Automatic date format conversion
+- 🔍 Advanced filtering with operators
+- 📄 Pagination and sorting
+- 🔗 Relation loading support
+- 📦 Bulk operations (update/delete)
+- 🌳 Tree-shakeable ESM/CJS builds
+
+## Installation
+
+```bash
+pnpm add @amaster.ai/entity-client @amaster.ai/http-client axios
+```
+
+## Quick Start
+
+```typescript
+import { createEntityClient } from "@amaster.ai/entity-client";
+
+const client = createEntityClient();
+
+// List with pagination
+const result = await client.list("default", "users", {
+  page: 1,
+  perPage: 20,
+  orderBy: "createdAt",
+  orderDir: "desc",
+});
+
+if (result.data) {
+  console.log(result.data.items); // Array of users
+  console.log(result.data.total); // Total count
+}
+```
+
+## API Reference
+
+### `list<T>(source, entity, params?)`
+
+List entities with pagination, sorting, and filtering.
+
+```typescript
+const result = await client.list("default", "tasks", {
+  page: 1,
+  perPage: 20,
+  orderBy: "createdAt",
+  orderDir: "desc",
+  status: "active", // Simple filter
+  "title[like]": "search", // Like operator
+});
+
+// result.data structure:
+// {
+//   items: T[],
+//   total: number,
+//   page?: number,
+//   perPage?: number
+// }
+```
+
+### `get<T>(source, entity, id)`
+
+Get a single entity by ID.
+
+```typescript
+const result = await client.get("default", "users", 1);
+if (result.data) {
+  console.log(result.data); // User object
+}
+```
+
+### `create<T>(source, entity, data)`
+
+Create a new entity.
+
+```typescript
+const result = await client.create("default", "tasks", {
+  title: "New Task",
+  dueDate: new Date(), // Automatically converted to backend format
+  status: "pending",
+});
+```
+
+### `update<T>(source, entity, id, data)`
+
+Update an existing entity.
+
+```typescript
+const result = await client.update("default", "tasks", 1, {
+  status: "completed",
+  completedAt: new Date(),
+});
+```
+
+### `delete(source, entity, id)`
+
+Delete an entity.
+
+```typescript
+const result = await client.delete("default", "tasks", 1);
+```
+
+### `options<T>(source, entity, fields?)`
+
+Get options for select fields.
+
+```typescript
+const result = await client.options("default", "users", ["id", "name"]);
+// Returns array of { id, name } objects
+```
+
+### `bulkUpdate<T>(source, entity, items)`
+
+Update multiple entities in one request.
+
+```typescript
+const result = await client.bulkUpdate("default", "tasks", [
+  { id: 1, status: "completed" },
+  { id: 2, status: "completed" },
+]);
+```
+
+### `bulkDelete(source, entity, ids)`
+
+Delete multiple entities in one request.
+
+```typescript
+const result = await client.bulkDelete("default", "tasks", [1, 2, 3]);
+```
+
+## Query Parameters
+
+### Pagination
+
+```typescript
+{
+  page: 1,        // Page number (starts from 1)
+  perPage: 20     // Items per page
+}
+```
+
+### Sorting
+
+```typescript
+{
+  orderBy: "createdAt",
+  orderDir: "desc"  // 'asc' or 'desc'
+}
+```
+
+### Simple Filters
+
+```typescript
+{
+  status: "active",          // Equals (default)
+  "age[gt]": 18,            // Greater than
+  "name[like]": "John",     // Like search
+  "email[sw]": "@example"   // Starts with
+}
+```
+
+### Filter Operators
+
+- `eq` - Equal (default)
+- `ne` - Not equal
+- `gt` - Greater than
+- `ge` - Greater or equal
+- `lt` - Less than
+- `le` - Less or equal
+- `like` - Fuzzy match
+- `sw` - Starts with
+- `ew` - Ends with
+- `bt` - Between
+- `in` - In array
+
+### Keyword Search
+
+Search across multiple fields:
+
+```typescript
+{
+  "__keywords[title,description]": "search term"
+}
+```
+
+### Relation Loading
+
+Load related entities:
+
+```typescript
+{
+  "__relations[]": ["author", "comments"]
+}
+```
+
+### Advanced Filters
+
+Complex AND/OR filter groups:
+
+```typescript
+{
+  __filter: {
+    conjunction: "and",
+    children: [
+      {
+        op: "equal",
+        left: { type: "field", field: "status" },
+        right: "active"
+      },
+      {
+        conjunction: "or",
+        children: [
+          {
+            op: "greater",
+            left: { type: "field", field: "priority" },
+            right: 5
+          },
+          {
+            op: "like",
+            left: { type: "field", field: "title" },
+            right: "urgent"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Date Handling
+
+Dates are automatically converted to backend format:
+
+```typescript
+// Input
+{
+  dueDate: new Date("2026-01-05T10:30:45.000Z"),
+  createdAt: "2026-01-05T10:30:45.000Z"
+}
+
+// Sent to backend as
+{
+  dueDate: "2026-01-05 10:30:45",
+  createdAt: "2026-01-05 10:30:45"
+}
+```
+
+## TypeScript Support
+
+Full generic type support:
+
+```typescript
+interface Task {
+  id: number;
+  title: string;
+  status: "pending" | "active" | "completed";
+  dueDate: string;
+}
+
+const result = await client.list<Task>("default", "tasks");
+if (result.data) {
+  result.data.items.forEach((task) => {
+    console.log(task.title); // Fully typed
+  });
+}
+```
+
+## Error Handling
+
+```typescript
+const result = await client.get("default", "users", 1);
+
+if (result.error) {
+  console.error("Error:", result.error.message);
+  console.error("Status:", result.error.status);
+}
+```
+
+## Custom HTTP Client
+
+Use a custom HTTP client with your own configuration:
+
+```typescript
+import { createHttpClient } from "@amaster.ai/http-client";
+import { createEntityClient } from "@amaster.ai/entity-client";
+import axios from "axios";
+
+const axiosInstance = axios.create({
+  baseURL: "https://api.example.com",
+  timeout: 5000,
+});
+
+const httpClient = createHttpClient(axiosInstance);
+const entityClient = createEntityClient(httpClient);
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,237 @@
+'use strict';
+
+var httpClient = require('@amaster.ai/http-client');
+
+// src/entity-client.ts
+function formatDateForBackend(date) {
+  let dateObj;
+  if (date instanceof Date) {
+    dateObj = date;
+  } else if (typeof date === "string") {
+    dateObj = new Date(date);
+  } else {
+    dateObj = new Date(date);
+  }
+  if (Number.isNaN(dateObj.getTime())) {
+    return String(date);
+  }
+  const year = dateObj.getUTCFullYear();
+  const month = String(dateObj.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(dateObj.getUTCDate()).padStart(2, "0");
+  const hours = String(dateObj.getUTCHours()).padStart(2, "0");
+  const minutes = String(dateObj.getUTCMinutes()).padStart(2, "0");
+  const seconds = String(dateObj.getUTCSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+function processDataForBackend(data) {
+  if (data === null || data === void 0) {
+    return data;
+  }
+  if (data instanceof Date) {
+    return formatDateForBackend(data);
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => processDataForBackend(item));
+  }
+  if (typeof data === "object") {
+    const processed = {};
+    for (const [key, value] of Object.entries(data)) {
+      processed[key] = processDataForBackend(value);
+    }
+    return processed;
+  }
+  if (typeof data === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(data)) {
+    return formatDateForBackend(data);
+  }
+  return data;
+}
+function buildEntityUrl(source, entity, path = "") {
+  const basePath = `/api/entity/data/${source}/${entity}`;
+  return path ? `${basePath}${path.startsWith("/") ? path : `/${path}`}` : basePath;
+}
+function encodeQueryParams(params) {
+  if (!params || Object.keys(params).length === 0) {
+    return "";
+  }
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (key === "__filter" && typeof value === "object") {
+      searchParams.append(key, JSON.stringify(value));
+    } else if (key === "__relations" && Array.isArray(value)) {
+      for (const v of value) {
+        searchParams.append("__relations[]", String(v));
+      }
+    } else if (Array.isArray(value)) {
+      for (const v of value) {
+        searchParams.append(key, String(v));
+      }
+    } else if (typeof value === "object" && !Array.isArray(value)) {
+      for (const [subKey, subValue] of Object.entries(value)) {
+        if (subValue !== void 0 && subValue !== null) {
+          searchParams.append(`${key}[${subKey}]`, String(subValue));
+        }
+      }
+    } else {
+      searchParams.append(key, String(value));
+    }
+  }
+  const query = searchParams.toString();
+  return query ? `?${query}` : "";
+}
+function createEntityClient(http = httpClient.createHttpClient()) {
+  return {
+    async list(source, entity, params) {
+      const url = buildEntityUrl(source, entity) + encodeQueryParams(params);
+      const result = await http.request({
+        url,
+        method: "get"
+      });
+      if (result.error || !result.data) {
+        return {
+          data: { items: [], total: 0 },
+          error: result.error,
+          status: result.status
+        };
+      }
+      const items = Array.isArray(result.data.items) ? result.data.items : [];
+      const total = result.data.total ?? result.data.count ?? items.length;
+      return {
+        ...result,
+        data: {
+          items,
+          total,
+          page: result.data.page,
+          perPage: result.data.perPage || result.data.pageSize
+        }
+      };
+    },
+    get(source, entity, id) {
+      if (!id) {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity ID is required", status: 400 },
+          status: 400
+        });
+      }
+      const url = buildEntityUrl(source, entity, `/${id}`);
+      return http.request({
+        url,
+        method: "get"
+      });
+    },
+    create(source, entity, data) {
+      if (!data || typeof data !== "object") {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity data is required", status: 400 },
+          status: 400
+        });
+      }
+      const processedData = processDataForBackend(data);
+      const url = buildEntityUrl(source, entity);
+      return http.request({
+        url,
+        method: "post",
+        headers: { "Content-Type": "application/json" },
+        data: processedData
+      });
+    },
+    update(source, entity, id, data) {
+      if (!id) {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity ID is required", status: 400 },
+          status: 400
+        });
+      }
+      if (!data || typeof data !== "object") {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity data is required", status: 400 },
+          status: 400
+        });
+      }
+      const processedData = processDataForBackend(data);
+      const url = buildEntityUrl(source, entity, `/${id}`);
+      return http.request({
+        url,
+        method: "put",
+        headers: { "Content-Type": "application/json" },
+        data: processedData
+      });
+    },
+    async delete(source, entity, id) {
+      if (!id) {
+        return {
+          data: null,
+          error: { message: "Entity ID is required", status: 400 },
+          status: 400
+        };
+      }
+      const url = buildEntityUrl(source, entity, `/${id}`);
+      const result = await http.request({
+        url,
+        method: "delete"
+      });
+      return result.status === 204 ? { ...result, data: null } : result;
+    },
+    async options(source, entity, fields) {
+      const params = fields && fields.length > 0 ? { "__fields[]": fields } : void 0;
+      const url = buildEntityUrl(source, entity, "/options") + encodeQueryParams(params);
+      const result = await http.request({
+        url,
+        method: "get"
+      });
+      if (result.error || !result.data) {
+        return {
+          data: null,
+          error: result.error,
+          status: result.status
+        };
+      }
+      return {
+        ...result,
+        data: result.data.items || []
+      };
+    },
+    bulkUpdate(source, entity, items) {
+      if (!items || items.length === 0) {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Items array is required", status: 400 },
+          status: 400
+        });
+      }
+      const processedItems = items.map((item) => processDataForBackend(item));
+      const url = buildEntityUrl(source, entity, "/bulkUpdate");
+      return http.request({
+        url,
+        method: "post",
+        headers: { "Content-Type": "application/json" },
+        data: { items: processedItems }
+      });
+    },
+    async bulkDelete(source, entity, ids) {
+      if (!ids || ids.length === 0) {
+        return {
+          data: null,
+          error: { message: "IDs array is required", status: 400 },
+          status: 400
+        };
+      }
+      const url = buildEntityUrl(source, entity, `/${ids.join(",")}`);
+      const result = await http.request({
+        url,
+        method: "delete"
+      });
+      return result.status === 204 ? { ...result, data: null } : result;
+    }
+  };
+}
+
+exports.createEntityClient = createEntityClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entity-client.ts"],"names":["createHttpClient"],"mappings":"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","file":"index.cjs","sourcesContent":["import { type ClientResult, createHttpClient, type HttpClient } from \"@amaster.ai/http-client\";\nimport type { EntityListResponse, EntityQueryParams } from \"./types\";\n\n// Export types for convenience\nexport type { EntityListResponse, EntityQueryParams, FilterGroup, FilterItem, FilterOperator } from \"./types\";\n\n/**\n * Entity Client - Type-safe client for entity CRUD operations\n *\n * ## Quick Start\n * ```typescript\n * const entityClient = createEntityClient();\n *\n * // List with pagination and sorting\n * const result = await entityClient.list('default', 'tasks', {\n *   page: 1,\n *   perPage: 20,\n *   orderBy: 'createdAt',\n *   orderDir: 'desc'\n * });\n *\n * // ⚠️ IMPORTANT: Access items via result.data.items, NOT result.data\n * setTasks(result.data?.items || []);  // ✅ Correct\n * setTotal(result.data?.total || 0);\n *\n * // ❌ WRONG: setTasks(result.data || [])  - result.data is an object, not an array!\n *\n * // Get single record\n * const task = await entityClient.get('default', 'tasks', 1);\n * setTask(result.data);  // ✅ result.data is the entity object directly\n *\n * // CRUD operations\n * await entityClient.create('default', 'tasks', { title: 'New', dueDate: new Date() });\n * await entityClient.update('default', 'tasks', 1, { status: 'done' });\n * await entityClient.delete('default', 'tasks', 1);\n * ```\n *\n * ## Date Handling\n * Date values are automatically converted to backend-compatible format:\n * - Date objects: `new Date()` → `\"2026-01-05 10:30:45\"`\n * - ISO 8601 strings: `\"2026-01-05T00:00:00.000Z\"` → `\"2026-01-05 00:00:00\"`\n * - Works in nested objects and arrays\n *\n * ## Filter Operators\n * eq, ne, gt, ge, lt, le, like, sw, ew, bt, in\n *\n * Usage: `{ 'field[op]': value }` or `{ field: value }` (eq is default)\n */\nexport type EntityClient = {\n  list<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    params?: EntityQueryParams\n  ): Promise<ClientResult<EntityListResponse<T>>>;\n  get<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    id: string | number\n  ): Promise<ClientResult<T>>;\n  create<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    data: Record<string, unknown>\n  ): Promise<ClientResult<T>>;\n  update<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    id: string | number,\n    data: Record<string, unknown>\n  ): Promise<ClientResult<T>>;\n  delete(source: string, entity: string, id: string | number): Promise<ClientResult<null>>;\n  options<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    fields?: string[]\n  ): Promise<ClientResult<T[]>>;\n  bulkUpdate<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    items: Array<Record<string, unknown> & { id: string | number }>\n  ): Promise<ClientResult<T>>;\n  bulkDelete(\n    source: string,\n    entity: string,\n    ids: Array<string | number>\n  ): Promise<ClientResult<null>>;\n};\n\n// ==================== Helper Functions ====================\n\n/**\n * Convert Date object or ISO 8601 string to backend-compatible DATETIME format\n * Backend expects: \"YYYY-MM-DD HH:MM:SS\" (space-separated, no T or Z)\n */\nfunction formatDateForBackend(date: Date | string): string {\n  let dateObj: Date;\n\n  if (date instanceof Date) {\n    dateObj = date;\n  } else if (typeof date === \"string\") {\n    dateObj = new Date(date);\n  } else {\n    dateObj = new Date(date);\n  }\n\n  // Check if date is valid\n  if (Number.isNaN(dateObj.getTime())) {\n    return String(date); // Return original value if invalid\n  }\n\n  // Format as \"YYYY-MM-DD HH:MM:SS\" in UTC\n  const year = dateObj.getUTCFullYear();\n  const month = String(dateObj.getUTCMonth() + 1).padStart(2, \"0\");\n  const day = String(dateObj.getUTCDate()).padStart(2, \"0\");\n  const hours = String(dateObj.getUTCHours()).padStart(2, \"0\");\n  const minutes = String(dateObj.getUTCMinutes()).padStart(2, \"0\");\n  const seconds = String(dateObj.getUTCSeconds()).padStart(2, \"0\");\n\n  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;\n}\n\n/**\n * Recursively process data object to convert Date values to backend format\n * Handles nested objects and arrays\n */\nfunction processDataForBackend(data: unknown): unknown {\n  if (data === null || data === undefined) {\n    return data;\n  }\n\n  // Handle Date objects\n  if (data instanceof Date) {\n    return formatDateForBackend(data);\n  }\n\n  // Handle arrays\n  if (Array.isArray(data)) {\n    return data.map((item) => processDataForBackend(item));\n  }\n\n  // Handle objects\n  if (typeof data === \"object\") {\n    const processed: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(data)) {\n      processed[key] = processDataForBackend(value);\n    }\n    return processed;\n  }\n\n  // Handle ISO 8601 date strings (detect pattern)\n  if (typeof data === \"string\" && /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}/.test(data)) {\n    return formatDateForBackend(data);\n  }\n\n  return data;\n}\n\nfunction buildEntityUrl(source: string, entity: string, path = \"\"): string {\n  const basePath = `/api/entity/data/${source}/${entity}`;\n  return path ? `${basePath}${path.startsWith(\"/\") ? path : `/${path}`}` : basePath;\n}\n\nfunction encodeQueryParams(params?: Record<string, unknown>): string {\n  if (!params || Object.keys(params).length === 0) {\n    return \"\";\n  }\n\n  const searchParams = new URLSearchParams();\n\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined || value === null) {\n      continue;\n    }\n\n    if (key === \"__filter\" && typeof value === \"object\") {\n      searchParams.append(key, JSON.stringify(value));\n    } else if (key === \"__relations\" && Array.isArray(value)) {\n      for (const v of value) {\n        searchParams.append(\"__relations[]\", String(v));\n      }\n    } else if (Array.isArray(value)) {\n      for (const v of value) {\n        searchParams.append(key, String(v));\n      }\n    } else if (typeof value === \"object\" && !Array.isArray(value)) {\n      for (const [subKey, subValue] of Object.entries(value)) {\n        if (subValue !== undefined && subValue !== null) {\n          searchParams.append(`${key}[${subKey}]`, String(subValue));\n        }\n      }\n    } else {\n      searchParams.append(key, String(value));\n    }\n  }\n\n  const query = searchParams.toString();\n  return query ? `?${query}` : \"\";\n}\n\n// ==================== Client Factory ====================\n\nexport function createEntityClient(http: HttpClient = createHttpClient()): EntityClient {\n  return {\n    async list<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      params?: EntityQueryParams\n    ): Promise<ClientResult<EntityListResponse<T>>> {\n      const url = buildEntityUrl(source, entity) + encodeQueryParams(params);\n      const result = await http.request<{\n        items: T[];\n        count?: number;\n        total?: number;\n        page?: number;\n        perPage?: number;\n        pageSize?: number;\n      }>({\n        url,\n        method: \"get\",\n      });\n\n      if (result.error || !result.data) {\n        return {\n          data: { items: [], total: 0 },\n          error: result.error,\n          status: result.status,\n        };\n      }\n\n      const items = Array.isArray(result.data.items) ? result.data.items : [];\n      const total = result.data.total ?? result.data.count ?? items.length;\n\n      return {\n        ...result,\n        data: {\n          items,\n          total,\n          page: result.data.page,\n          perPage: result.data.perPage || result.data.pageSize,\n        },\n      };\n    },\n\n    get<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      id: string | number\n    ): Promise<ClientResult<T>> {\n      if (!id) {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity ID is required\", status: 400 },\n          status: 400,\n        });\n      }\n      const url = buildEntityUrl(source, entity, `/${id}`);\n      return http.request<T>({\n        url,\n        method: \"get\",\n      });\n    },\n\n    create<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      data: Record<string, unknown>\n    ): Promise<ClientResult<T>> {\n      if (!data || typeof data !== \"object\") {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity data is required\", status: 400 },\n          status: 400,\n        });\n      }\n\n      const processedData = processDataForBackend(data);\n\n      const url = buildEntityUrl(source, entity);\n      return http.request<T>({\n        url,\n        method: \"post\",\n        headers: { \"Content-Type\": \"application/json\" },\n        data: processedData,\n      });\n    },\n\n    update<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      id: string | number,\n      data: Record<string, unknown>\n    ): Promise<ClientResult<T>> {\n      if (!id) {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity ID is required\", status: 400 },\n          status: 400,\n        });\n      }\n      if (!data || typeof data !== \"object\") {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity data is required\", status: 400 },\n          status: 400,\n        });\n      }\n\n      const processedData = processDataForBackend(data);\n\n      const url = buildEntityUrl(source, entity, `/${id}`);\n      return http.request<T>({\n        url,\n        method: \"put\",\n        headers: { \"Content-Type\": \"application/json\" },\n        data: processedData,\n      });\n    },\n\n    async delete(source: string, entity: string, id: string | number): Promise<ClientResult<null>> {\n      if (!id) {\n        return {\n          data: null,\n          error: { message: \"Entity ID is required\", status: 400 },\n          status: 400,\n        };\n      }\n      const url = buildEntityUrl(source, entity, `/${id}`);\n      const result = await http.request<null>({\n        url,\n        method: \"delete\",\n      });\n      return result.status === 204 ? { ...result, data: null } : result;\n    },\n\n    async options<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      fields?: string[]\n    ): Promise<ClientResult<T[]>> {\n      const params = fields && fields.length > 0 ? { \"__fields[]\": fields } : undefined;\n\n      const url = buildEntityUrl(source, entity, \"/options\") + encodeQueryParams(params);\n      const result = await http.request<{ items: T[] }>({\n        url,\n        method: \"get\",\n      });\n\n      if (result.error || !result.data) {\n        return {\n          data: null,\n          error: result.error,\n          status: result.status,\n        };\n      }\n\n      return {\n        ...result,\n        data: result.data.items || [],\n      };\n    },\n\n    bulkUpdate<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      items: Array<Record<string, unknown> & { id: string | number }>\n    ): Promise<ClientResult<T>> {\n      if (!items || items.length === 0) {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Items array is required\", status: 400 },\n          status: 400,\n        });\n      }\n\n      const processedItems = items.map((item) => processDataForBackend(item));\n\n      const url = buildEntityUrl(source, entity, \"/bulkUpdate\");\n      return http.request<T>({\n        url,\n        method: \"post\",\n        headers: { \"Content-Type\": \"application/json\" },\n        data: { items: processedItems },\n      });\n    },\n\n    async bulkDelete(\n      source: string,\n      entity: string,\n      ids: Array<string | number>\n    ): Promise<ClientResult<null>> {\n      if (!ids || ids.length === 0) {\n        return {\n          data: null,\n          error: { message: \"IDs array is required\", status: 400 },\n          status: 400,\n        };\n      }\n\n      const url = buildEntityUrl(source, entity, `/${ids.join(\",\")}`);\n      const result = await http.request<null>({\n        url,\n        method: \"delete\",\n      });\n\n      return result.status === 204 ? { ...result, data: null } : result;\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+import { ClientResult, HttpClient } from '@amaster.ai/http-client';
+
+/**
+ * Entity Client Type Definitions
+ */
+/**
+ * Filter operators supported by the entity API
+ */
+type FilterOperator = "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "like" | "sw" | "ew" | "bt" | "in";
+/**
+ * Advanced filter item
+ */
+type FilterItem = {
+    op: "equal" | "not_equal" | "less" | "less_or_equal" | "greater" | "greater_or_equal" | "like" | "starts_with" | "ends_with" | "between" | "is_empty" | "is_not_empty";
+    left: {
+        type: "field";
+        field: string;
+    };
+    right: string | number | boolean | Date | null | string[];
+};
+/**
+ * Advanced filter group (supports AND/OR combinations)
+ */
+type FilterGroup = {
+    conjunction: "and" | "or";
+    children: Array<FilterGroup | FilterItem>;
+};
+/**
+ * Entity query parameters
+ */
+type EntityQueryParams = {
+    page?: number;
+    perPage?: number;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    __keywords?: string;
+    __relations?: string[];
+    __filter?: FilterGroup;
+    [key: string]: unknown;
+};
+/**
+ * Entity list response
+ */
+type EntityListResponse<T = Record<string, unknown>> = {
+    items: T[];
+    total: number;
+    page?: number;
+    perPage?: number;
+};
+
+/**
+ * Entity Client - Type-safe client for entity CRUD operations
+ *
+ * ## Quick Start
+ * ```typescript
+ * const entityClient = createEntityClient();
+ *
+ * // List with pagination and sorting
+ * const result = await entityClient.list('default', 'tasks', {
+ *   page: 1,
+ *   perPage: 20,
+ *   orderBy: 'createdAt',
+ *   orderDir: 'desc'
+ * });
+ *
+ * // ⚠️ IMPORTANT: Access items via result.data.items, NOT result.data
+ * setTasks(result.data?.items || []);  // ✅ Correct
+ * setTotal(result.data?.total || 0);
+ *
+ * // ❌ WRONG: setTasks(result.data || [])  - result.data is an object, not an array!
+ *
+ * // Get single record
+ * const task = await entityClient.get('default', 'tasks', 1);
+ * setTask(result.data);  // ✅ result.data is the entity object directly
+ *
+ * // CRUD operations
+ * await entityClient.create('default', 'tasks', { title: 'New', dueDate: new Date() });
+ * await entityClient.update('default', 'tasks', 1, { status: 'done' });
+ * await entityClient.delete('default', 'tasks', 1);
+ * ```
+ *
+ * ## Date Handling
+ * Date values are automatically converted to backend-compatible format:
+ * - Date objects: `new Date()` → `"2026-01-05 10:30:45"`
+ * - ISO 8601 strings: `"2026-01-05T00:00:00.000Z"` → `"2026-01-05 00:00:00"`
+ * - Works in nested objects and arrays
+ *
+ * ## Filter Operators
+ * eq, ne, gt, ge, lt, le, like, sw, ew, bt, in
+ *
+ * Usage: `{ 'field[op]': value }` or `{ field: value }` (eq is default)
+ */
+type EntityClient = {
+    list<T = Record<string, unknown>>(source: string, entity: string, params?: EntityQueryParams): Promise<ClientResult<EntityListResponse<T>>>;
+    get<T = Record<string, unknown>>(source: string, entity: string, id: string | number): Promise<ClientResult<T>>;
+    create<T = Record<string, unknown>>(source: string, entity: string, data: Record<string, unknown>): Promise<ClientResult<T>>;
+    update<T = Record<string, unknown>>(source: string, entity: string, id: string | number, data: Record<string, unknown>): Promise<ClientResult<T>>;
+    delete(source: string, entity: string, id: string | number): Promise<ClientResult<null>>;
+    options<T = Record<string, unknown>>(source: string, entity: string, fields?: string[]): Promise<ClientResult<T[]>>;
+    bulkUpdate<T = Record<string, unknown>>(source: string, entity: string, items: Array<Record<string, unknown> & {
+        id: string | number;
+    }>): Promise<ClientResult<T>>;
+    bulkDelete(source: string, entity: string, ids: Array<string | number>): Promise<ClientResult<null>>;
+};
+declare function createEntityClient(http?: HttpClient): EntityClient;
+
+export { type EntityClient, type EntityListResponse, type EntityQueryParams, type FilterGroup, type FilterItem, type FilterOperator, createEntityClient };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { ClientResult, HttpClient } from '@amaster.ai/http-client';
+
+/**
+ * Entity Client Type Definitions
+ */
+/**
+ * Filter operators supported by the entity API
+ */
+type FilterOperator = "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "like" | "sw" | "ew" | "bt" | "in";
+/**
+ * Advanced filter item
+ */
+type FilterItem = {
+    op: "equal" | "not_equal" | "less" | "less_or_equal" | "greater" | "greater_or_equal" | "like" | "starts_with" | "ends_with" | "between" | "is_empty" | "is_not_empty";
+    left: {
+        type: "field";
+        field: string;
+    };
+    right: string | number | boolean | Date | null | string[];
+};
+/**
+ * Advanced filter group (supports AND/OR combinations)
+ */
+type FilterGroup = {
+    conjunction: "and" | "or";
+    children: Array<FilterGroup | FilterItem>;
+};
+/**
+ * Entity query parameters
+ */
+type EntityQueryParams = {
+    page?: number;
+    perPage?: number;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    __keywords?: string;
+    __relations?: string[];
+    __filter?: FilterGroup;
+    [key: string]: unknown;
+};
+/**
+ * Entity list response
+ */
+type EntityListResponse<T = Record<string, unknown>> = {
+    items: T[];
+    total: number;
+    page?: number;
+    perPage?: number;
+};
+
+/**
+ * Entity Client - Type-safe client for entity CRUD operations
+ *
+ * ## Quick Start
+ * ```typescript
+ * const entityClient = createEntityClient();
+ *
+ * // List with pagination and sorting
+ * const result = await entityClient.list('default', 'tasks', {
+ *   page: 1,
+ *   perPage: 20,
+ *   orderBy: 'createdAt',
+ *   orderDir: 'desc'
+ * });
+ *
+ * // ⚠️ IMPORTANT: Access items via result.data.items, NOT result.data
+ * setTasks(result.data?.items || []);  // ✅ Correct
+ * setTotal(result.data?.total || 0);
+ *
+ * // ❌ WRONG: setTasks(result.data || [])  - result.data is an object, not an array!
+ *
+ * // Get single record
+ * const task = await entityClient.get('default', 'tasks', 1);
+ * setTask(result.data);  // ✅ result.data is the entity object directly
+ *
+ * // CRUD operations
+ * await entityClient.create('default', 'tasks', { title: 'New', dueDate: new Date() });
+ * await entityClient.update('default', 'tasks', 1, { status: 'done' });
+ * await entityClient.delete('default', 'tasks', 1);
+ * ```
+ *
+ * ## Date Handling
+ * Date values are automatically converted to backend-compatible format:
+ * - Date objects: `new Date()` → `"2026-01-05 10:30:45"`
+ * - ISO 8601 strings: `"2026-01-05T00:00:00.000Z"` → `"2026-01-05 00:00:00"`
+ * - Works in nested objects and arrays
+ *
+ * ## Filter Operators
+ * eq, ne, gt, ge, lt, le, like, sw, ew, bt, in
+ *
+ * Usage: `{ 'field[op]': value }` or `{ field: value }` (eq is default)
+ */
+type EntityClient = {
+    list<T = Record<string, unknown>>(source: string, entity: string, params?: EntityQueryParams): Promise<ClientResult<EntityListResponse<T>>>;
+    get<T = Record<string, unknown>>(source: string, entity: string, id: string | number): Promise<ClientResult<T>>;
+    create<T = Record<string, unknown>>(source: string, entity: string, data: Record<string, unknown>): Promise<ClientResult<T>>;
+    update<T = Record<string, unknown>>(source: string, entity: string, id: string | number, data: Record<string, unknown>): Promise<ClientResult<T>>;
+    delete(source: string, entity: string, id: string | number): Promise<ClientResult<null>>;
+    options<T = Record<string, unknown>>(source: string, entity: string, fields?: string[]): Promise<ClientResult<T[]>>;
+    bulkUpdate<T = Record<string, unknown>>(source: string, entity: string, items: Array<Record<string, unknown> & {
+        id: string | number;
+    }>): Promise<ClientResult<T>>;
+    bulkDelete(source: string, entity: string, ids: Array<string | number>): Promise<ClientResult<null>>;
+};
+declare function createEntityClient(http?: HttpClient): EntityClient;
+
+export { type EntityClient, type EntityListResponse, type EntityQueryParams, type FilterGroup, type FilterItem, type FilterOperator, createEntityClient };

package/dist/index.js

@@ -0,0 +1,235 @@
+import { createHttpClient } from '@amaster.ai/http-client';
+
+// src/entity-client.ts
+function formatDateForBackend(date) {
+  let dateObj;
+  if (date instanceof Date) {
+    dateObj = date;
+  } else if (typeof date === "string") {
+    dateObj = new Date(date);
+  } else {
+    dateObj = new Date(date);
+  }
+  if (Number.isNaN(dateObj.getTime())) {
+    return String(date);
+  }
+  const year = dateObj.getUTCFullYear();
+  const month = String(dateObj.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(dateObj.getUTCDate()).padStart(2, "0");
+  const hours = String(dateObj.getUTCHours()).padStart(2, "0");
+  const minutes = String(dateObj.getUTCMinutes()).padStart(2, "0");
+  const seconds = String(dateObj.getUTCSeconds()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+function processDataForBackend(data) {
+  if (data === null || data === void 0) {
+    return data;
+  }
+  if (data instanceof Date) {
+    return formatDateForBackend(data);
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => processDataForBackend(item));
+  }
+  if (typeof data === "object") {
+    const processed = {};
+    for (const [key, value] of Object.entries(data)) {
+      processed[key] = processDataForBackend(value);
+    }
+    return processed;
+  }
+  if (typeof data === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(data)) {
+    return formatDateForBackend(data);
+  }
+  return data;
+}
+function buildEntityUrl(source, entity, path = "") {
+  const basePath = `/api/entity/data/${source}/${entity}`;
+  return path ? `${basePath}${path.startsWith("/") ? path : `/${path}`}` : basePath;
+}
+function encodeQueryParams(params) {
+  if (!params || Object.keys(params).length === 0) {
+    return "";
+  }
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (key === "__filter" && typeof value === "object") {
+      searchParams.append(key, JSON.stringify(value));
+    } else if (key === "__relations" && Array.isArray(value)) {
+      for (const v of value) {
+        searchParams.append("__relations[]", String(v));
+      }
+    } else if (Array.isArray(value)) {
+      for (const v of value) {
+        searchParams.append(key, String(v));
+      }
+    } else if (typeof value === "object" && !Array.isArray(value)) {
+      for (const [subKey, subValue] of Object.entries(value)) {
+        if (subValue !== void 0 && subValue !== null) {
+          searchParams.append(`${key}[${subKey}]`, String(subValue));
+        }
+      }
+    } else {
+      searchParams.append(key, String(value));
+    }
+  }
+  const query = searchParams.toString();
+  return query ? `?${query}` : "";
+}
+function createEntityClient(http = createHttpClient()) {
+  return {
+    async list(source, entity, params) {
+      const url = buildEntityUrl(source, entity) + encodeQueryParams(params);
+      const result = await http.request({
+        url,
+        method: "get"
+      });
+      if (result.error || !result.data) {
+        return {
+          data: { items: [], total: 0 },
+          error: result.error,
+          status: result.status
+        };
+      }
+      const items = Array.isArray(result.data.items) ? result.data.items : [];
+      const total = result.data.total ?? result.data.count ?? items.length;
+      return {
+        ...result,
+        data: {
+          items,
+          total,
+          page: result.data.page,
+          perPage: result.data.perPage || result.data.pageSize
+        }
+      };
+    },
+    get(source, entity, id) {
+      if (!id) {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity ID is required", status: 400 },
+          status: 400
+        });
+      }
+      const url = buildEntityUrl(source, entity, `/${id}`);
+      return http.request({
+        url,
+        method: "get"
+      });
+    },
+    create(source, entity, data) {
+      if (!data || typeof data !== "object") {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity data is required", status: 400 },
+          status: 400
+        });
+      }
+      const processedData = processDataForBackend(data);
+      const url = buildEntityUrl(source, entity);
+      return http.request({
+        url,
+        method: "post",
+        headers: { "Content-Type": "application/json" },
+        data: processedData
+      });
+    },
+    update(source, entity, id, data) {
+      if (!id) {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity ID is required", status: 400 },
+          status: 400
+        });
+      }
+      if (!data || typeof data !== "object") {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Entity data is required", status: 400 },
+          status: 400
+        });
+      }
+      const processedData = processDataForBackend(data);
+      const url = buildEntityUrl(source, entity, `/${id}`);
+      return http.request({
+        url,
+        method: "put",
+        headers: { "Content-Type": "application/json" },
+        data: processedData
+      });
+    },
+    async delete(source, entity, id) {
+      if (!id) {
+        return {
+          data: null,
+          error: { message: "Entity ID is required", status: 400 },
+          status: 400
+        };
+      }
+      const url = buildEntityUrl(source, entity, `/${id}`);
+      const result = await http.request({
+        url,
+        method: "delete"
+      });
+      return result.status === 204 ? { ...result, data: null } : result;
+    },
+    async options(source, entity, fields) {
+      const params = fields && fields.length > 0 ? { "__fields[]": fields } : void 0;
+      const url = buildEntityUrl(source, entity, "/options") + encodeQueryParams(params);
+      const result = await http.request({
+        url,
+        method: "get"
+      });
+      if (result.error || !result.data) {
+        return {
+          data: null,
+          error: result.error,
+          status: result.status
+        };
+      }
+      return {
+        ...result,
+        data: result.data.items || []
+      };
+    },
+    bulkUpdate(source, entity, items) {
+      if (!items || items.length === 0) {
+        return Promise.resolve({
+          data: null,
+          error: { message: "Items array is required", status: 400 },
+          status: 400
+        });
+      }
+      const processedItems = items.map((item) => processDataForBackend(item));
+      const url = buildEntityUrl(source, entity, "/bulkUpdate");
+      return http.request({
+        url,
+        method: "post",
+        headers: { "Content-Type": "application/json" },
+        data: { items: processedItems }
+      });
+    },
+    async bulkDelete(source, entity, ids) {
+      if (!ids || ids.length === 0) {
+        return {
+          data: null,
+          error: { message: "IDs array is required", status: 400 },
+          status: 400
+        };
+      }
+      const url = buildEntityUrl(source, entity, `/${ids.join(",")}`);
+      const result = await http.request({
+        url,
+        method: "delete"
+      });
+      return result.status === 204 ? { ...result, data: null } : result;
+    }
+  };
+}
+
+export { createEntityClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/entity-client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { type ClientResult, createHttpClient, type HttpClient } from \"@amaster.ai/http-client\";\nimport type { EntityListResponse, EntityQueryParams } from \"./types\";\n\n// Export types for convenience\nexport type { EntityListResponse, EntityQueryParams, FilterGroup, FilterItem, FilterOperator } from \"./types\";\n\n/**\n * Entity Client - Type-safe client for entity CRUD operations\n *\n * ## Quick Start\n * ```typescript\n * const entityClient = createEntityClient();\n *\n * // List with pagination and sorting\n * const result = await entityClient.list('default', 'tasks', {\n *   page: 1,\n *   perPage: 20,\n *   orderBy: 'createdAt',\n *   orderDir: 'desc'\n * });\n *\n * // ⚠️ IMPORTANT: Access items via result.data.items, NOT result.data\n * setTasks(result.data?.items || []);  // ✅ Correct\n * setTotal(result.data?.total || 0);\n *\n * // ❌ WRONG: setTasks(result.data || [])  - result.data is an object, not an array!\n *\n * // Get single record\n * const task = await entityClient.get('default', 'tasks', 1);\n * setTask(result.data);  // ✅ result.data is the entity object directly\n *\n * // CRUD operations\n * await entityClient.create('default', 'tasks', { title: 'New', dueDate: new Date() });\n * await entityClient.update('default', 'tasks', 1, { status: 'done' });\n * await entityClient.delete('default', 'tasks', 1);\n * ```\n *\n * ## Date Handling\n * Date values are automatically converted to backend-compatible format:\n * - Date objects: `new Date()` → `\"2026-01-05 10:30:45\"`\n * - ISO 8601 strings: `\"2026-01-05T00:00:00.000Z\"` → `\"2026-01-05 00:00:00\"`\n * - Works in nested objects and arrays\n *\n * ## Filter Operators\n * eq, ne, gt, ge, lt, le, like, sw, ew, bt, in\n *\n * Usage: `{ 'field[op]': value }` or `{ field: value }` (eq is default)\n */\nexport type EntityClient = {\n  list<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    params?: EntityQueryParams\n  ): Promise<ClientResult<EntityListResponse<T>>>;\n  get<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    id: string | number\n  ): Promise<ClientResult<T>>;\n  create<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    data: Record<string, unknown>\n  ): Promise<ClientResult<T>>;\n  update<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    id: string | number,\n    data: Record<string, unknown>\n  ): Promise<ClientResult<T>>;\n  delete(source: string, entity: string, id: string | number): Promise<ClientResult<null>>;\n  options<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    fields?: string[]\n  ): Promise<ClientResult<T[]>>;\n  bulkUpdate<T = Record<string, unknown>>(\n    source: string,\n    entity: string,\n    items: Array<Record<string, unknown> & { id: string | number }>\n  ): Promise<ClientResult<T>>;\n  bulkDelete(\n    source: string,\n    entity: string,\n    ids: Array<string | number>\n  ): Promise<ClientResult<null>>;\n};\n\n// ==================== Helper Functions ====================\n\n/**\n * Convert Date object or ISO 8601 string to backend-compatible DATETIME format\n * Backend expects: \"YYYY-MM-DD HH:MM:SS\" (space-separated, no T or Z)\n */\nfunction formatDateForBackend(date: Date | string): string {\n  let dateObj: Date;\n\n  if (date instanceof Date) {\n    dateObj = date;\n  } else if (typeof date === \"string\") {\n    dateObj = new Date(date);\n  } else {\n    dateObj = new Date(date);\n  }\n\n  // Check if date is valid\n  if (Number.isNaN(dateObj.getTime())) {\n    return String(date); // Return original value if invalid\n  }\n\n  // Format as \"YYYY-MM-DD HH:MM:SS\" in UTC\n  const year = dateObj.getUTCFullYear();\n  const month = String(dateObj.getUTCMonth() + 1).padStart(2, \"0\");\n  const day = String(dateObj.getUTCDate()).padStart(2, \"0\");\n  const hours = String(dateObj.getUTCHours()).padStart(2, \"0\");\n  const minutes = String(dateObj.getUTCMinutes()).padStart(2, \"0\");\n  const seconds = String(dateObj.getUTCSeconds()).padStart(2, \"0\");\n\n  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;\n}\n\n/**\n * Recursively process data object to convert Date values to backend format\n * Handles nested objects and arrays\n */\nfunction processDataForBackend(data: unknown): unknown {\n  if (data === null || data === undefined) {\n    return data;\n  }\n\n  // Handle Date objects\n  if (data instanceof Date) {\n    return formatDateForBackend(data);\n  }\n\n  // Handle arrays\n  if (Array.isArray(data)) {\n    return data.map((item) => processDataForBackend(item));\n  }\n\n  // Handle objects\n  if (typeof data === \"object\") {\n    const processed: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(data)) {\n      processed[key] = processDataForBackend(value);\n    }\n    return processed;\n  }\n\n  // Handle ISO 8601 date strings (detect pattern)\n  if (typeof data === \"string\" && /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}/.test(data)) {\n    return formatDateForBackend(data);\n  }\n\n  return data;\n}\n\nfunction buildEntityUrl(source: string, entity: string, path = \"\"): string {\n  const basePath = `/api/entity/data/${source}/${entity}`;\n  return path ? `${basePath}${path.startsWith(\"/\") ? path : `/${path}`}` : basePath;\n}\n\nfunction encodeQueryParams(params?: Record<string, unknown>): string {\n  if (!params || Object.keys(params).length === 0) {\n    return \"\";\n  }\n\n  const searchParams = new URLSearchParams();\n\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined || value === null) {\n      continue;\n    }\n\n    if (key === \"__filter\" && typeof value === \"object\") {\n      searchParams.append(key, JSON.stringify(value));\n    } else if (key === \"__relations\" && Array.isArray(value)) {\n      for (const v of value) {\n        searchParams.append(\"__relations[]\", String(v));\n      }\n    } else if (Array.isArray(value)) {\n      for (const v of value) {\n        searchParams.append(key, String(v));\n      }\n    } else if (typeof value === \"object\" && !Array.isArray(value)) {\n      for (const [subKey, subValue] of Object.entries(value)) {\n        if (subValue !== undefined && subValue !== null) {\n          searchParams.append(`${key}[${subKey}]`, String(subValue));\n        }\n      }\n    } else {\n      searchParams.append(key, String(value));\n    }\n  }\n\n  const query = searchParams.toString();\n  return query ? `?${query}` : \"\";\n}\n\n// ==================== Client Factory ====================\n\nexport function createEntityClient(http: HttpClient = createHttpClient()): EntityClient {\n  return {\n    async list<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      params?: EntityQueryParams\n    ): Promise<ClientResult<EntityListResponse<T>>> {\n      const url = buildEntityUrl(source, entity) + encodeQueryParams(params);\n      const result = await http.request<{\n        items: T[];\n        count?: number;\n        total?: number;\n        page?: number;\n        perPage?: number;\n        pageSize?: number;\n      }>({\n        url,\n        method: \"get\",\n      });\n\n      if (result.error || !result.data) {\n        return {\n          data: { items: [], total: 0 },\n          error: result.error,\n          status: result.status,\n        };\n      }\n\n      const items = Array.isArray(result.data.items) ? result.data.items : [];\n      const total = result.data.total ?? result.data.count ?? items.length;\n\n      return {\n        ...result,\n        data: {\n          items,\n          total,\n          page: result.data.page,\n          perPage: result.data.perPage || result.data.pageSize,\n        },\n      };\n    },\n\n    get<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      id: string | number\n    ): Promise<ClientResult<T>> {\n      if (!id) {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity ID is required\", status: 400 },\n          status: 400,\n        });\n      }\n      const url = buildEntityUrl(source, entity, `/${id}`);\n      return http.request<T>({\n        url,\n        method: \"get\",\n      });\n    },\n\n    create<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      data: Record<string, unknown>\n    ): Promise<ClientResult<T>> {\n      if (!data || typeof data !== \"object\") {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity data is required\", status: 400 },\n          status: 400,\n        });\n      }\n\n      const processedData = processDataForBackend(data);\n\n      const url = buildEntityUrl(source, entity);\n      return http.request<T>({\n        url,\n        method: \"post\",\n        headers: { \"Content-Type\": \"application/json\" },\n        data: processedData,\n      });\n    },\n\n    update<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      id: string | number,\n      data: Record<string, unknown>\n    ): Promise<ClientResult<T>> {\n      if (!id) {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity ID is required\", status: 400 },\n          status: 400,\n        });\n      }\n      if (!data || typeof data !== \"object\") {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Entity data is required\", status: 400 },\n          status: 400,\n        });\n      }\n\n      const processedData = processDataForBackend(data);\n\n      const url = buildEntityUrl(source, entity, `/${id}`);\n      return http.request<T>({\n        url,\n        method: \"put\",\n        headers: { \"Content-Type\": \"application/json\" },\n        data: processedData,\n      });\n    },\n\n    async delete(source: string, entity: string, id: string | number): Promise<ClientResult<null>> {\n      if (!id) {\n        return {\n          data: null,\n          error: { message: \"Entity ID is required\", status: 400 },\n          status: 400,\n        };\n      }\n      const url = buildEntityUrl(source, entity, `/${id}`);\n      const result = await http.request<null>({\n        url,\n        method: \"delete\",\n      });\n      return result.status === 204 ? { ...result, data: null } : result;\n    },\n\n    async options<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      fields?: string[]\n    ): Promise<ClientResult<T[]>> {\n      const params = fields && fields.length > 0 ? { \"__fields[]\": fields } : undefined;\n\n      const url = buildEntityUrl(source, entity, \"/options\") + encodeQueryParams(params);\n      const result = await http.request<{ items: T[] }>({\n        url,\n        method: \"get\",\n      });\n\n      if (result.error || !result.data) {\n        return {\n          data: null,\n          error: result.error,\n          status: result.status,\n        };\n      }\n\n      return {\n        ...result,\n        data: result.data.items || [],\n      };\n    },\n\n    bulkUpdate<T = Record<string, unknown>>(\n      source: string,\n      entity: string,\n      items: Array<Record<string, unknown> & { id: string | number }>\n    ): Promise<ClientResult<T>> {\n      if (!items || items.length === 0) {\n        return Promise.resolve({\n          data: null,\n          error: { message: \"Items array is required\", status: 400 },\n          status: 400,\n        });\n      }\n\n      const processedItems = items.map((item) => processDataForBackend(item));\n\n      const url = buildEntityUrl(source, entity, \"/bulkUpdate\");\n      return http.request<T>({\n        url,\n        method: \"post\",\n        headers: { \"Content-Type\": \"application/json\" },\n        data: { items: processedItems },\n      });\n    },\n\n    async bulkDelete(\n      source: string,\n      entity: string,\n      ids: Array<string | number>\n    ): Promise<ClientResult<null>> {\n      if (!ids || ids.length === 0) {\n        return {\n          data: null,\n          error: { message: \"IDs array is required\", status: 400 },\n          status: 400,\n        };\n      }\n\n      const url = buildEntityUrl(source, entity, `/${ids.join(\",\")}`);\n      const result = await http.request<null>({\n        url,\n        method: \"delete\",\n      });\n\n      return result.status === 204 ? { ...result, data: null } : result;\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@amaster.ai/entity-client",
+  "version": "1.0.0-beta.0",
+  "description": "Type-safe CRUD client for entity data management",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "entity",
+    "crud",
+    "api",
+    "client",
+    "typescript"
+  ],
+  "author": "Amaster Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@amaster.ai/http-client": "1.0.0-beta.0"
+  },
+  "peerDependencies": {
+    "axios": "^1.11.0"
+  },
+  "devDependencies": {
+    "axios": "^1.11.0",
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "type-check": "tsc --noEmit"
+  }
+}