@vahidkaargar/customized-api-client 0.2.4 → 0.4.0

package/README.md

@@ -187,6 +187,19 @@ setTimeout(() => controller.abort(), 5_000);
 await promise; // throws when aborted
 ```
 
+### Non-JSON:API bodies (multipart)
+
+For file uploads, send `FormData` — the client keeps `Accept: application/vnd.api+json`, omits JSON:API `Content-Type` (Axios sets the multipart boundary), and still sends `Idempotency-Key` on POST.
+
+```typescript
+const fd = new FormData();
+fd.append('file', file, file.name);
+
+await client.request({ method: 'POST', url: '/media', data: fd });
+// or:
+await client.postFormData('/media', fd);
+```
+
 ### Poll an async job (202)
 
 ```typescript
@@ -216,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 |
@@ -234,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
@@ -302,7 +340,11 @@ Synthetic codes when the body is missing or invalid: `EMPTY_ERROR_BODY`, `INVALI
 | `isAuthenticationError` | 401 |
 | `isForbiddenError` | 403 |
 | `isValidationError` | 422 |
-| `isPreconditionRequiredError` | 428 |
+| `isPreconditionRequiredError` | any **428** |
+| `isIdempotencyKeyRequiredError` | **428** + `IDEMPOTENCY_KEY_REQUIRED` |
+| `isIfMatchRequiredError` | **428** + `IF_MATCH_REQUIRED` |
+| `isMfaVerificationRequiredError` | **428** + `MFA_VERIFICATION_REQUIRED` |
+| `hasErrorCode` / `isApiClientErrorWithCode` | matching `errors[].code` |
 | `isPreconditionFailedError` | 412 |
 | `isConflictError` | 409 |
 | `isPayloadTooLargeError` | 413 |
@@ -439,13 +481,19 @@ This package ships **generic JSON:API types**, not endpoint-specific OpenAPI typ
 3. Use generics at call sites:
 
 ```typescript
+import type { JsonApiDocument, JsonApiResourceObject } from '@vahidkaargar/customized-api-client';
 import type { operations } from '@myorg/api-types';
 
-type MeResponse = operations['getMe']['responses'][200]['content']['application/vnd.api+json'];
-const me = await client.get<MeResponse>('/me');
+type MeDoc = JsonApiDocument<JsonApiResourceObject>;
+// Or from OpenAPI: operations['getMe']['responses'][200]['content']['application/vnd.api+json']
+
+const res = await client.get<MeDoc>('/me');
+if (res.kind === 'jsonapi-success') {
+  const me = res.document.data; // document typed as MeDoc
+}
 ```
 
-String paths and manual types work without OpenAPI.
+The generic narrows `document` on **`jsonapi-success`**; `accepted`, `no-content`, and `multi-status` shapes are unchanged. String paths and manual types work without OpenAPI.
 
 ---
 

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,
@@ -51,19 +52,28 @@ __export(index_exports, {
   getHeader: () => getHeader,
   getNextPageUrl: () => getNextPageUrl,
   groupValidationErrorsByPointer: () => groupValidationErrorsByPointer,
+  hasErrorCode: () => hasErrorCode,
   indexIncluded: () => indexIncluded,
   isApiClientError: () => isApiClientError,
+  isApiClientErrorWithCode: () => isApiClientErrorWithCode,
   isAuthenticationError: () => isAuthenticationError,
   isConflictError: () => isConflictError,
   isForbiddenError: () => isForbiddenError,
+  isIdempotencyKeyRequiredError: () => isIdempotencyKeyRequiredError,
+  isIfMatchRequiredError: () => isIfMatchRequiredError,
+  isMfaVerificationRequiredError: () => isMfaVerificationRequiredError,
   isMutationMethod: () => isMutationMethod,
   isPayloadTooLargeError: () => isPayloadTooLargeError,
   isPreconditionFailedError: () => isPreconditionFailedError,
   isPreconditionRequiredError: () => isPreconditionRequiredError,
   isRetryablePerPolicy: () => isRetryablePerPolicy,
   isValidationError: () => isValidationError,
+  localesMatch: () => localesMatch,
   normalizeAxiosResponse: () => normalizeAxiosResponse,
   normalizeHttpUrl: () => normalizeHttpUrl,
+  normalizeLocaleCode: () => normalizeLocaleCode,
+  notifyLocaleMismatch: () => notifyLocaleMismatch,
+  parseContentLanguage: () => parseContentLanguage,
   parseDeprecationHeaders: () => parseDeprecationHeaders,
   parseJsonApiDocument: () => parseJsonApiDocument,
   parseJsonApiErrorBody: () => parseJsonApiErrorBody,
@@ -72,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
@@ -86,7 +99,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@vahidkaargar/customized-api-client",
-  version: "0.2.4",
+  version: "0.4.0",
   description: "TypeScript Axios client for JSON:API v1.1 with idempotency, retries, and normalized results",
   type: "module",
   engines: {
@@ -170,14 +183,29 @@ function applyJsonApiHeaders(config, method) {
   const m = method.toUpperCase();
   const headers = { ...config.headers };
   headers.Accept = headers.Accept ?? JSON_API;
-  if (hasJsonBody(m, config)) {
+  if (shouldSetJsonApiContentType(m, config)) {
     headers["Content-Type"] = headers["Content-Type"] ?? JSON_API;
   }
   return { ...config, headers };
 }
-function hasJsonBody(method, config) {
+function shouldSetJsonApiContentType(method, config) {
   if (!["POST", "PATCH", "PUT"].includes(method)) return false;
-  return config.data !== void 0 && config.data !== null;
+  const data = config.data;
+  if (data === void 0 || data === null) return false;
+  return isJsonApiSerializableBody(data);
+}
+function isJsonApiSerializableBody(data) {
+  if (typeof data !== "object") return false;
+  if (Array.isArray(data)) return true;
+  if (typeof FormData !== "undefined" && data instanceof FormData) return false;
+  if (typeof Blob !== "undefined" && data instanceof Blob) return false;
+  if (data instanceof ArrayBuffer) return false;
+  if (ArrayBuffer.isView(data)) return false;
+  if (typeof URLSearchParams !== "undefined" && data instanceof URLSearchParams) return false;
+  if (data instanceof Date) return false;
+  if (typeof ReadableStream !== "undefined" && data instanceof ReadableStream) return false;
+  const proto = Object.getPrototypeOf(data);
+  return proto === Object.prototype || proto === null;
 }
 
 // src/headers/auth.ts
@@ -193,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
@@ -285,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;
@@ -730,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,
@@ -746,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;
@@ -774,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(
@@ -845,6 +943,9 @@ function createApiClient(config) {
     async post(path, data, opts) {
       return perform("POST", resolvePath(path), { ...opts, data });
     },
+    async postFormData(path, data, opts) {
+      return perform("POST", resolvePath(path), { ...opts, data });
+    },
     async patch(path, data, opts) {
       return perform("PATCH", resolvePath(path), { ...opts, data });
     },
@@ -877,20 +978,42 @@ function createApiClient(config) {
         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)),
-    safeGetByUrl: (url, opts) => safe(() => client.getByUrl(url, opts)),
-    safePatchWithVersion: (path, data, version, opts) => safe(() => client.patchWithVersion(path, data, version, opts))
+    safeGet: (path, opts) => safe(() => perform("GET", resolvePath(path), opts ?? {})),
+    safePost: (path, data, opts) => safe(() => perform("POST", resolvePath(path), { ...opts, data })),
+    safePatch: (path, data, opts) => safe(() => perform("PATCH", resolvePath(path), { ...opts, data })),
+    safePut: (path, data, opts) => safe(() => perform("PUT", resolvePath(path), { ...opts, data })),
+    safeDelete: (path, opts) => safe(() => perform("DELETE", resolvePath(path), opts ?? {})),
+    safeHead: (path, opts) => safe(() => perform("HEAD", resolvePath(path), opts ?? {})),
+    safeRequest: (ax, opts) => safe(() => {
+      const method = (ax.method ?? "GET").toUpperCase();
+      const rawUrl = ax.url ?? "/";
+      const u = 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")
+      });
+    }),
+    safeGetByUrl: (fullUrl, opts) => safe(() => perform("GET", fullUrl, opts ?? {})),
+    safePatchWithVersion: (path, data, version, opts) => safe(
+      () => perform("PATCH", resolvePath(path), {
+        ...opts,
+        data,
+        ifMatchVersion: version
+      })
+    )
   };
   return client;
 }
 
 // src/guards.ts
+function hasErrorCode(error, code) {
+  if (!(error instanceof ApiClientError)) return false;
+  return error.errors.some((e) => e.code === code);
+}
+function isApiClientErrorWithCode(error, code) {
+  return hasErrorCode(error, code);
+}
 function isAuthenticationError(e) {
   return isApiErr(e, 401);
 }
@@ -900,6 +1023,15 @@ function isForbiddenError(e) {
 function isPreconditionRequiredError(e) {
   return isApiErr(e, 428);
 }
+function isIdempotencyKeyRequiredError(e) {
+  return isApiErrWithCode(e, 428, "IDEMPOTENCY_KEY_REQUIRED");
+}
+function isIfMatchRequiredError(e) {
+  return isApiErrWithCode(e, 428, "IF_MATCH_REQUIRED");
+}
+function isMfaVerificationRequiredError(e) {
+  return isApiErrWithCode(e, 428, "MFA_VERIFICATION_REQUIRED");
+}
 function isPreconditionFailedError(e) {
   return isApiErr(e, 412);
 }
@@ -925,6 +1057,9 @@ function isRetryablePerPolicy(e, policy) {
 function isApiErr(e, status) {
   return e instanceof ApiClientError && e.status === status;
 }
+function isApiErrWithCode(e, status, code) {
+  return isApiErr(e, status) && hasErrorCode(e, code);
+}
 
 // src/parse/pagination.ts
 function parsePaginationKind(meta, links) {
@@ -1121,6 +1256,7 @@ var PACKAGE_VERSION = package_default.version;
   DEFAULT_TIMEOUT_MS,
   IDEMPOTENCY_MAX_LENGTH,
   PACKAGE_VERSION,
+  acceptLanguageForRequest,
   applyJsonApiHeaders,
   applyTransformKeys,
   assertValidIdempotencyKey,
@@ -1137,19 +1273,28 @@ var PACKAGE_VERSION = package_default.version;
   getHeader,
   getNextPageUrl,
   groupValidationErrorsByPointer,
+  hasErrorCode,
   indexIncluded,
   isApiClientError,
+  isApiClientErrorWithCode,
   isAuthenticationError,
   isConflictError,
   isForbiddenError,
+  isIdempotencyKeyRequiredError,
+  isIfMatchRequiredError,
+  isMfaVerificationRequiredError,
   isMutationMethod,
   isPayloadTooLargeError,
   isPreconditionFailedError,
   isPreconditionRequiredError,
   isRetryablePerPolicy,
   isValidationError,
+  localesMatch,
   normalizeAxiosResponse,
   normalizeHttpUrl,
+  normalizeLocaleCode,
+  notifyLocaleMismatch,
+  parseContentLanguage,
   parseDeprecationHeaders,
   parseJsonApiDocument,
   parseJsonApiErrorBody,
@@ -1158,11 +1303,14 @@ var PACKAGE_VERSION = package_default.version;
   parseRetryAfterSeconds,
   pollAsyncResult,
   readResourceVersion,
+  readResponseContentLanguage,
   redactHeaderRecord,
   resolveAcceptLanguage,
   resolveAcceptedLocation,
   resolveAuthorizationHeader,
   resolveIncluded,
+  resolveLocaleProvider,
+  resolveRequestLocale,
   resolveResourcePath,
   retryAllowed,
   truncateForLog