@herowcode/utils 1.1.11 → 1.2.2

package/README.md

@@ -11,6 +11,7 @@ A lightweight collection of utility functions for everyday JavaScript/TypeScript
 - 🎯 **Tree-shakable** - Only import what you need
 - 📂 **Scoped exports** - Import from specific modules
 - 🎥 **YouTube utilities** - Extract video IDs, generate URLs, and get video durations
+- 🌐 **API client** - HTTP client with retry logic, authentication, and standardized error handling
 
 ## Installation
 
@@ -24,7 +25,7 @@ yarn add @herowcode/utils
 
 ### Import everything:
 ```typescript
-import { formatDate, capitalize, debounce, extractYouTubeId } from '@herowcode/utils';
+import { formatDate, capitalize, debounce, extractYouTubeId, apiClient } from '@herowcode/utils';
 ```
 
 ### Import by scope:
@@ -34,6 +35,7 @@ import { capitalize, camelCase } from '@herowcode/utils/string';
 import { randomInt } from '@herowcode/utils/number';
 import { debounce, throttle } from '@herowcode/utils/function';
 import { extractYouTubeId, generateYoutubeURL } from '@herowcode/utils/youtube';
+import { apiClient, apiWrapper } from '@herowcode/utils/api';
 ```
 
 ### Examples:
@@ -57,10 +59,135 @@ const embedUrl = generateYoutubeURL({
   embed: true, 
   autoplay: true 
 }); // "https://www.youtube.com/embed/abc123?autoplay=1"
+
+// API utilities
+const client = apiClient({ baseURL: 'https://api.example.com' });
+const result = await client.get('/users', { params: { page: 1 } });
+if (result.error) {
+  console.error('API Error:', result.error.message);
+} else {
+  console.log('Users:', result.data);
+}
 ```
 
 ## API Reference
 
+### API Utilities
+
+#### `apiClient(config?: TApiClientProps)`
+Creates a configured HTTP client with standardized error handling, authentication, retry logic, and response processing.
+
+**Configuration Options:**
+- `baseURL`: Base URL for all requests
+- `onSignoutUnauthorized`: Callback for 401 responses outside sign-in paths
+- `getAccessToken`: Function to retrieve auth tokens
+- `getUserIP`: Function to get user IP for headers
+
+**Methods:**
+- `get<T>(url, options?)`: GET request
+- `post<T>(url, options?)`: POST request  
+- `put<T>(url, options?)`: PUT request
+- `delete<T>(url, options?)`: DELETE request
+- `patch<T>(url, options?)`: PATCH request
+
+**Request Options (`ICustomRequestInit`):**
+- `json`: Data to be JSON-stringified as request body
+- `params`: Query parameters object  
+- `retry`: Retry configuration with limit, methods, status codes, and backoff
+- All standard `RequestInit` options except `body`
+
+```typescript
+import { apiClient } from '@herowcode/utils/api';
+
+// Basic usage
+const client = apiClient({
+  baseURL: 'https://api.example.com',
+  getAccessToken: () => Promise.resolve('token123'),
+  onSignoutUnauthorized: (response) => {
+    // Handle logout
+    console.log('Unauthorized:', response);
+  }
+});
+
+// GET with query parameters
+const result = await client.get('/users', {
+  params: { page: 1, limit: 10 }
+});
+
+// POST with JSON body
+const newUser = await client.post('/users', {
+  json: { name: 'John', email: 'john@example.com' }
+});
+
+// PUT with retry configuration
+const updated = await client.put('/users/123', {
+  json: { name: 'Jane' },
+  retry: {
+    limit: 3,
+    methods: ['put'],
+    statusCodes: [500, 502, 503],
+    backoffLimit: 5000
+  }
+});
+
+// Handle response
+if (result.error) {
+  console.error('API Error:', result.error.message);
+} else {
+  console.log('Data:', result.data);
+}
+```
+
+#### `apiWrapper<T, D>(apiCall: () => Promise<T>, defaultData?: D)`
+Wraps API calls with standardized error handling and returns a consistent result object.
+
+**Returns:** `{ data: T | D, error: IApiError | null }`
+
+**Error Types Handled:**
+- `Response` objects (fetch errors)
+- `AxiosError` objects  
+- Standard `Error` objects
+- Unknown error types
+
+**IApiError Properties:**
+- `message`: Error description
+- `status`: HTTP status code (if applicable)
+- `code`: Error code (if available)
+- `details`: Additional error details
+- `path`: Request path (if applicable)
+- `timestamp`: Error timestamp (if provided by API)
+
+```typescript
+import { apiWrapper } from '@herowcode/utils/api';
+
+// Basic usage
+const fetchUser = async (id: string) => {
+  const response = await fetch(`/api/users/${id}`);
+  if (!response.ok) throw response;
+  return response.json();
+};
+
+const result = await apiWrapper(() => fetchUser('123'));
+if (result.error) {
+  console.error('Failed to fetch user:', result.error.message);
+  console.log('Status:', result.error.status);
+} else {
+  console.log('User data:', result.data);
+}
+
+// With default data
+const defaultPosts = [];
+const postsResult = await apiWrapper(() => fetchPosts(), defaultPosts);
+// postsResult.data will be [] instead of null on error
+```
+
+**Features:**
+- Automatic error type detection and standardization
+- Support for fetch Response, Axios, and standard Error objects
+- Extraction of error details from response bodies
+- Consistent error format across different error types
+- Optional default data for graceful error handling
+
 ### Array Utilities
 
 #### `shuffle<T>(array: T[]): T[]`

package/dist/api/client.d.ts

@@ -0,0 +1,25 @@
+interface ICustomRequestInit extends Omit<RequestInit, "body"> {
+    json?: unknown;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    retry?: {
+        limit?: number;
+        methods?: string[];
+        statusCodes?: number[];
+        backoffLimit?: number;
+    };
+}
+type TApiClientProps = {
+    baseURL?: string;
+    onSignoutUnauthorized?: (response?: unknown) => void;
+    getAccessToken?: () => Promise<string | null>;
+    getUserIP?: () => Promise<string | undefined>;
+};
+export declare const apiClient: (config?: TApiClientProps) => {
+    get: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    post: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    put: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    delete: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    patch: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+};
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAEA,UAAU,kBAAmB,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC;IAC5D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IACrE,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;QAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;QACtB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AAoGD,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qBAAqB,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IACpD,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC7C,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAC9C,CAAA;AAiED,eAAO,MAAM,SAAS,GAAI,SAAS,eAAe;UAMxC,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;WAGrD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;UAGvD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;aAGnD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;YAKvD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;CAGjE,CAAA"}

package/dist/api/index.d.ts

@@ -0,0 +1,3 @@
+export { apiClient } from "./client";
+export type { IApiError } from "./wrapper";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA"}

package/dist/api/wrapper.d.ts

@@ -0,0 +1,27 @@
+import type { TTryCatchResult } from "../function";
+export interface IApiError {
+    message: string;
+    status?: number;
+    code?: string;
+    details?: unknown;
+    path?: string;
+    timestamp?: string;
+}
+/**
+ * Wraps API calls with standardized error handling
+ *
+ * @param apiCall - The API call function to execute
+ * @param defaultData - Optional default value to return when an error occurs
+ * @returns A standardized result object with data or formatted error message
+ *
+ * @example
+ * // Basic usage
+ * const result = await apiWrapper(() => fetchUserData(userId));
+ *
+ * @example
+ * // With default data value
+ * const result = await apiWrapper(() => fetchPosts(), []);
+ * // result.data will be [] instead of null on error
+ */
+export declare function apiWrapper<T, D = null>(apiCall: () => Promise<T>, defaultData?: D): Promise<TTryCatchResult<T, IApiError, D extends null ? null : D>>;
+//# sourceMappingURL=wrapper.d.ts.map

package/dist/api/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../src/api/wrapper.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAGlD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwJD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,EAC1C,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,WAAW,CAAC,EAAE,CAAC,GACd,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAcnE"}

package/dist/cjs/api/client.d.ts

@@ -0,0 +1,25 @@
+interface ICustomRequestInit extends Omit<RequestInit, "body"> {
+    json?: unknown;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    retry?: {
+        limit?: number;
+        methods?: string[];
+        statusCodes?: number[];
+        backoffLimit?: number;
+    };
+}
+type TApiClientProps = {
+    baseURL?: string;
+    onSignoutUnauthorized?: (response?: unknown) => void;
+    getAccessToken?: () => Promise<string | null>;
+    getUserIP?: () => Promise<string | undefined>;
+};
+export declare const apiClient: (config?: TApiClientProps) => {
+    get: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    post: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    put: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    delete: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+    patch: <T = unknown>(url: string, options?: ICustomRequestInit) => Promise<import("..").TTryCatchResult<T, import("./wrapper").IApiError, null>>;
+};
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"AAEA,UAAU,kBAAmB,SAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC;IAC5D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IACrE,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;QAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;QACtB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AAoGD,KAAK,eAAe,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qBAAqB,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IACpD,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC7C,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAC9C,CAAA;AAiED,eAAO,MAAM,SAAS,GAAI,SAAS,eAAe;UAMxC,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;WAGrD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;UAGvD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;aAGnD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;YAKvD,CAAC,iBAAiB,MAAM,YAAY,kBAAkB;CAGjE,CAAA"}

package/dist/cjs/api/client.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiClient = void 0;
+const wrapper_1 = require("./wrapper");
+const defaultRetryConfig = {
+    limit: 5,
+    methods: ["get"],
+    statusCodes: [413],
+    backoffLimit: 3000,
+};
+function buildQueryString(params) {
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+        if (value !== null && value !== undefined) {
+            searchParams.append(key, String(value));
+        }
+    });
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : "";
+}
+async function beforeRequestHook(request, getAccessToken, getUserIP) {
+    const token = await (getAccessToken === null || getAccessToken === void 0 ? void 0 : getAccessToken());
+    const headers = new Headers(request.headers);
+    if (token) {
+        headers.set("Authorization", `Bearer ${token}`);
+    }
+    const userIP = await (getUserIP === null || getUserIP === void 0 ? void 0 : getUserIP());
+    if (userIP) {
+        headers.set("X-User-IP", userIP);
+    }
+    return new Request(request, { headers });
+}
+async function afterResponseHook(request, response, onSignoutUnauthorized) {
+    const possibleSignInPaths = ["signin", "sign-in", "login"];
+    const isSignInPath = possibleSignInPaths.some((path) => request.url.includes(path));
+    const needsBody = response.status === 401 && !isSignInPath;
+    let responseBody = null;
+    let responseBodyFor401 = null;
+    if (needsBody) {
+        const clone = response.clone();
+        try {
+            responseBody = await clone.json();
+            responseBodyFor401 = responseBody;
+        }
+        catch (_a) {
+            responseBody = await clone.text();
+        }
+    }
+    if (response.status === 401 && !isSignInPath) {
+        return onSignoutUnauthorized === null || onSignoutUnauthorized === void 0 ? void 0 : onSignoutUnauthorized(responseBodyFor401);
+    }
+}
+async function fetchWithRetry(input, init) {
+    var _a, _b, _c, _d;
+    const retryConfig = (init === null || init === void 0 ? void 0 : init.retry) || defaultRetryConfig;
+    const method = ((init === null || init === void 0 ? void 0 : init.method) || "GET").toLowerCase();
+    let attempt = 0;
+    while (true) {
+        attempt++;
+        const response = await fetch(input, init);
+        const shouldRetry = ((_a = retryConfig.statusCodes) === null || _a === void 0 ? void 0 : _a.includes(response.status)) &&
+            ((_b = retryConfig.methods) === null || _b === void 0 ? void 0 : _b.includes(method)) &&
+            attempt < ((_c = retryConfig.limit) !== null && _c !== void 0 ? _c : 5);
+        if (!shouldRetry)
+            return response;
+        const backoff = Math.min(2 ** attempt * 100, (_d = retryConfig.backoffLimit) !== null && _d !== void 0 ? _d : 3000);
+        await new Promise((resolve) => setTimeout(resolve, backoff));
+    }
+}
+async function api(config, endpoint, options = {}) {
+    var _a;
+    let url = endpoint.startsWith("http")
+        ? endpoint
+        : `${(_a = config.baseURL) === null || _a === void 0 ? void 0 : _a.replace(/\/$/, "")}/${endpoint.replace(/^\//, "")}`;
+    // Add query parameters if provided
+    if (options.params) {
+        const queryString = buildQueryString(options.params);
+        url += queryString;
+    }
+    // Apply default options
+    const init = {
+        credentials: "include",
+        ...options,
+    };
+    let body;
+    if (options.json) {
+        body = JSON.stringify(options.json);
+        init.headers = {
+            ...init.headers,
+            "Content-Type": "application/json",
+        };
+    }
+    // Create initial request
+    let request = new Request(url, { ...init, body });
+    // Run pre-request hooks
+    request = await beforeRequestHook(request, config.getAccessToken, config.getUserIP);
+    // Keep init headers in sync with the mutated request so fetch keeps auth headers
+    init.headers = new Headers(request.headers);
+    // Execute request with retry logic
+    const response = await fetchWithRetry(request, init);
+    // Run post-response hooks
+    await afterResponseHook(request, response, config.onSignoutUnauthorized);
+    if (!response.ok) {
+        throw response;
+    }
+    if (response.status === 204) {
+        return null;
+    }
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    return JSON.parse(text);
+}
+const apiClient = (config) => {
+    const apiConfig = {
+        ...config,
+    };
+    return {
+        get: (url, options) => (0, wrapper_1.apiWrapper)(() => api(apiConfig, url, options)),
+        post: (url, options) => (0, wrapper_1.apiWrapper)(() => api(apiConfig, url, { ...options, method: "POST" })),
+        put: (url, options) => (0, wrapper_1.apiWrapper)(() => api(apiConfig, url, { ...options, method: "PUT" })),
+        delete: (url, options) => (0, wrapper_1.apiWrapper)(() => api(apiConfig, url, { ...options, method: "DELETE" })),
+        patch: (url, options) => (0, wrapper_1.apiWrapper)(() => api(apiConfig, url, { ...options, method: "PATCH" })),
+    };
+};
+exports.apiClient = apiClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/api/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/api/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/api/index.d.ts

@@ -0,0 +1,3 @@
+export { apiClient } from "./client";
+export type { IApiError } from "./wrapper";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA"}

package/dist/cjs/api/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "apiClient", { enumerable: true, get: function () { return client_1.apiClient; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/index.ts"],"names":[],"mappings":";;;AAAA,mCAAoC;AAA3B,mGAAA,SAAS,OAAA"}

package/dist/cjs/api/wrapper.d.ts

@@ -0,0 +1,27 @@
+import type { TTryCatchResult } from "../function";
+export interface IApiError {
+    message: string;
+    status?: number;
+    code?: string;
+    details?: unknown;
+    path?: string;
+    timestamp?: string;
+}
+/**
+ * Wraps API calls with standardized error handling
+ *
+ * @param apiCall - The API call function to execute
+ * @param defaultData - Optional default value to return when an error occurs
+ * @returns A standardized result object with data or formatted error message
+ *
+ * @example
+ * // Basic usage
+ * const result = await apiWrapper(() => fetchUserData(userId));
+ *
+ * @example
+ * // With default data value
+ * const result = await apiWrapper(() => fetchPosts(), []);
+ * // result.data will be [] instead of null on error
+ */
+export declare function apiWrapper<T, D = null>(apiCall: () => Promise<T>, defaultData?: D): Promise<TTryCatchResult<T, IApiError, D extends null ? null : D>>;
+//# sourceMappingURL=wrapper.d.ts.map

package/dist/cjs/api/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../../src/api/wrapper.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAGlD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwJD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,EAC1C,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,WAAW,CAAC,EAAE,CAAC,GACd,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAcnE"}

package/dist/cjs/api/wrapper.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiWrapper = apiWrapper;
+const axios_1 = require("axios");
+/**
+ * Extracts error properties from Axios errors
+ */
+async function extractAxiosErrorDetails(error) {
+    var _a, _b, _c;
+    const errorObj = {
+        message: error.message || "Axios Error",
+        status: (_a = error.response) === null || _a === void 0 ? void 0 : _a.status,
+        path: (_b = error.config) === null || _b === void 0 ? void 0 : _b.url,
+    };
+    if (((_c = error.response) === null || _c === void 0 ? void 0 : _c.data) && typeof error.response.data === "object") {
+        return await enrichErrorWithData(errorObj, Promise.resolve(error.response.data));
+    }
+    return errorObj;
+}
+/**
+ * Extracts error properties from standard Error objects
+ */
+function extractStandardErrorDetails(error) {
+    const errorObj = {
+        message: error.message,
+    };
+    // Capture any custom properties the error might have
+    const extendedError = error;
+    if (extendedError.code)
+        errorObj.code = String(extendedError.code);
+    if (extendedError.status)
+        errorObj.status = Number(extendedError.status);
+    if (extendedError.details)
+        errorObj.details = extendedError.details;
+    return errorObj;
+}
+/**
+ * Extracts error properties from fetch Response objects
+ */
+async function extractResponseErrorDetails(response) {
+    const errorObj = {
+        message: `HTTP Error ${response.status}: ${response.statusText}`,
+        status: response.status,
+        path: response.url,
+    };
+    try {
+        // Clone the response to avoid consuming the body stream
+        const clonedResponse = response.clone();
+        const errorData = await clonedResponse.json();
+        // Directly enrich the error object with the parsed data
+        if (errorData && typeof errorData === "object") {
+            if ("message" in errorData && errorData.message) {
+                errorObj.message = String(errorData.message);
+            }
+            if ("code" in errorData) {
+                errorObj.code = String(errorData.code);
+            }
+            if ("details" in errorData) {
+                errorObj.details = errorData.details;
+            }
+            else if ("issues" in errorData) {
+                errorObj.details = errorData.issues;
+            }
+            if ("timestamp" in errorData) {
+                errorObj.timestamp = String(errorData.timestamp);
+            }
+        }
+        return errorObj;
+    }
+    catch (_a) {
+        // If JSON parsing fails, return the basic error object
+        return errorObj;
+    }
+}
+/**
+ * Enriches an error object with additional data from response
+ */
+async function enrichErrorWithData(errorObj, errorData, path) {
+    const data = await errorData;
+    if (data) {
+        if ("message" in data) {
+            errorObj.message = String(data.message);
+        }
+        if ("code" in data) {
+            errorObj.code = String(data.code);
+        }
+        if ("details" in data) {
+            errorObj.details = data.details;
+        }
+        else if ("issues" in data) {
+            errorObj.details = data.issues;
+        }
+        if ("timestamp" in data) {
+            errorObj.timestamp = String(data.timestamp);
+        }
+        if (path) {
+            errorObj.path = path;
+        }
+    }
+    return errorObj;
+}
+/**
+ * Determines the type of error and routes to appropriate handler
+ */
+async function processError(error) {
+    if (error instanceof Response) {
+        return extractResponseErrorDetails(error);
+    }
+    if ((0, axios_1.isAxiosError)(error)) {
+        return extractAxiosErrorDetails(error);
+    }
+    if (error instanceof Error) {
+        return extractStandardErrorDetails(error);
+    }
+    // Handle unknown error types
+    return {
+        message: error ? JSON.stringify(error) : "Unknown error",
+    };
+}
+/**
+ * Wraps API calls with standardized error handling
+ *
+ * @param apiCall - The API call function to execute
+ * @param defaultData - Optional default value to return when an error occurs
+ * @returns A standardized result object with data or formatted error message
+ *
+ * @example
+ * // Basic usage
+ * const result = await apiWrapper(() => fetchUserData(userId));
+ *
+ * @example
+ * // With default data value
+ * const result = await apiWrapper(() => fetchPosts(), []);
+ * // result.data will be [] instead of null on error
+ */
+async function apiWrapper(apiCall, defaultData) {
+    try {
+        const data = await apiCall();
+        return {
+            data,
+            error: null,
+        };
+    }
+    catch (error) {
+        const errorObj = await processError(error);
+        return {
+            data: (defaultData !== null && defaultData !== void 0 ? defaultData : null),
+            error: errorObj,
+        };
+    }
+}
+//# sourceMappingURL=wrapper.js.map

package/dist/cjs/api/wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.js","sourceRoot":"","sources":["../../../src/api/wrapper.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./api/index.js";
 export * from "./array/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/dist/cjs/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./api/index.js"), exports); // API utilities
 __exportStar(require("./array/index.js"), exports); // Array utilities
 __exportStar(require("./date/index.js"), exports); // Date utilities
 __exportStar(require("./files/index.js"), exports); // Files utilities

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAgC,CAAC,kBAAkB;AACnD,kDAA+B,CAAC,iBAAiB;AACjD,mDAAgC,CAAC,kBAAkB;AACnD,sDAAmC,CAAC,qBAAqB;AACzD,oDAAiC,CAAC,mBAAmB;AACrD,qDAAkC,CAAC,oBAAoB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA8B,CAAC,gBAAgB;AAC/C,mDAAgC,CAAC,kBAAkB;AACnD,kDAA+B,CAAC,iBAAiB;AACjD,mDAAgC,CAAC,kBAAkB;AACnD,sDAAmC,CAAC,qBAAqB;AACzD,oDAAiC,CAAC,mBAAmB;AACrD,qDAAkC,CAAC,oBAAoB"}

package/dist/esm/api/client.js

@@ -0,0 +1,123 @@
+import { apiWrapper } from "./wrapper.js";
+const defaultRetryConfig = {
+    limit: 5,
+    methods: ["get"],
+    statusCodes: [413],
+    backoffLimit: 3000,
+};
+function buildQueryString(params) {
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+        if (value !== null && value !== undefined) {
+            searchParams.append(key, String(value));
+        }
+    });
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : "";
+}
+async function beforeRequestHook(request, getAccessToken, getUserIP) {
+    const token = await (getAccessToken === null || getAccessToken === void 0 ? void 0 : getAccessToken());
+    const headers = new Headers(request.headers);
+    if (token) {
+        headers.set("Authorization", `Bearer ${token}`);
+    }
+    const userIP = await (getUserIP === null || getUserIP === void 0 ? void 0 : getUserIP());
+    if (userIP) {
+        headers.set("X-User-IP", userIP);
+    }
+    return new Request(request, { headers });
+}
+async function afterResponseHook(request, response, onSignoutUnauthorized) {
+    const possibleSignInPaths = ["signin", "sign-in", "login"];
+    const isSignInPath = possibleSignInPaths.some((path) => request.url.includes(path));
+    const needsBody = response.status === 401 && !isSignInPath;
+    let responseBody = null;
+    let responseBodyFor401 = null;
+    if (needsBody) {
+        const clone = response.clone();
+        try {
+            responseBody = await clone.json();
+            responseBodyFor401 = responseBody;
+        }
+        catch (_a) {
+            responseBody = await clone.text();
+        }
+    }
+    if (response.status === 401 && !isSignInPath) {
+        return onSignoutUnauthorized === null || onSignoutUnauthorized === void 0 ? void 0 : onSignoutUnauthorized(responseBodyFor401);
+    }
+}
+async function fetchWithRetry(input, init) {
+    var _a, _b, _c, _d;
+    const retryConfig = (init === null || init === void 0 ? void 0 : init.retry) || defaultRetryConfig;
+    const method = ((init === null || init === void 0 ? void 0 : init.method) || "GET").toLowerCase();
+    let attempt = 0;
+    while (true) {
+        attempt++;
+        const response = await fetch(input, init);
+        const shouldRetry = ((_a = retryConfig.statusCodes) === null || _a === void 0 ? void 0 : _a.includes(response.status)) &&
+            ((_b = retryConfig.methods) === null || _b === void 0 ? void 0 : _b.includes(method)) &&
+            attempt < ((_c = retryConfig.limit) !== null && _c !== void 0 ? _c : 5);
+        if (!shouldRetry)
+            return response;
+        const backoff = Math.min(2 ** attempt * 100, (_d = retryConfig.backoffLimit) !== null && _d !== void 0 ? _d : 3000);
+        await new Promise((resolve) => setTimeout(resolve, backoff));
+    }
+}
+async function api(config, endpoint, options = {}) {
+    var _a;
+    let url = endpoint.startsWith("http")
+        ? endpoint
+        : `${(_a = config.baseURL) === null || _a === void 0 ? void 0 : _a.replace(/\/$/, "")}/${endpoint.replace(/^\//, "")}`;
+    // Add query parameters if provided
+    if (options.params) {
+        const queryString = buildQueryString(options.params);
+        url += queryString;
+    }
+    // Apply default options
+    const init = {
+        credentials: "include",
+        ...options,
+    };
+    let body;
+    if (options.json) {
+        body = JSON.stringify(options.json);
+        init.headers = {
+            ...init.headers,
+            "Content-Type": "application/json",
+        };
+    }
+    // Create initial request
+    let request = new Request(url, { ...init, body });
+    // Run pre-request hooks
+    request = await beforeRequestHook(request, config.getAccessToken, config.getUserIP);
+    // Keep init headers in sync with the mutated request so fetch keeps auth headers
+    init.headers = new Headers(request.headers);
+    // Execute request with retry logic
+    const response = await fetchWithRetry(request, init);
+    // Run post-response hooks
+    await afterResponseHook(request, response, config.onSignoutUnauthorized);
+    if (!response.ok) {
+        throw response;
+    }
+    if (response.status === 204) {
+        return null;
+    }
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    return JSON.parse(text);
+}
+export const apiClient = (config) => {
+    const apiConfig = {
+        ...config,
+    };
+    return {
+        get: (url, options) => apiWrapper(() => api(apiConfig, url, options)),
+        post: (url, options) => apiWrapper(() => api(apiConfig, url, { ...options, method: "POST" })),
+        put: (url, options) => apiWrapper(() => api(apiConfig, url, { ...options, method: "PUT" })),
+        delete: (url, options) => apiWrapper(() => api(apiConfig, url, { ...options, method: "DELETE" })),
+        patch: (url, options) => apiWrapper(() => api(apiConfig, url, { ...options, method: "PATCH" })),
+    };
+};

package/dist/esm/api/index.js

@@ -0,0 +1 @@
+export { apiClient } from "./client.js";

package/dist/esm/api/wrapper.js

@@ -0,0 +1,148 @@
+import { isAxiosError } from "axios";
+/**
+ * Extracts error properties from Axios errors
+ */
+async function extractAxiosErrorDetails(error) {
+    var _a, _b, _c;
+    const errorObj = {
+        message: error.message || "Axios Error",
+        status: (_a = error.response) === null || _a === void 0 ? void 0 : _a.status,
+        path: (_b = error.config) === null || _b === void 0 ? void 0 : _b.url,
+    };
+    if (((_c = error.response) === null || _c === void 0 ? void 0 : _c.data) && typeof error.response.data === "object") {
+        return await enrichErrorWithData(errorObj, Promise.resolve(error.response.data));
+    }
+    return errorObj;
+}
+/**
+ * Extracts error properties from standard Error objects
+ */
+function extractStandardErrorDetails(error) {
+    const errorObj = {
+        message: error.message,
+    };
+    // Capture any custom properties the error might have
+    const extendedError = error;
+    if (extendedError.code)
+        errorObj.code = String(extendedError.code);
+    if (extendedError.status)
+        errorObj.status = Number(extendedError.status);
+    if (extendedError.details)
+        errorObj.details = extendedError.details;
+    return errorObj;
+}
+/**
+ * Extracts error properties from fetch Response objects
+ */
+async function extractResponseErrorDetails(response) {
+    const errorObj = {
+        message: `HTTP Error ${response.status}: ${response.statusText}`,
+        status: response.status,
+        path: response.url,
+    };
+    try {
+        // Clone the response to avoid consuming the body stream
+        const clonedResponse = response.clone();
+        const errorData = await clonedResponse.json();
+        // Directly enrich the error object with the parsed data
+        if (errorData && typeof errorData === "object") {
+            if ("message" in errorData && errorData.message) {
+                errorObj.message = String(errorData.message);
+            }
+            if ("code" in errorData) {
+                errorObj.code = String(errorData.code);
+            }
+            if ("details" in errorData) {
+                errorObj.details = errorData.details;
+            }
+            else if ("issues" in errorData) {
+                errorObj.details = errorData.issues;
+            }
+            if ("timestamp" in errorData) {
+                errorObj.timestamp = String(errorData.timestamp);
+            }
+        }
+        return errorObj;
+    }
+    catch (_a) {
+        // If JSON parsing fails, return the basic error object
+        return errorObj;
+    }
+}
+/**
+ * Enriches an error object with additional data from response
+ */
+async function enrichErrorWithData(errorObj, errorData, path) {
+    const data = await errorData;
+    if (data) {
+        if ("message" in data) {
+            errorObj.message = String(data.message);
+        }
+        if ("code" in data) {
+            errorObj.code = String(data.code);
+        }
+        if ("details" in data) {
+            errorObj.details = data.details;
+        }
+        else if ("issues" in data) {
+            errorObj.details = data.issues;
+        }
+        if ("timestamp" in data) {
+            errorObj.timestamp = String(data.timestamp);
+        }
+        if (path) {
+            errorObj.path = path;
+        }
+    }
+    return errorObj;
+}
+/**
+ * Determines the type of error and routes to appropriate handler
+ */
+async function processError(error) {
+    if (error instanceof Response) {
+        return extractResponseErrorDetails(error);
+    }
+    if (isAxiosError(error)) {
+        return extractAxiosErrorDetails(error);
+    }
+    if (error instanceof Error) {
+        return extractStandardErrorDetails(error);
+    }
+    // Handle unknown error types
+    return {
+        message: error ? JSON.stringify(error) : "Unknown error",
+    };
+}
+/**
+ * Wraps API calls with standardized error handling
+ *
+ * @param apiCall - The API call function to execute
+ * @param defaultData - Optional default value to return when an error occurs
+ * @returns A standardized result object with data or formatted error message
+ *
+ * @example
+ * // Basic usage
+ * const result = await apiWrapper(() => fetchUserData(userId));
+ *
+ * @example
+ * // With default data value
+ * const result = await apiWrapper(() => fetchPosts(), []);
+ * // result.data will be [] instead of null on error
+ */
+export async function apiWrapper(apiCall, defaultData) {
+    try {
+        const data = await apiCall();
+        return {
+            data,
+            error: null,
+        };
+    }
+    catch (error) {
+        const errorObj = await processError(error);
+        return {
+            data: (defaultData !== null && defaultData !== void 0 ? defaultData : null),
+            error: errorObj,
+        };
+    }
+}

package/dist/esm/index.js

@@ -1,3 +1,4 @@
+export * from "./api/index.js"; // API utilities
 export * from "./array/index.js"; // Array utilities
 export * from "./date/index.js"; // Date utilities
 export * from "./files/index.js"; // Files utilities

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./api/index.js";
 export * from "./array/index.js";
 export * from "./date/index.js";
 export * from "./files/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herowcode/utils",
-  "version": "1.1.11",
+  "version": "1.2.2",
   "description": "A lightweight collection of utility functions for everyday JavaScript/TypeScript development",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -40,6 +40,11 @@
       "types": "./dist/youtube/index.d.ts",
       "import": "./dist/esm/youtube/index.js",
       "require": "./dist/cjs/youtube/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/esm/api/index.js",
+      "require": "./dist/cjs/api/index.js"
     }
   },
   "files": [
@@ -78,11 +83,12 @@
   },
   "license": "MIT",
   "dependencies": {
+    "axios": "1.12.2",
     "dayjs": "^1.11.10",
     "react": "19.1.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.2.3",
+    "@biomejs/biome": "2.1.4",
     "@testing-library/dom": "10.4.1",
     "@testing-library/jest-dom": "6.8.0",
     "@testing-library/react": "16.3.0",