@vahidkaargar/customized-api-client 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -26,11 +26,31 @@ interface IdempotencyReplayContext {
     readonly url?: string;
     readonly method?: string;
 }
+interface LocaleMismatchContext {
+    /** Locale from `getLocale` before default omission. */
+    readonly requested?: string;
+    /** `Content-Language` from the response. */
+    readonly resolved: string;
+    readonly url?: string;
+    readonly method?: string;
+}
+interface LocaleClientOptions {
+    readonly getLocale?: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * When the resolved locale matches this value (primary subtag), `Accept-Language` is omitted.
+     */
+    readonly defaultLocale?: string;
+    readonly onLocaleMismatch?: 'warn' | ((ctx: Readonly<LocaleMismatchContext>) => void);
+}
 interface ApiClientConfig {
     readonly baseURL: string;
     /** Default Mode B — see `BaseUrlMode`. */
     readonly baseUrlMode?: BaseUrlMode;
     readonly auth?: AuthConfig;
+    readonly locale?: LocaleClientOptions;
+    /**
+     * @deprecated Use `locale.getLocale` instead.
+     */
     readonly getAcceptLanguage?: () => string | null | undefined | Promise<string | null | undefined>;
     readonly defaultHeaders?: Readonly<Record<string, string>>;
     readonly timeout?: number;
@@ -191,6 +211,10 @@ declare function isMfaVerificationRequiredError(e: unknown): boolean;
 declare function isPreconditionFailedError(e: unknown): boolean;
 declare function isValidationError(e: unknown): boolean;
 declare function isConflictError(e: unknown): boolean;
+/** HTTP **409** + primary `errors[].code === 'IDEMPOTENCY_KEY_REUSED'`. */
+declare function isIdempotencyKeyReusedError(e: unknown): boolean;
+/** HTTP **409** + primary `errors[].code === 'IDEMPOTENCY_REQUEST_IN_PROGRESS'`. */
+declare function isIdempotencyInProgressError(e: unknown): boolean;
 declare function isPayloadTooLargeError(e: unknown): boolean;
 declare function isRetryablePerPolicy(e: unknown, policy?: Readonly<{
     retryMutationsOnServerError?: boolean;
@@ -212,9 +236,63 @@ declare function defaultIdempotencyKey(): string;
 declare function assertValidIdempotencyKey(key: string): void;
 declare function isMutationMethod(method: string): boolean;
 
+/** Whether the next mutation should keep or replace the active idempotency key. */
+type IdempotencyRotation = 'reuse' | 'rotate';
+/** Caller-owned idempotency key lifecycle across separate client invocations. */
+interface IdempotencyIntent {
+    readonly activeKey: string | null;
+    hasActiveIntent: () => boolean;
+    begin: () => string;
+    keyFor: (rotation: IdempotencyRotation) => string;
+    complete: () => void;
+    abandon: () => void;
+}
+interface CreateIdempotencyIntentOptions {
+    readonly generateKey?: () => string;
+}
+/**
+ * Track one user intent's idempotency key across multiple `client.post`/`patch`/… calls.
+ *
+ * Transport retries inside a single client call reuse the same key automatically; this helper
+ * covers **separate** invocations (e.g. user clicks Retry after a network error).
+ */
+declare function createIdempotencyIntent(options?: CreateIdempotencyIntentOptions): IdempotencyIntent;
+/**
+ * @deprecated Prefer {@link createIdempotencyIntent}. Alias for app-layer naming compatibility.
+ */
+declare const createMutationIdempotency: typeof createIdempotencyIntent;
+
+/**
+ * Suggested rotation when reacting to an error before retrying the same user action.
+ *
+ * - Network / abort / no response → reuse
+ * - `IDEMPOTENCY_REQUEST_IN_PROGRESS` → reuse (transport may already retry once)
+ * - `IDEMPOTENCY_KEY_REUSED` or validation **422** → rotate
+ * - Other `ApiClientError` → reuse when payload unchanged (caller may override)
+ *
+ * **412 If-Match** is not idempotency rotation — refresh version separately.
+ */
+declare function idempotencyRotationForRetry(error: unknown): IdempotencyRotation;
+
 declare function formatIfMatch(version: number): string;
 
-declare function resolveAcceptLanguage(provider?: () => string | null | undefined | Promise<string | null | undefined>): Promise<string | undefined>;
+type LocaleProvider = () => string | null | undefined | Promise<string | null | undefined>;
+/** Primary language subtag only: `fr-FR` → `fr`. */
+declare function normalizeLocaleCode(tag: string | undefined): string | undefined;
+/** First language tag from a `Content-Language` (or similar) header value. */
+declare function parseContentLanguage(header: string | undefined): string | undefined;
+/** Compare primary subtags (e.g. `fr-FR` and `fr` match). */
+declare function localesMatch(a: string | undefined, b: string | undefined): boolean;
+declare function resolveLocaleProvider(getAcceptLanguage?: LocaleProvider, locale?: LocaleClientOptions): LocaleProvider | undefined;
+declare function resolveRequestLocale(getAcceptLanguage?: LocaleProvider, locale?: LocaleClientOptions): Promise<string | undefined>;
+/**
+ * Value to send as `Accept-Language`, or `undefined` to omit the header
+ * when the resolved locale matches `defaultLocale` (normalized).
+ */
+declare function acceptLanguageForRequest(resolved: string | undefined, defaultLocale?: string): string | undefined;
+declare function resolveAcceptLanguage(provider?: LocaleProvider): Promise<string | undefined>;
+declare function readResponseContentLanguage(flatHeaders: Readonly<Record<string, string>>): string | undefined;
+declare function notifyLocaleMismatch(locale: LocaleClientOptions | undefined, ctx: Readonly<LocaleMismatchContext>): void;
 
 declare function resolveAuthorizationHeader(auth: AuthConfig | undefined): Promise<string | undefined>;
 
@@ -336,4 +414,4 @@ declare function pollAsyncResult(client: ApiClient, initial: Extract<ClientSucce
 
 declare const PACKAGE_VERSION: string;
 
-export { type AcceptedBody, type ApiClient, type ApiClientConfig, ApiClientError, type AuthConfig, type BaseUrlMode, type ClientSuccess, type ClientSuccessWithDocument, type CursorPagination, DEFAULT_PAGE_SIZE_CAP, DEFAULT_TIMEOUT_MS, type DeprecationInfo, type ErrResult, IDEMPOTENCY_MAX_LENGTH, type IdempotencyReplayContext, type IncludedIndex, type JsonApiDocument, type JsonApiErrorDocument, type JsonApiErrorObject, type JsonApiPrimaryData, type JsonApiQueryInput, type JsonApiResourceLinkage, type JsonApiResourceObject, type JsonApiSuccessBody, type MultiStatusBody, type MultiStatusItem, type NoContentBody, type NormalizedResponseHeaders, type OffsetPagination, type OkResult, PACKAGE_VERSION, type PollOptions, type RequestCallOptions, type Result, type RetryOptions, type TokenProvider, type TransformResponseKeysMode, type UnknownPagination, type ValidationGroups, applyJsonApiHeaders, applyTransformKeys, assertValidIdempotencyKey, buildCursorPageParams, buildJsonApiQuery, buildOffsetPageParams, createApiClient, createHealthCheck, defaultIdempotencyKey, dispatchWithRetry, etagFromResponseHeaders, flattenAxiosHeaders, formatIfMatch, getHeader, getNextPageUrl, groupValidationErrorsByPointer, hasErrorCode, indexIncluded, isApiClientError, isApiClientErrorWithCode, isAuthenticationError, isConflictError, isForbiddenError, isIdempotencyKeyRequiredError, isIfMatchRequiredError, isMfaVerificationRequiredError, isMutationMethod, isPayloadTooLargeError, isPreconditionFailedError, isPreconditionRequiredError, isRetryablePerPolicy, isValidationError, normalizeAxiosResponse, normalizeHttpUrl, parseDeprecationHeaders, parseJsonApiDocument, parseJsonApiErrorBody, parseMultiStatusBody, parsePaginationKind, parseRetryAfterSeconds, pollAsyncResult, readResourceVersion, redactHeaderRecord, resolveAcceptLanguage, resolveAcceptedLocation, resolveAuthorizationHeader, resolveIncluded, resolveResourcePath, retryAllowed, truncateForLog };
+export { type AcceptedBody, type ApiClient, type ApiClientConfig, ApiClientError, type AuthConfig, type BaseUrlMode, type ClientSuccess, type ClientSuccessWithDocument, type CreateIdempotencyIntentOptions, type CursorPagination, DEFAULT_PAGE_SIZE_CAP, DEFAULT_TIMEOUT_MS, type DeprecationInfo, type ErrResult, IDEMPOTENCY_MAX_LENGTH, type IdempotencyIntent, type IdempotencyReplayContext, type IdempotencyRotation, type IncludedIndex, type JsonApiDocument, type JsonApiErrorDocument, type JsonApiErrorObject, type JsonApiPrimaryData, type JsonApiQueryInput, type JsonApiResourceLinkage, type JsonApiResourceObject, type JsonApiSuccessBody, type LocaleClientOptions, type LocaleMismatchContext, type LocaleProvider, type MultiStatusBody, type MultiStatusItem, type NoContentBody, type NormalizedResponseHeaders, type OffsetPagination, type OkResult, PACKAGE_VERSION, type PollOptions, type RequestCallOptions, type Result, type RetryOptions, type TokenProvider, type TransformResponseKeysMode, type UnknownPagination, type ValidationGroups, acceptLanguageForRequest, applyJsonApiHeaders, applyTransformKeys, assertValidIdempotencyKey, buildCursorPageParams, buildJsonApiQuery, buildOffsetPageParams, createApiClient, createHealthCheck, createIdempotencyIntent, createMutationIdempotency, defaultIdempotencyKey, dispatchWithRetry, etagFromResponseHeaders, flattenAxiosHeaders, formatIfMatch, getHeader, getNextPageUrl, groupValidationErrorsByPointer, hasErrorCode, idempotencyRotationForRetry, indexIncluded, isApiClientError, isApiClientErrorWithCode, isAuthenticationError, isConflictError, isForbiddenError, isIdempotencyInProgressError, isIdempotencyKeyRequiredError, isIdempotencyKeyReusedError, isIfMatchRequiredError, isMfaVerificationRequiredError, isMutationMethod, isPayloadTooLargeError, isPreconditionFailedError, isPreconditionRequiredError, isRetryablePerPolicy, isValidationError, localesMatch, normalizeAxiosResponse, normalizeHttpUrl, normalizeLocaleCode, notifyLocaleMismatch, parseContentLanguage, parseDeprecationHeaders, parseJsonApiDocument, parseJsonApiErrorBody, parseMultiStatusBody, parsePaginationKind, parseRetryAfterSeconds, pollAsyncResult, readResourceVersion, readResponseContentLanguage, redactHeaderRecord, resolveAcceptLanguage, resolveAcceptedLocation, resolveAuthorizationHeader, resolveIncluded, resolveLocaleProvider, resolveRequestLocale, resolveResourcePath, retryAllowed, truncateForLog };

package/dist/index.js

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@vahidkaargar/customized-api-client",
-  version: "0.3.0",
+  version: "0.5.0",
   description: "TypeScript Axios client for JSON:API v1.1 with idempotency, retries, and normalized results",
   type: "module",
   engines: {
@@ -125,11 +125,85 @@ async function resolveAuthorizationHeader(auth) {
   return `Bearer ${s}`;
 }
 
+// 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/headers/locale.ts
+function normalizeLocaleCode(tag) {
+  if (tag === void 0) return void 0;
+  const trimmed = tag.trim();
+  if (!trimmed) return void 0;
+  const base = trimmed.split(/[-_]/)[0]?.trim();
+  return base ? base.toLowerCase() : void 0;
+}
+function parseContentLanguage(header) {
+  if (header === void 0) return void 0;
+  const first = header.split(",")[0]?.trim();
+  if (!first) return void 0;
+  const tag = first.split(";")[0]?.trim();
+  return tag && tag.length > 0 ? tag : void 0;
+}
+function localesMatch(a, b) {
+  const na = normalizeLocaleCode(a);
+  const nb = normalizeLocaleCode(b);
+  if (na === void 0 || nb === void 0) return false;
+  return na === nb;
+}
+function resolveLocaleProvider(getAcceptLanguage, locale) {
+  return locale?.getLocale ?? getAcceptLanguage;
+}
+async function resolveRequestLocale(getAcceptLanguage, locale) {
+  return resolveAcceptLanguage(resolveLocaleProvider(getAcceptLanguage, locale));
+}
+function acceptLanguageForRequest(resolved, defaultLocale) {
+  if (resolved === void 0) return void 0;
+  if (defaultLocale !== void 0 && localesMatch(resolved, defaultLocale)) {
+    return void 0;
+  }
+  return resolved;
+}
 async function resolveAcceptLanguage(provider) {
   if (!provider) return void 0;
   const v = await provider();
-  return v ?? void 0;
+  if (v === null || v === void 0) return void 0;
+  const trimmed = v.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function readResponseContentLanguage(flatHeaders) {
+  return parseContentLanguage(getHeader(flatHeaders, "content-language"));
+}
+function notifyLocaleMismatch(locale, ctx) {
+  const handler = locale?.onLocaleMismatch;
+  if (!handler) return;
+  if (ctx.requested === void 0) return;
+  if (localesMatch(ctx.requested, ctx.resolved)) return;
+  if (handler === "warn") {
+    console.warn(
+      "[@vahidkaargar/customized-api-client] Content-Language mismatch",
+      ctx
+    );
+    return;
+  }
+  handler(ctx);
 }
 
 // src/headers/idempotency.ts
@@ -217,28 +291,6 @@ function parseRetryAfterSeconds(value) {
   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;
@@ -662,6 +714,7 @@ function createApiClient(config) {
   const mode = config.baseUrlMode ?? "modeB";
   const genKey = config.generateIdempotencyKey ?? defaultIdempotencyKey;
   warnInsecureBaseUrl(config.baseURL);
+  const localeByRequest = /* @__PURE__ */ new WeakMap();
   const instance = axios.create({
     baseURL: config.baseURL,
     timeout: config.timeout ?? DEFAULT_TIMEOUT_MS,
@@ -678,9 +731,15 @@ function createApiClient(config) {
     if (authHeader) {
       next.headers.Authorization = authHeader;
     }
-    const lang = await resolveAcceptLanguage(config.getAcceptLanguage);
-    if (lang) {
-      next.headers["Accept-Language"] = lang;
+    const resolved = await resolveRequestLocale(
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- legacy `getAcceptLanguage` fallback
+      config.getAcceptLanguage,
+      config.locale
+    );
+    localeByRequest.set(next, resolved);
+    const toSend = acceptLanguageForRequest(resolved, config.locale?.defaultLocale);
+    if (toSend) {
+      next.headers["Accept-Language"] = toSend;
     }
     if (isMutationMethod(method)) {
       const h = next.headers;
@@ -706,6 +765,17 @@ function createApiClient(config) {
       if (dep && config.onDeprecated) {
         config.onDeprecated(dep);
       }
+      const contentLang = readResponseContentLanguage(flat);
+      if (contentLang) {
+        notifyLocaleMismatch(config.locale, {
+          requested: localeByRequest.get(res.config),
+          resolved: contentLang,
+          /* v8 ignore start -- @preserve axios config url/method are strings */
+          url: typeof res.config.url === "string" ? res.config.url : void 0,
+          method: typeof res.config.method === "string" ? res.config.method : void 0
+          /* v8 ignore stop -- @preserve */
+        });
+      }
       return res;
     },
     (err) => Promise.reject(
@@ -875,6 +945,12 @@ function isValidationError(e) {
 function isConflictError(e) {
   return isApiErr(e, 409);
 }
+function isIdempotencyKeyReusedError(e) {
+  return isApiErrWithCode(e, 409, "IDEMPOTENCY_KEY_REUSED");
+}
+function isIdempotencyInProgressError(e) {
+  return isApiErrWithCode(e, 409, "IDEMPOTENCY_REQUEST_IN_PROGRESS");
+}
 function isPayloadTooLargeError(e) {
   return isApiErr(e, 413);
 }
@@ -895,6 +971,59 @@ function isApiErrWithCode(e, status, code) {
   return isApiErr(e, status) && hasErrorCode(e, code);
 }
 
+// src/idempotency/intent.ts
+function createIdempotencyIntent(options) {
+  const generateKey = options?.generateKey ?? defaultIdempotencyKey;
+  let activeKey = null;
+  return {
+    get activeKey() {
+      return activeKey;
+    },
+    hasActiveIntent() {
+      return activeKey !== null;
+    },
+    begin() {
+      activeKey = generateKey();
+      return activeKey;
+    },
+    keyFor(rotation) {
+      if (rotation === "rotate") {
+        activeKey = generateKey();
+        return activeKey;
+      }
+      if (activeKey === null) {
+        activeKey = generateKey();
+        return activeKey;
+      }
+      return activeKey;
+    },
+    complete() {
+      activeKey = null;
+    },
+    abandon() {
+      activeKey = null;
+    }
+  };
+}
+var createMutationIdempotency = createIdempotencyIntent;
+
+// src/idempotency/rotation.ts
+function idempotencyRotationForRetry(error) {
+  if (!(error instanceof ApiClientError)) {
+    return "reuse";
+  }
+  if (isIdempotencyInProgressError(error)) {
+    return "reuse";
+  }
+  if (isIdempotencyKeyReusedError(error)) {
+    return "rotate";
+  }
+  if (isValidationError(error)) {
+    return "rotate";
+  }
+  return "reuse";
+}
+
 // src/parse/pagination.ts
 function parsePaginationKind(meta, links) {
   const m = meta ?? {};
@@ -1089,6 +1218,7 @@ export {
   DEFAULT_TIMEOUT_MS,
   IDEMPOTENCY_MAX_LENGTH,
   PACKAGE_VERSION,
+  acceptLanguageForRequest,
   applyJsonApiHeaders,
   applyTransformKeys,
   assertValidIdempotencyKey,
@@ -1097,6 +1227,8 @@ export {
   buildOffsetPageParams,
   createApiClient,
   createHealthCheck,
+  createIdempotencyIntent,
+  createMutationIdempotency,
   defaultIdempotencyKey,
   dispatchWithRetry,
   etagFromResponseHeaders,
@@ -1106,13 +1238,16 @@ export {
   getNextPageUrl,
   groupValidationErrorsByPointer,
   hasErrorCode,
+  idempotencyRotationForRetry,
   indexIncluded,
   isApiClientError,
   isApiClientErrorWithCode,
   isAuthenticationError,
   isConflictError,
   isForbiddenError,
+  isIdempotencyInProgressError,
   isIdempotencyKeyRequiredError,
+  isIdempotencyKeyReusedError,
   isIfMatchRequiredError,
   isMfaVerificationRequiredError,
   isMutationMethod,
@@ -1121,8 +1256,12 @@ export {
   isPreconditionRequiredError,
   isRetryablePerPolicy,
   isValidationError,
+  localesMatch,
   normalizeAxiosResponse,
   normalizeHttpUrl,
+  normalizeLocaleCode,
+  notifyLocaleMismatch,
+  parseContentLanguage,
   parseDeprecationHeaders,
   parseJsonApiDocument,
   parseJsonApiErrorBody,
@@ -1131,11 +1270,14 @@ export {
   parseRetryAfterSeconds,
   pollAsyncResult,
   readResourceVersion,
+  readResponseContentLanguage,
   redactHeaderRecord,
   resolveAcceptLanguage,
   resolveAcceptedLocation,
   resolveAuthorizationHeader,
   resolveIncluded,
+  resolveLocaleProvider,
+  resolveRequestLocale,
   resolveResourcePath,
   retryAllowed,
   truncateForLog