@vahidkaargar/customized-api-client 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1171 @@
+"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 index_exports = {};
+__export(index_exports, {
+  ApiClientError: () => ApiClientError,
+  DEFAULT_PAGE_SIZE_CAP: () => DEFAULT_PAGE_SIZE_CAP,
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  IDEMPOTENCY_MAX_LENGTH: () => IDEMPOTENCY_MAX_LENGTH,
+  PACKAGE_VERSION: () => PACKAGE_VERSION,
+  applyJsonApiHeaders: () => applyJsonApiHeaders,
+  applyTransformKeys: () => applyTransformKeys,
+  assertValidIdempotencyKey: () => assertValidIdempotencyKey,
+  buildCursorPageParams: () => buildCursorPageParams,
+  buildJsonApiQuery: () => buildJsonApiQuery,
+  buildOffsetPageParams: () => buildOffsetPageParams,
+  createApiClient: () => createApiClient,
+  createHealthCheck: () => createHealthCheck,
+  defaultIdempotencyKey: () => defaultIdempotencyKey,
+  dispatchWithRetry: () => dispatchWithRetry,
+  etagFromResponseHeaders: () => etagFromResponseHeaders,
+  flattenAxiosHeaders: () => flattenAxiosHeaders,
+  formatIfMatch: () => formatIfMatch,
+  getHeader: () => getHeader,
+  getNextPageUrl: () => getNextPageUrl,
+  groupValidationErrorsByPointer: () => groupValidationErrorsByPointer,
+  indexIncluded: () => indexIncluded,
+  isApiClientError: () => isApiClientError,
+  isAuthenticationError: () => isAuthenticationError,
+  isConflictError: () => isConflictError,
+  isForbiddenError: () => isForbiddenError,
+  isMutationMethod: () => isMutationMethod,
+  isPayloadTooLargeError: () => isPayloadTooLargeError,
+  isPreconditionFailedError: () => isPreconditionFailedError,
+  isPreconditionRequiredError: () => isPreconditionRequiredError,
+  isRetryablePerPolicy: () => isRetryablePerPolicy,
+  isValidationError: () => isValidationError,
+  normalizeAxiosResponse: () => normalizeAxiosResponse,
+  normalizeHttpUrl: () => normalizeHttpUrl,
+  parseDeprecationHeaders: () => parseDeprecationHeaders,
+  parseJsonApiDocument: () => parseJsonApiDocument,
+  parseJsonApiErrorBody: () => parseJsonApiErrorBody,
+  parseMultiStatusBody: () => parseMultiStatusBody,
+  parsePaginationKind: () => parsePaginationKind,
+  parseRetryAfterSeconds: () => parseRetryAfterSeconds,
+  pollAsyncResult: () => pollAsyncResult,
+  readResourceVersion: () => readResourceVersion,
+  redactHeaderRecord: () => redactHeaderRecord,
+  resolveAcceptLanguage: () => resolveAcceptLanguage,
+  resolveAcceptedLocation: () => resolveAcceptedLocation,
+  resolveAuthorizationHeader: () => resolveAuthorizationHeader,
+  resolveIncluded: () => resolveIncluded,
+  resolveResourcePath: () => resolveResourcePath,
+  retryAllowed: () => retryAllowed,
+  truncateForLog: () => truncateForLog
+});
+module.exports = __toCommonJS(index_exports);
+
+// package.json
+var package_default = {
+  name: "@vahidkaargar/customized-api-client",
+  version: "0.2.0",
+  description: "TypeScript Axios client for JSON:API v1.1 with idempotency, retries, and normalized results",
+  type: "module",
+  engines: {
+    node: ">=20"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      require: "./dist/index.cjs"
+    }
+  },
+  main: "./dist/index.cjs",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  scripts: {
+    build: "tsup src/index.ts --dts --format esm,cjs --clean --sourcemap",
+    prepublishOnly: "npm run build",
+    test: "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    lint: 'eslint "src/**/*.ts" "test/**/*.ts" && npm run lint:md',
+    "lint:md": "markdownlint-cli2",
+    "lint:md:fix": "markdownlint-cli2 --fix",
+    format: "prettier --write .",
+    "format:check": "prettier --check .",
+    typecheck: "tsc --noEmit"
+  },
+  dependencies: {
+    axios: "^1.7.9",
+    ulid: "^2.3.0"
+  },
+  devDependencies: {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    eslint: "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.31.0",
+    "markdownlint-cli2": "^0.22.1",
+    msw: "^2.7.0",
+    prettier: "^3.4.2",
+    tsup: "^8.3.5",
+    typescript: "^5.7.2",
+    "typescript-eslint": "^8.18.2",
+    vitest: "^2.1.8"
+  },
+  keywords: [
+    "jsonapi",
+    "axios",
+    "typescript",
+    "api-client"
+  ],
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/vahidkaargar/customized-api-client.git"
+  },
+  bugs: {
+    url: "https://github.com/vahidkaargar/customized-api-client/issues"
+  },
+  homepage: "https://github.com/vahidkaargar/customized-api-client#readme",
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/create-api-client.ts
+var import_axios = __toESM(require("axios"), 1);
+
+// src/types/config.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_PAGE_SIZE_CAP = 100;
+
+// src/headers/jsonapi-headers.ts
+var JSON_API = "application/vnd.api+json";
+function applyJsonApiHeaders(config, method) {
+  const m = method.toUpperCase();
+  const headers = { ...config.headers };
+  headers.Accept = headers.Accept ?? JSON_API;
+  if (hasJsonBody(m, config)) {
+    headers["Content-Type"] = headers["Content-Type"] ?? JSON_API;
+  }
+  return { ...config, headers };
+}
+function hasJsonBody(method, config) {
+  if (!["POST", "PATCH", "PUT"].includes(method)) return false;
+  return config.data !== void 0 && config.data !== null;
+}
+
+// src/headers/auth.ts
+async function resolveAuthorizationHeader(auth) {
+  if (!auth) return void 0;
+  if (auth.type === "bearer") {
+    const t = await auth.getToken();
+    if (!t) return void 0;
+    return `Bearer ${t}`;
+  }
+  const s = await auth.getSecret();
+  if (!s) return void 0;
+  return `Bearer ${s}`;
+}
+
+// src/headers/locale.ts
+async function resolveAcceptLanguage(provider) {
+  if (!provider) return void 0;
+  const v = await provider();
+  return v ?? void 0;
+}
+
+// src/headers/idempotency.ts
+var import_ulid = require("ulid");
+var IDEMPOTENCY_MAX_LENGTH = 64;
+function defaultIdempotencyKey() {
+  return (0, import_ulid.ulid)();
+}
+function assertValidIdempotencyKey(key) {
+  if (!key || key.trim().length === 0) {
+    throw new Error("Idempotency-Key must be non-empty");
+  }
+  if (key.length > IDEMPOTENCY_MAX_LENGTH) {
+    throw new Error(`Idempotency-Key exceeds ${String(IDEMPOTENCY_MAX_LENGTH)} characters`);
+  }
+}
+function isMutationMethod(method) {
+  const m = method.toUpperCase();
+  return m === "POST" || m === "PATCH" || m === "PUT" || m === "DELETE";
+}
+
+// src/headers/if-match.ts
+function formatIfMatch(version) {
+  if (!Number.isFinite(version) || version < 0) {
+    throw new Error("If-Match version must be a non-negative finite number");
+  }
+  return `"v=${String(version)}"`;
+}
+
+// src/headers/resolve-url.ts
+function resolveResourcePath(baseURL, path, mode) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const base = baseURL.replace(/\/+$/, "");
+  if (mode === "modeB") {
+    if (normalizedPath.startsWith("/api/v1/") && base.endsWith("/api/v1")) {
+      const rest = normalizedPath.slice("/api/v1".length);
+      return rest.length > 0 ? rest : "/";
+    }
+    return normalizedPath;
+  }
+  return normalizedPath.startsWith("/api/v1") ? normalizedPath : `/api/v1${normalizedPath}`;
+}
+function normalizeHttpUrl(fullUrl) {
+  return fullUrl;
+}
+
+// src/retry/policy.ts
+function retryAllowed(ctx) {
+  const m = ctx.method.toUpperCase();
+  const isRead = m === "GET" || m === "HEAD";
+  if (ctx.isNetworkError) {
+    return true;
+  }
+  const s = ctx.status;
+  if (s === void 0) return false;
+  if (s === 401 || s === 403 || s === 412 || s === 428) return false;
+  if (s === 422 || s === 400 || s === 406 || s === 415 || s === 413) return false;
+  if (s === 409) {
+    if (ctx.primaryErrorCode === "IDEMPOTENCY_KEY_REUSED") return false;
+    if (ctx.primaryErrorCode === "IDEMPOTENCY_REQUEST_IN_PROGRESS") return true;
+    return false;
+  }
+  if (!isRead) {
+    return false;
+  }
+  if (s === 408) return true;
+  if (s === 429) return true;
+  if (s >= 502 && s <= 504) return true;
+  if (s >= 500 && s < 600) return true;
+  return false;
+}
+
+// src/retry/retry-after.ts
+function parseRetryAfterSeconds(value) {
+  if (!value) return void 0;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isNaN(n)) return n;
+  const ms = Date.parse(value);
+  if (!Number.isNaN(ms)) {
+    return Math.max(0, Math.ceil((ms - Date.now()) / 1e3));
+  }
+  return void 0;
+}
+
+// src/http/header-utils.ts
+function flattenAxiosHeaders(headers) {
+  if (!headers) return {};
+  if (typeof headers.forEach === "function") {
+    const out2 = {};
+    headers.forEach((value, key) => {
+      out2[key.toLowerCase()] = value;
+    });
+    return out2;
+  }
+  const o = headers;
+  const out = {};
+  for (const [k, v] of Object.entries(o)) {
+    if (typeof v === "string") out[k.toLowerCase()] = v;
+    else if (Array.isArray(v) && v[0]) out[k.toLowerCase()] = v[0];
+  }
+  return out;
+}
+function getHeader(headers, name) {
+  return headers[name.toLowerCase()];
+}
+
+// src/retry/execute-with-retry.ts
+var DEFAULT_MAX_ATTEMPTS = 4;
+var DEFAULT_BASE_MS = 200;
+async function dispatchWithRetry(instance, config, options) {
+  const max = options.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const baseDelay = options.retry?.baseDelayMs ?? DEFAULT_BASE_MS;
+  const maxDelay = options.retry?.maxDelayMs ?? 1e4;
+  const jitterRatio = options.retry?.jitterRatio ?? 0.2;
+  let attempt = 0;
+  let lastResponse;
+  while (attempt < max) {
+    try {
+      const res = await instance.request(config);
+      lastResponse = res;
+      const status = res.status;
+      const flat = flattenAxiosHeaders(res.headers);
+      const primary = status >= 400 ? extractPrimaryCode(res.data, options.getPrimaryErrorCodeFromBody) : void 0;
+      const allowed = retryAllowed({
+        method: String(config.method ?? "GET"),
+        status,
+        primaryErrorCode: primary,
+        isNetworkError: false
+      });
+      if (allowed && attempt < max - 1) {
+        const retryAfter = parseRetryAfterSeconds(flat["retry-after"]);
+        const delayMs = computeDelay(
+          attempt,
+          baseDelay,
+          maxDelay,
+          jitterRatio,
+          retryAfter
+        );
+        await sleep(delayMs);
+        attempt += 1;
+        continue;
+      }
+      return res;
+    } catch (err) {
+      const isNet = isAxiosNetworkError(err);
+      const allowed = retryAllowed({
+        method: String(config.method ?? "GET"),
+        isNetworkError: isNet
+      });
+      if (!allowed || attempt >= max - 1) {
+        throw err;
+      }
+      const delayMs = computeDelay(attempt, baseDelay, maxDelay, jitterRatio, void 0);
+      await sleep(delayMs);
+      attempt += 1;
+    }
+  }
+  if (lastResponse) return lastResponse;
+  throw new Error("dispatchWithRetry: exhausted without response");
+}
+function extractPrimaryCode(body, fn) {
+  if (fn) return fn(body);
+  if (body && typeof body === "object" && "errors" in body) {
+    const errors = body.errors;
+    if (Array.isArray(errors) && errors[0]?.code) {
+      return errors[0].code;
+    }
+  }
+  return void 0;
+}
+function isAxiosNetworkError(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  return e.isAxiosError === true && !e.response;
+}
+function computeDelay(attempt, base, max, jitterRatio, retryAfterSec) {
+  let exp = Math.min(max, base * 2 ** attempt);
+  if (retryAfterSec !== void 0) {
+    exp = Math.min(max, Math.max(exp, retryAfterSec * 1e3));
+  }
+  const jitter = exp * jitterRatio * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(exp + jitter));
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/parse/success.ts
+function parseJsonApiDocument(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new TypeError("JSON:API document must be an object");
+  }
+  const o = payload;
+  if (!("data" in o)) {
+    throw new TypeError('JSON:API document must include "data"');
+  }
+  return payload;
+}
+
+// src/security/redact.ts
+var DEFAULT_MAX_BODY_LOG = 2048;
+function truncateForLog(body, maxLen = DEFAULT_MAX_BODY_LOG) {
+  let s;
+  try {
+    s = typeof body === "string" ? body : JSON.stringify(body);
+  } catch {
+    s = "[Unserializable]";
+  }
+  if (s.length <= maxLen) return s;
+  return `${s.slice(0, maxLen)}\u2026`;
+}
+function redactHeaderRecord(headers) {
+  const out = { ...headers };
+  for (const key of Object.keys(out)) {
+    const lower = key.toLowerCase();
+    if (lower === "authorization" || lower === "idempotency-key") {
+      out[key] = "[REDACTED]";
+    }
+  }
+  return out;
+}
+
+// src/types/api-client-error.ts
+var ApiClientError = class _ApiClientError extends Error {
+  constructor(status, errors, primaryCode, responseHeaders, retryAfterSeconds, requestMethod, options) {
+    super(_ApiClientError.#messageFrom(errors, status), options);
+    this.status = status;
+    this.errors = errors;
+    this.primaryCode = primaryCode;
+    this.responseHeaders = responseHeaders;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.requestMethod = requestMethod;
+  }
+  status;
+  errors;
+  primaryCode;
+  responseHeaders;
+  retryAfterSeconds;
+  requestMethod;
+  name = "ApiClientError";
+  static #messageFrom(errors, status) {
+    const first = errors[0];
+    const code = first?.code ?? "";
+    const detail = first?.detail ?? first?.title ?? "";
+    const base = detail || code || `HTTP ${String(status)}`;
+    return `[ApiClientError ${String(status)}] ${base}`;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      status: this.status,
+      errors: this.errors,
+      primaryCode: this.primaryCode,
+      retryAfterSeconds: this.retryAfterSeconds,
+      requestMethod: this.requestMethod,
+      responseHeaders: this.responseHeaders ? redactHeaderRecord({ ...this.responseHeaders }) : void 0
+    };
+  }
+};
+function isApiClientError(value) {
+  return value instanceof ApiClientError;
+}
+
+// src/parse/errors.ts
+function parseJsonApiErrorBody(status, rawBody, headers, requestMethod) {
+  const retryAfterSeconds = headers["retry-after"] ? parseRetryAfterHeader(headers["retry-after"]) : void 0;
+  if (rawBody === null || rawBody === void 0 || rawBody === "") {
+    return new ApiClientError(
+      status,
+      [{ detail: `HTTP ${String(status)}`, code: "EMPTY_ERROR_BODY" }],
+      "EMPTY_ERROR_BODY",
+      headers,
+      retryAfterSeconds,
+      requestMethod
+    );
+  }
+  if (typeof rawBody === "string") {
+    try {
+      const parsed = JSON.parse(rawBody);
+      return parseFromObject(status, parsed, headers, retryAfterSeconds, requestMethod);
+    } catch {
+      return syntheticError(status, "INVALID_JSON", "Response body is not valid JSON", requestMethod);
+    }
+  }
+  if (typeof rawBody === "object") {
+    return parseFromObject(status, rawBody, headers, retryAfterSeconds, requestMethod);
+  }
+  return syntheticError(
+    status,
+    "INVALID_ERROR_DOCUMENT",
+    "Unknown error payload shape",
+    requestMethod
+  );
+}
+function parseFromObject(status, body, headers, retryAfterSeconds, requestMethod) {
+  if (!body || typeof body !== "object") {
+    return syntheticError(
+      status,
+      "INVALID_ERROR_DOCUMENT",
+      "Error payload must be an object",
+      requestMethod
+    );
+  }
+  const doc = body;
+  const errors = doc.errors;
+  if (!Array.isArray(errors) || errors.length === 0) {
+    return syntheticError(
+      status,
+      "MISSING_ERRORS_ARRAY",
+      "errors[] missing or empty",
+      requestMethod
+    );
+  }
+  const list = errors;
+  const primaryCode = list[0]?.code;
+  return new ApiClientError(status, list, primaryCode, headers, retryAfterSeconds, requestMethod);
+}
+function syntheticError(status, code, detail, requestMethod) {
+  return new ApiClientError(status, [{ code, detail }], code, void 0, void 0, requestMethod);
+}
+function parseRetryAfterHeader(v) {
+  const n = Number.parseInt(v, 10);
+  if (!Number.isNaN(n)) return n;
+  const ms = Date.parse(v);
+  if (!Number.isNaN(ms)) {
+    const delta = Math.max(0, Math.ceil((ms - Date.now()) / 1e3));
+    return delta;
+  }
+  return void 0;
+}
+
+// src/parse/bulk-207.ts
+function parseMultiStatusBody(raw) {
+  if (raw && typeof raw === "object" && "items" in raw) {
+    const items = raw.items;
+    if (Array.isArray(items)) {
+      return items.map((it) => normalizeItem(it));
+    }
+  }
+  if (Array.isArray(raw)) {
+    return raw.map((it) => normalizeItem(it));
+  }
+  return [{ httpStatus: 500, body: raw }];
+}
+function normalizeItem(it) {
+  if (it && typeof it === "object") {
+    const o = it;
+    const s = o.httpStatus ?? o.status;
+    const httpStatus = typeof s === "number" && Number.isFinite(s) ? s : 500;
+    return { httpStatus, body: o.body ?? o.response ?? it };
+  }
+  return { httpStatus: 500, body: it };
+}
+
+// src/parse/accepted-202.ts
+function resolveAcceptedLocation(headers, requestUrl) {
+  const flat = flattenAxiosHeaders(headers);
+  const loc = getHeader(flat, "location");
+  if (!loc) return requestUrl;
+  try {
+    return new URL(loc, requestUrl).href;
+  } catch {
+    return loc;
+  }
+}
+
+// src/helpers/transform-keys.ts
+function applyTransformKeys(doc, mode) {
+  if (mode === "none") return doc;
+  const data = doc.data;
+  const mapResource = (r) => {
+    const o = { ...r };
+    if (o.attributes && typeof o.attributes === "object") {
+      o.attributes = camelKeys(o.attributes);
+    }
+    if (o.meta && typeof o.meta === "object") {
+      o.meta = camelKeys(o.meta);
+    }
+    return o;
+  };
+  if (data === null) {
+    return {
+      ...doc,
+      meta: doc.meta ? camelKeys(doc.meta) : doc.meta
+    };
+  }
+  if (Array.isArray(data)) {
+    return {
+      ...doc,
+      data: data.map((r) => mapResource(r)),
+      meta: doc.meta ? camelKeys(doc.meta) : doc.meta
+    };
+  }
+  return {
+    ...doc,
+    data: mapResource(data),
+    /* v8 ignore next -- document meta absent on single-resource responses */
+    meta: doc.meta ? camelKeys(doc.meta) : doc.meta
+  };
+}
+function camelKeys(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[toCamelCase(k)] = v;
+  }
+  return out;
+}
+function toCamelCase(s) {
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+// src/http/normalize-response.ts
+function normalizeAxiosResponse(response, options) {
+  const status = response.status;
+  const headers = flattenAxiosHeaders(response.headers);
+  if (status >= 400) {
+    throw parseJsonApiErrorBody(status, response.data, headers, options.requestMethod);
+  }
+  const normHeaders = normalizeHeaders(headers);
+  if (status === 204) {
+    return { kind: "no-content", status: 204, headers: normHeaders };
+  }
+  if (status === 202) {
+    const location = resolveAcceptedLocation(headers, options.requestUrl);
+    return {
+      kind: "accepted",
+      status: 202,
+      location,
+      rawBody: response.data,
+      headers: normHeaders
+    };
+  }
+  if (status === 207) {
+    return {
+      kind: "multi-status",
+      status: 207,
+      items: parseMultiStatusBody(response.data),
+      headers: normHeaders
+    };
+  }
+  if (status === 200 || status === 201) {
+    const doc = parseJsonApiDocument(response.data);
+    const transformed = applyTransformResponse(
+      doc,
+      options.transformResponseKeys ?? "none"
+    );
+    const body = {
+      kind: "jsonapi-success",
+      status,
+      headers: normHeaders,
+      document: transformed
+    };
+    return body;
+  }
+  throw new ApiClientError(
+    status,
+    [{ code: "UNSUPPORTED_SUCCESS_STATUS", detail: String(status) }],
+    "UNSUPPORTED_SUCCESS_STATUS",
+    headers,
+    parseRetryAfterSeconds(getHeader(headers, "retry-after")),
+    options.requestMethod
+  );
+}
+function normalizeHeaders(headers) {
+  const idem = getHeader(headers, "idempotent-replayed");
+  return {
+    etag: getHeader(headers, "etag"),
+    contentLanguage: getHeader(headers, "content-language"),
+    idempotentReplayed: idem === "true" || idem === "True",
+    retryAfterSeconds: parseRetryAfterSeconds(getHeader(headers, "retry-after"))
+  };
+}
+function applyTransformResponse(doc, mode) {
+  if (mode === "none") return doc;
+  return applyTransformKeys(doc, mode);
+}
+
+// src/helpers/deprecation.ts
+function parseDeprecationHeaders(headerBag) {
+  const flat = flattenAxiosHeaders(headerBag);
+  const dep = flat.deprecation;
+  const sunset = flat.sunset;
+  if (!dep && !sunset) return null;
+  return {
+    deprecation: dep,
+    sunset,
+    rawHeaders: flat
+  };
+}
+
+// src/create-api-client.ts
+function readHeader(ax, name) {
+  const h = ax.headers;
+  if (!h) return void 0;
+  const v = h[name] ?? h[name.toLowerCase()];
+  if (Array.isArray(v)) return v[0];
+  return typeof v === "string" ? v : void 0;
+}
+function buildRequestUrl(cfg, fallback) {
+  if (typeof cfg.url === "string" && /^https?:\/\//i.test(cfg.url)) {
+    return cfg.url;
+  }
+  const base = cfg.baseURL ?? "";
+  const p = cfg.url ?? "";
+  try {
+    return new URL(p, base).href;
+  } catch {
+    return fallback;
+  }
+}
+function warnInsecureBaseUrl(baseURL) {
+  try {
+    const u = new URL(baseURL);
+    if (u.protocol !== "http:") return;
+    const host = u.hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1") return;
+    console.warn(
+      "[@vahidkaargar/customized-api-client] baseURL uses HTTP outside localhost; prefer HTTPS in production."
+    );
+  } catch {
+  }
+}
+async function safe(fn) {
+  try {
+    const value = await fn();
+    return { ok: true, value };
+  } catch (e) {
+    if (e instanceof ApiClientError) {
+      return { ok: false, error: e };
+    }
+    throw e;
+  }
+}
+function createApiClient(config) {
+  const mode = config.baseUrlMode ?? "modeB";
+  const genKey = config.generateIdempotencyKey ?? defaultIdempotencyKey;
+  warnInsecureBaseUrl(config.baseURL);
+  const instance = import_axios.default.create({
+    baseURL: config.baseURL,
+    timeout: config.timeout ?? DEFAULT_TIMEOUT_MS,
+    validateStatus: () => true,
+    headers: {
+      Accept: "application/vnd.api+json",
+      ...config.defaultHeaders
+    }
+  });
+  instance.interceptors.request.use(async (req) => {
+    const method = (req.method ?? "get").toUpperCase();
+    const next = applyJsonApiHeaders(req, method);
+    const authHeader = await resolveAuthorizationHeader(config.auth);
+    if (authHeader) {
+      next.headers.Authorization = authHeader;
+    }
+    const lang = await resolveAcceptLanguage(config.getAcceptLanguage);
+    if (lang) {
+      next.headers["Accept-Language"] = lang;
+    }
+    if (isMutationMethod(method)) {
+      const h = next.headers;
+      const existing = h["Idempotency-Key"] ?? h["idempotency-key"];
+      const key = typeof existing === "string" && existing.length > 0 ? existing : genKey();
+      assertValidIdempotencyKey(key);
+      next.headers["Idempotency-Key"] = key;
+    }
+    return next;
+  });
+  instance.interceptors.response.use(
+    (res) => {
+      const flat = flattenAxiosHeaders(res.headers);
+      if (flat["idempotent-replayed"] === "true" && config.onIdempotencyReplay) {
+        config.onIdempotencyReplay({
+          /* v8 ignore next 2 -- config url/method are strings from axios */
+          url: typeof res.config.url === "string" ? res.config.url : void 0,
+          method: typeof res.config.method === "string" ? res.config.method : void 0
+        });
+      }
+      const dep = parseDeprecationHeaders(res.headers);
+      if (dep && config.onDeprecated) {
+        config.onDeprecated(dep);
+      }
+      return res;
+    },
+    (err) => Promise.reject(
+      /* v8 ignore next -- axios rejects with Error; non-Error is defensive */
+      err instanceof Error ? err : new Error(String(err))
+    )
+  );
+  function resolvePath(path) {
+    return resolveResourcePath(config.baseURL, path, mode);
+  }
+  async function perform(method, url, options) {
+    const headers = {};
+    if (options.idempotencyKey !== void 0) {
+      assertValidIdempotencyKey(options.idempotencyKey);
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    if (options.ifMatchVersion !== void 0) {
+      headers["If-Match"] = formatIfMatch(options.ifMatchVersion);
+    }
+    const axConfig = {
+      method,
+      url,
+      data: options.data,
+      headers: { ...headers }
+    };
+    try {
+      const response = await dispatchWithRetry(instance, axConfig, {
+        retry: config.retry
+      });
+      try {
+        return normalizeAxiosResponse(response, {
+          transformResponseKeys: config.transformResponseKeys,
+          requestUrl: buildRequestUrl(response.config, url),
+          requestMethod: method.toUpperCase()
+        });
+      } catch (e) {
+        if (e instanceof ApiClientError && e.status === 401 && config.onUnauthorized) {
+          await config.onUnauthorized(e);
+        }
+        throw e;
+      }
+    } catch (err) {
+      if ((0, import_axios.isAxiosError)(err) && err.response) {
+        const res = err.response;
+        try {
+          return normalizeAxiosResponse(res, {
+            transformResponseKeys: config.transformResponseKeys,
+            requestUrl: buildRequestUrl(res.config, url),
+            requestMethod: method.toUpperCase()
+          });
+        } catch (e) {
+          if (e instanceof ApiClientError && e.status === 401 && config.onUnauthorized) {
+            await config.onUnauthorized(e);
+          }
+          throw e;
+        }
+      }
+      throw err;
+    }
+  }
+  const client = {
+    async get(path, opts) {
+      return perform("GET", resolvePath(path), opts ?? {});
+    },
+    async head(path, opts) {
+      return perform("HEAD", resolvePath(path), opts ?? {});
+    },
+    async post(path, data, opts) {
+      return perform("POST", resolvePath(path), { ...opts, data });
+    },
+    async patch(path, data, opts) {
+      return perform("PATCH", resolvePath(path), { ...opts, data });
+    },
+    async put(path, data, opts) {
+      return perform("PUT", resolvePath(path), { ...opts, data });
+    },
+    async delete(path, opts) {
+      return perform("DELETE", resolvePath(path), opts ?? {});
+    },
+    async request(ax, opts) {
+      const method = (ax.method ?? "GET").toUpperCase();
+      const rawUrl = ax.url ?? "/";
+      const u = (
+        /* v8 ignore next -- axios types url as string; non-string is defensive */
+        typeof rawUrl === "string" && /^https?:\/\//i.test(rawUrl) ? rawUrl : resolvePath(rawUrl)
+      );
+      return perform(method, u, {
+        ...opts,
+        data: ax.data,
+        idempotencyKey: opts?.idempotencyKey ?? readHeader(ax, "Idempotency-Key")
+      });
+    },
+    async getByUrl(fullUrl, opts) {
+      return perform("GET", fullUrl, opts ?? {});
+    },
+    async patchWithVersion(path, data, version, opts) {
+      return perform("PATCH", resolvePath(path), {
+        ...opts,
+        data,
+        ifMatchVersion: version
+      });
+    },
+    safeGet: (path, opts) => safe(() => client.get(path, opts)),
+    safePost: (path, data, opts) => safe(() => client.post(path, data, opts)),
+    safePatch: (path, data, opts) => safe(() => client.patch(path, data, opts)),
+    safePut: (path, data, opts) => safe(() => client.put(path, data, opts)),
+    safeDelete: (path, opts) => safe(() => client.delete(path, opts)),
+    safeHead: (path, opts) => safe(() => client.head(path, opts)),
+    safeRequest: (ax, opts) => safe(() => client.request(ax, opts))
+  };
+  return client;
+}
+
+// src/guards.ts
+function isAuthenticationError(e) {
+  return isApiErr(e, 401);
+}
+function isForbiddenError(e) {
+  return isApiErr(e, 403);
+}
+function isPreconditionRequiredError(e) {
+  return isApiErr(e, 428);
+}
+function isPreconditionFailedError(e) {
+  return isApiErr(e, 412);
+}
+function isValidationError(e) {
+  return isApiErr(e, 422);
+}
+function isConflictError(e) {
+  return isApiErr(e, 409);
+}
+function isPayloadTooLargeError(e) {
+  return isApiErr(e, 413);
+}
+function isRetryablePerPolicy(e) {
+  if (!(e instanceof ApiClientError)) return false;
+  return retryAllowed({
+    method: e.requestMethod ?? "GET",
+    status: e.status,
+    primaryErrorCode: e.primaryCode,
+    isNetworkError: false
+  });
+}
+function isApiErr(e, status) {
+  return e instanceof ApiClientError && e.status === status;
+}
+
+// src/parse/pagination.ts
+function parsePaginationKind(meta, links) {
+  const m = meta ?? {};
+  const linksNext = typeof links?.next === "string" ? links.next : void 0;
+  if (linksNext) {
+    const fromCursor = extractQueryParam(linksNext, "page[cursor]") ?? extractQueryParam(linksNext, "page%5Bcursor%5D");
+    if (fromCursor) {
+      return { kind: "cursor", hasMore: true, nextCursor: fromCursor };
+    }
+    const legacy = parseLegacyOffsetFromUrl(linksNext);
+    if (legacy) return legacy;
+  }
+  const lastPage = num(m.last_page);
+  const current = num(m.current_page) ?? num(m.page);
+  const total = num(m.total);
+  const hasMore = bool(m.has_more);
+  if (lastPage !== void 0 || current !== void 0 || total !== void 0) {
+    return {
+      kind: "offset",
+      page: current ?? 1,
+      totalPages: lastPage,
+      total
+    };
+  }
+  if (hasMore !== void 0) {
+    return {
+      kind: "cursor",
+      hasMore,
+      nextCursor: typeof m.next_cursor === "string" ? m.next_cursor : void 0
+    };
+  }
+  return { kind: "unknown" };
+}
+function getNextPageUrl(links) {
+  const n = links?.next;
+  return typeof n === "string" ? n : void 0;
+}
+function parseLegacyOffsetFromUrl(url) {
+  try {
+    const u = new URL(url, "http://local.test");
+    const hasPerPage = u.searchParams.has("per_page");
+    const pagePlain = u.searchParams.get("page");
+    const pageBracket = u.searchParams.get("page[number]");
+    if (!hasPerPage && !pagePlain && !pageBracket) return void 0;
+    const pageNum = num(pagePlain) ?? num(pageBracket) ?? 1;
+    return { kind: "offset", page: pageNum, totalPages: void 0, total: void 0 };
+  } catch {
+    return void 0;
+  }
+}
+function num(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && /^-?\d+$/.test(v)) return Number.parseInt(v, 10);
+  return void 0;
+}
+function bool(v) {
+  if (typeof v === "boolean") return v;
+  return void 0;
+}
+function extractQueryParam(url, key) {
+  try {
+    const u = new URL(url, "http://local.test");
+    return u.searchParams.get(key) ?? u.searchParams.get(key.replace(/\[/g, "").replace(/\]/g, ""));
+  } catch {
+    return null;
+  }
+}
+
+// src/helpers/query.ts
+function buildJsonApiQuery(input) {
+  const params = {};
+  if (input.filter) {
+    for (const [k, v] of Object.entries(input.filter)) {
+      if (v === void 0) continue;
+      params[`filter[${k}]`] = String(v);
+    }
+  }
+  if (input.sort?.length) {
+    params.sort = input.sort.join(",");
+  }
+  if (input.fields) {
+    for (const [type, fields] of Object.entries(input.fields)) {
+      params[`fields[${type}]`] = fields.join(",");
+    }
+  }
+  if (input.include?.length) {
+    params.include = input.include.join(",");
+  }
+  return params;
+}
+function buildOffsetPageParams(input) {
+  const size = Math.min(Math.max(1, input.size), DEFAULT_PAGE_SIZE_CAP);
+  return {
+    "page[number]": input.number,
+    "page[size]": size
+  };
+}
+function buildCursorPageParams(input) {
+  const size = Math.min(Math.max(1, input.size), DEFAULT_PAGE_SIZE_CAP);
+  return {
+    "page[cursor]": input.cursor,
+    "page[size]": size
+  };
+}
+
+// src/helpers/included-index.ts
+function indexIncluded(included) {
+  const map = /* @__PURE__ */ new Map();
+  if (!included) return map;
+  for (const r of included) {
+    map.set(`${r.type}:${r.id}`, r);
+  }
+  return map;
+}
+function resolveIncluded(ref, index) {
+  return index.get(`${ref.type}:${ref.id}`);
+}
+
+// src/helpers/version.ts
+function readResourceVersion(resource, etagHeader) {
+  const meta = resource.meta;
+  const mv = meta?.version;
+  const fromMeta = coerceUnsigned(mv);
+  if (fromMeta !== void 0) return fromMeta;
+  const etag = etagHeader;
+  if (typeof etag === "string") {
+    const m = /v=(\d+)/i.exec(etag);
+    if (m?.[1]) return Number.parseInt(m[1], 10);
+  }
+  return void 0;
+}
+function coerceUnsigned(v) {
+  if (typeof v === "number" && Number.isFinite(v) && v >= 0) return v;
+  if (typeof v === "string" && /^\d+$/.test(v)) return Number.parseInt(v, 10);
+  return void 0;
+}
+function etagFromResponseHeaders(headerBag) {
+  const h = flattenAxiosHeaders(headerBag);
+  return getHeader(h, "etag");
+}
+
+// src/helpers/form-errors.ts
+function groupValidationErrorsByPointer(errors) {
+  const out = {};
+  for (const e of errors) {
+    const ptr = e.source?.pointer ?? "/";
+    const msg = e.detail ?? e.title ?? e.code ?? "Error";
+    out[ptr] ??= [];
+    out[ptr].push(msg);
+  }
+  return out;
+}
+
+// src/helpers/health.ts
+function createHealthCheck(target) {
+  const client = isGettable(target) ? target : createApiClient(target);
+  return async () => {
+    try {
+      await client.get("/health/live");
+      return true;
+    } catch {
+      return false;
+    }
+  };
+}
+function isGettable(target) {
+  return typeof target.get === "function";
+}
+
+// src/poll-async.ts
+async function pollAsyncResult(client, initial, options) {
+  const max = options?.maxAttempts ?? 10;
+  const delay = options?.delayMs ?? 200;
+  let url = initial.location;
+  for (let i = 0; i < max; i += 1) {
+    const res = await client.getByUrl(url);
+    if (res.kind !== "accepted") return res;
+    url = res.location;
+    await sleep2(delay);
+  }
+  throw new Error("pollAsyncResult: max attempts exceeded");
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/index.ts
+var PACKAGE_VERSION = package_default.version;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiClientError,
+  DEFAULT_PAGE_SIZE_CAP,
+  DEFAULT_TIMEOUT_MS,
+  IDEMPOTENCY_MAX_LENGTH,
+  PACKAGE_VERSION,
+  applyJsonApiHeaders,
+  applyTransformKeys,
+  assertValidIdempotencyKey,
+  buildCursorPageParams,
+  buildJsonApiQuery,
+  buildOffsetPageParams,
+  createApiClient,
+  createHealthCheck,
+  defaultIdempotencyKey,
+  dispatchWithRetry,
+  etagFromResponseHeaders,
+  flattenAxiosHeaders,
+  formatIfMatch,
+  getHeader,
+  getNextPageUrl,
+  groupValidationErrorsByPointer,
+  indexIncluded,
+  isApiClientError,
+  isAuthenticationError,
+  isConflictError,
+  isForbiddenError,
+  isMutationMethod,
+  isPayloadTooLargeError,
+  isPreconditionFailedError,
+  isPreconditionRequiredError,
+  isRetryablePerPolicy,
+  isValidationError,
+  normalizeAxiosResponse,
+  normalizeHttpUrl,
+  parseDeprecationHeaders,
+  parseJsonApiDocument,
+  parseJsonApiErrorBody,
+  parseMultiStatusBody,
+  parsePaginationKind,
+  parseRetryAfterSeconds,
+  pollAsyncResult,
+  readResourceVersion,
+  redactHeaderRecord,
+  resolveAcceptLanguage,
+  resolveAcceptedLocation,
+  resolveAuthorizationHeader,
+  resolveIncluded,
+  resolveResourcePath,
+  retryAllowed,
+  truncateForLog
+});
+//# sourceMappingURL=index.cjs.map