feat(client): add idempotency key support

packages/client/src/core/apply-request-metadata.ts

@@ -2,4 +2,9 @@ import type { ExecutionContext } from './execution-context';
 
 export function applyRequestMetadata(execution: ExecutionContext): void {
   execution.headers['x-request-id'] = execution.headers['x-request-id'] ?? execution.requestId;
+
+  if (execution.request.idempotencyKey) {
+    execution.headers['idempotency-key'] =
+      execution.headers['idempotency-key'] ?? execution.request.idempotencyKey;
+  }
 }

packages/client/src/types/request.ts

@@ -13,6 +13,7 @@ export type RequestConfig = {
   retry?: RetryConfig;
   signal?: AbortSignal;
   requestId?: string;
+  idempotencyKey?: string;
   validateResponse?: ResponseValidator;
 };
 

packages/client/tests/integration/headers.test.ts

@@ -187,4 +187,71 @@ describe('request headers', () => {
     expect(typeof requestId).toBe('string');
     expect(requestId!.length).toBeGreaterThan(0);
   });
+
+  it('propagates idempotencyKey to idempotency-key header', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+        },
+      }),
+    );
+
+    const client = createClient({
+      baseUrl: 'https://api.test.com',
+      fetch: fetchMock,
+    });
+
+    await client.post(
+      '/payments',
+      {
+        amount: 100,
+      },
+      {
+        idempotencyKey: 'idem_123',
+      },
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    const init = getFirstFetchInit(fetchMock);
+    const headers = init.headers as Record<string, string>;
+
+    expect(headers['idempotency-key']).toBe('idem_123');
+  });
+
+  it('prefers explicit idempotency-key header over idempotencyKey option', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: {
+          'content-type': 'application/json',
+        },
+      }),
+    );
+
+    const client = createClient({
+      baseUrl: 'https://api.test.com',
+      fetch: fetchMock,
+    });
+
+    await client.post(
+      '/payments',
+      {
+        amount: 100,
+      },
+      {
+        idempotencyKey: 'idem_from_option',
+        headers: {
+          'idempotency-key': 'idem_from_header',
+        },
+      },
+    );
+
+    const init = getFirstFetchInit(fetchMock);
+    const headers = init.headers as Record<string, string>;
+
+    expect(headers['idempotency-key']).toBe('idem_from_header');
+  });
 });

packages/client/tests/unit/apply-request-metadata.test.ts

@@ -45,4 +45,44 @@ describe('applyRequestMetadata', () => {
 
     expect(execution.headers['x-request-id']).toBe('existing-request-id');
   });
+
+  it('adds idempotency-key header when idempotencyKey is provided', () => {
+    const execution = createExecutionContext({
+      request: {
+        method: 'POST',
+        path: '/payments',
+        idempotencyKey: 'idem-123',
+      },
+    });
+
+    applyRequestMetadata(execution);
+
+    expect(execution.headers['idempotency-key']).toBe('idem-123');
+  });
+
+  it('does not overwrite an existing idempotency-key header', () => {
+    const execution = createExecutionContext({
+      request: {
+        method: 'POST',
+        path: '/payments',
+        idempotencyKey: 'idem-from-option',
+      },
+      headers: {
+        accept: 'application/json',
+        'idempotency-key': 'idem-from-header',
+      },
+    });
+
+    applyRequestMetadata(execution);
+
+    expect(execution.headers['idempotency-key']).toBe('idem-from-header');
+  });
+
+  it('does not add idempotency-key header when idempotencyKey is not provided', () => {
+    const execution = createExecutionContext();
+
+    applyRequestMetadata(execution);
+
+    expect(execution.headers).not.toHaveProperty('idempotency-key');
+  });
 });