feat(api): add idempotent pledge endpoint

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Idempotent pledge creation using the `Idempotency-Key` request header.
+- 24-hour response caching for duplicate pledge requests with the same idempotency key.
+- Redis-backed idempotency cache with in-memory LRU fallback for non-production environments.
+- `X-Idempotency-Cache` response header (`HIT` or `MISS`) for debugging cache behavior.
+
+### Changed
+
 ## [0.6.0] - 2026-05-27
 
 ### Added

README.md

@@ -325,6 +325,11 @@ Request body:
 
 - `contributor`
 - `amount`
+- `assetCode`
+
+Request headers:
+
+- `Idempotency-Key` (optional): A unique key used to make the request idempotent. When provided, duplicate requests with the same key (for the same user and campaign) will return the cached response instead of creating a new pledge. Cache entries expire after 24 hours. The `X-Idempotency-Cache` response header indicates whether the response was served from cache (`HIT`) or generated fresh (`MISS`).
 
 ### `POST /api/campaigns/:id/pledges/reconcile`
 

backend/src/api.test.ts

@@ -70,7 +70,25 @@ async function post(apiPath: string, body: unknown) {
     body: JSON.stringify(body),
   });
   const data = await response.json().catch(() => null);
-  return { status: response.status, data };
+  return { status: response.status, data, headers: response.headers };
+}
+
+async function postWithHeaders(
+  apiPath: string,
+  body: unknown,
+  headers: Record<string, string>,
+) {
+  const mergedHeaders: Record<string, string> = {
+    'Content-Type': 'application/json',
+    ...headers,
+  };
+  const response = await fetch(`${baseUrl}${apiPath}`, {
+    method: 'POST',
+    headers: mergedHeaders,
+    body: JSON.stringify(body),
+  });
+  const data = await response.json().catch(() => null);
+  return { status: response.status, data, headers: response.headers };
 }
 
 async function get(apiPath: string) {
@@ -646,3 +664,168 @@ describe('GET /api/stats', () => {
     });
   });
 });
+
+describe('POST /api/campaigns/:id/pledges with Idempotency-Key', () => {
+  const CONTRIBUTOR_C = `G${'D'.repeat(55)}`;
+  const CONTRIBUTOR_D = `G${'E'.repeat(55)}`;
+
+  async function createTestCampaign() {
+    const createRes = await post('/api/campaigns', {
+      creator: CREATOR,
+      title: 'Idempotency Test Campaign',
+      description: 'This campaign is used to test idempotency behavior.',
+      acceptedTokens: ['USDC'],
+      targetAmount: 500,
+      deadline: Math.floor(Date.now() / 1000) + 86400,
+    });
+    return createRes.data.data.id;
+  }
+
+  it('request with Idempotency-Key creates a pledge', async () => {
+    const campaignId = await createTestCampaign();
+
+    const res = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'test-key-1' });
+
+    expect(res.status).toBe(201);
+    expect(res.data.data.progress.pledgeCount).toBe(1);
+  });
+
+  it('duplicate request with same Idempotency-Key returns cached response', async () => {
+    const campaignId = await createTestCampaign();
+
+    const firstRes = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'dup-key-1' });
+    expect(firstRes.status).toBe(201);
+
+    const secondRes = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'dup-key-1' });
+    expect(secondRes.status).toBe(201);
+    expect(secondRes.data).toEqual(firstRes.data);
+  });
+
+  it('duplicate request with same Idempotency-Key performs only one database write', async () => {
+    const campaignId = await createTestCampaign();
+
+    await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'db-write-key' });
+
+    const db = getDb();
+    const pledgeCountBefore = db.prepare('SELECT COUNT(*) AS count FROM pledges').get() as { count: number };
+
+    await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'db-write-key' });
+
+    const pledgeCountAfter = db.prepare('SELECT COUNT(*) AS count FROM pledges').get() as { count: number };
+    expect(pledgeCountAfter.count).toBe(pledgeCountBefore.count);
+  });
+
+  it('missing Idempotency-Key behaves exactly as before', async () => {
+    const campaignId = await createTestCampaign();
+
+    const res = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    });
+    expect(res.status).toBe(201);
+    expect(res.data.data.progress.pledgeCount).toBe(1);
+  });
+
+  it('different idempotency keys create independent pledges', async () => {
+    const campaignId = await createTestCampaign();
+
+    const res1 = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 50,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'key-A' });
+    expect(res1.status).toBe(201);
+
+    const res2 = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 50,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'key-B' });
+    expect(res2.status).toBe(201);
+
+    const db = getDb();
+    const pledgeCount = db.prepare('SELECT COUNT(*) AS count FROM pledges').get() as { count: number };
+    expect(pledgeCount.count).toBe(2);
+  });
+
+  it('different users using the same idempotency key do not share cached responses', async () => {
+    const campaignId = await createTestCampaign();
+
+    const userARes = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'shared-key' });
+    expect(userARes.status).toBe(201);
+    expect(userARes.data.data.progress.pledgeCount).toBe(1);
+
+    const userBRes = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_D,
+      amount: 100,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'shared-key' });
+    expect(userBRes.status).toBe(201);
+    expect(userBRes.data.data.progress.pledgeCount).toBe(2);
+  });
+
+  it('cached response preserves original status and payload', async () => {
+    const campaignId = await createTestCampaign();
+
+    const firstRes = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 75,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'status-payload-key' });
+    expect(firstRes.status).toBe(201);
+
+    const cachedRes = await post(`/api/campaigns/${campaignId}/pledges`, {
+      contributor: CONTRIBUTOR_C,
+      amount: 75,
+      assetCode: 'USDC',
+    }, { 'Idempotency-Key': 'status-payload-key' });
+    expect(cachedRes.status).toBe(201);
+    expect(cachedRes.data.data.id).toBe(firstRes.data.data.id);
+    expect(cachedRes.data.data.amount).toBe(firstRes.data.data.amount);
+  });
+
+  it('X-Idempotency-Cache header is MISS on first request and HIT on duplicate', async () => {
+    const campaignId = await createTestCampaign();
+
+    const firstRes = await postWithHeaders(
+      `/api/campaigns/${campaignId}/pledges`,
+      { contributor: CONTRIBUTOR_C, amount: 100, assetCode: 'USDC' },
+      { 'Idempotency-Key': 'header-test-key' },
+    );
+    expect(firstRes.status).toBe(201);
+    expect(firstRes.headers.get('X-Idempotency-Cache')).toBe('MISS');
+
+    const secondRes = await postWithHeaders(
+      `/api/campaigns/${campaignId}/pledges`,
+      { contributor: CONTRIBUTOR_C, amount: 100, assetCode: 'USDC' },
+      { 'Idempotency-Key': 'header-test-key' },
+    );
+    expect(secondRes.status).toBe(201);
+    expect(secondRes.headers.get('X-Idempotency-Cache')).toBe('HIT');
+  });
+});

backend/src/index.ts

@@ -595,6 +595,7 @@ app.post(
 app.post(
   '/api/campaigns/:id/pledges',
   applyRateLimit(WRITE_RATE_LIMIT_MAX_REQUESTS),
+  idempotencyMiddleware,
   validateBody(createPledgePayloadSchema),
   (req: Request, res: Response) => {
     const parsedId = parseCampaignId(req.params.id);

backend/src/middleware/idempotencyMiddleware.ts

@@ -0,0 +1,66 @@
+import type { Request, Response, NextFunction } from 'express';
+import {
+  getIdempotencyCacheEntry,
+  setIdempotencyCacheEntry,
+  buildIdempotencyCacheKey,
+} from '../services/idempotencyCache';
+import type { RequestWithApiKey } from './apiKeyAuth';
+
+interface IdempotencyRequest extends Request {
+  idempotencyKey?: string;
+}
+
+export function idempotencyMiddleware(
+  req: IdempotencyRequest,
+  res: Response,
+  next: NextFunction,
+): void {
+  const idempotencyKey = req.header('Idempotency-Key');
+
+  if (!idempotencyKey) {
+    return next();
+  }
+
+  const apiKey = (req as unknown as RequestWithApiKey).apiKey ?? 'anonymous';
+  const campaignId = req.params.id as string;
+  const cacheKey = buildIdempotencyCacheKey(apiKey, campaignId, idempotencyKey);
+
+  getIdempotencyCacheEntry(cacheKey).then(
+    (cached) => {
+      if (cached) {
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('X-Idempotency-Cache', 'HIT');
+        for (const [name, value] of Object.entries(cached.headers)) {
+          res.setHeader(name, value);
+        }
+        res.status(cached.statusCode).send(cached.body);
+        return;
+      }
+
+      const originalSend = res.send.bind(res);
+      res.send = function (data: unknown) {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          const body = typeof data === 'string' ? data : JSON.stringify(data);
+          const entry = {
+            statusCode: res.statusCode,
+            body,
+            headers: {
+              'Content-Type': res.getHeader('Content-Type') as string,
+            },
+          };
+          setIdempotencyCacheEntry(cacheKey, entry).catch(() => {
+            // Silently fail cache writes
+          });
+          res.setHeader('X-Idempotency-Cache', 'MISS');
+        }
+
+        return originalSend(data);
+      };
+
+      next();
+    },
+    () => {
+      next();
+    },
+  );
+}

backend/src/openapi.ts

@@ -630,6 +630,7 @@ registry.registerPath({
   path: '/api/campaigns/{id}/pledges',
   tags: ['Pledges'],
   summary: 'Create a pledge',
+  description: 'Creates a pledge for a campaign. Use the Idempotency-Key header to make the request idempotent. Cached responses are returned for 24 hours.',
   request: {
     params: z.object({ id: campaignIdParamSchema }),
     body: {

backend/src/services/cache.ts

@@ -39,6 +39,9 @@ export async function initRedisCache(): Promise<void> {
   } catch {
     redisClient = null;
     isConnected = false;
+  } catch {
+    redisClient = null;
+    isConnected = false;
   }
 }
 

backend/src/services/idempotencyCache.ts

@@ -0,0 +1,62 @@
+import { LRUCache } from 'lru-cache';
+import { getCacheValue, setCacheValue, isCacheAvailable } from './cache';
+
+const IDEMPOTENCY_TTL_SECONDS = 86_400;
+
+const MAX_CACHE_SIZE = Number(process.env.IDEMPOTENCY_CACHE_MAX_SIZE ?? 1000);
+
+interface IdempotencyCacheEntry {
+  statusCode: number;
+  body: string;
+  headers: Record<string, string>;
+}
+
+const memoryCache = new LRUCache<string, IdempotencyCacheEntry>({
+  max: MAX_CACHE_SIZE,
+  ttl: IDEMPOTENCY_TTL_SECONDS * 1000,
+});
+
+export function buildIdempotencyCacheKey(
+  apiKey: string,
+  campaignId: string,
+  idempotencyKey: string,
+): string {
+  return `idempotency:${apiKey}:${campaignId}:${idempotencyKey}`;
+}
+
+export async function getIdempotencyCacheEntry(
+  key: string,
+): Promise<IdempotencyCacheEntry | null> {
+  if (isCacheAvailable()) {
+    const cached = await getCacheValue(key);
+    if (cached) {
+      return JSON.parse(cached) as IdempotencyCacheEntry;
+    }
+  }
+
+  const memoryEntry = memoryCache.get(key);
+  if (memoryEntry) {
+    return memoryEntry;
+  }
+
+  return null;
+}
+
+export async function setIdempotencyCacheEntry(
+  key: string,
+  entry: IdempotencyCacheEntry,
+): Promise<void> {
+  const serialized = JSON.stringify(entry);
+
+  if (isCacheAvailable()) {
+    await setCacheValue(key, serialized, IDEMPOTENCY_TTL_SECONDS).catch(() => {
+      // Silently fail Redis writes; memory cache still works
+    });
+  }
+
+  memoryCache.set(key, entry);
+}
+
+export function clearIdempotencyCache(): void {
+  memoryCache.clear();
+}