@zairakai/js-http-client 1.0.0

package/README.md

@@ -0,0 +1,139 @@
+# @zairakai/js-http-client
+
+[![Main][pipeline-main-badge]][pipeline-main-link]
+[![Develop][pipeline-develop-badge]][pipeline-develop-link]
+[![Coverage][coverage-badge]][coverage-link]
+
+[![npm][npm-badge]][npm-link]
+[![GitLab Release][gitlab-release-badge]][gitlab-release]
+[![License][license-badge]][license]
+
+[![Node.js][node-badge]][node]
+[![ESLint][eslint-badge]][eslint]
+[![Prettier][prettier-badge]][prettier]
+
+Axios-based HTTP client with request tracking, interceptor management, and Laravel CSRF support.
+
+---
+
+## Features
+
+- **Three factory functions** — `createHttpClient`, `createApiClient`, `createLaravelClient`
+- **Request tracking** — reactive `isLoading` and `requestCount` per client instance
+- **Built-in interceptors** — CSRF token, auth bearer, retry with backoff, error logging, timeout
+- **Laravel ready** — automatic `X-Requested-With` and CSRF headers
+- **TypeScript first** — full type exports including `AxiosInstance`, `AxiosResponse`, `HttpMethod`
+
+---
+
+## Install
+
+```bash
+npm install @zairakai/js-http-client
+```
+
+---
+
+## Usage
+
+```ts
+import { createHttpClient, createLaravelClient, createApiClient } from '@zairakai/js-http-client'
+
+// Generic API client
+const api = createHttpClient({
+  baseURL: 'https://api.example.com',
+  timeout: 5000,
+  authToken: () => localStorage.getItem('token'),
+  retries: 3,
+})
+
+const { data } = await api.get<User>('/users/1')
+
+// Laravel full-stack client (CSRF + credentials + Laravel headers)
+const laravelApi = createLaravelClient({ baseURL: '/api' })
+await laravelApi.post('/users', { name: 'Alice' })
+
+// Pure API client (no Laravel headers)
+const publicApi = createApiClient({ baseURL: 'https://public.api.com' })
+
+// Request tracking
+console.log(api.isLoading)     // true while requests are pending
+console.log(api.requestCount)  // number of active requests
+```
+
+---
+
+## API
+
+### Factory functions
+
+| Function | Description |
+| - | - |
+| `createHttpClient(options?)` | Base factory. Full control over all options. |
+| `createLaravelClient(options?)` | Adds `withCredentials`, `X-Requested-With`, and CSRF support. |
+| `createApiClient(options?)` | Clean JSON API client without Laravel-specific headers. |
+
+### Options
+
+| Option | Type | Default | Description |
+| - | - | - | - |
+| `baseURL` | `string` | `''` | Base URL for all requests |
+| `timeout` | `number` | `10000` | Request timeout in ms |
+| `authToken` | `string \| (() => string)` | — | Bearer token or token factory |
+| `csrfToken` | `string \| (() => string)` | — | CSRF token or factory |
+| `retries` | `number` | `0` | Number of retry attempts on failure |
+| `retryDelay` | `number` | `1000` | Delay between retries in ms |
+| `trackRequests` | `boolean` | `true` | Enable `isLoading` / `requestCount` |
+| `logger` | `Logger` | — | Custom error logger |
+
+### Standalone interceptors
+
+```ts
+import { createRetryInterceptor, createAuthInterceptor, createCSRFInterceptor } from '@zairakai/js-http-client'
+```
+
+---
+
+## Development
+
+```bash
+make quality       # eslint + prettier + knip + markdownlint
+make quality-fix   # auto-fix all fixable issues
+make test          # vitest
+make test-all      # vitest + bats + coverage
+```
+
+---
+
+## Getting Help
+
+[![License][license-badge]][license]
+[![Security Policy][security-badge]][security]
+[![Issues][issues-badge]][issues]
+
+**Made with ❤️ by [Zairakai][ecosystem]**
+
+<!-- Reference Links -->
+[pipeline-main-badge]: https://gitlab.com/zairakai/npm-packages/js-http-client/badges/main/pipeline.svg?ignore_skipped=true&key_text=Main
+[pipeline-main-link]: https://gitlab.com/zairakai/npm-packages/js-http-client/-/commits/main
+[pipeline-develop-badge]: https://gitlab.com/zairakai/npm-packages/js-http-client/badges/develop/pipeline.svg?ignore_skipped=true&key_text=Develop
+[pipeline-develop-link]: https://gitlab.com/zairakai/npm-packages/js-http-client/-/commits/develop
+[coverage-badge]: https://gitlab.com/zairakai/npm-packages/js-http-client/badges/main/coverage.svg
+[coverage-link]: https://gitlab.com/zairakai/npm-packages/js-http-client/-/pipelines?ref=main
+[npm-badge]: https://img.shields.io/npm/v/@zairakai/js-http-client
+[npm-link]: https://www.npmjs.com/package/@zairakai/js-http-client
+[gitlab-release-badge]: https://img.shields.io/gitlab/v/release/zairakai/npm-packages/js-http-client?logo=gitlab
+[gitlab-release]: https://gitlab.com/zairakai/npm-packages/js-http-client/-/releases
+[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[license]: ./LICENSE
+[security-badge]: https://img.shields.io/badge/security-scanned-green.svg
+[security]: ./SECURITY.md
+[issues-badge]: https://img.shields.io/gitlab/issues/open-raw/zairakai%2Fnpm-packages%2Fhttp-client?logo=gitlab&label=Issues
+[issues]: https://gitlab.com/zairakai/npm-packages/js-http-client/-/issues
+[node-badge]: https://img.shields.io/badge/node.js-%3E%3D22-green.svg?logo=node.js
+[node]: https://nodejs.org
+[eslint-badge]: https://img.shields.io/badge/code%20style-eslint-4B32C3.svg?logo=eslint
+[eslint]: https://eslint.org
+[prettier-badge]: https://img.shields.io/badge/formatter-prettier-F7B93E.svg?logo=prettier
+[prettier]: https://prettier.io
+[ecosystem]: https://gitlab.com/zairakai

package/dist/chunk-SSH6WKEL.js

@@ -0,0 +1,74 @@
+// src/interceptors.ts
+import axios from "axios";
+var createTrackingInterceptors = (tracker) => ({
+  request: (config) => {
+    tracker.increment();
+    return config;
+  },
+  requestError: (error) => {
+    return Promise.reject(error);
+  },
+  response: (response) => {
+    tracker.decrement();
+    return response;
+  },
+  responseError: (error) => {
+    tracker.decrement();
+    return Promise.reject(error);
+  }
+});
+var createCSRFInterceptor = (tokenSource) => (config) => {
+  const token = "function" === typeof tokenSource ? tokenSource() : tokenSource;
+  if (token) {
+    config.headers = config.headers ?? {};
+    config.headers["X-CSRF-TOKEN"] = token;
+  }
+  return config;
+};
+var createAuthInterceptor = (tokenSource, type = "Bearer") => (config) => {
+  const token = "function" === typeof tokenSource ? tokenSource() : tokenSource;
+  if (token) {
+    config.headers = config.headers ?? {};
+    config.headers["Authorization"] = `${type} ${token}`;
+  }
+  return config;
+};
+var createErrorLoggerInterceptor = (logger = console.error) => (error) => {
+  const logData = {
+    message: error.message,
+    status: error.response?.status,
+    statusText: error.response?.statusText,
+    url: error.config?.url,
+    method: error.config?.method?.toUpperCase()
+  };
+  logger("HTTP Error:", logData);
+  return Promise.reject(error);
+};
+var createTimeoutInterceptor = (timeout) => (config) => {
+  config.timeout = timeout;
+  return config;
+};
+var createRetryInterceptor = (retries = 3, delay = 1e3, shouldRetry = () => true) => {
+  return async (error) => {
+    const config = error.config;
+    if (!config || (config.__retryCount ?? 0) >= retries) {
+      return Promise.reject(error);
+    }
+    if (!shouldRetry(error)) {
+      return Promise.reject(error);
+    }
+    config.__retryCount = (config.__retryCount ?? 0) + 1;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    const axiosInstance = config._axios ?? axios;
+    return axiosInstance.request(config);
+  };
+};
+
+export {
+  createTrackingInterceptors,
+  createCSRFInterceptor,
+  createAuthInterceptor,
+  createErrorLoggerInterceptor,
+  createTimeoutInterceptor,
+  createRetryInterceptor
+};

package/dist/index.cjs

@@ -0,0 +1,244 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  axios: () => import_axios3.default,
+  createApiClient: () => createApiClient,
+  createAuthInterceptor: () => createAuthInterceptor,
+  createCSRFInterceptor: () => createCSRFInterceptor,
+  createErrorLoggerInterceptor: () => createErrorLoggerInterceptor,
+  createHttpClient: () => createHttpClient,
+  createLaravelClient: () => createLaravelClient,
+  createRequestTracker: () => createRequestTracker,
+  createRetryInterceptor: () => createRetryInterceptor,
+  createTimeoutInterceptor: () => createTimeoutInterceptor,
+  createTrackingInterceptors: () => createTrackingInterceptors,
+  globalRequestTracker: () => globalRequestTracker
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/client.ts
+var import_axios2 = __toESM(require("axios"), 1);
+
+// src/interceptors.ts
+var import_axios = __toESM(require("axios"), 1);
+var createTrackingInterceptors = (tracker) => ({
+  request: (config) => {
+    tracker.increment();
+    return config;
+  },
+  requestError: (error) => {
+    return Promise.reject(error);
+  },
+  response: (response) => {
+    tracker.decrement();
+    return response;
+  },
+  responseError: (error) => {
+    tracker.decrement();
+    return Promise.reject(error);
+  }
+});
+var createCSRFInterceptor = (tokenSource) => (config) => {
+  const token = "function" === typeof tokenSource ? tokenSource() : tokenSource;
+  if (token) {
+    config.headers = config.headers ?? {};
+    config.headers["X-CSRF-TOKEN"] = token;
+  }
+  return config;
+};
+var createAuthInterceptor = (tokenSource, type = "Bearer") => (config) => {
+  const token = "function" === typeof tokenSource ? tokenSource() : tokenSource;
+  if (token) {
+    config.headers = config.headers ?? {};
+    config.headers["Authorization"] = `${type} ${token}`;
+  }
+  return config;
+};
+var createErrorLoggerInterceptor = (logger = console.error) => (error) => {
+  const logData = {
+    message: error.message,
+    status: error.response?.status,
+    statusText: error.response?.statusText,
+    url: error.config?.url,
+    method: error.config?.method?.toUpperCase()
+  };
+  logger("HTTP Error:", logData);
+  return Promise.reject(error);
+};
+var createTimeoutInterceptor = (timeout) => (config) => {
+  config.timeout = timeout;
+  return config;
+};
+var createRetryInterceptor = (retries = 3, delay = 1e3, shouldRetry = () => true) => {
+  return async (error) => {
+    const config = error.config;
+    if (!config || (config.__retryCount ?? 0) >= retries) {
+      return Promise.reject(error);
+    }
+    if (!shouldRetry(error)) {
+      return Promise.reject(error);
+    }
+    config.__retryCount = (config.__retryCount ?? 0) + 1;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    const axiosInstance = config._axios ?? import_axios.default;
+    return axiosInstance.request(config);
+  };
+};
+
+// src/request-tracker.ts
+var createRequestTracker = () => {
+  let nbrInternal = 0;
+  return {
+    get count() {
+      return nbrInternal;
+    },
+    set count(val) {
+      nbrInternal = Math.max(0, val);
+    },
+    get isActive() {
+      return 0 < nbrInternal;
+    },
+    increment() {
+      nbrInternal++;
+    },
+    decrement() {
+      nbrInternal = Math.max(0, nbrInternal - 1);
+    },
+    reset() {
+      nbrInternal = 0;
+    }
+  };
+};
+var globalRequestTracker = createRequestTracker();
+
+// src/client.ts
+var DEFAULT_CONFIG = {
+  baseURL: "",
+  timeout: 1e4,
+  withCredentials: false,
+  headers: {
+    "Content-Type": "application/json",
+    Accept: "application/json"
+  }
+};
+var createHttpClient = (options = {}) => {
+  const config = { ...DEFAULT_CONFIG, ...options };
+  const client = import_axios2.default.create({
+    baseURL: config.baseURL,
+    timeout: config.timeout,
+    withCredentials: config.withCredentials,
+    headers: { ...DEFAULT_CONFIG.headers, ...config.headers }
+  });
+  const tracker = false !== config.trackRequests ? createRequestTracker() : null;
+  if (tracker) {
+    const trackingInterceptors = createTrackingInterceptors(tracker);
+    client.interceptors.request.use(trackingInterceptors.request, trackingInterceptors.requestError);
+    client.interceptors.response.use(trackingInterceptors.response, trackingInterceptors.responseError);
+  }
+  if (config.csrfToken) {
+    client.interceptors.request.use(createCSRFInterceptor(config.csrfToken));
+  }
+  if (config.authToken) {
+    client.interceptors.request.use(createAuthInterceptor(config.authToken, config.authType));
+  }
+  if (config.timeout !== DEFAULT_CONFIG.timeout) {
+    client.interceptors.request.use(createTimeoutInterceptor(config.timeout));
+  }
+  if (false !== config.enableErrorLogging) {
+    client.interceptors.response.use((response) => response, createErrorLoggerInterceptor(config.logger));
+  }
+  if (config.retries && 0 < config.retries) {
+    client.interceptors.request.use((reqConfig) => {
+      ;
+      reqConfig._axios = client;
+      return reqConfig;
+    });
+    client.interceptors.response.use(
+      (response) => response,
+      createRetryInterceptor(config.retries, config.retryDelay, config.shouldRetry)
+    );
+  }
+  if (false !== config.laravel) {
+    client.defaults.headers.common["X-Requested-With"] = "XMLHttpRequest";
+  }
+  return {
+    client,
+    tracker,
+    // Convenience methods
+    get: (url, config2) => client.get(url, config2),
+    post: (url, data, config2) => client.post(url, data, config2),
+    put: (url, data, config2) => client.put(url, data, config2),
+    patch: (url, data, config2) => client.patch(url, data, config2),
+    delete: (url, config2) => client.delete(url, config2),
+    // Request status
+    get isLoading() {
+      return tracker ? tracker.isActive : false;
+    },
+    get requestCount() {
+      return tracker ? tracker.count : 0;
+    }
+  };
+};
+var createLaravelClient = (options = {}) => {
+  return createHttpClient({
+    withCredentials: true,
+    headers: {
+      "X-Requested-With": "XMLHttpRequest"
+    },
+    ...options
+  });
+};
+var createApiClient = (options = {}) => {
+  return createHttpClient({
+    withCredentials: false,
+    laravel: false,
+    ...options
+  });
+};
+
+// src/index.ts
+var import_axios3 = __toESM(require("axios"), 1);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  axios,
+  createApiClient,
+  createAuthInterceptor,
+  createCSRFInterceptor,
+  createErrorLoggerInterceptor,
+  createHttpClient,
+  createLaravelClient,
+  createRequestTracker,
+  createRetryInterceptor,
+  createTimeoutInterceptor,
+  createTrackingInterceptors,
+  globalRequestTracker
+});

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+export { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse, Method as HttpMethod, default as axios } from 'axios';
+import { R as RequestTracker, T as TokenSource, L as Logger, S as ShouldRetryFunction } from './interceptors-Pv-t9Hbf.cjs';
+export { a as TrackingInterceptors, c as createAuthInterceptor, b as createCSRFInterceptor, d as createErrorLoggerInterceptor, e as createRequestTracker, f as createRetryInterceptor, g as createTimeoutInterceptor, h as createTrackingInterceptors, i as globalRequestTracker } from './interceptors-Pv-t9Hbf.cjs';
+
+/**
+ * HTTP client factory with configurable options
+ */
+
+/**
+ * HTTP client configuration options
+ */
+interface HttpClientOptions {
+    /** Base URL for requests */
+    baseURL?: string;
+    /** Default headers */
+    headers?: Record<string, string>;
+    /** Include credentials */
+    withCredentials?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable request tracking */
+    trackRequests?: boolean;
+    /** CSRF token or getter function */
+    csrfToken?: TokenSource;
+    /** Auth token or getter function */
+    authToken?: TokenSource;
+    /** Auth token type (Bearer, Token, etc.) */
+    authType?: string;
+    /** Enable error logging */
+    enableErrorLogging?: boolean;
+    /** Custom logger function */
+    logger?: Logger;
+    /** Number of retries for failed requests */
+    retries?: number;
+    /** Delay between retries in milliseconds */
+    retryDelay?: number;
+    /** Custom retry logic */
+    shouldRetry?: ShouldRetryFunction;
+    /** Enable Laravel-specific features */
+    laravel?: boolean;
+}
+/**
+ * HTTP client instance with convenience methods
+ */
+interface HttpClient {
+    /** Axios instance */
+    readonly client: AxiosInstance;
+    /** Request tracker instance (null if tracking disabled) */
+    readonly tracker: RequestTracker | null;
+    /** Whether there are active requests */
+    readonly isLoading: boolean;
+    /** Current number of active requests */
+    readonly requestCount: number;
+    get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    patch<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+}
+/**
+ * Creates a configured HTTP client with interceptors
+ * @param options - Configuration options
+ * @returns Configured axios instance with tracker
+ */
+declare const createHttpClient: (options?: HttpClientOptions) => HttpClient;
+/**
+ * Creates a Laravel-compatible HTTP client
+ * @param options - Configuration options
+ * @returns Configured HTTP client
+ */
+declare const createLaravelClient: (options?: HttpClientOptions) => HttpClient;
+/**
+ * Creates an API client (typically for external APIs)
+ * @param options - Configuration options
+ * @returns Configured HTTP client
+ */
+declare const createApiClient: (options?: HttpClientOptions) => HttpClient;
+
+export { type HttpClient, type HttpClientOptions, Logger, RequestTracker, ShouldRetryFunction, TokenSource, createApiClient, createHttpClient, createLaravelClient };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+export { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse, Method as HttpMethod, default as axios } from 'axios';
+import { R as RequestTracker, T as TokenSource, L as Logger, S as ShouldRetryFunction } from './interceptors-Pv-t9Hbf.js';
+export { a as TrackingInterceptors, c as createAuthInterceptor, b as createCSRFInterceptor, d as createErrorLoggerInterceptor, e as createRequestTracker, f as createRetryInterceptor, g as createTimeoutInterceptor, h as createTrackingInterceptors, i as globalRequestTracker } from './interceptors-Pv-t9Hbf.js';
+
+/**
+ * HTTP client factory with configurable options
+ */
+
+/**
+ * HTTP client configuration options
+ */
+interface HttpClientOptions {
+    /** Base URL for requests */
+    baseURL?: string;
+    /** Default headers */
+    headers?: Record<string, string>;
+    /** Include credentials */
+    withCredentials?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable request tracking */
+    trackRequests?: boolean;
+    /** CSRF token or getter function */
+    csrfToken?: TokenSource;
+    /** Auth token or getter function */
+    authToken?: TokenSource;
+    /** Auth token type (Bearer, Token, etc.) */
+    authType?: string;
+    /** Enable error logging */
+    enableErrorLogging?: boolean;
+    /** Custom logger function */
+    logger?: Logger;
+    /** Number of retries for failed requests */
+    retries?: number;
+    /** Delay between retries in milliseconds */
+    retryDelay?: number;
+    /** Custom retry logic */
+    shouldRetry?: ShouldRetryFunction;
+    /** Enable Laravel-specific features */
+    laravel?: boolean;
+}
+/**
+ * HTTP client instance with convenience methods
+ */
+interface HttpClient {
+    /** Axios instance */
+    readonly client: AxiosInstance;
+    /** Request tracker instance (null if tracking disabled) */
+    readonly tracker: RequestTracker | null;
+    /** Whether there are active requests */
+    readonly isLoading: boolean;
+    /** Current number of active requests */
+    readonly requestCount: number;
+    get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    patch<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+}
+/**
+ * Creates a configured HTTP client with interceptors
+ * @param options - Configuration options
+ * @returns Configured axios instance with tracker
+ */
+declare const createHttpClient: (options?: HttpClientOptions) => HttpClient;
+/**
+ * Creates a Laravel-compatible HTTP client
+ * @param options - Configuration options
+ * @returns Configured HTTP client
+ */
+declare const createLaravelClient: (options?: HttpClientOptions) => HttpClient;
+/**
+ * Creates an API client (typically for external APIs)
+ * @param options - Configuration options
+ * @returns Configured HTTP client
+ */
+declare const createApiClient: (options?: HttpClientOptions) => HttpClient;
+
+export { type HttpClient, type HttpClientOptions, Logger, RequestTracker, ShouldRetryFunction, TokenSource, createApiClient, createHttpClient, createLaravelClient };