// First request - creates user
const response = await fetch("/api/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(), // e.g. "idx_abc123"
  },
  body: JSON.stringify({ email: "user@example.com", name: "John" }),
});

// Same key - returns cached response (no duplicate creation)
const retry = await fetch("/api/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "idx_abc123", // Same key!
  },
  body: JSON.stringify({ email: "user@example.com", name: "John" }),
});

idx_<ulid>  // Recommended: index + ULID
req_<uuid>  // Alternative: request + UUID
<uuid>      // Simple UUID

// idempotency-middleware.ts
export async function idempotencyMiddleware(c, next) {
  const key = c.req.header("Idempotency-Key");

  if (!key) {
    return c.json({ error: "Idempotency-Key required" }, 400);
  }

  const cached = await cache.get(`idx:${key}`);
  if (cached) {
    return c.json(cached.body, cached.status);
  }

  await next();

  // Store response after handler runs
  const response = c.get("response");
  await cache.set(
    `idx:${key}`,
    {
      body: response.body,
      status: response.status,
    },
    TTL,
  );
}

TTL = 86400 seconds (24 hours)

{
  "error": "Idempotency-Key header is required"
}

{
  "error": "Idempotency-Key must be a valid string (max 256 chars)"
}

{
  "error": "Request with this Idempotency-Key is already being processed"
}

IDEMPOTENCY_ENABLED=true
IDEMPOTENCY_TTL=86400

// idempotency.test.ts
describe("Idempotency", () => {
  it("returns cached response for duplicate key", async () => {
    const key = crypto.randomUUID();

    // First request
    const res1 = await fetch("/api/v1/users", {
      method: "POST",
      headers: { "Idempotency-Key": key },
      body: JSON.stringify({ email: "test@example.com" }),
    });

    // Retry
    const res2 = await fetch("/api/v1/users", {
      method: "POST",
      headers: { "Idempotency-Key": key },
      body: JSON.stringify({ email: "test@example.com" }),
    });

    expect(res1.status).toBe(res2.status);
    expect(await res1.json()).toEqual(await res2.json());
  });
});