@vahidkaargar/customized-api-client 0.2.3 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ TypeScript **Axios** client for **JSON:API v1.1** APIs — Bearer auth, mandator
 - **Errors** — `ApiClientError` with `status`, `primaryCode`, `errors[]`, safe `toJSON()` for logs
 - **Idempotency** — `Idempotency-Key` on POST/PATCH/PUT/DELETE (ULID by default)
 - **Concurrency** — `If-Match: "v=<n>"` via `patchWithVersion` or `ifMatchVersion`
-- **Retries** — explicit policy (safe GET/HEAD vs mutations); honors `Retry-After`
+- **Retries** — explicit policy (safe GET/HEAD vs mutations); honors `Retry-After`; optional mutation **5xx** retries
 - **Two ergonomics** — throwing verbs **or** `safe*` methods returning `{ ok, value \| error }`
 - **Cancellation** — optional `AbortSignal` per request
 
@@ -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
@@ -302,18 +315,23 @@ 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 |
-| `isRetryablePerPolicy` | Would retry per client policy (UI hints) |
+| `isRetryablePerPolicy` | Would retry per client policy (UI hints); pass `{ retryMutationsOnServerError: true }` to match clients that opt into mutation **5xx** retries |
 
 ---
 
 ## Idempotency
 
 - **POST, PATCH, PUT, DELETE** send **`Idempotency-Key`** (ULID per request by default).
-- Retries reuse the **same key and body**.
+- 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.
 - Server replay → header `Idempotent-Replayed: true` → `headers.idempotentReplayed` + optional `onIdempotencyReplay`.
 - **GET / HEAD** never send idempotency keys.
 
@@ -341,17 +359,20 @@ Read version with `readResourceVersion(resource, etag)` — prefers `meta.versio
 | `baseDelayMs` | `200` |
 | `maxDelayMs` | `10000` |
 | `jitterRatio` | `0.2` |
+| `retryMutationsOnServerError` | `false` |
 
 | Situation | Retried? |
 |-----------|----------|
 | Network error (no response) | Yes |
 | GET/HEAD **408, 429, 5xx** | Yes |
 | GET/HEAD **401, 403, 412, 428**, validation 4xx | No |
-| Mutations **5xx / 429** | No |
+| Mutations **5xx / 429** | No (set `retry: { retryMutationsOnServerError: true }` to retry **5xx** only; **429** stays off) |
 | Mutation **409** `IDEMPOTENCY_REQUEST_IN_PROGRESS` | Yes |
 | **409** `IDEMPOTENCY_KEY_REUSED` | No |
 
-Disable: `retry: { maxAttempts: 1 }`. Inspect logic: `retryAllowed({ … })`.
+When `retryMutationsOnServerError` is **true**, POST/PUT/PATCH/DELETE responses with status **500–599** use the same backoff and `Retry-After` handling as reads, with the **same** request config (so the same `Idempotency-Key` and body). Use this when your server does **not** persist a replay body for **5xx** and allows the handler to run again for the same key.
+
+Disable: `retry: { maxAttempts: 1 }`. Inspect logic: `retryAllowed({ … })` (include `retryMutationsOnServerError` when mirroring client config). For thrown errors: `isRetryablePerPolicy(err, { retryMutationsOnServerError: true })`.
 
 ---
 
@@ -435,13 +456,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

@@ -51,11 +51,16 @@ __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,
@@ -86,7 +91,7 @@ module.exports = __toCommonJS(index_exports);
 // 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: {
@@ -170,14 +175,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
@@ -261,6 +281,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;
@@ -325,7 +348,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"]);
@@ -345,7 +369,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;
@@ -840,6 +865,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 });
     },
@@ -872,20 +900,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);
 }
@@ -895,6 +945,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);
 }
@@ -907,18 +966,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) {
@@ -1131,11 +1194,16 @@ var PACKAGE_VERSION = package_default.version;
   getHeader,
   getNextPageUrl,
   groupValidationErrorsByPointer,
+  hasErrorCode,
   indexIncluded,
   isApiClientError,
+  isApiClientErrorWithCode,
   isAuthenticationError,
   isConflictError,
   isForbiddenError,
+  isIdempotencyKeyRequiredError,
+  isIfMatchRequiredError,
+  isMfaVerificationRequiredError,
   isMutationMethod,
   isPayloadTooLargeError,
   isPreconditionFailedError,