@amaster.ai/http-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,170 @@
+# @amaster.ai/http-client
+
+Base HTTP client with error handling and response unwrapping for backend API communication.
+
+## Features
+
+- 🔄 Automatic backend response unwrapping (`{ status: 0, data: {...} }` → `{...}`)
+- 📅 Backend datetime format conversion (`"2026-01-05 10:30:45"` → `"2026-01-05T10:30:45.000Z"`)
+- ⚠️ Consistent error handling with normalized error messages
+- 🔌 Built on Axios with full TypeScript support
+- 🌳 Tree-shakeable ESM/CJS builds
+
+## Installation
+
+```bash
+pnpm add @amaster.ai/http-client axios
+```
+
+> **Note:** `axios` is a peer dependency and must be installed separately.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createHttpClient } from "@amaster.ai/http-client";
+
+const client = createHttpClient();
+
+const result = await client.request({
+  url: "/api/users",
+  method: "get",
+});
+
+if (result.data) {
+  console.log(result.data);
+} else {
+  console.error(result.error.message);
+}
+```
+
+### With Custom Axios Instance
+
+```typescript
+import axios from "axios";
+import { createHttpClient } from "@amaster.ai/http-client";
+
+const instance = axios.create({
+  baseURL: "https://api.example.com",
+  timeout: 5000,
+  headers: {
+    "Authorization": "Bearer token",
+  },
+});
+
+const client = createHttpClient(instance);
+```
+
+### Response Format
+
+All requests return a `ClientResult<T>`:
+
+```typescript
+type ClientResult<T> = {
+  data: T | null;       // Response data (null on error)
+  error: ClientError | null;  // Error details (null on success)
+  status: number;       // HTTP status code
+};
+```
+
+### Error Handling
+
+```typescript
+const result = await client.request({
+  url: "/api/users/123",
+  method: "get",
+});
+
+if (result.error) {
+  console.error("Error:", result.error.message);
+  console.error("Status:", result.error.status);
+  console.error("Details:", result.error.details);
+}
+```
+
+## Features in Detail
+
+### Backend Response Unwrapping
+
+The client automatically unwraps backend standard response format:
+
+```typescript
+// Backend returns:
+{
+  "status": 0,
+  "data": { "id": 1, "name": "John" }
+}
+
+// Client returns:
+{
+  data: { "id": 1, "name": "John" },
+  error: null,
+  status: 200
+}
+```
+
+### Datetime Conversion
+
+Backend datetime strings are automatically converted to ISO 8601 format:
+
+```typescript
+// Backend returns:
+{
+  "createdAt": "2026-01-05 10:30:45"
+}
+
+// Client returns:
+{
+  "createdAt": "2026-01-05T10:30:45.000Z"
+}
+```
+
+This works recursively for nested objects and arrays.
+
+### Error Normalization
+
+The client normalizes various backend error formats:
+
+```typescript
+// Backend may return any of:
+{ "message": "Error" }
+{ "error": "Error" }
+{ "msg": "Error" }
+{ "detail": "Error" }
+
+// Client always returns:
+{
+  error: {
+    message: "Error",
+    status: 400,
+    details: { /* original response */ }
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with generic types:
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const result = await client.request<User>({
+  url: "/api/users/1",
+  method: "get",
+});
+
+if (result.data) {
+  // result.data is typed as User
+  console.log(result.data.name);
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+// src/http.ts
+function normalizeErrorMessage(payload) {
+  if (!payload) {
+    return "Request failed";
+  }
+  if (typeof payload === "string") {
+    return payload;
+  }
+  if (typeof payload === "object") {
+    const errorPayload = payload;
+    return errorPayload.message || errorPayload.error || errorPayload.msg || errorPayload.detail || "Request failed";
+  }
+  return "Request failed";
+}
+function isBackendStandardFormat(data) {
+  if (!data || typeof data !== "object" || !("data" in data)) {
+    return false;
+  }
+  if ("status" in data) {
+    const status = data.status;
+    return status === 0 || status === 1 || status === "0" || status === "1";
+  }
+  return false;
+}
+function unwrapBackendResponse(responseData) {
+  if (isBackendStandardFormat(responseData)) {
+    return responseData.data;
+  }
+  return responseData;
+}
+var BACKEND_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+function isBackendDatetime(value) {
+  return BACKEND_DATETIME_REGEX.test(value);
+}
+function parseBackendDatetime(value) {
+  return `${value.replace(" ", "T")}.000Z`;
+}
+function processResponseDates(data) {
+  if (data === null || data === void 0) {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => processResponseDates(item));
+  }
+  if (typeof data === "object") {
+    const processed = {};
+    for (const [key, value] of Object.entries(data)) {
+      processed[key] = processResponseDates(value);
+    }
+    return processed;
+  }
+  if (typeof data === "string" && isBackendDatetime(data)) {
+    return parseBackendDatetime(data);
+  }
+  return data;
+}
+function createHttpClient(axiosInstance) {
+  let instance = axiosInstance;
+  return {
+    async request(config) {
+      if (!instance) {
+        const axios = await import('axios');
+        instance = axios.default.create();
+      }
+      try {
+        const resp = await instance(config);
+        const status = resp?.status ?? 0;
+        if (status >= 200 && status < 300) {
+          const unwrappedData = unwrapBackendResponse(resp?.data);
+          const processedData = processResponseDates(unwrappedData);
+          return { data: processedData ?? null, error: null, status };
+        }
+        return {
+          data: null,
+          error: {
+            status,
+            message: normalizeErrorMessage(resp?.data) || `HTTP ${status}`,
+            details: resp?.data
+          },
+          status
+        };
+      } catch (error_) {
+        const error = error_;
+        const status = error.response?.status || 0;
+        return {
+          data: null,
+          error: {
+            status,
+            message: normalizeErrorMessage(error.response?.data) || error.message || "Network error",
+            details: error.response?.data
+          },
+          status
+        };
+      }
+    }
+  };
+}
+
+exports.createHttpClient = createHttpClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { AxiosInstance, AxiosRequestConfig } from \"axios\";\n\nexport type ClientError = {\n  message: string;\n  status?: number;\n  code?: string;\n  details?: unknown;\n};\n\nexport type ClientResult<T> = {\n  data: T | null;\n  error: ClientError | null;\n  status: number;\n};\n\nexport type HttpClient = {\n  request<T>(\n    config: AxiosRequestConfig & {\n      url: string;\n      method: NonNullable<AxiosRequestConfig[\"method\"]>;\n    }\n  ): Promise<ClientResult<T>>;\n};\n\ninterface ErrorPayload {\n  message?: string;\n  error?: string;\n  msg?: string;\n  detail?: string;\n}\n\nfunction normalizeErrorMessage(payload: unknown): string {\n  if (!payload) {\n    return \"Request failed\";\n  }\n  if (typeof payload === \"string\") {\n    return payload;\n  }\n  if (typeof payload === \"object\") {\n    const errorPayload = payload as ErrorPayload;\n    return (\n      errorPayload.message ||\n      errorPayload.error ||\n      errorPayload.msg ||\n      errorPayload.detail ||\n      \"Request failed\"\n    );\n  }\n  return \"Request failed\";\n}\n\ninterface BackendStandardResponse {\n  status: number | string;\n  data: unknown;\n}\n\n/**\n * Check if response data matches backend standard format: { status: 0/1, data: {...} }\n * Handles both number and string status values\n */\nfunction isBackendStandardFormat(data: unknown): data is BackendStandardResponse {\n  if (!data || typeof data !== \"object\" || !(\"data\" in data)) {\n    return false;\n  }\n\n  // Check status field - handle both number and string values\n  if (\"status\" in data) {\n    const status = (data as BackendStandardResponse).status;\n    // Accept 0, 1, \"0\", \"1\" as valid status values\n    return status === 0 || status === 1 || status === \"0\" || status === \"1\";\n  }\n\n  return false;\n}\n\n/**\n * Unwrap backend standard format response\n * Backend returns: { status: 0, data: {...} }\n * We extract the inner 'data' field for cleaner client usage\n */\nfunction unwrapBackendResponse<T>(responseData: unknown): T {\n  if (isBackendStandardFormat(responseData)) {\n    // Extract inner data field\n    return responseData.data as T;\n  }\n  // Return as-is if not standard format (e.g., BPM/Workflow APIs)\n  return responseData as T;\n}\n\n/**\n * Backend datetime format regex: \"YYYY-MM-DD HH:MM:SS\"\n */\nconst BACKEND_DATETIME_REGEX = /^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$/;\n\n/**\n * Check if a string matches backend datetime format\n */\nfunction isBackendDatetime(value: string): boolean {\n  return BACKEND_DATETIME_REGEX.test(value);\n}\n\n/**\n * Convert backend datetime string to ISO 8601 format\n * \"2026-01-05 10:30:45\" → \"2026-01-05T10:30:45.000Z\"\n */\nfunction parseBackendDatetime(value: string): string {\n  // Replace space with T and append Z for UTC\n  return `${value.replace(\" \", \"T\")}.000Z`;\n}\n\n/**\n * Recursively process response data to convert backend datetime strings to ISO format\n * Handles nested objects and arrays\n */\nfunction processResponseDates(data: unknown): unknown {\n  if (data === null || data === undefined) {\n    return data;\n  }\n\n  // Handle arrays\n  if (Array.isArray(data)) {\n    return data.map((item) => processResponseDates(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] = processResponseDates(value);\n    }\n    return processed;\n  }\n\n  // Handle backend datetime strings\n  if (typeof data === \"string\" && isBackendDatetime(data)) {\n    return parseBackendDatetime(data);\n  }\n\n  return data;\n}\n\n/**\n * Create an HTTP client instance\n * \n * @param axiosInstance - Optional axios instance to use (defaults to a basic axios instance)\n * @returns HttpClient with request method\n * \n * @example\n * ```typescript\n * import axios from \"axios\";\n * import { createHttpClient } from \"@amaster.ai/http-client\";\n * \n * const instance = axios.create({ baseURL: \"https://api.example.com\" });\n * const client = createHttpClient(instance);\n * \n * const result = await client.request({\n *   url: \"/users\",\n *   method: \"get\",\n * });\n * ```\n */\nexport function createHttpClient(axiosInstance?: AxiosInstance): HttpClient {\n  // Import axios dynamically to avoid bundling it\n  let instance = axiosInstance;\n  \n  return {\n    async request<T>(\n      config: AxiosRequestConfig & {\n        url: string;\n        method: NonNullable<AxiosRequestConfig[\"method\"]>;\n      }\n    ) {\n      // Lazy load axios if not provided\n      if (!instance) {\n        const axios = await import(\"axios\");\n        instance = axios.default.create();\n      }\n\n      try {\n        const resp = await instance(config);\n        const status = resp?.status ?? 0;\n\n        if (status >= 200 && status < 300) {\n          // Unwrap backend standard format: { status: 0, data: {...} } -> {...}\n          const unwrappedData = unwrapBackendResponse<T>(resp?.data);\n          // Convert backend datetime strings to ISO format\n          const processedData = processResponseDates(unwrappedData);\n          return { data: (processedData ?? null) as T | null, error: null, status };\n        }\n\n        return {\n          data: null,\n          error: {\n            status,\n            message: normalizeErrorMessage(resp?.data) || `HTTP ${status}`,\n            details: resp?.data,\n          },\n          status,\n        };\n      } catch (error_: unknown) {\n        // Catch network errors, timeouts, and other axios exceptions\n        const error = error_ as {\n          response?: { status?: number; data?: unknown };\n          message?: string;\n        };\n        const status = error.response?.status || 0;\n        return {\n          data: null,\n          error: {\n            status,\n            message:\n              normalizeErrorMessage(error.response?.data) || error.message || \"Network error\",\n            details: error.response?.data,\n          },\n          status,\n        };\n      }\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+
+type ClientError = {
+    message: string;
+    status?: number;
+    code?: string;
+    details?: unknown;
+};
+type ClientResult<T> = {
+    data: T | null;
+    error: ClientError | null;
+    status: number;
+};
+type HttpClient = {
+    request<T>(config: AxiosRequestConfig & {
+        url: string;
+        method: NonNullable<AxiosRequestConfig["method"]>;
+    }): Promise<ClientResult<T>>;
+};
+/**
+ * Create an HTTP client instance
+ *
+ * @param axiosInstance - Optional axios instance to use (defaults to a basic axios instance)
+ * @returns HttpClient with request method
+ *
+ * @example
+ * ```typescript
+ * import axios from "axios";
+ * import { createHttpClient } from "@amaster.ai/http-client";
+ *
+ * const instance = axios.create({ baseURL: "https://api.example.com" });
+ * const client = createHttpClient(instance);
+ *
+ * const result = await client.request({
+ *   url: "/users",
+ *   method: "get",
+ * });
+ * ```
+ */
+declare function createHttpClient(axiosInstance?: AxiosInstance): HttpClient;
+
+export { type ClientError, type ClientResult, type HttpClient, createHttpClient };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+
+type ClientError = {
+    message: string;
+    status?: number;
+    code?: string;
+    details?: unknown;
+};
+type ClientResult<T> = {
+    data: T | null;
+    error: ClientError | null;
+    status: number;
+};
+type HttpClient = {
+    request<T>(config: AxiosRequestConfig & {
+        url: string;
+        method: NonNullable<AxiosRequestConfig["method"]>;
+    }): Promise<ClientResult<T>>;
+};
+/**
+ * Create an HTTP client instance
+ *
+ * @param axiosInstance - Optional axios instance to use (defaults to a basic axios instance)
+ * @returns HttpClient with request method
+ *
+ * @example
+ * ```typescript
+ * import axios from "axios";
+ * import { createHttpClient } from "@amaster.ai/http-client";
+ *
+ * const instance = axios.create({ baseURL: "https://api.example.com" });
+ * const client = createHttpClient(instance);
+ *
+ * const result = await client.request({
+ *   url: "/users",
+ *   method: "get",
+ * });
+ * ```
+ */
+declare function createHttpClient(axiosInstance?: AxiosInstance): HttpClient;
+
+export { type ClientError, type ClientResult, type HttpClient, createHttpClient };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/http.ts
+function normalizeErrorMessage(payload) {
+  if (!payload) {
+    return "Request failed";
+  }
+  if (typeof payload === "string") {
+    return payload;
+  }
+  if (typeof payload === "object") {
+    const errorPayload = payload;
+    return errorPayload.message || errorPayload.error || errorPayload.msg || errorPayload.detail || "Request failed";
+  }
+  return "Request failed";
+}
+function isBackendStandardFormat(data) {
+  if (!data || typeof data !== "object" || !("data" in data)) {
+    return false;
+  }
+  if ("status" in data) {
+    const status = data.status;
+    return status === 0 || status === 1 || status === "0" || status === "1";
+  }
+  return false;
+}
+function unwrapBackendResponse(responseData) {
+  if (isBackendStandardFormat(responseData)) {
+    return responseData.data;
+  }
+  return responseData;
+}
+var BACKEND_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+function isBackendDatetime(value) {
+  return BACKEND_DATETIME_REGEX.test(value);
+}
+function parseBackendDatetime(value) {
+  return `${value.replace(" ", "T")}.000Z`;
+}
+function processResponseDates(data) {
+  if (data === null || data === void 0) {
+    return data;
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => processResponseDates(item));
+  }
+  if (typeof data === "object") {
+    const processed = {};
+    for (const [key, value] of Object.entries(data)) {
+      processed[key] = processResponseDates(value);
+    }
+    return processed;
+  }
+  if (typeof data === "string" && isBackendDatetime(data)) {
+    return parseBackendDatetime(data);
+  }
+  return data;
+}
+function createHttpClient(axiosInstance) {
+  let instance = axiosInstance;
+  return {
+    async request(config) {
+      if (!instance) {
+        const axios = await import('axios');
+        instance = axios.default.create();
+      }
+      try {
+        const resp = await instance(config);
+        const status = resp?.status ?? 0;
+        if (status >= 200 && status < 300) {
+          const unwrappedData = unwrapBackendResponse(resp?.data);
+          const processedData = processResponseDates(unwrappedData);
+          return { data: processedData ?? null, error: null, status };
+        }
+        return {
+          data: null,
+          error: {
+            status,
+            message: normalizeErrorMessage(resp?.data) || `HTTP ${status}`,
+            details: resp?.data
+          },
+          status
+        };
+      } catch (error_) {
+        const error = error_;
+        const status = error.response?.status || 0;
+        return {
+          data: null,
+          error: {
+            status,
+            message: normalizeErrorMessage(error.response?.data) || error.message || "Network error",
+            details: error.response?.data
+          },
+          status
+        };
+      }
+    }
+  };
+}
+
+export { createHttpClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/http.ts"],"names":[],"mappings":";AA+BA,SAAS,sBAAsB,OAAA,EAA0B;AACvD,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,OAAO,gBAAA;AAAA,EACT;AACA,EAAA,IAAI,OAAO,YAAY,QAAA,EAAU;AAC/B,IAAA,OAAO,OAAA;AAAA,EACT;AACA,EAAA,IAAI,OAAO,YAAY,QAAA,EAAU;AAC/B,IAAA,MAAM,YAAA,GAAe,OAAA;AACrB,IAAA,OACE,aAAa,OAAA,IACb,YAAA,CAAa,SACb,YAAA,CAAa,GAAA,IACb,aAAa,MAAA,IACb,gBAAA;AAAA,EAEJ;AACA,EAAA,OAAO,gBAAA;AACT;AAWA,SAAS,wBAAwB,IAAA,EAAgD;AAC/E,EAAA,IAAI,CAAC,IAAA,IAAQ,OAAO,SAAS,QAAA,IAAY,EAAE,UAAU,IAAA,CAAA,EAAO;AAC1D,IAAA,OAAO,KAAA;AAAA,EACT;AAGA,EAAA,IAAI,YAAY,IAAA,EAAM;AACpB,IAAA,MAAM,SAAU,IAAA,CAAiC,MAAA;AAEjD,IAAA,OAAO,WAAW,CAAA,IAAK,MAAA,KAAW,CAAA,IAAK,MAAA,KAAW,OAAO,MAAA,KAAW,GAAA;AAAA,EACtE;AAEA,EAAA,OAAO,KAAA;AACT;AAOA,SAAS,sBAAyB,YAAA,EAA0B;AAC1D,EAAA,IAAI,uBAAA,CAAwB,YAAY,CAAA,EAAG;AAEzC,IAAA,OAAO,YAAA,CAAa,IAAA;AAAA,EACtB;AAEA,EAAA,OAAO,YAAA;AACT;AAKA,IAAM,sBAAA,GAAyB,uCAAA;AAK/B,SAAS,kBAAkB,KAAA,EAAwB;AACjD,EAAA,OAAO,sBAAA,CAAuB,KAAK,KAAK,CAAA;AAC1C;AAMA,SAAS,qBAAqB,KAAA,EAAuB;AAEnD,EAAA,OAAO,CAAA,EAAG,KAAA,CAAM,OAAA,CAAQ,GAAA,EAAK,GAAG,CAAC,CAAA,KAAA,CAAA;AACnC;AAMA,SAAS,qBAAqB,IAAA,EAAwB;AACpD,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,MAAA,EAAW;AACvC,IAAA,OAAO,IAAA;AAAA,EACT;AAGA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA,EAAG;AACvB,IAAA,OAAO,KAAK,GAAA,CAAI,CAAC,IAAA,KAAS,oBAAA,CAAqB,IAAI,CAAC,CAAA;AAAA,EACtD;AAGA,EAAA,IAAI,OAAO,SAAS,QAAA,EAAU;AAC5B,IAAA,MAAM,YAAqC,EAAC;AAC5C,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAA,EAAG;AAC/C,MAAA,SAAA,CAAU,GAAG,CAAA,GAAI,oBAAA,CAAqB,KAAK,CAAA;AAAA,IAC7C;AACA,IAAA,OAAO,SAAA;AAAA,EACT;AAGA,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,iBAAA,CAAkB,IAAI,CAAA,EAAG;AACvD,IAAA,OAAO,qBAAqB,IAAI,CAAA;AAAA,EAClC;AAEA,EAAA,OAAO,IAAA;AACT;AAsBO,SAAS,iBAAiB,aAAA,EAA2C;AAE1E,EAAA,IAAI,QAAA,GAAW,aAAA;AAEf,EAAA,OAAO;AAAA,IACL,MAAM,QACJ,MAAA,EAIA;AAEA,MAAA,IAAI,CAAC,QAAA,EAAU;AACb,QAAA,MAAM,KAAA,GAAQ,MAAM,OAAO,OAAO,CAAA;AAClC,QAAA,QAAA,GAAW,KAAA,CAAM,QAAQ,MAAA,EAAO;AAAA,MAClC;AAEA,MAAA,IAAI;AACF,QAAA,MAAM,IAAA,GAAO,MAAM,QAAA,CAAS,MAAM,CAAA;AAClC,QAAA,MAAM,MAAA,GAAS,MAAM,MAAA,IAAU,CAAA;AAE/B,QAAA,IAAI,MAAA,IAAU,GAAA,IAAO,MAAA,GAAS,GAAA,EAAK;AAEjC,UAAA,MAAM,aAAA,GAAgB,qBAAA,CAAyB,IAAA,EAAM,IAAI,CAAA;AAEzD,UAAA,MAAM,aAAA,GAAgB,qBAAqB,aAAa,CAAA;AACxD,UAAA,OAAO,EAAE,IAAA,EAAO,aAAA,IAAiB,IAAA,EAAmB,KAAA,EAAO,MAAM,MAAA,EAAO;AAAA,QAC1E;AAEA,QAAA,OAAO;AAAA,UACL,IAAA,EAAM,IAAA;AAAA,UACN,KAAA,EAAO;AAAA,YACL,MAAA;AAAA,YACA,SAAS,qBAAA,CAAsB,IAAA,EAAM,IAAI,CAAA,IAAK,QAAQ,MAAM,CAAA,CAAA;AAAA,YAC5D,SAAS,IAAA,EAAM;AAAA,WACjB;AAAA,UACA;AAAA,SACF;AAAA,MACF,SAAS,MAAA,EAAiB;AAExB,QAAA,MAAM,KAAA,GAAQ,MAAA;AAId,QAAA,MAAM,MAAA,GAAS,KAAA,CAAM,QAAA,EAAU,MAAA,IAAU,CAAA;AACzC,QAAA,OAAO;AAAA,UACL,IAAA,EAAM,IAAA;AAAA,UACN,KAAA,EAAO;AAAA,YACL,MAAA;AAAA,YACA,SACE,qBAAA,CAAsB,KAAA,CAAM,UAAU,IAAI,CAAA,IAAK,MAAM,OAAA,IAAW,eAAA;AAAA,YAClE,OAAA,EAAS,MAAM,QAAA,EAAU;AAAA,WAC3B;AAAA,UACA;AAAA,SACF;AAAA,MACF;AAAA,IACF;AAAA,GACF;AACF","file":"index.js","sourcesContent":["import type { AxiosInstance, AxiosRequestConfig } from \"axios\";\n\nexport type ClientError = {\n  message: string;\n  status?: number;\n  code?: string;\n  details?: unknown;\n};\n\nexport type ClientResult<T> = {\n  data: T | null;\n  error: ClientError | null;\n  status: number;\n};\n\nexport type HttpClient = {\n  request<T>(\n    config: AxiosRequestConfig & {\n      url: string;\n      method: NonNullable<AxiosRequestConfig[\"method\"]>;\n    }\n  ): Promise<ClientResult<T>>;\n};\n\ninterface ErrorPayload {\n  message?: string;\n  error?: string;\n  msg?: string;\n  detail?: string;\n}\n\nfunction normalizeErrorMessage(payload: unknown): string {\n  if (!payload) {\n    return \"Request failed\";\n  }\n  if (typeof payload === \"string\") {\n    return payload;\n  }\n  if (typeof payload === \"object\") {\n    const errorPayload = payload as ErrorPayload;\n    return (\n      errorPayload.message ||\n      errorPayload.error ||\n      errorPayload.msg ||\n      errorPayload.detail ||\n      \"Request failed\"\n    );\n  }\n  return \"Request failed\";\n}\n\ninterface BackendStandardResponse {\n  status: number | string;\n  data: unknown;\n}\n\n/**\n * Check if response data matches backend standard format: { status: 0/1, data: {...} }\n * Handles both number and string status values\n */\nfunction isBackendStandardFormat(data: unknown): data is BackendStandardResponse {\n  if (!data || typeof data !== \"object\" || !(\"data\" in data)) {\n    return false;\n  }\n\n  // Check status field - handle both number and string values\n  if (\"status\" in data) {\n    const status = (data as BackendStandardResponse).status;\n    // Accept 0, 1, \"0\", \"1\" as valid status values\n    return status === 0 || status === 1 || status === \"0\" || status === \"1\";\n  }\n\n  return false;\n}\n\n/**\n * Unwrap backend standard format response\n * Backend returns: { status: 0, data: {...} }\n * We extract the inner 'data' field for cleaner client usage\n */\nfunction unwrapBackendResponse<T>(responseData: unknown): T {\n  if (isBackendStandardFormat(responseData)) {\n    // Extract inner data field\n    return responseData.data as T;\n  }\n  // Return as-is if not standard format (e.g., BPM/Workflow APIs)\n  return responseData as T;\n}\n\n/**\n * Backend datetime format regex: \"YYYY-MM-DD HH:MM:SS\"\n */\nconst BACKEND_DATETIME_REGEX = /^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$/;\n\n/**\n * Check if a string matches backend datetime format\n */\nfunction isBackendDatetime(value: string): boolean {\n  return BACKEND_DATETIME_REGEX.test(value);\n}\n\n/**\n * Convert backend datetime string to ISO 8601 format\n * \"2026-01-05 10:30:45\" → \"2026-01-05T10:30:45.000Z\"\n */\nfunction parseBackendDatetime(value: string): string {\n  // Replace space with T and append Z for UTC\n  return `${value.replace(\" \", \"T\")}.000Z`;\n}\n\n/**\n * Recursively process response data to convert backend datetime strings to ISO format\n * Handles nested objects and arrays\n */\nfunction processResponseDates(data: unknown): unknown {\n  if (data === null || data === undefined) {\n    return data;\n  }\n\n  // Handle arrays\n  if (Array.isArray(data)) {\n    return data.map((item) => processResponseDates(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] = processResponseDates(value);\n    }\n    return processed;\n  }\n\n  // Handle backend datetime strings\n  if (typeof data === \"string\" && isBackendDatetime(data)) {\n    return parseBackendDatetime(data);\n  }\n\n  return data;\n}\n\n/**\n * Create an HTTP client instance\n * \n * @param axiosInstance - Optional axios instance to use (defaults to a basic axios instance)\n * @returns HttpClient with request method\n * \n * @example\n * ```typescript\n * import axios from \"axios\";\n * import { createHttpClient } from \"@amaster.ai/http-client\";\n * \n * const instance = axios.create({ baseURL: \"https://api.example.com\" });\n * const client = createHttpClient(instance);\n * \n * const result = await client.request({\n *   url: \"/users\",\n *   method: \"get\",\n * });\n * ```\n */\nexport function createHttpClient(axiosInstance?: AxiosInstance): HttpClient {\n  // Import axios dynamically to avoid bundling it\n  let instance = axiosInstance;\n  \n  return {\n    async request<T>(\n      config: AxiosRequestConfig & {\n        url: string;\n        method: NonNullable<AxiosRequestConfig[\"method\"]>;\n      }\n    ) {\n      // Lazy load axios if not provided\n      if (!instance) {\n        const axios = await import(\"axios\");\n        instance = axios.default.create();\n      }\n\n      try {\n        const resp = await instance(config);\n        const status = resp?.status ?? 0;\n\n        if (status >= 200 && status < 300) {\n          // Unwrap backend standard format: { status: 0, data: {...} } -> {...}\n          const unwrappedData = unwrapBackendResponse<T>(resp?.data);\n          // Convert backend datetime strings to ISO format\n          const processedData = processResponseDates(unwrappedData);\n          return { data: (processedData ?? null) as T | null, error: null, status };\n        }\n\n        return {\n          data: null,\n          error: {\n            status,\n            message: normalizeErrorMessage(resp?.data) || `HTTP ${status}`,\n            details: resp?.data,\n          },\n          status,\n        };\n      } catch (error_: unknown) {\n        // Catch network errors, timeouts, and other axios exceptions\n        const error = error_ as {\n          response?: { status?: number; data?: unknown };\n          message?: string;\n        };\n        const status = error.response?.status || 0;\n        return {\n          data: null,\n          error: {\n            status,\n            message:\n              normalizeErrorMessage(error.response?.data) || error.message || \"Network error\",\n            details: error.response?.data,\n          },\n          status,\n        };\n      }\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@amaster.ai/http-client",
+  "version": "1.0.0-beta.0",
+  "description": "Base HTTP client with error handling and response unwrapping",
+  "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": [
+    "http",
+    "client",
+    "axios",
+    "api",
+    "typescript"
+  ],
+  "author": "Amaster Team",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "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"
+  }
+}