@vahidkaargar/customized-api-client 0.3.0 → 0.5.0

package/README.md

@@ -229,7 +229,8 @@ Client-level options for `createApiClient({ … })`:
 | `defaultHeaders` | — | Merged into every request |
 | `retry` | see [Retries](#retries) | `maxAttempts`, backoff, jitter |
 | `generateIdempotencyKey` | ULID | Factory for mutation keys |
-| `getAcceptLanguage` | — | Sets `Accept-Language` when non-empty |
+| `locale` | — | `getLocale`, `defaultLocale`, `onLocaleMismatch` — see [Locale](#locale-accept-language--content-language) |
+| `getAcceptLanguage` | — | **Deprecated** — use `locale.getLocale`; sets `Accept-Language` when non-empty |
 | `onIdempotencyReplay` | — | Fired when `Idempotent-Replayed: true` |
 | `onUnauthorized` | — | Fired on normalized **401** |
 | `onDeprecated` | — | Deprecation / sunset headers |
@@ -247,6 +248,30 @@ auth: { type: 'partner-bearer', getSecret: () => process.env.PARTNER_SECRET }
 
 If `getToken` / `getSecret` returns `null` or `undefined`, no `Authorization` header is sent.
 
+### Locale (Accept-Language / Content-Language)
+
+Configure locale once on the client (e.g. for backends with `SetLocaleMiddleware`). This package only sets HTTP headers and optional mismatch reporting — not vue-i18n, `GET /locales`, or `GET /translations`.
+
+```typescript
+const client = createApiClient({
+  baseURL: 'https://api.example.com/api/v1',
+  locale: {
+    getLocale: () => getStoredLocale(), // 'en' | 'fr' | 'fa'
+    defaultLocale: 'en', // omit Accept-Language when UI locale is English (server default)
+    onLocaleMismatch: import.meta.env.DEV ? 'warn' : undefined,
+  },
+});
+```
+
+| Behavior | Detail |
+|----------|--------|
+| **Accept-Language** | From `locale.getLocale()` on every request via this client |
+| **Omit for default** | When resolved locale matches `defaultLocale` (primary subtag), header is not sent |
+| **Content-Language** | Exposed on success as `res.headers.contentLanguage` |
+| **Mismatch** | If response `Content-Language` differs from requested locale (base tag: `fr` vs `fr-FR` match), `'warn'` or your callback runs — UI locale is never changed |
+
+Legacy `getAcceptLanguage` still works; `locale.getLocale` takes precedence when both are set.
+
 ---
 
 ## Making requests
@@ -322,6 +347,8 @@ Synthetic codes when the body is missing or invalid: `EMPTY_ERROR_BODY`, `INVALI
 | `hasErrorCode` / `isApiClientErrorWithCode` | matching `errors[].code` |
 | `isPreconditionFailedError` | 412 |
 | `isConflictError` | 409 |
+| `isIdempotencyKeyReusedError` | **409** + `IDEMPOTENCY_KEY_REUSED` |
+| `isIdempotencyInProgressError` | **409** + `IDEMPOTENCY_REQUEST_IN_PROGRESS` |
 | `isPayloadTooLargeError` | 413 |
 | `isRetryablePerPolicy` | Would retry per client policy (UI hints); pass `{ retryMutationsOnServerError: true }` to match clients that opt into mutation **5xx** retries |
 
@@ -329,12 +356,46 @@ Synthetic codes when the body is missing or invalid: `EMPTY_ERROR_BODY`, `INVALI
 
 ## Idempotency
 
+### Transport (this client)
+
 - **POST, PATCH, PUT, DELETE** send **`Idempotency-Key`** (ULID per request by default).
-- Retries reuse the **same key and body** within one client call (`dispatchWithRetry`).
-- For **separate** `post`/`patch`/… invocations, pass the same `idempotencyKey` yourself if they represent the same user intent.
+- Retries **inside one** `client.post()` / `patch()` / … reuse the **same key and body** (`dispatchWithRetry`).
 - Server replay → header `Idempotent-Replayed: true` → `headers.idempotentReplayed` + optional `onIdempotencyReplay`.
 - **GET / HEAD** never send idempotency keys.
 
+### Intent (your app)
+
+Separate user actions (Save, Retry button, confirm dialog) are **separate client calls**. Reuse the same key only when retrying the **same intent** after abort/network/`IDEMPOTENCY_REQUEST_IN_PROGRESS`; rotate after validation fixes or conflicting payload.
+
+```typescript
+import {
+  createApiClient,
+  createIdempotencyIntent,
+  idempotencyRotationForRetry,
+} from '@vahidkaargar/customized-api-client';
+
+const client = createApiClient({ baseURL: '…' });
+const intent = createIdempotencyIntent();
+
+async function save(rotation: 'reuse' | 'rotate' = 'rotate') {
+  await client.patch('/widgets/42', payload, {
+    idempotencyKey: intent.keyFor(rotation),
+  });
+  intent.complete();
+}
+
+// UI Retry after network → save('reuse')
+// Next Save after 422 → save('rotate') or save(idempotencyRotationForRetry(lastError))
+```
+
+| Helper | Role |
+|--------|------|
+| `createIdempotencyIntent()` | `begin` / `keyFor('reuse'\|'rotate')` / `complete` / `abandon` |
+| `idempotencyRotationForRetry(error)` | Suggested `'reuse'` vs `'rotate'` from an error |
+| `createMutationIdempotency` | Deprecated alias of `createIdempotencyIntent` |
+
+**412 If-Match** is not idempotency rotation — refresh `If-Match` version first, then retry with `'reuse'` if the payload is unchanged.
+
 ---
 
 ## Optimistic concurrency

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   IDEMPOTENCY_MAX_LENGTH: () => IDEMPOTENCY_MAX_LENGTH,
   PACKAGE_VERSION: () => PACKAGE_VERSION,
+  acceptLanguageForRequest: () => acceptLanguageForRequest,
   applyJsonApiHeaders: () => applyJsonApiHeaders,
   applyTransformKeys: () => applyTransformKeys,
   assertValidIdempotencyKey: () => assertValidIdempotencyKey,
@@ -43,6 +44,8 @@ __export(index_exports, {
   buildOffsetPageParams: () => buildOffsetPageParams,
   createApiClient: () => createApiClient,
   createHealthCheck: () => createHealthCheck,
+  createIdempotencyIntent: () => createIdempotencyIntent,
+  createMutationIdempotency: () => createMutationIdempotency,
   defaultIdempotencyKey: () => defaultIdempotencyKey,
   dispatchWithRetry: () => dispatchWithRetry,
   etagFromResponseHeaders: () => etagFromResponseHeaders,
@@ -52,13 +55,16 @@ __export(index_exports, {
   getNextPageUrl: () => getNextPageUrl,
   groupValidationErrorsByPointer: () => groupValidationErrorsByPointer,
   hasErrorCode: () => hasErrorCode,
+  idempotencyRotationForRetry: () => idempotencyRotationForRetry,
   indexIncluded: () => indexIncluded,
   isApiClientError: () => isApiClientError,
   isApiClientErrorWithCode: () => isApiClientErrorWithCode,
   isAuthenticationError: () => isAuthenticationError,
   isConflictError: () => isConflictError,
   isForbiddenError: () => isForbiddenError,
+  isIdempotencyInProgressError: () => isIdempotencyInProgressError,
   isIdempotencyKeyRequiredError: () => isIdempotencyKeyRequiredError,
+  isIdempotencyKeyReusedError: () => isIdempotencyKeyReusedError,
   isIfMatchRequiredError: () => isIfMatchRequiredError,
   isMfaVerificationRequiredError: () => isMfaVerificationRequiredError,
   isMutationMethod: () => isMutationMethod,
@@ -67,8 +73,12 @@ __export(index_exports, {
   isPreconditionRequiredError: () => isPreconditionRequiredError,
   isRetryablePerPolicy: () => isRetryablePerPolicy,
   isValidationError: () => isValidationError,
+  localesMatch: () => localesMatch,
   normalizeAxiosResponse: () => normalizeAxiosResponse,
   normalizeHttpUrl: () => normalizeHttpUrl,
+  normalizeLocaleCode: () => normalizeLocaleCode,
+  notifyLocaleMismatch: () => notifyLocaleMismatch,
+  parseContentLanguage: () => parseContentLanguage,
   parseDeprecationHeaders: () => parseDeprecationHeaders,
   parseJsonApiDocument: () => parseJsonApiDocument,
   parseJsonApiErrorBody: () => parseJsonApiErrorBody,
@@ -77,11 +87,14 @@ __export(index_exports, {
   parseRetryAfterSeconds: () => parseRetryAfterSeconds,
   pollAsyncResult: () => pollAsyncResult,
   readResourceVersion: () => readResourceVersion,
+  readResponseContentLanguage: () => readResponseContentLanguage,
   redactHeaderRecord: () => redactHeaderRecord,
   resolveAcceptLanguage: () => resolveAcceptLanguage,
   resolveAcceptedLocation: () => resolveAcceptedLocation,
   resolveAuthorizationHeader: () => resolveAuthorizationHeader,
   resolveIncluded: () => resolveIncluded,
+  resolveLocaleProvider: () => resolveLocaleProvider,
+  resolveRequestLocale: () => resolveRequestLocale,
   resolveResourcePath: () => resolveResourcePath,
   retryAllowed: () => retryAllowed,
   truncateForLog: () => truncateForLog
@@ -91,7 +104,7 @@ module.exports = __toCommonJS(index_exports);
 // 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: {
@@ -213,11 +226,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
@@ -305,28 +392,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;
@@ -750,6 +815,7 @@ function createApiClient(config) {
   const mode = config.baseUrlMode ?? "modeB";
   const genKey = config.generateIdempotencyKey ?? defaultIdempotencyKey;
   warnInsecureBaseUrl(config.baseURL);
+  const localeByRequest = /* @__PURE__ */ new WeakMap();
   const instance = import_axios.default.create({
     baseURL: config.baseURL,
     timeout: config.timeout ?? DEFAULT_TIMEOUT_MS,
@@ -766,9 +832,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;
@@ -794,6 +866,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(
@@ -963,6 +1046,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);
 }
@@ -983,6 +1072,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 ?? {};
@@ -1178,6 +1320,7 @@ var PACKAGE_VERSION = package_default.version;
   DEFAULT_TIMEOUT_MS,
   IDEMPOTENCY_MAX_LENGTH,
   PACKAGE_VERSION,
+  acceptLanguageForRequest,
   applyJsonApiHeaders,
   applyTransformKeys,
   assertValidIdempotencyKey,
@@ -1186,6 +1329,8 @@ var PACKAGE_VERSION = package_default.version;
   buildOffsetPageParams,
   createApiClient,
   createHealthCheck,
+  createIdempotencyIntent,
+  createMutationIdempotency,
   defaultIdempotencyKey,
   dispatchWithRetry,
   etagFromResponseHeaders,
@@ -1195,13 +1340,16 @@ var PACKAGE_VERSION = package_default.version;
   getNextPageUrl,
   groupValidationErrorsByPointer,
   hasErrorCode,
+  idempotencyRotationForRetry,
   indexIncluded,
   isApiClientError,
   isApiClientErrorWithCode,
   isAuthenticationError,
   isConflictError,
   isForbiddenError,
+  isIdempotencyInProgressError,
   isIdempotencyKeyRequiredError,
+  isIdempotencyKeyReusedError,
   isIfMatchRequiredError,
   isMfaVerificationRequiredError,
   isMutationMethod,
@@ -1210,8 +1358,12 @@ var PACKAGE_VERSION = package_default.version;
   isPreconditionRequiredError,
   isRetryablePerPolicy,
   isValidationError,
+  localesMatch,
   normalizeAxiosResponse,
   normalizeHttpUrl,
+  normalizeLocaleCode,
+  notifyLocaleMismatch,
+  parseContentLanguage,
   parseDeprecationHeaders,
   parseJsonApiDocument,
   parseJsonApiErrorBody,
@@ -1220,11 +1372,14 @@ var PACKAGE_VERSION = package_default.version;
   parseRetryAfterSeconds,
   pollAsyncResult,
   readResourceVersion,
+  readResponseContentLanguage,
   redactHeaderRecord,
   resolveAcceptLanguage,
   resolveAcceptedLocation,
   resolveAuthorizationHeader,
   resolveIncluded,
+  resolveLocaleProvider,
+  resolveRequestLocale,
   resolveResourcePath,
   retryAllowed,
   truncateForLog