@vahidkaargar/customized-api-client 0.2.4 → 0.4.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;
@@ -124,6 +144,9 @@ interface MultiStatusBody {
     readonly headers: NormalizedResponseHeaders;
 }
 type ClientSuccess = JsonApiSuccessBody | NoContentBody | AcceptedBody | MultiStatusBody;
+type ClientSuccessWithDocument<T extends JsonApiDocument = JsonApiDocument> = (JsonApiSuccessBody & {
+    readonly document: T;
+}) | NoContentBody | AcceptedBody | MultiStatusBody;
 interface OkResult<T extends ClientSuccess> {
     readonly ok: true;
     readonly value: T;
@@ -154,30 +177,37 @@ interface RequestCallOptions {
     readonly signal?: AbortSignal;
 }
 interface ApiClient {
-    readonly get: (path: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly head: (path: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly post: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly patch: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly put: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly delete: (path: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly request: (ax: AxiosRequestConfig, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly getByUrl: (fullUrl: string, opts?: RequestCallOptions) => Promise<ClientSuccess>;
-    readonly patchWithVersion: (path: string, data: unknown, version: number, opts?: Omit<RequestCallOptions, 'ifMatchVersion'>) => Promise<ClientSuccess>;
-    readonly safeGet: (path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safePost: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safePatch: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safePut: (path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safeDelete: (path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safeHead: (path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safeRequest: (ax: AxiosRequestConfig, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safeGetByUrl: (fullUrl: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccess, ApiClientError>>;
-    readonly safePatchWithVersion: (path: string, data: unknown, version: number, opts?: Omit<RequestCallOptions, 'ifMatchVersion'>) => Promise<Result<ClientSuccess, ApiClientError>>;
+    readonly get: <T extends JsonApiDocument = JsonApiDocument>(path: string, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly head: <T extends JsonApiDocument = JsonApiDocument>(path: string, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly post: <T extends JsonApiDocument = JsonApiDocument>(path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly patch: <T extends JsonApiDocument = JsonApiDocument>(path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly put: <T extends JsonApiDocument = JsonApiDocument>(path: string, data?: unknown, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly delete: <T extends JsonApiDocument = JsonApiDocument>(path: string, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly postFormData: <T extends JsonApiDocument = JsonApiDocument>(path: string, data: FormData, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly request: <T extends JsonApiDocument = JsonApiDocument>(ax: AxiosRequestConfig, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly getByUrl: <T extends JsonApiDocument = JsonApiDocument>(fullUrl: string, opts?: RequestCallOptions) => Promise<ClientSuccessWithDocument<T>>;
+    readonly patchWithVersion: <T extends JsonApiDocument = JsonApiDocument>(path: string, data: unknown, version: number, opts?: Omit<RequestCallOptions, 'ifMatchVersion'>) => Promise<ClientSuccessWithDocument<T>>;
+    readonly safeGet: <T extends JsonApiDocument = JsonApiDocument>(path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safePost: <T extends JsonApiDocument = JsonApiDocument>(path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safePatch: <T extends JsonApiDocument = JsonApiDocument>(path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safePut: <T extends JsonApiDocument = JsonApiDocument>(path: string, data?: unknown, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safeDelete: <T extends JsonApiDocument = JsonApiDocument>(path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safeHead: <T extends JsonApiDocument = JsonApiDocument>(path: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safeRequest: <T extends JsonApiDocument = JsonApiDocument>(ax: AxiosRequestConfig, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safeGetByUrl: <T extends JsonApiDocument = JsonApiDocument>(fullUrl: string, opts?: RequestCallOptions) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
+    readonly safePatchWithVersion: <T extends JsonApiDocument = JsonApiDocument>(path: string, data: unknown, version: number, opts?: Omit<RequestCallOptions, 'ifMatchVersion'>) => Promise<Result<ClientSuccessWithDocument<T>, ApiClientError>>;
 }
 declare function createApiClient(config: ApiClientConfig): ApiClient;
 
+declare function hasErrorCode(error: unknown, code: string): boolean;
+declare function isApiClientErrorWithCode(error: unknown, code: string): error is ApiClientError;
 declare function isAuthenticationError(e: unknown): boolean;
 declare function isForbiddenError(e: unknown): boolean;
+/** True for any HTTP 428. Prefer code-specific helpers when branching on `errors[].code`. */
 declare function isPreconditionRequiredError(e: unknown): boolean;
+declare function isIdempotencyKeyRequiredError(e: unknown): boolean;
+declare function isIfMatchRequiredError(e: unknown): boolean;
+declare function isMfaVerificationRequiredError(e: unknown): boolean;
 declare function isPreconditionFailedError(e: unknown): boolean;
 declare function isValidationError(e: unknown): boolean;
 declare function isConflictError(e: unknown): boolean;
@@ -204,7 +234,23 @@ declare function isMutationMethod(method: string): boolean;
 
 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>;
 
@@ -326,4 +372,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 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, 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 };
+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 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, defaultIdempotencyKey, dispatchWithRetry, etagFromResponseHeaders, flattenAxiosHeaders, formatIfMatch, 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, 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.2.4",
+  version: "0.4.0",
   description: "TypeScript Axios client for JSON:API v1.1 with idempotency, retries, and normalized results",
   type: "module",
   engines: {
@@ -87,14 +87,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
@@ -110,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
@@ -202,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;
@@ -647,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,
@@ -663,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;
@@ -691,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(
@@ -762,6 +847,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 });
     },
@@ -794,20 +882,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);
 }
@@ -817,6 +927,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);
 }
@@ -842,6 +961,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) {
@@ -1037,6 +1159,7 @@ export {
   DEFAULT_TIMEOUT_MS,
   IDEMPOTENCY_MAX_LENGTH,
   PACKAGE_VERSION,
+  acceptLanguageForRequest,
   applyJsonApiHeaders,
   applyTransformKeys,
   assertValidIdempotencyKey,
@@ -1053,19 +1176,28 @@ export {
   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,
@@ -1074,11 +1206,14 @@ export {
   parseRetryAfterSeconds,
   pollAsyncResult,
   readResourceVersion,
+  readResponseContentLanguage,
   redactHeaderRecord,
   resolveAcceptLanguage,
   resolveAcceptedLocation,
   resolveAuthorizationHeader,
   resolveIncluded,
+  resolveLocaleProvider,
+  resolveRequestLocale,
   resolveResourcePath,
   retryAllowed,
   truncateForLog