@vahidkaargar/customized-api-client 0.4.0 → 0.5.0

package/README.md

@@ -347,6 +347,8 @@ Synthetic codes when the body is missing or invalid: `EMPTY_ERROR_BODY`, `INVALI
 | `hasErrorCode` / `isApiClientErrorWithCode` | matching `errors[].code` |
 | `isPreconditionFailedError` | 412 |
 | `isConflictError` | 409 |
+| `isIdempotencyKeyReusedError` | **409** + `IDEMPOTENCY_KEY_REUSED` |
+| `isIdempotencyInProgressError` | **409** + `IDEMPOTENCY_REQUEST_IN_PROGRESS` |
 | `isPayloadTooLargeError` | 413 |
 | `isRetryablePerPolicy` | Would retry per client policy (UI hints); pass `{ retryMutationsOnServerError: true }` to match clients that opt into mutation **5xx** retries |
 
@@ -354,12 +356,46 @@ Synthetic codes when the body is missing or invalid: `EMPTY_ERROR_BODY`, `INVALI
 
 ## Idempotency
 
+### Transport (this client)
+
 - **POST, PATCH, PUT, DELETE** send **`Idempotency-Key`** (ULID per request by default).
-- 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.
+- Retries **inside one** `client.post()` / `patch()` / … reuse the **same key and body** (`dispatchWithRetry`).
 - Server replay → header `Idempotent-Replayed: true` → `headers.idempotentReplayed` + optional `onIdempotencyReplay`.
 - **GET / HEAD** never send idempotency keys.
 
+### Intent (your app)
+
+Separate user actions (Save, Retry button, confirm dialog) are **separate client calls**. Reuse the same key only when retrying the **same intent** after abort/network/`IDEMPOTENCY_REQUEST_IN_PROGRESS`; rotate after validation fixes or conflicting payload.
+
+```typescript
+import {
+  createApiClient,
+  createIdempotencyIntent,
+  idempotencyRotationForRetry,
+} from '@vahidkaargar/customized-api-client';
+
+const client = createApiClient({ baseURL: '…' });
+const intent = createIdempotencyIntent();
+
+async function save(rotation: 'reuse' | 'rotate' = 'rotate') {
+  await client.patch('/widgets/42', payload, {
+    idempotencyKey: intent.keyFor(rotation),
+  });
+  intent.complete();
+}
+
+// UI Retry after network → save('reuse')
+// Next Save after 422 → save('rotate') or save(idempotencyRotationForRetry(lastError))
+```
+
+| Helper | Role |
+|--------|------|
+| `createIdempotencyIntent()` | `begin` / `keyFor('reuse'\|'rotate')` / `complete` / `abandon` |
+| `idempotencyRotationForRetry(error)` | Suggested `'reuse'` vs `'rotate'` from an error |
+| `createMutationIdempotency` | Deprecated alias of `createIdempotencyIntent` |
+
+**412 If-Match** is not idempotency rotation — refresh `If-Match` version first, then retry with `'reuse'` if the payload is unchanged.
+
 ---
 
 ## Optimistic concurrency

package/dist/index.cjs

@@ -44,6 +44,8 @@ __export(index_exports, {
   buildOffsetPageParams: () => buildOffsetPageParams,
   createApiClient: () => createApiClient,
   createHealthCheck: () => createHealthCheck,
+  createIdempotencyIntent: () => createIdempotencyIntent,
+  createMutationIdempotency: () => createMutationIdempotency,
   defaultIdempotencyKey: () => defaultIdempotencyKey,
   dispatchWithRetry: () => dispatchWithRetry,
   etagFromResponseHeaders: () => etagFromResponseHeaders,
@@ -53,13 +55,16 @@ __export(index_exports, {
   getNextPageUrl: () => getNextPageUrl,
   groupValidationErrorsByPointer: () => groupValidationErrorsByPointer,
   hasErrorCode: () => hasErrorCode,
+  idempotencyRotationForRetry: () => idempotencyRotationForRetry,
   indexIncluded: () => indexIncluded,
   isApiClientError: () => isApiClientError,
   isApiClientErrorWithCode: () => isApiClientErrorWithCode,
   isAuthenticationError: () => isAuthenticationError,
   isConflictError: () => isConflictError,
   isForbiddenError: () => isForbiddenError,
+  isIdempotencyInProgressError: () => isIdempotencyInProgressError,
   isIdempotencyKeyRequiredError: () => isIdempotencyKeyRequiredError,
+  isIdempotencyKeyReusedError: () => isIdempotencyKeyReusedError,
   isIfMatchRequiredError: () => isIfMatchRequiredError,
   isMfaVerificationRequiredError: () => isMfaVerificationRequiredError,
   isMutationMethod: () => isMutationMethod,
@@ -99,7 +104,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@vahidkaargar/customized-api-client",
-  version: "0.4.0",
+  version: "0.5.0",
   description: "TypeScript Axios client for JSON:API v1.1 with idempotency, retries, and normalized results",
   type: "module",
   engines: {
@@ -1041,6 +1046,12 @@ function isValidationError(e) {
 function isConflictError(e) {
   return isApiErr(e, 409);
 }
+function isIdempotencyKeyReusedError(e) {
+  return isApiErrWithCode(e, 409, "IDEMPOTENCY_KEY_REUSED");
+}
+function isIdempotencyInProgressError(e) {
+  return isApiErrWithCode(e, 409, "IDEMPOTENCY_REQUEST_IN_PROGRESS");
+}
 function isPayloadTooLargeError(e) {
   return isApiErr(e, 413);
 }
@@ -1061,6 +1072,59 @@ function isApiErrWithCode(e, status, code) {
   return isApiErr(e, status) && hasErrorCode(e, code);
 }
 
+// src/idempotency/intent.ts
+function createIdempotencyIntent(options) {
+  const generateKey = options?.generateKey ?? defaultIdempotencyKey;
+  let activeKey = null;
+  return {
+    get activeKey() {
+      return activeKey;
+    },
+    hasActiveIntent() {
+      return activeKey !== null;
+    },
+    begin() {
+      activeKey = generateKey();
+      return activeKey;
+    },
+    keyFor(rotation) {
+      if (rotation === "rotate") {
+        activeKey = generateKey();
+        return activeKey;
+      }
+      if (activeKey === null) {
+        activeKey = generateKey();
+        return activeKey;
+      }
+      return activeKey;
+    },
+    complete() {
+      activeKey = null;
+    },
+    abandon() {
+      activeKey = null;
+    }
+  };
+}
+var createMutationIdempotency = createIdempotencyIntent;
+
+// src/idempotency/rotation.ts
+function idempotencyRotationForRetry(error) {
+  if (!(error instanceof ApiClientError)) {
+    return "reuse";
+  }
+  if (isIdempotencyInProgressError(error)) {
+    return "reuse";
+  }
+  if (isIdempotencyKeyReusedError(error)) {
+    return "rotate";
+  }
+  if (isValidationError(error)) {
+    return "rotate";
+  }
+  return "reuse";
+}
+
 // src/parse/pagination.ts
 function parsePaginationKind(meta, links) {
   const m = meta ?? {};
@@ -1265,6 +1329,8 @@ var PACKAGE_VERSION = package_default.version;
   buildOffsetPageParams,
   createApiClient,
   createHealthCheck,
+  createIdempotencyIntent,
+  createMutationIdempotency,
   defaultIdempotencyKey,
   dispatchWithRetry,
   etagFromResponseHeaders,
@@ -1274,13 +1340,16 @@ var PACKAGE_VERSION = package_default.version;
   getNextPageUrl,
   groupValidationErrorsByPointer,
   hasErrorCode,
+  idempotencyRotationForRetry,
   indexIncluded,
   isApiClientError,
   isApiClientErrorWithCode,
   isAuthenticationError,
   isConflictError,
   isForbiddenError,
+  isIdempotencyInProgressError,
   isIdempotencyKeyRequiredError,
+  isIdempotencyKeyReusedError,
   isIfMatchRequiredError,
   isMfaVerificationRequiredError,
   isMutationMethod,