@oncely/next 1.0.1 → 1.0.2

package/README.md

@@ -1,145 +1,118 @@
 # @oncely/next
 
-Next.js integration for oncely idempotency.
+Next.js integration for HTTP idempotency. Supports App Router and Pages Router.
+
+[![npm version](https://img.shields.io/npm/v/@oncely/next.svg)](https://www.npmjs.com/package/@oncely/next)
 
 ## Installation
 
+```bash
 npm install @oncely/core @oncely/next
+```
 
 ## App Router
 
+```typescript
 // 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 });
+  const order = await createOrder(await req.json());
+  return Response.json(order, { status: 201 });
 });
-
-// With options
-export const POST = next({
-required: true,
-ttl: '1h',
-})(handler);
+```
 
 ## Pages Router
 
+```typescript
 // pages/api/orders.ts
 import { pages } from '@oncely/next/pages';
 
 export default pages()(async (req, res) => {
-res.status(201).json(await createOrder(req.body));
+  const order = await createOrder(req.body);
+  res.status(201).json(order);
 });
+```
+
+## Configuration
+
+Both `next()` and `pages()` accept the same options:
+
+```typescript
+export const POST = next({
+  storage: upstash(), // Storage adapter
+  ttl: '1h', // Cache duration
+  required: true, // Require Idempotency-Key header
+  failOpen: true, // Continue if storage fails
+  getKey: (req) => req.headers.get('x-request-id'), // Custom key extraction
+  getHash: async (req) => hashObject(await req.json()), // Custom hash
+  onHit: (key, response) => {}, // Cache hit callback
+  onMiss: (key) => {}, // Cache miss callback
+  onError: (key, error) => {}, // Error callback
+})(handler);
+```
 
 ## Pre-configured Factory
 
+Share configuration across routes:
+
+```typescript
+// lib/idempotency.ts
 import { configure } from '@oncely/next';
 import { upstash } from '@oncely/upstash';
 
 export const idempotent = configure({
-storage: upstash(),
-ttl: '1h',
+  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";
+// app/api/orders/route.ts
+import { idempotent } from '@/lib/idempotency';
 
-export default oncely(
-  async (req, res) => {
-    const order = await createOrder(req.body);
-    res.status(201).json(order);
-  },
-  { storage: memory },
-);
-````
+export const POST = idempotent()(handler);
+```
 
-### Shared Configuration (Pages)
+Pages Router has its own configure:
 
 ```typescript
 // lib/idempotency.ts
-import { configure } from 'oncely-next/pages';
-import { ioredis } from 'oncely-redis';
+import { configure } from '@oncely/next/pages';
 
-export const oncely = configure({
-  storage: ioredis({ client: redis }),
-  ttl: '24h',
+export const idempotent = configure({
+  storage: upstash(),
+  ttl: '1h',
 });
 
 // pages/api/orders.ts
-import { oncely } from '@/lib/idempotency';
+import { idempotent } from '@/lib/idempotency';
 
-export default oncely(async (req, res) => {
-  const order = await createOrder(req.body);
-  res.status(201).json(order);
-});
+export default idempotent()(handler);
 ```
 
-## Options
+## Headers
 
-```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) => {},
-});
-```
+| Header               | Direction | Description                           |
+| -------------------- | --------- | ------------------------------------- |
+| `Idempotency-Key`    | Request   | Client-provided unique key            |
+| `Idempotency-Key`    | Response  | Echo of the key used                  |
+| `Idempotency-Replay` | Response  | `true` when returning cached response |
 
-## Response Headers
+## Error Responses
 
-When `responseHeaders` is enabled (default), responses include:
+All errors follow [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807):
 
-```
-Idempotency-Key: <key>
-Idempotency-Status: hit | created
-Idempotency-Created: <ISO timestamp>  (on cache hit)
-Retry-After: <seconds>                 (on 409 conflict)
+| Status | Type           | Cause                               |
+| ------ | -------------- | ----------------------------------- |
+| 400    | `key-required` | Missing key when `required: true`   |
+| 409    | `conflict`     | Request with same key in progress   |
+| 422    | `mismatch`     | Same key reused with different body |
+
+## With Upstash (Serverless)
+
+```typescript
+import { upstash } from '@oncely/upstash';
+
+export const POST = next({ storage: upstash() })(handler);
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oncely/next",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Next.js integration for oncely idempotency",
   "author": "stacks0x",
   "license": "MIT",
@@ -40,19 +40,19 @@
   ],
   "peerDependencies": {
     "next": ">=13.0.0",
-    "@oncely/core": "0.2.1"
+    "@oncely/core": "0.2.2"
   },
   "devDependencies": {
     "next": "^16.1.4",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
-    "@oncely/core": "0.2.1"
+    "@oncely/core": "0.2.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build": "tsup",