lambder 3.4.2 → 3.5.2

package/dist/LambderCaller.js

@@ -3,6 +3,7 @@ export default class LambderCaller {
     isCorsEnabled;
     apiPath;
     apiVersion;
+    timeoutMs;
     fetchTrackerList = [];
     isLoading = false;
     versionExpiredHandler;
@@ -17,10 +18,11 @@ export default class LambderCaller {
     sessionTokenCookieKey = "LMDRSESSIONTKID";
     sessionCsrfCookieKey = "LMDRSESSIONCSTK";
     sessionCookieDomain;
-    constructor({ apiPath, apiVersion, isCorsEnabled = false, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, }) {
+    constructor({ apiPath, apiVersion, isCorsEnabled = false, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, }) {
         this.apiPath = apiPath ?? "/api";
         this.apiVersion = apiVersion;
         this.isCorsEnabled = isCorsEnabled;
+        this.timeoutMs = timeoutMs;
         this.sessionCookieDomain = sessionCookieDomain;
         this.versionExpiredHandler = versionExpiredHandler;
         this.sessionExpiredHandler = sessionExpiredHandler;
@@ -37,6 +39,32 @@ export default class LambderCaller {
         this.sessionTokenCookieKey = sessionTokenCookieKey;
         this.sessionCsrfCookieKey = sessionCsrfCookieKey;
     }
+    /**
+     * Generate an idempotency key for one logical operation. Create it when
+     * the operation begins (a form opens, a draft starts), send the same key
+     * on every attempt of that operation, and generate a new one after a
+     * confirmed success. Uses crypto.randomUUID when available and falls back
+     * to a v4 UUID from getRandomValues, because randomUUID only exists in
+     * secure contexts (plain-http LAN device testing lacks it).
+     */
+    static createIdempotencyKey() {
+        const cryptoObj = globalThis.crypto;
+        if (cryptoObj?.randomUUID)
+            return cryptoObj.randomUUID();
+        const bytes = new Uint8Array(16);
+        if (cryptoObj?.getRandomValues) {
+            cryptoObj.getRandomValues(bytes);
+        }
+        else {
+            for (let i = 0; i < 16; i += 1) {
+                bytes[i] = Math.floor(Math.random() * 256);
+            }
+        }
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
     clearSessionCookies() {
         const domainOption = this.sessionCookieDomain;
         const hostname = typeof window !== "undefined" ? window.location.hostname : "";
@@ -48,117 +76,227 @@ export default class LambderCaller {
                 Cookies.remove(key, { domain: resolvedDomain, path: "/" });
         }
     }
-    async apiRaw(apiName, payload, options) {
+    /** One call, one outcome. Never throws; every failure path resolves to { ok: false }. */
+    async dispatch(apiName, payload, options) {
+        // Per-call overrides win over the constructor handlers.
+        const versionExpiredHandler = options?.versionExpiredHandler ?? this.versionExpiredHandler;
+        const sessionExpiredHandler = options?.sessionExpiredHandler ?? this.sessionExpiredHandler;
+        const messageHandler = options?.messageHandler ?? this.messageHandler;
+        const errorMessageHandler = options?.errorMessageHandler ?? this.errorMessageHandler;
+        const notAuthorizedHandler = options?.notAuthorizedHandler ?? this.notAuthorizedHandler;
+        const errorHandler = options?.errorHandler ?? this.errorHandler;
+        const apiInputValidationErrorHandler = options?.apiInputValidationErrorHandler ?? this.apiInputValidationErrorHandler;
+        const fetchStartedHandler = options?.fetchStartedHandler ?? this.fetchStartedHandler;
+        const fetchEndedHandler = options?.fetchEndedHandler ?? this.fetchEndedHandler;
         const headers = options?.headers;
         const fetchTracker = { apiName, done: false, fetchEndCalled: false };
+        const fetchEnded = async (fetchResult) => {
+            fetchTracker.done = true;
+            if (fetchTracker.fetchEndCalled || !fetchEndedHandler)
+                return;
+            fetchTracker.fetchEndCalled = true;
+            await fetchEndedHandler({
+                fetchParams: { apiName, payload, headers },
+                fetchResult,
+                activeFetchList: this.fetchTrackerList.filter(v => !v.done),
+            });
+        };
+        let errorHandlerCalled = false;
+        const reportError = async (err) => {
+            if (errorHandlerCalled || !errorHandler)
+                return;
+            errorHandlerCalled = true;
+            await errorHandler(err);
+        };
+        // Timeout / abort wiring: the timeout gets its own controller chained
+        // to any external signal, so either source aborts the fetch.
+        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
+        const externalSignal = options?.signal;
+        let timedOut = false;
+        let signal = externalSignal;
+        let timeoutId;
+        if (timeoutMs !== undefined) {
+            const controller = new AbortController();
+            if (externalSignal) {
+                if (externalSignal.aborted) {
+                    controller.abort(externalSignal.reason);
+                }
+                else {
+                    externalSignal.addEventListener("abort", () => controller.abort(externalSignal.reason), { once: true });
+                }
+            }
+            timeoutId = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+            signal = controller.signal;
+        }
         try {
             this.fetchTrackerList.push(fetchTracker);
-            if (this.fetchStartedHandler)
-                await this.fetchStartedHandler({
+            if (fetchStartedHandler)
+                await fetchStartedHandler({
                     fetchParams: { apiName, payload, headers, },
                     activeFetchList: this.fetchTrackerList.filter(v => !v.done)
                 });
             const version = this.apiVersion;
             const token = Cookies.get(this.sessionCsrfCookieKey) || "";
             const siteHost = window.location.hostname;
-            let data = await fetch(this.apiPath, {
-                method: 'POST', cache: 'no-cache',
-                // Cross-origin API hosts need CORS mode and included credentials.
-                mode: this.isCorsEnabled ? 'cors' : 'same-origin',
-                credentials: this.isCorsEnabled ? 'include' : 'same-origin',
-                redirect: 'follow', referrerPolicy: 'origin',
-                headers: { 'Content-Type': 'application/json', ...(headers || {}) },
-                body: JSON.stringify({ apiName, version, token, siteHost, payload, }),
-            }).then(async (res) => {
-                if (res.status >= 500)
-                    throw new Error("Request failed: " + res.status + " - " + res.statusText);
-                if (res.status === 422) {
-                    const errorData = await res.json();
-                    if (this.apiInputValidationErrorHandler) {
-                        await this.apiInputValidationErrorHandler(errorData.zodError);
-                    }
-                    else if (this.errorHandler) {
-                        await this.errorHandler(new Error("API Input Validation Error", { cause: errorData.zodError }));
+            let res;
+            try {
+                res = await fetch(this.apiPath, {
+                    method: 'POST', cache: 'no-cache',
+                    // Cross-origin API hosts need CORS mode and included credentials.
+                    mode: this.isCorsEnabled ? 'cors' : 'same-origin',
+                    credentials: this.isCorsEnabled ? 'include' : 'same-origin',
+                    redirect: 'follow', referrerPolicy: 'origin',
+                    headers: { 'Content-Type': 'application/json', ...(headers || {}) },
+                    body: JSON.stringify({
+                        apiName, version, token, siteHost, payload,
+                        ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
+                    }),
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (err) {
+                const wrappedError = err instanceof Error ? err : new Error("Request failed", { cause: err });
+                await fetchEnded(wrappedError);
+                await reportError(wrappedError);
+                return { ok: false, reason: timedOut ? 'timeout' : 'network', error: wrappedError };
+            }
+            if (res.status >= 500) {
+                // Lambder's own 500 fallback is a JSON envelope, but custom
+                // error handlers may answer text/HTML: parse defensively.
+                let errorMessage;
+                try {
+                    const bodyText = await res.text();
+                    try {
+                        errorMessage = JSON.parse(bodyText)?.errorMessage;
                     }
-                    return null;
+                    catch { /* not an envelope */ }
+                }
+                catch { /* body unavailable */ }
+                const wrappedError = new Error("Request failed: " + res.status + " - " + res.statusText);
+                await fetchEnded(wrappedError);
+                await reportError(wrappedError);
+                return { ok: false, reason: 'server', status: res.status, errorMessage, error: wrappedError };
+            }
+            if (res.status === 422) {
+                // A 422 without Lambder's validation body (e.g. a proxy's
+                // error page) is a server failure, not a validation result.
+                let zodError;
+                try {
+                    zodError = (await res.json())?.zodError;
                 }
-                ;
-                if (res.headers.get("Content-Type")?.includes("application/lambder-json-stream")) {
-                    const decompressed = res.json();
-                    return decompressed;
+                catch { /* not JSON */ }
+                if (zodError === undefined) {
+                    const wrappedError = new Error("Request failed: 422 without a validation body");
+                    await fetchEnded(wrappedError);
+                    await reportError(wrappedError);
+                    return { ok: false, reason: 'server', status: res.status, error: wrappedError };
+                }
+                await fetchEnded(null);
+                if (apiInputValidationErrorHandler) {
+                    await apiInputValidationErrorHandler(zodError);
                 }
                 else {
-                    return res.json();
+                    await reportError(new Error("API Input Validation Error", { cause: zodError }));
                 }
-            });
-            fetchTracker.done = true;
-            if (this.fetchEndedHandler) {
-                fetchTracker.fetchEndCalled = true;
-                await this.fetchEndedHandler({
-                    fetchParams: { apiName, payload, headers },
-                    fetchResult: data,
-                    activeFetchList: this.fetchTrackerList.filter(v => !v.done),
-                });
+                return { ok: false, reason: 'validation', status: res.status, zodError };
+            }
+            let data;
+            try {
+                data = await res.json();
+                if (data === null || typeof data !== "object")
+                    throw new Error("Response is not an object");
             }
-            if (data && data.logList) {
+            catch (err) {
+                // A non-envelope body (e.g. an HTML error page) is a server failure.
+                const wrappedError = new Error("Request failed: response is not a valid API envelope (status " + res.status + ")", { cause: err });
+                await fetchEnded(wrappedError);
+                await reportError(wrappedError);
+                return { ok: false, reason: 'server', status: res.status, error: wrappedError };
+            }
+            await fetchEnded(data);
+            if (data.logList?.length) {
                 for (const record of data.logList) {
-                    // Log to API response for debugging
+                    console.log("[lambder]", record);
                 }
             }
-            if (data && data.versionExpired) {
-                if (this.versionExpiredHandler) {
-                    await this.versionExpiredHandler();
+            if (data.versionExpired) {
+                if (versionExpiredHandler) {
+                    await versionExpiredHandler();
                 }
-                else if (this.errorHandler) {
-                    await this.errorHandler(new Error("Version Expired; Please refresh;"));
+                else {
+                    await reportError(new Error("Version Expired; Please refresh;"));
                 }
-                return null;
+                return { ok: false, reason: 'versionExpired', status: res.status, errorMessage: data.errorMessage, response: data };
             }
-            if (data && data.sessionExpired) {
+            if (data.sessionExpired) {
                 this.clearSessionCookies();
-                if (this.sessionExpiredHandler) {
-                    await this.sessionExpiredHandler();
+                if (sessionExpiredHandler) {
+                    await sessionExpiredHandler();
                 }
-                else if (this.errorHandler) {
-                    await this.errorHandler(new Error("Session Expired; Please log in again;"));
+                else {
+                    await reportError(new Error("Session Expired; Please log in again;"));
                 }
-                return null;
+                return { ok: false, reason: 'sessionExpired', status: res.status, errorMessage: data.errorMessage, response: data };
             }
-            if (data && data.notAuthorized) {
-                if (this.notAuthorizedHandler) {
-                    await this.notAuthorizedHandler();
+            if (data.notAuthorized) {
+                if (notAuthorizedHandler) {
+                    await notAuthorizedHandler();
                 }
-                else if (this.errorHandler) {
-                    await this.errorHandler(new Error("Not Authorized;"));
+                else {
+                    await reportError(new Error("Not Authorized;"));
                 }
-                return null;
+                return { ok: false, reason: 'notAuthorized', status: res.status, errorMessage: data.errorMessage, response: data };
             }
-            if (data && data.message && this.messageHandler) {
-                await this.messageHandler(data.message);
+            if (data.message && messageHandler) {
+                await messageHandler(data.message);
             }
-            if (data && data.errorMessage && this.errorMessageHandler) {
-                await this.errorMessageHandler(data.errorMessage);
+            if (data.errorMessage) {
+                if (errorMessageHandler) {
+                    await errorMessageHandler(data.errorMessage);
+                }
+                return { ok: false, reason: 'errorMessage', status: res.status, errorMessage: data.errorMessage, response: data };
             }
-            return data;
+            return { ok: true, payload: data.payload, response: data };
         }
         catch (err) {
+            // Escape hatch for anything above (typically an app handler throwing):
+            // dispatch never throws, so api()/apiOutcome() call sites never do.
             const wrappedError = err instanceof Error ? err : new Error("Error: ", { cause: err });
-            fetchTracker.done = true;
-            if (!fetchTracker.fetchEndCalled && this.fetchEndedHandler) {
-                await this.fetchEndedHandler({
-                    fetchParams: { apiName, payload, headers, },
-                    fetchResult: wrappedError,
-                    activeFetchList: this.fetchTrackerList.filter(v => !v.done)
-                });
-            }
-            if (this.errorHandler) {
-                this.errorHandler(wrappedError);
+            try {
+                await fetchEnded(wrappedError);
+                await reportError(wrappedError);
             }
-            return null;
+            catch { /* an app handler threw again; never propagate */ }
+            return { ok: false, reason: 'unknown', error: wrappedError };
+        }
+        finally {
+            fetchTracker.done = true;
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
         }
     }
     ;
-    // Use the same type for api but adjust the return type
+    /**
+     * Full-fidelity call: resolves to a discriminated LambderApiOutcome
+     * instead of collapsing every failure to null. Never throws.
+     */
+    async apiOutcome(apiName, payload, options) {
+        return await this.dispatch(apiName, payload, options);
+    }
+    ;
+    /**
+     * Legacy shape: the parsed envelope on success (and on structured
+     * errorMessage refusals, which carry an envelope), null on every other
+     * failure. Prefer apiOutcome() when the call site needs to know why.
+     */
+    async apiRaw(apiName, payload, options) {
+        const outcome = await this.dispatch(apiName, payload, options);
+        if (outcome.ok)
+            return outcome.response;
+        return outcome.reason === 'errorMessage' ? outcome.response : null;
+    }
+    ;
+    /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
     async api(apiName, payload, options) {
         const result = await this.apiRaw(apiName, payload, options);
         return result?.payload;

package/dist/LambderDdbCache.d.ts

@@ -2,6 +2,8 @@ import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 export interface LambderDdbCacheOptions {
     tableName: string;
     region?: string;
+    /** Partition key prefix, keeps cache items separated from other systems in a shared table. Default: "CACHE". */
+    keyPrefix?: string;
     namespace?: string;
     defaultTtlSeconds?: number;
     chunkBytes?: number;
@@ -26,9 +28,15 @@ export interface LambderDdbCacheGetOrSetOptions extends LambderDdbCacheSetOption
  * chunk succeeds, so readers see either the previous complete version or the
  * new complete version. DynamoDB TTL is cleanup only; every read also checks
  * expiresAt because TTL deletion can lag.
+ *
+ * Table shape: string hash key `pk`, string range key `sk`, TTL on
+ * `expiresAt`. Items are prefixed `CACHE#<namespace>#` by default, so the
+ * table can be shared with LambderDdbRateLimiter (`RL#`) and
+ * LambderDdbIdempotency (`IDEM#`) without key collisions.
  */
 export declare class LambderDdbCache {
     readonly tableName: string;
+    readonly keyPrefix: string;
     readonly namespace: string;
     private readonly client;
     private readonly defaultTtlSeconds;

package/dist/LambderDdbCache.js

@@ -76,9 +76,15 @@ const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, mil
  * chunk succeeds, so readers see either the previous complete version or the
  * new complete version. DynamoDB TTL is cleanup only; every read also checks
  * expiresAt because TTL deletion can lag.
+ *
+ * Table shape: string hash key `pk`, string range key `sk`, TTL on
+ * `expiresAt`. Items are prefixed `CACHE#<namespace>#` by default, so the
+ * table can be shared with LambderDdbRateLimiter (`RL#`) and
+ * LambderDdbIdempotency (`IDEM#`) without key collisions.
  */
 export class LambderDdbCache {
     tableName;
+    keyPrefix;
     namespace;
     client;
     defaultTtlSeconds;
@@ -91,6 +97,7 @@ export class LambderDdbCache {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
         this.tableName = options.tableName;
+        this.keyPrefix = options.keyPrefix ?? "CACHE";
         this.namespace = options.namespace?.trim() || "default";
         if (Buffer.byteLength(this.namespace, "utf8") > 128) {
             throw new Error("namespace must be at most 128 UTF-8 bytes");
@@ -492,7 +499,7 @@ export class LambderDdbCache {
         return key;
     }
     async partitionKey(key) {
-        return `${this.namespace}#${await sha256(key)}`;
+        return `${this.keyPrefix}#${this.namespace}#${await sha256(key)}`;
     }
     chunkSortKey(version, index) {
         return `chunk#${version}#${String(index).padStart(6, "0")}`;

package/dist/LambderDdbIdempotency.d.ts

@@ -0,0 +1,72 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+export interface LambderDdbIdempotencyOptions {
+    tableName: string;
+    region?: string;
+    /** Partition key prefix, keeps records separated from other systems in a shared table. Default: "IDEM". */
+    keyPrefix?: string;
+    client?: DynamoDBClient;
+}
+export type LambderIdempotencyBeginResult = {
+    state: "new";
+    ownerToken: string;
+} | {
+    state: "pending";
+} | {
+    state: "done";
+    statusCode: number;
+    contentType: string | null;
+    body: string;
+};
+/**
+ * DynamoDB-backed idempotency records: one item per (identity, api, key)
+ * scope, claimed atomically with a conditional put. The first request claims
+ * the scope as "pending"; concurrent duplicates see "pending"; once the
+ * response is stored via complete(), replays get it back verbatim until the
+ * TTL. Records whose expiresAt has passed count as absent (DynamoDB TTL
+ * deletion is lazy, so expiry is enforced in the condition, not left to TTL).
+ *
+ * Every claim carries a random ownerToken, and complete()/abandon() are
+ * conditional on still holding it: an original that outlives its pending TTL
+ * and loses the scope to a retry can no longer overwrite or delete the
+ * retry's claim (both settle calls become silent no-ops instead).
+ *
+ * Table shape: string hash key `pk`, string range key `sk`, TTL on
+ * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
+ * shared with LambderDdbRateLimiter (`RL#`) and LambderDdbCache (`CACHE#`)
+ * without key collisions.
+ */
+export declare class LambderDdbIdempotency {
+    readonly tableName: string;
+    readonly keyPrefix: string;
+    private readonly client;
+    constructor(options: LambderDdbIdempotencyOptions);
+    private itemKey;
+    /**
+     * Claim the scope. "new" means this request now owns it (proven by the
+     * returned ownerToken) and must call complete() or abandon(); "pending"
+     * means another request owns it right now; "done" carries the stored
+     * response to replay.
+     */
+    begin(scopeKey: string, { pendingTtlSeconds }: {
+        pendingTtlSeconds: number;
+    }): Promise<LambderIdempotencyBeginResult>;
+    /**
+     * Store the response for replays, overwriting the pending claim. Requires
+     * still holding the claim: returns false (storing nothing) when the
+     * ownerToken no longer matches, i.e. the claim expired and a retry took
+     * the scope over.
+     */
+    complete(scopeKey: string, ownerToken: string, { statusCode, contentType, body, ttlSeconds }: {
+        statusCode: number;
+        contentType: string | null;
+        body: string;
+        ttlSeconds: number;
+    }): Promise<boolean>;
+    /**
+     * Release the claim without storing a response (crash, uncacheable
+     * response), so a retry can execute. Conditional on still holding the
+     * claim; a lost claim makes this a silent no-op.
+     */
+    abandon(scopeKey: string, ownerToken: string): Promise<void>;
+}
+export default LambderDdbIdempotency;

package/dist/LambderDdbIdempotency.js

@@ -0,0 +1,132 @@
+import crypto from "crypto";
+import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } from "@aws-sdk/client-dynamodb";
+/**
+ * DynamoDB-backed idempotency records: one item per (identity, api, key)
+ * scope, claimed atomically with a conditional put. The first request claims
+ * the scope as "pending"; concurrent duplicates see "pending"; once the
+ * response is stored via complete(), replays get it back verbatim until the
+ * TTL. Records whose expiresAt has passed count as absent (DynamoDB TTL
+ * deletion is lazy, so expiry is enforced in the condition, not left to TTL).
+ *
+ * Every claim carries a random ownerToken, and complete()/abandon() are
+ * conditional on still holding it: an original that outlives its pending TTL
+ * and loses the scope to a retry can no longer overwrite or delete the
+ * retry's claim (both settle calls become silent no-ops instead).
+ *
+ * Table shape: string hash key `pk`, string range key `sk`, TTL on
+ * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
+ * shared with LambderDdbRateLimiter (`RL#`) and LambderDdbCache (`CACHE#`)
+ * without key collisions.
+ */
+export class LambderDdbIdempotency {
+    tableName;
+    keyPrefix;
+    client;
+    constructor(options) {
+        if (!options.tableName.trim())
+            throw new Error("tableName is required");
+        this.tableName = options.tableName;
+        this.keyPrefix = options.keyPrefix ?? "IDEM";
+        this.client = options.client ?? new DynamoDBClient(options.region ? { region: options.region } : {});
+    }
+    itemKey(scopeKey) {
+        return { pk: { S: `${this.keyPrefix}#${scopeKey}` }, sk: { S: "idem" } };
+    }
+    /**
+     * Claim the scope. "new" means this request now owns it (proven by the
+     * returned ownerToken) and must call complete() or abandon(); "pending"
+     * means another request owns it right now; "done" carries the stored
+     * response to replay.
+     */
+    async begin(scopeKey, { pendingTtlSeconds }) {
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const ownerToken = crypto.randomBytes(16).toString("hex");
+        try {
+            await this.client.send(new PutItemCommand({
+                TableName: this.tableName,
+                Item: {
+                    ...this.itemKey(scopeKey),
+                    state: { S: "pending" },
+                    ownerToken: { S: ownerToken },
+                    expiresAt: { N: String(nowSeconds + pendingTtlSeconds) },
+                },
+                ConditionExpression: "attribute_not_exists(pk) OR expiresAt <= :now",
+                ExpressionAttributeValues: { ":now": { N: String(nowSeconds) } },
+            }));
+            return { state: "new", ownerToken };
+        }
+        catch (error) {
+            if (error.name !== "ConditionalCheckFailedException")
+                throw error;
+        }
+        const existing = await this.client.send(new GetItemCommand({
+            TableName: this.tableName,
+            Key: this.itemKey(scopeKey),
+            ConsistentRead: true,
+        }));
+        const item = existing.Item;
+        // Deleted between the put and the read: treat as in-flight, the retry resolves it.
+        if (!item)
+            return { state: "pending" };
+        if (item.state?.S === "done") {
+            return {
+                state: "done",
+                statusCode: Number(item.statusCode?.N ?? 200),
+                contentType: item.contentType?.S ?? null,
+                body: item.body?.S ?? "",
+            };
+        }
+        return { state: "pending" };
+    }
+    /**
+     * Store the response for replays, overwriting the pending claim. Requires
+     * still holding the claim: returns false (storing nothing) when the
+     * ownerToken no longer matches, i.e. the claim expired and a retry took
+     * the scope over.
+     */
+    async complete(scopeKey, ownerToken, { statusCode, contentType, body, ttlSeconds }) {
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        try {
+            await this.client.send(new PutItemCommand({
+                TableName: this.tableName,
+                Item: {
+                    ...this.itemKey(scopeKey),
+                    state: { S: "done" },
+                    ownerToken: { S: ownerToken },
+                    statusCode: { N: String(statusCode) },
+                    ...(contentType ? { contentType: { S: contentType } } : {}),
+                    body: { S: body },
+                    expiresAt: { N: String(nowSeconds + ttlSeconds) },
+                },
+                ConditionExpression: "ownerToken = :owner",
+                ExpressionAttributeValues: { ":owner": { S: ownerToken } },
+            }));
+            return true;
+        }
+        catch (error) {
+            if (error.name !== "ConditionalCheckFailedException")
+                throw error;
+            return false;
+        }
+    }
+    /**
+     * Release the claim without storing a response (crash, uncacheable
+     * response), so a retry can execute. Conditional on still holding the
+     * claim; a lost claim makes this a silent no-op.
+     */
+    async abandon(scopeKey, ownerToken) {
+        try {
+            await this.client.send(new DeleteItemCommand({
+                TableName: this.tableName,
+                Key: this.itemKey(scopeKey),
+                ConditionExpression: "ownerToken = :owner",
+                ExpressionAttributeValues: { ":owner": { S: ownerToken } },
+            }));
+        }
+        catch (error) {
+            if (error.name !== "ConditionalCheckFailedException")
+                throw error;
+        }
+    }
+}
+export default LambderDdbIdempotency;

package/dist/LambderDdbRateLimiter.d.ts

@@ -13,7 +13,7 @@ export type LambderRateLimitResult = false | LambderRateLimitExceededMap;
 export interface LambderDdbRateLimiterOptions {
     tableName: string;
     region?: string;
-    /** Partition key prefix, keeps counters separated from other items. */
+    /** Partition key prefix, keeps counters separated from other systems in a shared table. Default: "RL". */
     keyPrefix?: string;
     /** Multiplier applied to the window length when setting the item TTL. */
     ttlWindowMultiplier?: number;
@@ -31,6 +31,9 @@ export interface LambderDdbRateLimiterOptions {
  * larger counters. Items carry an `expiresAt` attribute for DynamoDB TTL.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on `expiresAt`.
+ * Items are prefixed `RL#` by default, so the table can be shared with
+ * LambderDdbCache (`CACHE#`) and LambderDdbIdempotency (`IDEM#`) without key
+ * collisions.
  */
 export declare class LambderDdbRateLimiter {
     readonly tableName: string;

package/dist/LambderDdbRateLimiter.js

@@ -17,6 +17,9 @@ const WINDOW_CONFIG = [
  * larger counters. Items carry an `expiresAt` attribute for DynamoDB TTL.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on `expiresAt`.
+ * Items are prefixed `RL#` by default, so the table can be shared with
+ * LambderDdbCache (`CACHE#`) and LambderDdbIdempotency (`IDEM#`) without key
+ * collisions.
  */
 export class LambderDdbRateLimiter {
     tableName;