@vahidkaargar/customized-api-client 0.3.0 → 0.4.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

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,
@@ -67,8 +68,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 +82,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 +99,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@vahidkaargar/customized-api-client",
-  version: "0.3.0",
+  version: "0.4.0",
   description: "TypeScript Axios client for JSON:API v1.1 with idempotency, retries, and normalized results",
   type: "module",
   engines: {
@@ -213,11 +221,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 +387,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 +810,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 +827,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 +861,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(
@@ -1178,6 +1256,7 @@ var PACKAGE_VERSION = package_default.version;
   DEFAULT_TIMEOUT_MS,
   IDEMPOTENCY_MAX_LENGTH,
   PACKAGE_VERSION,
+  acceptLanguageForRequest,
   applyJsonApiHeaders,
   applyTransformKeys,
   assertValidIdempotencyKey,
@@ -1210,8 +1289,12 @@ var PACKAGE_VERSION = package_default.version;
   isPreconditionRequiredError,
   isRetryablePerPolicy,
   isValidationError,
+  localesMatch,
   normalizeAxiosResponse,
   normalizeHttpUrl,
+  normalizeLocaleCode,
+  notifyLocaleMismatch,
+  parseContentLanguage,
   parseDeprecationHeaders,
   parseJsonApiDocument,
   parseJsonApiErrorBody,
@@ -1220,11 +1303,14 @@ var PACKAGE_VERSION = package_default.version;
   parseRetryAfterSeconds,
   pollAsyncResult,
   readResourceVersion,
+  readResponseContentLanguage,
   redactHeaderRecord,
   resolveAcceptLanguage,
   resolveAcceptedLocation,
   resolveAuthorizationHeader,
   resolveIncluded,
+  resolveLocaleProvider,
+  resolveRequestLocale,
   resolveResourcePath,
   retryAllowed,
   truncateForLog