@oncely/client 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stacks0x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,84 +1,124 @@
 # @oncely/client
 
-Client-side utilities for generating idempotency keys.
+Client-side utilities for idempotency key generation and response handling.
+
+[![npm version](https://img.shields.io/npm/v/@oncely/client.svg)](https://www.npmjs.com/package/@oncely/client)
 
 ## Installation
 
+```bash
 npm install @oncely/client
+```
 
-## Usage
+## Quick Start
 
-import { store, generateKey, randomKey, compositeKey } from '@oncely/client';
+```typescript
+import { generateKey } from '@oncely/client';
 
-// Generate a UUID-based key
-const key = generateKey(); // "550e8400-e29b-41d4-a716-446655440000"
+const response = await fetch('/api/orders', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Idempotency-Key': generateKey(),
+  },
+  body: JSON.stringify(order),
+});
+```
 
-// Generate a random alphanumeric key
-const key = randomKey(); // "x7k9m2n4p1"
-const key = randomKey(32); // longer key
+## Key Generation
 
-// Create composite keys
-const key = compositeKey('order', orderId, 'attempt', 1);
-// "order:123:attempt:1"
+```typescript
+import { generateKey, generatePrefixedKey, createKeyGenerator } from '@oncely/client';
 
-// Store and retrieve keys (in-memory)
-store.set('current-order', key);
-const stored = store.get('current-order');
-store.delete('current-order');
-store.clear();
+// UUID v4
+const key = generateKey();
+// => '550e8400-e29b-41d4-a716-446655440000'
 
-## License
+// Prefixed UUID
+const key = generatePrefixedKey('ord');
+// => 'ord_550e8400-e29b-41d4-a716-446655440000'
 
-MIT
-// Response headers include: Idempotency-Replay: true
-}
+// Deterministic key from components
+const key = generateKey('user', userId, 'create-order');
+// => 'f8e9b4a2' (consistent hash for same inputs)
 
-// Check if response indicates a conflict (409)
-if (oncely.isConflict(response)) {
-// Request with this key is already in progress
-const retryAfter = oncely.getRetryAfter(response);
-await delay(retryAfter \* 1000);
-// Retry...
-}
+// Key generator namespace
+const key = createKeyGenerator();
+key(); // UUID
+key('a', 'b', 'c'); // Deterministic hash
+key.prefixed('txn'); // Prefixed UUID
+```
+
+## Key Store
 
-// Check if response indicates a mismatch (422)
-if (oncely.isMismatch(response)) {
-// Key was reused with different request body
-// Generate a new key and retry
+Track pending requests to prevent duplicate submissions:
+
+```typescript
+import { createStore } from '@oncely/client';
+
+const store = createStore({
+  prefix: 'oncely:',
+  ttl: '5m',
+  storage: localStorage,
+});
+
+// Mark request as pending
+store.pending('key-123');
+
+// Check if request is pending
+if (store.isPending('key-123')) {
+  throw new Error('Request already in progress');
 }
 
-// Parse RFC 7807 problem details from error response
-const problem = await oncely.getProblem(response);
-// => { type: "https://oncely.dev/errors/conflict", title: "Request in progress", ... }
+// Mark as completed
+store.complete('key-123');
 
-````
+// Clear a specific key
+store.clear('key-123');
+
+// Clear all oncely keys
+store.clearAll();
+```
 
-### Constants
+## Response Helpers
 
 ```typescript
-import { oncely } from '@oncely/client';
+import { isReplay, isConflict, isMismatch, getRetryAfter } from '@oncely/client';
 
-// Standard header name (IETF draft)
-oncely.HEADER; // => "Idempotency-Key"
+const response = await fetch('/api/orders', { ... });
+
+// Check if response was served from cache
+if (isReplay(response)) {
+  console.log('Cached response');
+}
+
+// Handle 409 Conflict
+if (isConflict(response)) {
+  const seconds = getRetryAfter(response);
+  await delay(seconds * 1000);
+  // Retry with same key...
+}
 
-// Replay indicator header
-oncely.HEADER_REPLAY; // => "Idempotency-Replay"
-````
+// Handle 422 Mismatch
+if (isMismatch(response)) {
+  // Key was reused with different body - generate new key
+}
+```
 
-## Usage with Fetch Wrappers
+## Usage with Fetch Libraries
 
-### With ky
+### ky
 
 ```typescript
 import ky from 'ky';
-import { oncely } from '@oncely/client';
+import { generateKey, IDEMPOTENCY_KEY_HEADER } from '@oncely/client';
 
 const api = ky.extend({
   hooks: {
     beforeRequest: [
       (request) => {
         if (['POST', 'PUT', 'PATCH'].includes(request.method)) {
-          request.headers.set(oncely.HEADER, oncely.key());
+          request.headers.set(IDEMPOTENCY_KEY_HEADER, generateKey());
         }
       },
     ],
@@ -86,47 +126,31 @@ const api = ky.extend({
 });
 ```
 
-### With axios
+### axios
 
 ```typescript
 import axios from 'axios';
-import { oncely } from '@oncely/client';
+import { generateKey, IDEMPOTENCY_KEY_HEADER } from '@oncely/client';
 
 const api = axios.create();
 
 api.interceptors.request.use((config) => {
-  if (['post', 'put', 'patch'].includes(config.method?.toLowerCase() ?? '')) {
-    config.headers[oncely.HEADER] = oncely.key();
+  if (['post', 'put', 'patch'].includes(config.method ?? '')) {
+    config.headers[IDEMPOTENCY_KEY_HEADER] = generateKey();
   }
   return config;
 });
 ```
 
-## TypeScript
-
-Full TypeScript support with exported types:
+## Constants
 
 ```typescript
-import type { ProblemDetails } from '@oncely/client';
+import { IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_REPLAY_HEADER } from '@oncely/client';
 
-const problem: ProblemDetails = await oncely.getProblem(response);
+IDEMPOTENCY_KEY_HEADER; // 'Idempotency-Key'
+IDEMPOTENCY_REPLAY_HEADER; // 'Idempotency-Replay'
 ```
 
-## Browser Support
-
-Works in all modern browsers. For older browsers, ensure you have:
-
-- `crypto.randomUUID()` polyfill (or use custom key generator)
-- `localStorage` / `sessionStorage` (for key store)
-
-## Related Packages
-
-- [@oncely/core](../core) - Core idempotency engine for servers
-- [@oncely/redis](../redis) - Redis storage adapter
-- [@oncely/upstash](../upstash) - Upstash Redis adapter
-- [@oncely/express](../express) - Express.js middleware
-- [@oncely/next](../next) - Next.js API route handlers
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oncely/client",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Client-side idempotency helpers for browser and frontend applications",
   "author": "stacks0x",
   "license": "MIT",
@@ -34,18 +34,21 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
-  },
   "devDependencies": {
     "tsup": "^8.0.1",
     "typescript": "^5.3.3"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.0.0"
   },
-  "sideEffects": false
-}
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}