@venturekit/runtime 0.0.0-dev.20260312012510 → 0.0.0-dev.20260329102450

package/dist/patterns/circuit-breaker.d.ts

@@ -0,0 +1,78 @@
+/**
+ * VentureKit Circuit Breaker
+ *
+ * Prevents cascading failures when invoking other Lambda functions.
+ * Tracks failures per target and "opens" the circuit after a threshold,
+ * returning a configurable default/fallback result instead of attempting
+ * the call.
+ *
+ * ## States
+ *
+ * - **Closed** — normal operation, requests pass through.
+ * - **Open** — too many recent failures, requests are short-circuited
+ *   with the fallback result.
+ * - **Half-open** — after a cooldown period, one probe request is
+ *   allowed through. If it succeeds the circuit closes; if it fails
+ *   the circuit re-opens.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createCircuitBreaker } from '@venturekit/runtime';
+ *
+ * const breaker = createCircuitBreaker({
+ *   failureThreshold: 5,     // open after 5 failures
+ *   resetTimeoutMs: 30_000,  // try again after 30 s
+ * });
+ *
+ * const result = await breaker.call(
+ *   'billing-dev-fn-charge',
+ *   () => invoke({ function: 'charge', project: 'billing' }, { payload }),
+ *   { statusCode: 503, data: null, headers: {} },   // fallback
+ * );
+ * ```
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures before the circuit opens.
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time in ms to wait before switching from open → half-open.
+     * @default 30000 (30 seconds)
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Optional callback fired when the circuit state changes.
+     */
+    onStateChange?: (target: string, from: CircuitState, to: CircuitState) => void;
+}
+export interface CircuitBreaker {
+    /**
+     * Execute `fn` with circuit breaker protection.
+     *
+     * @param target  - Logical name of the target (e.g. function name)
+     * @param fn      - The async function to execute
+     * @param fallback - Value returned when the circuit is open
+     * @returns The result of `fn`, or `fallback` if the circuit is open.
+     */
+    call<T>(target: string, fn: () => Promise<T>, fallback: T): Promise<T>;
+    /** Get the current state for a target. */
+    getState(target: string): CircuitState;
+    /** Manually reset a target to closed. */
+    reset(target: string): void;
+    /** Reset all targets. */
+    resetAll(): void;
+}
+/**
+ * Create a circuit breaker instance.
+ *
+ * The returned object is stateful (in-process) — each Lambda warm
+ * container gets its own breaker. This is intentional: a single
+ * container seeing repeated failures should stop hammering the target,
+ * while other containers may still be healthy.
+ */
+export declare function createCircuitBreaker(options?: CircuitBreakerOptions): CircuitBreaker;
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/patterns/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/patterns/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;CAChF;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEvE,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IAEvC,yCAAyC;IACzC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,yBAAyB;IACzB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAiFxF"}

package/dist/patterns/circuit-breaker.js

@@ -0,0 +1,113 @@
+/**
+ * VentureKit Circuit Breaker
+ *
+ * Prevents cascading failures when invoking other Lambda functions.
+ * Tracks failures per target and "opens" the circuit after a threshold,
+ * returning a configurable default/fallback result instead of attempting
+ * the call.
+ *
+ * ## States
+ *
+ * - **Closed** — normal operation, requests pass through.
+ * - **Open** — too many recent failures, requests are short-circuited
+ *   with the fallback result.
+ * - **Half-open** — after a cooldown period, one probe request is
+ *   allowed through. If it succeeds the circuit closes; if it fails
+ *   the circuit re-opens.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createCircuitBreaker } from '@venturekit/runtime';
+ *
+ * const breaker = createCircuitBreaker({
+ *   failureThreshold: 5,     // open after 5 failures
+ *   resetTimeoutMs: 30_000,  // try again after 30 s
+ * });
+ *
+ * const result = await breaker.call(
+ *   'billing-dev-fn-charge',
+ *   () => invoke({ function: 'charge', project: 'billing' }, { payload }),
+ *   { statusCode: 503, data: null, headers: {} },   // fallback
+ * );
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Create a circuit breaker instance.
+ *
+ * The returned object is stateful (in-process) — each Lambda warm
+ * container gets its own breaker. This is intentional: a single
+ * container seeing repeated failures should stop hammering the target,
+ * while other containers may still be healthy.
+ */
+export function createCircuitBreaker(options = {}) {
+    const { failureThreshold = 5, resetTimeoutMs = 30_000, onStateChange, } = options;
+    const targets = new Map();
+    function getOrCreate(target) {
+        let ts = targets.get(target);
+        if (!ts) {
+            ts = { state: 'closed', failures: 0, lastFailureAt: 0 };
+            targets.set(target, ts);
+        }
+        return ts;
+    }
+    function transition(target, ts, to) {
+        if (ts.state === to)
+            return;
+        const from = ts.state;
+        ts.state = to;
+        onStateChange?.(target, from, to);
+    }
+    return {
+        async call(target, fn, fallback) {
+            const ts = getOrCreate(target);
+            // --- Open state ---
+            if (ts.state === 'open') {
+                // Check if cooldown has elapsed → half-open
+                if (Date.now() - ts.lastFailureAt >= resetTimeoutMs) {
+                    transition(target, ts, 'half-open');
+                }
+                else {
+                    // Still open — return fallback
+                    return fallback;
+                }
+            }
+            // --- Closed or Half-open: attempt the call ---
+            try {
+                const result = await fn();
+                // Success: reset to closed
+                ts.failures = 0;
+                transition(target, ts, 'closed');
+                return result;
+            }
+            catch (error) {
+                ts.failures++;
+                ts.lastFailureAt = Date.now();
+                if (ts.state === 'half-open') {
+                    // Probe failed — re-open immediately
+                    transition(target, ts, 'open');
+                    return fallback;
+                }
+                if (ts.failures >= failureThreshold) {
+                    transition(target, ts, 'open');
+                    return fallback;
+                }
+                // Below threshold — propagate error normally
+                throw error;
+            }
+        },
+        getState(target) {
+            return getOrCreate(target).state;
+        },
+        reset(target) {
+            targets.delete(target);
+        },
+        resetAll() {
+            targets.clear();
+        },
+    };
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/patterns/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/patterns/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/patterns/idempotency.d.ts

@@ -0,0 +1,175 @@
+/**
+ * VentureKit Idempotency Support
+ *
+ * Middleware for ensuring handler idempotency.
+ * Stores request results keyed by an idempotency key, returning
+ * cached responses for duplicate requests within a TTL window.
+ *
+ * Storage backend is pluggable (DynamoDB, Postgres, in-memory, etc.).
+ */
+import type { RequestContext } from '../handler/context.js';
+import type { Middleware } from '../middleware/middleware.js';
+/**
+ * Stored idempotency record
+ */
+export interface IdempotencyRecord {
+    /** The idempotency key */
+    key: string;
+    /** The cached response (serialized) */
+    response: string;
+    /** Status of the record */
+    status: 'pending' | 'completed';
+    /** Expiry timestamp (ms since epoch) */
+    expiresAt: number;
+}
+/**
+ * Idempotency store interface.
+ * Implement this to plug in any storage backend.
+ */
+export interface IdempotencyStore {
+    /**
+     * Get a stored record by key.
+     * Returns null if not found or expired.
+     */
+    get(key: string): Promise<IdempotencyRecord | null>;
+    /**
+     * Save a record. If a record with the same key already exists
+     * and is 'pending', throw a ConflictError (concurrent request).
+     */
+    save(record: IdempotencyRecord): Promise<void>;
+    /**
+     * Update an existing record (e.g. from pending → completed).
+     */
+    update(key: string, updates: Partial<IdempotencyRecord>): Promise<void>;
+    /**
+     * Delete a record (e.g. on failure, to allow retry).
+     */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Key extraction strategy
+ */
+export type IdempotencyKeyExtractor = (ctx: RequestContext) => string | null;
+/**
+ * Extract idempotency key from a header
+ */
+export declare function headerKeyExtractor(headerName: string): IdempotencyKeyExtractor;
+/**
+ * Extract idempotency key from a body field
+ */
+export declare function bodyFieldKeyExtractor(fieldName: string): IdempotencyKeyExtractor;
+/**
+ * Idempotency middleware options
+ */
+export interface IdempotencyOptions {
+    /** Storage backend for idempotency records */
+    store: IdempotencyStore;
+    /**
+     * Extract the idempotency key from the request.
+     * Default: reads from 'Idempotency-Key' header.
+     */
+    keyExtractor?: IdempotencyKeyExtractor;
+    /** TTL in seconds for idempotency records (default: 86400 = 24h) */
+    ttlSeconds?: number;
+    /**
+     * If true, requests without an idempotency key are rejected with 400.
+     * If false (default), requests without a key pass through without idempotency.
+     */
+    required?: boolean;
+}
+/**
+ * Idempotency middleware
+ *
+ * Ensures that duplicate requests with the same idempotency key
+ * return the same response without re-executing the handler.
+ *
+ * Flow:
+ * 1. Extract idempotency key from request
+ * 2. Check store for existing record
+ *    - If completed: return cached response
+ *    - If pending: return 409 Conflict (concurrent request in flight)
+ * 3. Save 'pending' record
+ * 4. Execute handler
+ * 5. Update record to 'completed' with response
+ * 6. On error: delete record so the request can be retried
+ */
+export declare function idempotencyMiddleware(options: IdempotencyOptions): Middleware<RequestContext>;
+/**
+ * In-memory idempotency store (for development/testing).
+ *
+ * **WARNING:** State is per-process. Does NOT work correctly with
+ * multiple Lambda instances. Use only for local dev/testing.
+ * For production, use `createDynamoDBIdempotencyStore()`.
+ */
+export declare function createMemoryIdempotencyStore(): IdempotencyStore;
+/**
+ * DynamoDB idempotency store options.
+ */
+export interface DynamoDBIdempotencyStoreOptions {
+    /** DynamoDB table name (default: 'venturekit-idempotency') */
+    tableName?: string;
+    /** AWS region (default: process.env.AWS_REGION) */
+    region?: string;
+}
+/**
+ * Create a DynamoDB-backed idempotency store.
+ *
+ * Uses conditional writes for conflict detection and DynamoDB TTL
+ * for automatic cleanup of expired records.
+ *
+ * ### DynamoDB Table Schema
+ *
+ * The table must have:
+ * - **Partition key:** `pk` (String) — the idempotency key
+ * - **TTL attribute:** `ttl` (Number) — epoch seconds for auto-cleanup
+ *
+ * @example
+ * ```typescript
+ * import { idempotencyMiddleware, createDynamoDBIdempotencyStore } from '@venturekit/runtime';
+ *
+ * const store = await createDynamoDBIdempotencyStore();
+ * const idempotency = idempotencyMiddleware({ store });
+ * ```
+ */
+export declare function createDynamoDBIdempotencyStore(options?: DynamoDBIdempotencyStoreOptions): Promise<IdempotencyStore>;
+/**
+ * Error thrown when an idempotency conflict is detected
+ * (a request with the same key is already in progress).
+ */
+export declare class IdempotencyConflictError extends Error {
+    readonly code = "IDEMPOTENCY_CONFLICT";
+    constructor(key: string);
+}
+/**
+ * Error thrown when a required idempotency key is missing.
+ */
+export declare class MissingIdempotencyKeyError extends Error {
+    readonly code = "MISSING_IDEMPOTENCY_KEY";
+    constructor();
+}
+/**
+ * Options for the default idempotency store.
+ */
+export interface DefaultIdempotencyStoreOptions {
+    /** DynamoDB table name */
+    tableName?: string;
+    /** Force in-memory store even in production */
+    forceMemory?: boolean;
+}
+/**
+ * Create an idempotency store with sensible defaults.
+ *
+ * - In production (Lambda): uses DynamoDB for distributed idempotency
+ * - In local dev: uses in-memory store
+ *
+ * @example
+ * ```typescript
+ * import { idempotencyMiddleware, createDefaultIdempotencyStore } from '@venturekit/runtime';
+ *
+ * // Zero-config — auto-selects DynamoDB (Lambda) or memory (local)
+ * const store = await createDefaultIdempotencyStore();
+ * const idempotency = idempotencyMiddleware({ store });
+ * ```
+ */
+export declare function createDefaultIdempotencyStore(options?: DefaultIdempotencyStoreOptions): Promise<IdempotencyStore>;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/patterns/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/patterns/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAEpD;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,GAAG,IAAI,CAAC;AAE7E;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,uBAAuB,CAK9E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAShF;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,KAAK,EAAE,gBAAgB,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC;IAEvC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU,CAAC,cAAc,CAAC,CA0E7F;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,gBAAgB,CAiC/D;AAMD;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,gBAAgB,CAAC,CAwG3B;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAgB,IAAI,0BAA0B;gBAClC,GAAG,EAAE,MAAM;CAIxB;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,IAAI,6BAA6B;;CAKlD;AAMD;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CAU3B"}

package/dist/patterns/idempotency.js

@@ -0,0 +1,305 @@
+/**
+ * VentureKit Idempotency Support
+ *
+ * Middleware for ensuring handler idempotency.
+ * Stores request results keyed by an idempotency key, returning
+ * cached responses for duplicate requests within a TTL window.
+ *
+ * Storage backend is pluggable (DynamoDB, Postgres, in-memory, etc.).
+ */
+/**
+ * Extract idempotency key from a header
+ */
+export function headerKeyExtractor(headerName) {
+    return (ctx) => {
+        const key = ctx.rawEvent.headers?.[headerName.toLowerCase()];
+        return key ?? null;
+    };
+}
+/**
+ * Extract idempotency key from a body field
+ */
+export function bodyFieldKeyExtractor(fieldName) {
+    return (ctx) => {
+        try {
+            const body = ctx.rawEvent.body ? JSON.parse(ctx.rawEvent.body) : null;
+            return body?.[fieldName] ?? null;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/**
+ * Idempotency middleware
+ *
+ * Ensures that duplicate requests with the same idempotency key
+ * return the same response without re-executing the handler.
+ *
+ * Flow:
+ * 1. Extract idempotency key from request
+ * 2. Check store for existing record
+ *    - If completed: return cached response
+ *    - If pending: return 409 Conflict (concurrent request in flight)
+ * 3. Save 'pending' record
+ * 4. Execute handler
+ * 5. Update record to 'completed' with response
+ * 6. On error: delete record so the request can be retried
+ */
+export function idempotencyMiddleware(options) {
+    const { store, keyExtractor = headerKeyExtractor('idempotency-key'), ttlSeconds = 86400, required = false, } = options;
+    return {
+        name: 'idempotency',
+        fn: async (ctx, next) => {
+            const key = keyExtractor(ctx);
+            // No idempotency key
+            if (!key) {
+                if (required) {
+                    return {
+                        statusCode: 400,
+                        body: JSON.stringify({
+                            error: { code: 'MISSING_IDEMPOTENCY_KEY', message: 'Idempotency-Key header is required' },
+                        }),
+                    };
+                }
+                // Pass through without idempotency
+                return next();
+            }
+            // Check for existing record
+            const existing = await store.get(key);
+            if (existing) {
+                if (existing.status === 'completed') {
+                    // Return cached response
+                    return JSON.parse(existing.response);
+                }
+                if (existing.status === 'pending') {
+                    // Concurrent request — reject
+                    return {
+                        statusCode: 409,
+                        body: JSON.stringify({
+                            error: { code: 'IDEMPOTENCY_CONFLICT', message: 'A request with this idempotency key is already in progress' },
+                        }),
+                    };
+                }
+            }
+            // Save pending record
+            const record = {
+                key,
+                response: '',
+                status: 'pending',
+                expiresAt: Date.now() + (ttlSeconds * 1000),
+            };
+            await store.save(record);
+            try {
+                // Execute handler
+                const response = await next();
+                // Store completed response
+                await store.update(key, {
+                    status: 'completed',
+                    response: JSON.stringify(response),
+                });
+                return response;
+            }
+            catch (error) {
+                // Delete record so request can be retried
+                await store.delete(key);
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * In-memory idempotency store (for development/testing).
+ *
+ * **WARNING:** State is per-process. Does NOT work correctly with
+ * multiple Lambda instances. Use only for local dev/testing.
+ * For production, use `createDynamoDBIdempotencyStore()`.
+ */
+export function createMemoryIdempotencyStore() {
+    const records = new Map();
+    return {
+        async get(key) {
+            const record = records.get(key);
+            if (!record)
+                return null;
+            if (record.expiresAt < Date.now()) {
+                records.delete(key);
+                return null;
+            }
+            return record;
+        },
+        async save(record) {
+            const existing = records.get(record.key);
+            if (existing && existing.status === 'pending' && existing.expiresAt >= Date.now()) {
+                throw new Error('Concurrent idempotency conflict');
+            }
+            records.set(record.key, record);
+        },
+        async update(key, updates) {
+            const existing = records.get(key);
+            if (existing) {
+                records.set(key, { ...existing, ...updates });
+            }
+        },
+        async delete(key) {
+            records.delete(key);
+        },
+    };
+}
+/**
+ * Create a DynamoDB-backed idempotency store.
+ *
+ * Uses conditional writes for conflict detection and DynamoDB TTL
+ * for automatic cleanup of expired records.
+ *
+ * ### DynamoDB Table Schema
+ *
+ * The table must have:
+ * - **Partition key:** `pk` (String) — the idempotency key
+ * - **TTL attribute:** `ttl` (Number) — epoch seconds for auto-cleanup
+ *
+ * @example
+ * ```typescript
+ * import { idempotencyMiddleware, createDynamoDBIdempotencyStore } from '@venturekit/runtime';
+ *
+ * const store = await createDynamoDBIdempotencyStore();
+ * const idempotency = idempotencyMiddleware({ store });
+ * ```
+ */
+export async function createDynamoDBIdempotencyStore(options = {}) {
+    const tableName = options.tableName
+        || process.env.VENTURE_IDEMPOTENCY_TABLE
+        || 'venturekit-idempotency';
+    const region = options.region || process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || 'us-east-1';
+    const { DynamoDBClient, PutItemCommand, GetItemCommand, UpdateItemCommand, DeleteItemCommand, } = await import('@aws-sdk/client-dynamodb');
+    const client = new DynamoDBClient({ region });
+    return {
+        async get(key) {
+            const result = await client.send(new GetItemCommand({
+                TableName: tableName,
+                Key: { pk: { S: key } },
+            }));
+            if (!result.Item)
+                return null;
+            const expiresAt = parseInt(result.Item.expiresAt?.N ?? '0', 10);
+            if (expiresAt < Date.now())
+                return null;
+            return {
+                key: result.Item.pk.S,
+                response: result.Item.response?.S ?? '',
+                status: result.Item.status?.S,
+                expiresAt,
+            };
+        },
+        async save(record) {
+            const ttl = Math.ceil(record.expiresAt / 1000);
+            try {
+                await client.send(new PutItemCommand({
+                    TableName: tableName,
+                    Item: {
+                        pk: { S: record.key },
+                        response: { S: record.response },
+                        status: { S: record.status },
+                        expiresAt: { N: String(record.expiresAt) },
+                        ttl: { N: String(ttl) },
+                    },
+                    // Conditional: only allow write if no pending record exists
+                    ConditionExpression: 'attribute_not_exists(pk) OR #s <> :pending OR #exp < :now',
+                    ExpressionAttributeNames: { '#s': 'status', '#exp': 'expiresAt' },
+                    ExpressionAttributeValues: {
+                        ':pending': { S: 'pending' },
+                        ':now': { N: String(Date.now()) },
+                    },
+                }));
+            }
+            catch (err) {
+                if (err.name === 'ConditionalCheckFailedException') {
+                    throw new Error('Concurrent idempotency conflict');
+                }
+                throw err;
+            }
+        },
+        async update(key, updates) {
+            const expressionParts = [];
+            const names = {};
+            const values = {};
+            let counter = 0;
+            for (const [k, v] of Object.entries(updates)) {
+                if (v === undefined)
+                    continue;
+                counter++;
+                const attrName = `#a${counter}`;
+                const attrValue = `:v${counter}`;
+                names[attrName] = k;
+                if (typeof v === 'number') {
+                    values[attrValue] = { N: String(v) };
+                }
+                else {
+                    values[attrValue] = { S: String(v) };
+                }
+                expressionParts.push(`${attrName} = ${attrValue}`);
+            }
+            if (expressionParts.length === 0)
+                return;
+            await client.send(new UpdateItemCommand({
+                TableName: tableName,
+                Key: { pk: { S: key } },
+                UpdateExpression: `SET ${expressionParts.join(', ')}`,
+                ExpressionAttributeNames: names,
+                ExpressionAttributeValues: values,
+            }));
+        },
+        async delete(key) {
+            await client.send(new DeleteItemCommand({
+                TableName: tableName,
+                Key: { pk: { S: key } },
+            }));
+        },
+    };
+}
+/**
+ * Error thrown when an idempotency conflict is detected
+ * (a request with the same key is already in progress).
+ */
+export class IdempotencyConflictError extends Error {
+    code = 'IDEMPOTENCY_CONFLICT';
+    constructor(key) {
+        super(`A request with idempotency key '${key}' is already in progress`);
+        this.name = 'IdempotencyConflictError';
+    }
+}
+/**
+ * Error thrown when a required idempotency key is missing.
+ */
+export class MissingIdempotencyKeyError extends Error {
+    code = 'MISSING_IDEMPOTENCY_KEY';
+    constructor() {
+        super('Idempotency key is required but was not found in the request');
+        this.name = 'MissingIdempotencyKeyError';
+    }
+}
+/**
+ * Create an idempotency store with sensible defaults.
+ *
+ * - In production (Lambda): uses DynamoDB for distributed idempotency
+ * - In local dev: uses in-memory store
+ *
+ * @example
+ * ```typescript
+ * import { idempotencyMiddleware, createDefaultIdempotencyStore } from '@venturekit/runtime';
+ *
+ * // Zero-config — auto-selects DynamoDB (Lambda) or memory (local)
+ * const store = await createDefaultIdempotencyStore();
+ * const idempotency = idempotencyMiddleware({ store });
+ * ```
+ */
+export async function createDefaultIdempotencyStore(options = {}) {
+    const isLocal = !process.env.AWS_LAMBDA_FUNCTION_NAME && !process.env.AWS_EXECUTION_ENV;
+    if (isLocal || options.forceMemory) {
+        return createMemoryIdempotencyStore();
+    }
+    return createDynamoDBIdempotencyStore({
+        tableName: options.tableName,
+    });
+}
+//# sourceMappingURL=idempotency.js.map