@vahidkaargar/customized-api-client 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -16,6 +16,11 @@ interface RetryOptions {
     readonly baseDelayMs?: number;
     readonly maxDelayMs?: number;
     readonly jitterRatio?: number;
+    /**
+     * When true, POST/PUT/PATCH/DELETE responses in the **5xx** range are retried like GET/HEAD
+     * (same `AxiosRequestConfig`, so same `Idempotency-Key` and body). Default false.
+     */
+    readonly retryMutationsOnServerError?: boolean;
 }
 interface IdempotencyReplayContext {
     readonly url?: string;
@@ -119,6 +124,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;
@@ -149,35 +157,44 @@ 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;
 declare function isPayloadTooLargeError(e: unknown): boolean;
-declare function isRetryablePerPolicy(e: unknown): boolean;
+declare function isRetryablePerPolicy(e: unknown, policy?: Readonly<{
+    retryMutationsOnServerError?: boolean;
+}>): boolean;
 
 /**
  * Truncate a value for safe logging (respects `maxBodyLogLength` from config when passed).
@@ -258,6 +275,8 @@ interface RetryPolicyContext {
     /** First JSON:API error `code` when present */
     readonly primaryErrorCode?: string;
     readonly isNetworkError: boolean;
+    /** When true, mutations retry on HTTP 5xx (after idempotency 409 rules). */
+    readonly retryMutationsOnServerError?: boolean;
 }
 /** Pure policy per [.cursor/tasks/project-plan.md §7](../tasks/project-plan.md). */
 declare function retryAllowed(ctx: RetryPolicyContext): boolean;
@@ -317,4 +336,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 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 };

package/dist/index.js

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "@vahidkaargar/customized-api-client",
-  version: "0.2.3",
+  version: "0.3.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
@@ -178,6 +193,9 @@ function retryAllowed(ctx) {
     return false;
   }
   if (!isRead) {
+    if (ctx.retryMutationsOnServerError === true && s >= 500 && s < 600) {
+      return true;
+    }
     return false;
   }
   if (s === 408) return true;
@@ -242,7 +260,8 @@ async function dispatchWithRetry(instance, config, options) {
         method: String(config.method ?? "GET"),
         status,
         primaryErrorCode: primary,
-        isNetworkError: false
+        isNetworkError: false,
+        retryMutationsOnServerError: options.retry?.retryMutationsOnServerError
       });
       if (allowed && attempt < max - 1) {
         const retryAfter = parseRetryAfterSeconds(flat["retry-after"]);
@@ -262,7 +281,8 @@ async function dispatchWithRetry(instance, config, options) {
       const isNet = isAxiosNetworkError(err);
       const allowed = retryAllowed({
         method: String(config.method ?? "GET"),
-        isNetworkError: isNet
+        isNetworkError: isNet,
+        retryMutationsOnServerError: options.retry?.retryMutationsOnServerError
       });
       if (!allowed || attempt >= max - 1) {
         throw err;
@@ -757,6 +777,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 });
     },
@@ -789,20 +812,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);
 }
@@ -812,6 +857,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);
 }
@@ -824,18 +878,22 @@ function isConflictError(e) {
 function isPayloadTooLargeError(e) {
   return isApiErr(e, 413);
 }
-function isRetryablePerPolicy(e) {
+function isRetryablePerPolicy(e, policy) {
   if (!(e instanceof ApiClientError)) return false;
   return retryAllowed({
     method: e.requestMethod ?? "GET",
     status: e.status,
     primaryErrorCode: e.primaryCode,
-    isNetworkError: false
+    isNetworkError: false,
+    retryMutationsOnServerError: policy?.retryMutationsOnServerError
   });
 }
 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) {
@@ -1047,11 +1105,16 @@ export {
   getHeader,
   getNextPageUrl,
   groupValidationErrorsByPointer,
+  hasErrorCode,
   indexIncluded,
   isApiClientError,
+  isApiClientErrorWithCode,
   isAuthenticationError,
   isConflictError,
   isForbiddenError,
+  isIdempotencyKeyRequiredError,
+  isIfMatchRequiredError,
+  isMfaVerificationRequiredError,
   isMutationMethod,
   isPayloadTooLargeError,
   isPreconditionFailedError,