@oncely/next 1.0.0

package/README.md

@@ -0,0 +1,147 @@
+# @oncely/next
+
+Next.js integration for oncely idempotency.
+
+## Installation
+
+npm install @oncely/core @oncely/next
+
+## App Router
+
+// app/api/orders/route.ts
+import { next } from '@oncely/next';
+
+export const POST = next()(async (req) => {
+const body = await req.json();
+return Response.json(await createOrder(body), { status: 201 });
+});
+
+// With options
+export const POST = next({
+required: true,
+ttl: '1h',
+})(handler);
+
+## Pages Router
+
+// pages/api/orders.ts
+import { pages } from '@oncely/next/pages';
+
+export default pages()(async (req, res) => {
+res.status(201).json(await createOrder(req.body));
+});
+
+## Pre-configured Factory
+
+import { configure } from '@oncely/next';
+import { upstash } from '@oncely/upstash';
+
+export const idempotent = configure({
+storage: upstash(),
+ttl: '1h',
+});
+
+// Usage
+export const POST = idempotent()(handler);
+
+## Headers
+
+Request: Idempotency-Key
+Response: Idempotency-Key, Idempotency-Replay (on cache hit)
+
+## License
+
+MIT
+}
+
+      const result = await idempotency.run({
+        key,
+        hash: hashObject(body),
+        handler: () => handler(req, ctx, body),
+      });
+
+      return result.data;
+    }
+
+    return handler(req, ctx, body);
+
+};
+}
+
+````
+
+## Pages Router
+
+```typescript
+// pages/api/orders.ts
+import { oncely } from "oncely-next/pages";
+import { memory } from "oncely";
+
+export default oncely(
+  async (req, res) => {
+    const order = await createOrder(req.body);
+    res.status(201).json(order);
+  },
+  { storage: memory },
+);
+````
+
+### Shared Configuration (Pages)
+
+```typescript
+// lib/idempotency.ts
+import { configure } from 'oncely-next/pages';
+import { ioredis } from 'oncely-redis';
+
+export const oncely = configure({
+  storage: ioredis({ client: redis }),
+  ttl: '24h',
+});
+
+// pages/api/orders.ts
+import { oncely } from '@/lib/idempotency';
+
+export default oncely(async (req, res) => {
+  const order = await createOrder(req.body);
+  res.status(201).json(order);
+});
+```
+
+## Options
+
+```typescript
+oncely(handler, {
+  // Required
+  storage: StorageAdapter,
+
+  // Optional
+  keyHeader: 'Idempotency-Key', // Header name (default: 'Idempotency-Key')
+  required: false, // Require key? (default: false)
+  responseHeaders: true, // Add idempotency headers to response
+  ttl: '24h', // Key expiration
+  debug: false, // Enable debug logging
+
+  // Custom hash function
+  hashRequest: async (req) => hashObject(await req.json()),
+
+  // Callbacks
+  onHit: (key) => {},
+  onMiss: (key) => {},
+  onError: (key, err) => {},
+});
+```
+
+## Response Headers
+
+When `responseHeaders` is enabled (default), responses include:
+
+```
+Idempotency-Key: <key>
+Idempotency-Status: hit | created
+Idempotency-Created: <ISO timestamp>  (on cache hit)
+Retry-After: <seconds>                 (on 409 conflict)
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,264 @@
+'use strict';
+
+var core = require('@oncely/core');
+
+// src/index.ts
+var PROBLEM_BASE = "https://oncely.dev/errors";
+var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+var IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+var defaultStorage = null;
+function getStorage(provided) {
+  if (provided) return provided;
+  if (!defaultStorage) {
+    defaultStorage = new core.MemoryStorage();
+  }
+  return defaultStorage;
+}
+async function defaultGetHash(req) {
+  const clone = req.clone();
+  try {
+    const body = await clone.json();
+    return core.hashObject(body);
+  } catch {
+    return null;
+  }
+}
+function next(options = {}) {
+  const {
+    storage: providedStorage,
+    ttl = "24h",
+    required = false,
+    getKey = (req) => req.headers.get(IDEMPOTENCY_KEY_HEADER),
+    getHash = defaultGetHash,
+    includeHeaders = true,
+    debug = false,
+    failOpen = false,
+    onHit,
+    onMiss,
+    onError
+  } = options;
+  const storage = getStorage(providedStorage);
+  const ttlMs = core.parseTtl(ttl);
+  const log = (message) => {
+    if (debug) {
+      console.log(`[oncely/next] ${message}`);
+    }
+  };
+  return (handler) => {
+    return async (req, context) => {
+      const key = getKey(req);
+      if (!key && !required) {
+        return handler(req, context);
+      }
+      if (!key && required) {
+        const headers = {};
+        if (includeHeaders) {
+          headers["Content-Type"] = "application/problem+json";
+        }
+        return new Response(
+          JSON.stringify({
+            type: `${PROBLEM_BASE}/key-required`,
+            title: "Idempotency Key Required",
+            status: 400,
+            detail: `The ${IDEMPOTENCY_KEY_HEADER} header is required for this request.`
+          }),
+          { status: 400, headers }
+        );
+      }
+      const hash = await getHash(req);
+      try {
+        log(`Acquiring lock for key: ${key}`);
+        let result;
+        try {
+          result = await storage.acquire(key, hash, ttlMs);
+        } catch (storageErr) {
+          if (failOpen) {
+            log(`Storage error for key: ${key}, failing open`);
+            onError?.(key, storageErr);
+            return handler(req, context);
+          }
+          throw storageErr;
+        }
+        if (result.status === "hit") {
+          log(`Cache hit for key: ${key}`);
+          onHit?.(key, result.response);
+          const cached = result.response.data;
+          const responseHeaders = {
+            ...cached.headers
+          };
+          if (includeHeaders) {
+            responseHeaders[IDEMPOTENCY_KEY_HEADER] = key;
+            responseHeaders[IDEMPOTENCY_REPLAY_HEADER] = "true";
+          }
+          if (cached.isJson) {
+            return new Response(JSON.stringify(cached.body), {
+              status: cached.status,
+              headers: { ...responseHeaders, "Content-Type": "application/json" }
+            });
+          }
+          return new Response(String(cached.body ?? ""), {
+            status: cached.status,
+            headers: responseHeaders
+          });
+        }
+        if (result.status === "conflict") {
+          log(`Conflict for key: ${key}`);
+          const headers = {
+            "Content-Type": "application/problem+json"
+          };
+          if (includeHeaders) {
+            headers[IDEMPOTENCY_KEY_HEADER] = key;
+            headers["Retry-After"] = "1";
+          }
+          return new Response(
+            JSON.stringify({
+              type: `${PROBLEM_BASE}/conflict`,
+              title: "Conflict",
+              status: 409,
+              detail: "A request with this idempotency key is already being processed."
+            }),
+            { status: 409, headers }
+          );
+        }
+        if (result.status === "mismatch") {
+          log(`Hash mismatch for key: ${key}`);
+          const headers = {
+            "Content-Type": "application/problem+json"
+          };
+          if (includeHeaders) {
+            headers[IDEMPOTENCY_KEY_HEADER] = key;
+          }
+          return new Response(
+            JSON.stringify({
+              type: `${PROBLEM_BASE}/mismatch`,
+              title: "Idempotency Key Mismatch",
+              status: 422,
+              detail: "The request body does not match the original request for this idempotency key.",
+              existingHash: result.existingHash,
+              providedHash: result.providedHash
+            }),
+            { status: 422, headers }
+          );
+        }
+        log(`Lock acquired for key: ${key}`);
+        onMiss?.(key);
+        try {
+          const response = await handler(req, context);
+          const clone = response.clone();
+          let body;
+          let isJson = false;
+          const contentType = response.headers.get("Content-Type") || "";
+          if (contentType.includes("application/json")) {
+            try {
+              body = await clone.json();
+              isJson = true;
+            } catch {
+              body = await clone.text();
+            }
+          } else {
+            body = await clone.text();
+          }
+          const responseHeaders = {};
+          response.headers.forEach((value, key2) => {
+            responseHeaders[key2] = value;
+          });
+          const cached = {
+            status: response.status,
+            headers: responseHeaders,
+            body,
+            isJson
+          };
+          const storedResponse = {
+            data: cached,
+            createdAt: Date.now(),
+            hash
+          };
+          storage.save(key, storedResponse).catch((err) => {
+            log(`Failed to save response for key: ${key}`);
+            onError?.(key, err);
+          });
+          if (includeHeaders) {
+            const newHeaders = new Headers(response.headers);
+            newHeaders.set(IDEMPOTENCY_KEY_HEADER, key);
+            return new Response(response.body, {
+              status: response.status,
+              statusText: response.statusText,
+              headers: newHeaders
+            });
+          }
+          return response;
+        } catch (err) {
+          log(`Handler error for key: ${key}, releasing lock`);
+          await storage.release(key).catch(() => {
+          });
+          throw err;
+        }
+      } catch (err) {
+        if (err instanceof core.IdempotencyError) {
+          const headers = {
+            "Content-Type": "application/problem+json"
+          };
+          if (includeHeaders) {
+            headers[IDEMPOTENCY_KEY_HEADER] = key;
+            if (err instanceof core.ConflictError) {
+              headers["Retry-After"] = String(err.retryAfter ?? 1);
+            }
+          }
+          let type = `${PROBLEM_BASE}/error`;
+          if (err instanceof core.MissingKeyError) type = `${PROBLEM_BASE}/key-required`;
+          else if (err instanceof core.ConflictError) type = `${PROBLEM_BASE}/conflict`;
+          else if (err instanceof core.MismatchError) type = `${PROBLEM_BASE}/mismatch`;
+          return new Response(
+            JSON.stringify({
+              type,
+              title: err.name,
+              status: err.statusCode,
+              detail: err.message
+            }),
+            { status: err.statusCode, headers }
+          );
+        }
+        throw err;
+      }
+    };
+  };
+}
+function configure(defaults) {
+  return (overrides = {}) => next({ ...defaults, ...overrides });
+}
+core.oncely.next = next;
+
+Object.defineProperty(exports, "ConflictError", {
+  enumerable: true,
+  get: function () { return core.ConflictError; }
+});
+Object.defineProperty(exports, "IdempotencyError", {
+  enumerable: true,
+  get: function () { return core.IdempotencyError; }
+});
+Object.defineProperty(exports, "MemoryStorage", {
+  enumerable: true,
+  get: function () { return core.MemoryStorage; }
+});
+Object.defineProperty(exports, "MismatchError", {
+  enumerable: true,
+  get: function () { return core.MismatchError; }
+});
+Object.defineProperty(exports, "MissingKeyError", {
+  enumerable: true,
+  get: function () { return core.MissingKeyError; }
+});
+Object.defineProperty(exports, "hashObject", {
+  enumerable: true,
+  get: function () { return core.hashObject; }
+});
+Object.defineProperty(exports, "oncely", {
+  enumerable: true,
+  get: function () { return core.oncely; }
+});
+exports.IDEMPOTENCY_KEY_HEADER = IDEMPOTENCY_KEY_HEADER;
+exports.IDEMPOTENCY_REPLAY_HEADER = IDEMPOTENCY_REPLAY_HEADER;
+exports.configure = configure;
+exports.next = next;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["MemoryStorage","hashObject","parseTtl","key","IdempotencyError","ConflictError","MissingKeyError","MismatchError","oncely"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @oncely/next - Next.js App Router integration for oncely idempotency\n *\n * Provides a wrapper for Next.js App Router route handlers with idempotency protection.\n *\n * @example\n * ```typescript\n * // app/api/orders/route.ts\n * import { next } from '@oncely/next';\n *\n * export const POST = next()(async (req) => {\n *   const body = await req.json();\n *   const order = await createOrder(body);\n *   return Response.json(order, { status: 201 });\n * });\n * ```\n */\n\nimport {\n  oncely,\n  MemoryStorage,\n  hashObject,\n  parseTtl,\n  IdempotencyError,\n  ConflictError,\n  MissingKeyError,\n  MismatchError,\n  type StorageAdapter,\n  type OncelyOptions,\n  type StoredResponse,\n} from '@oncely/core';\n\n// RFC 7807 Problem Details type URL base\nconst PROBLEM_BASE = 'https://oncely.dev/errors';\n\n/**\n * IETF standard header names\n */\nexport const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key';\nexport const IDEMPOTENCY_REPLAY_HEADER = 'Idempotency-Replay';\n\n/**\n * Options for the Next.js App Router wrapper\n */\nexport interface NextMiddlewareOptions {\n  /**\n   * Storage adapter for persisting idempotency records.\n   * @default MemoryStorage\n   */\n  storage?: StorageAdapter;\n\n  /**\n   * TTL for idempotency records in milliseconds or duration string.\n   * @default '24h'\n   */\n  ttl?: number | string;\n\n  /**\n   * Whether to require an idempotency key.\n   * If true, returns 400 when key is missing.\n   * @default false\n   */\n  required?: boolean;\n\n  /**\n   * Custom function to extract idempotency key from request.\n   * @default Reads Idempotency-Key header\n   */\n  getKey?: (req: Request) => string | undefined | null;\n\n  /**\n   * Custom function to generate hash from request for mismatch detection.\n   * @default Hashes request body as JSON\n   */\n  getHash?: (req: Request) => Promise<string | null> | string | null;\n\n  /**\n   * Whether to add idempotency headers to responses.\n   * @default true\n   */\n  includeHeaders?: boolean;\n\n  /**\n   * Debug mode for logging.\n   * @default false\n   */\n  debug?: boolean;\n\n  /**\n   * Callback when a cached response is returned.\n   */\n  onHit?: OncelyOptions['onHit'];\n\n  /**\n   * Callback when a new response is generated.\n   */\n  onMiss?: OncelyOptions['onMiss'];\n\n  /**\n   * Callback when an error occurs.\n   */\n  onError?: OncelyOptions['onError'];\n\n  /**\n   * If true, proceed with the request when storage fails (e.g., Redis down).\n   * When false (default), storage errors return 500.\n   * Use with non-critical idempotency where availability is more important.\n   * @default false\n   */\n  failOpen?: boolean;\n}\n\n/**\n * Stored response data for replay\n */\ninterface CachedResponse {\n  status: number;\n  headers: Record<string, string>;\n  body: unknown;\n  isJson: boolean;\n}\n\n/**\n * Route handler function signature\n */\ntype RouteHandler = (req: Request, context?: unknown) => Promise<Response> | Response;\n\n// Shared default storage instance\nlet defaultStorage: StorageAdapter | null = null;\n\nfunction getStorage(provided?: StorageAdapter): StorageAdapter {\n  if (provided) return provided;\n  if (!defaultStorage) {\n    defaultStorage = new MemoryStorage();\n  }\n  return defaultStorage;\n}\n\n/**\n * Default hash function that reads and hashes request body\n */\nasync function defaultGetHash(req: Request): Promise<string | null> {\n  const clone = req.clone();\n  try {\n    const body = await clone.json();\n    return hashObject(body);\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Create a Next.js App Router route handler wrapper with idempotency protection.\n *\n * @example\n * ```typescript\n * // app/api/orders/route.ts\n * import { next } from '@oncely/next';\n *\n * // Basic usage\n * export const POST = next()(async (req) => {\n *   const body = await req.json();\n *   const order = await createOrder(body);\n *   return Response.json(order, { status: 201 });\n * });\n *\n * // With options\n * export const POST = next({ required: true, ttl: '1h' })(async (req) => {\n *   const body = await req.json();\n *   return Response.json(await processPayment(body));\n * });\n * ```\n */\nexport function next(options: NextMiddlewareOptions = {}): (handler: RouteHandler) => RouteHandler {\n  const {\n    storage: providedStorage,\n    ttl = '24h',\n    required = false,\n    getKey = (req) => req.headers.get(IDEMPOTENCY_KEY_HEADER),\n    getHash = defaultGetHash,\n    includeHeaders = true,\n    debug = false,\n    failOpen = false,\n    onHit,\n    onMiss,\n    onError,\n  } = options;\n\n  const storage = getStorage(providedStorage);\n  const ttlMs = parseTtl(ttl);\n\n  const log = (message: string) => {\n    if (debug) {\n      console.log(`[oncely/next] ${message}`);\n    }\n  };\n\n  return (handler: RouteHandler): RouteHandler => {\n    return async (req: Request, context?: unknown): Promise<Response> => {\n      // Get idempotency key\n      const key = getKey(req);\n\n      // Skip if no key and not required\n      if (!key && !required) {\n        return handler(req, context);\n      }\n\n      // Return 400 if key required but not provided\n      if (!key && required) {\n        const headers: Record<string, string> = {};\n        if (includeHeaders) {\n          headers['Content-Type'] = 'application/problem+json';\n        }\n        return new Response(\n          JSON.stringify({\n            type: `${PROBLEM_BASE}/key-required`,\n            title: 'Idempotency Key Required',\n            status: 400,\n            detail: `The ${IDEMPOTENCY_KEY_HEADER} header is required for this request.`,\n          }),\n          { status: 400, headers }\n        );\n      }\n\n      // Compute request hash\n      const hash = await getHash(req);\n\n      try {\n        log(`Acquiring lock for key: ${key}`);\n        let result;\n        try {\n          result = await storage.acquire(key!, hash, ttlMs);\n        } catch (storageErr) {\n          // Storage failed (e.g., Redis down)\n          if (failOpen) {\n            log(`Storage error for key: ${key}, failing open`);\n            onError?.(key!, storageErr as Error);\n            return handler(req, context); // Proceed without idempotency protection\n          }\n          throw storageErr;\n        }\n\n        if (result.status === 'hit') {\n          // Return cached response\n          log(`Cache hit for key: ${key}`);\n          onHit?.(key!, result.response);\n\n          const cached = result.response.data as CachedResponse;\n          const responseHeaders: Record<string, string> = {\n            ...cached.headers,\n          };\n\n          if (includeHeaders) {\n            responseHeaders[IDEMPOTENCY_KEY_HEADER] = key!;\n            responseHeaders[IDEMPOTENCY_REPLAY_HEADER] = 'true';\n          }\n\n          if (cached.isJson) {\n            return new Response(JSON.stringify(cached.body), {\n              status: cached.status,\n              headers: { ...responseHeaders, 'Content-Type': 'application/json' },\n            });\n          }\n\n          return new Response(String(cached.body ?? ''), {\n            status: cached.status,\n            headers: responseHeaders,\n          });\n        }\n\n        if (result.status === 'conflict') {\n          log(`Conflict for key: ${key}`);\n          const headers: Record<string, string> = {\n            'Content-Type': 'application/problem+json',\n          };\n          if (includeHeaders) {\n            headers[IDEMPOTENCY_KEY_HEADER] = key!;\n            headers['Retry-After'] = '1';\n          }\n          return new Response(\n            JSON.stringify({\n              type: `${PROBLEM_BASE}/conflict`,\n              title: 'Conflict',\n              status: 409,\n              detail: 'A request with this idempotency key is already being processed.',\n            }),\n            { status: 409, headers }\n          );\n        }\n\n        if (result.status === 'mismatch') {\n          log(`Hash mismatch for key: ${key}`);\n          const headers: Record<string, string> = {\n            'Content-Type': 'application/problem+json',\n          };\n          if (includeHeaders) {\n            headers[IDEMPOTENCY_KEY_HEADER] = key!;\n          }\n          return new Response(\n            JSON.stringify({\n              type: `${PROBLEM_BASE}/mismatch`,\n              title: 'Idempotency Key Mismatch',\n              status: 422,\n              detail:\n                'The request body does not match the original request for this idempotency key.',\n              existingHash: result.existingHash,\n              providedHash: result.providedHash,\n            }),\n            { status: 422, headers }\n          );\n        }\n\n        // status === 'acquired' - execute handler\n        log(`Lock acquired for key: ${key}`);\n        onMiss?.(key!);\n\n        try {\n          const response = await handler(req, context);\n\n          // Capture response for storage\n          const clone = response.clone();\n          let body: unknown;\n          let isJson = false;\n\n          const contentType = response.headers.get('Content-Type') || '';\n          if (contentType.includes('application/json')) {\n            try {\n              body = await clone.json();\n              isJson = true;\n            } catch {\n              body = await clone.text();\n            }\n          } else {\n            body = await clone.text();\n          }\n\n          // Capture headers\n          const responseHeaders: Record<string, string> = {};\n          response.headers.forEach((value, key) => {\n            responseHeaders[key] = value;\n          });\n\n          // Save to storage\n          const cached: CachedResponse = {\n            status: response.status,\n            headers: responseHeaders,\n            body,\n            isJson,\n          };\n\n          const storedResponse: StoredResponse = {\n            data: cached,\n            createdAt: Date.now(),\n            hash,\n          };\n\n          storage.save(key!, storedResponse).catch((err) => {\n            log(`Failed to save response for key: ${key}`);\n            onError?.(key!, err as Error);\n          });\n\n          // Add idempotency headers to original response\n          if (includeHeaders) {\n            const newHeaders = new Headers(response.headers);\n            newHeaders.set(IDEMPOTENCY_KEY_HEADER, key!);\n\n            return new Response(response.body, {\n              status: response.status,\n              statusText: response.statusText,\n              headers: newHeaders,\n            });\n          }\n\n          return response;\n        } catch (err) {\n          // Release lock on error\n          log(`Handler error for key: ${key}, releasing lock`);\n          await storage.release(key!).catch(() => {});\n          throw err;\n        }\n      } catch (err) {\n        // Handle idempotency errors\n        if (err instanceof IdempotencyError) {\n          const headers: Record<string, string> = {\n            'Content-Type': 'application/problem+json',\n          };\n          if (includeHeaders) {\n            headers[IDEMPOTENCY_KEY_HEADER] = key!;\n            if (err instanceof ConflictError) {\n              headers['Retry-After'] = String(err.retryAfter ?? 1);\n            }\n          }\n\n          let type = `${PROBLEM_BASE}/error`;\n          if (err instanceof MissingKeyError) type = `${PROBLEM_BASE}/key-required`;\n          else if (err instanceof ConflictError) type = `${PROBLEM_BASE}/conflict`;\n          else if (err instanceof MismatchError) type = `${PROBLEM_BASE}/mismatch`;\n\n          return new Response(\n            JSON.stringify({\n              type,\n              title: err.name,\n              status: err.statusCode,\n              detail: err.message,\n            }),\n            { status: err.statusCode, headers }\n          );\n        }\n\n        throw err;\n      }\n    };\n  };\n}\n\n/**\n * Create a pre-configured wrapper factory with default options.\n *\n * @example\n * ```typescript\n * // lib/idempotency.ts\n * import { configure } from '@oncely/next';\n * import { redis } from '@oncely/redis';\n *\n * export const idempotent = configure({\n *   storage: redis(),\n *   ttl: '1h',\n * });\n *\n * // app/api/orders/route.ts\n * import { idempotent } from '@/lib/idempotency';\n *\n * export const POST = idempotent()(async (req) => {\n *   const body = await req.json();\n *   return Response.json(await createOrder(body), { status: 201 });\n * });\n * ```\n */\nexport function configure(\n  defaults: NextMiddlewareOptions\n): (overrides?: Partial<NextMiddlewareOptions>) => (handler: RouteHandler) => RouteHandler {\n  return (overrides = {}) => next({ ...defaults, ...overrides });\n}\n\n// Augment oncely namespace\ndeclare module '@oncely/core' {\n  interface OncelyNamespace {\n    /**\n     * Create Next.js App Router wrapper with idempotency.\n     */\n    next: typeof next;\n  }\n}\n\n// Register on oncely namespace\n(oncely as Record<string, unknown>).next = next;\n\n// Re-export types and utilities\nexport {\n  oncely,\n  MemoryStorage,\n  hashObject,\n  IdempotencyError,\n  MissingKeyError,\n  ConflictError,\n  MismatchError,\n  type StorageAdapter,\n  type OncelyOptions,\n} from '@oncely/core';\n"]}

package/dist/index.d.cts

@@ -0,0 +1,147 @@
+import { StorageAdapter, OncelyOptions } from '@oncely/core';
+export { ConflictError, IdempotencyError, MemoryStorage, MismatchError, MissingKeyError, OncelyOptions, StorageAdapter, hashObject, oncely } from '@oncely/core';
+
+/**
+ * @oncely/next - Next.js App Router integration for oncely idempotency
+ *
+ * Provides a wrapper for Next.js App Router route handlers with idempotency protection.
+ *
+ * @example
+ * ```typescript
+ * // app/api/orders/route.ts
+ * import { next } from '@oncely/next';
+ *
+ * export const POST = next()(async (req) => {
+ *   const body = await req.json();
+ *   const order = await createOrder(body);
+ *   return Response.json(order, { status: 201 });
+ * });
+ * ```
+ */
+
+/**
+ * IETF standard header names
+ */
+declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+declare const IDEMPOTENCY_REPLAY_HEADER = "Idempotency-Replay";
+/**
+ * Options for the Next.js App Router wrapper
+ */
+interface NextMiddlewareOptions {
+    /**
+     * Storage adapter for persisting idempotency records.
+     * @default MemoryStorage
+     */
+    storage?: StorageAdapter;
+    /**
+     * TTL for idempotency records in milliseconds or duration string.
+     * @default '24h'
+     */
+    ttl?: number | string;
+    /**
+     * Whether to require an idempotency key.
+     * If true, returns 400 when key is missing.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Custom function to extract idempotency key from request.
+     * @default Reads Idempotency-Key header
+     */
+    getKey?: (req: Request) => string | undefined | null;
+    /**
+     * Custom function to generate hash from request for mismatch detection.
+     * @default Hashes request body as JSON
+     */
+    getHash?: (req: Request) => Promise<string | null> | string | null;
+    /**
+     * Whether to add idempotency headers to responses.
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Debug mode for logging.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback when a cached response is returned.
+     */
+    onHit?: OncelyOptions['onHit'];
+    /**
+     * Callback when a new response is generated.
+     */
+    onMiss?: OncelyOptions['onMiss'];
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: OncelyOptions['onError'];
+    /**
+     * If true, proceed with the request when storage fails (e.g., Redis down).
+     * When false (default), storage errors return 500.
+     * Use with non-critical idempotency where availability is more important.
+     * @default false
+     */
+    failOpen?: boolean;
+}
+/**
+ * Route handler function signature
+ */
+type RouteHandler = (req: Request, context?: unknown) => Promise<Response> | Response;
+/**
+ * Create a Next.js App Router route handler wrapper with idempotency protection.
+ *
+ * @example
+ * ```typescript
+ * // app/api/orders/route.ts
+ * import { next } from '@oncely/next';
+ *
+ * // Basic usage
+ * export const POST = next()(async (req) => {
+ *   const body = await req.json();
+ *   const order = await createOrder(body);
+ *   return Response.json(order, { status: 201 });
+ * });
+ *
+ * // With options
+ * export const POST = next({ required: true, ttl: '1h' })(async (req) => {
+ *   const body = await req.json();
+ *   return Response.json(await processPayment(body));
+ * });
+ * ```
+ */
+declare function next(options?: NextMiddlewareOptions): (handler: RouteHandler) => RouteHandler;
+/**
+ * Create a pre-configured wrapper factory with default options.
+ *
+ * @example
+ * ```typescript
+ * // lib/idempotency.ts
+ * import { configure } from '@oncely/next';
+ * import { redis } from '@oncely/redis';
+ *
+ * export const idempotent = configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ * });
+ *
+ * // app/api/orders/route.ts
+ * import { idempotent } from '@/lib/idempotency';
+ *
+ * export const POST = idempotent()(async (req) => {
+ *   const body = await req.json();
+ *   return Response.json(await createOrder(body), { status: 201 });
+ * });
+ * ```
+ */
+declare function configure(defaults: NextMiddlewareOptions): (overrides?: Partial<NextMiddlewareOptions>) => (handler: RouteHandler) => RouteHandler;
+declare module '@oncely/core' {
+    interface OncelyNamespace {
+        /**
+         * Create Next.js App Router wrapper with idempotency.
+         */
+        next: typeof next;
+    }
+}
+
+export { IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_REPLAY_HEADER, type NextMiddlewareOptions, configure, next };