Add 6 additive pre-1.0 features (#34)

* Add 6 additive pre-1.0 features

StorageAdapter:
- Add clear() to interface, implement on Memory + Redis
- Add count(), keys(), has() introspection methods

Events:
- Add durationMs to bot:reject event for timing visibility
- Add errorMessage to error events + extractErrorMessage() helper

Rendering hints:
- Add limitVideoQuality, useSystemFonts, disablePrefetch

Probe:
- Add runProbeWithRetry() with exponential backoff + jitter (ESM only,
  IIFE bundle unchanged at 1022 bytes)

* Add .ckb/ to .gitignore

* Fix PR #34 review issues: remove has(), add SCAN, fix retry on 5xx

- Remove redundant has() from StorageAdapter (pure alias for exists())
- Replace Redis KEYS with SCAN-based iteration, fall back to KEYS
- Fix runProbeWithRetry to retry on 5xx (was silently returning)
- Extract shared probe internals to _internal.ts to eliminate duplication
- Move Hono validationStart before JSON parse for consistency
- Add JSDoc to durationMs fields clarifying measurement semantics
- Improve extractErrorMessage to handle plain objects with .message
- Add tests for 5xx retry, SCAN operations, extractErrorMessage
- Update CHANGELOG with has() breaking change and migration guide

Author: SimplyLiz

.gitignore

@@ -7,4 +7,5 @@ coverage/
 *.tsbuildinfo
 .turbo/
 .DS_Store
+.ckb/
 *.log

CHANGELOG.md

@@ -10,12 +10,27 @@
 - **`profile:store` event now carries `StoredSignals` instead of `RawSignals`** — The event previously emitted the raw probe payload (including `userAgent`/`viewport`), not what was actually stored. The `signals` field now matches the persisted data. `bot:reject` still carries `RawSignals` (it fires before stripping)
 - **Rename default cookie `dr_session` → `device-router-session`** — Self-documenting name before 1.0 locks the cookie in. If you hardcode `cookieName: 'dr_session'` in your options you are unaffected; if you rely on the default, existing sessions will reset once on deploy
 - **Remove `disableAutoplay` rendering hint** — `disableAutoplay` triggered on identical conditions to `deferHeavyComponents` (`isLowEnd || isSlowConnection || isBatteryConstrained`). Use `deferHeavyComponents` instead
+- **Remove `has()` from `StorageAdapter`** — `has()` was a redundant alias for `exists()`. Custom adapters must remove their `has()` implementation
 - **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
 
+### Migration Guide
+
+If you have a custom `StorageAdapter` implementation:
+
+- Remove the `has()` method — use `exists()` instead
+- Replace any `adapter.has(token)` calls with `adapter.exists(token)`
+
 ### Features
 
 - **Composable middleware** — `createMiddleware()`, `createProbeEndpoint()`, and `createInjectionMiddleware()` are now first-class exports with full threshold validation and documentation. Use them independently for fine-grained control without the `createDeviceRouter()` factory
 - **`loadProbeScript()` utility** — New helper exported from all middleware packages that reads the minified probe bundle and optionally rewrites the endpoint URL. Pairs with `createInjectionMiddleware()` for standalone probe injection
+- **`clear()` on StorageAdapter** — `clear()` is now part of the `StorageAdapter` interface. `MemoryStorageAdapter` and `RedisStorageAdapter` both implement it. Redis implementation uses SCAN (when available) or KEYS + `DEL` with graceful error handling
+- **StorageAdapter introspection** — New `count()` and `keys()` methods on `StorageAdapter` for inspecting stored profiles. `keys()` returns session tokens (not prefixed keys). All methods handle errors gracefully on Redis
+- **Redis SCAN support** — `RedisStorageAdapter` uses the optional `scan()` method on the client for `clear()`, `count()`, and `keys()` operations, avoiding the blocking `KEYS` command. Falls back to `KEYS` when `scan` is not available
+- **`durationMs` on `bot:reject` event** — The `bot:reject` event now includes `durationMs` measuring validation and bot detection time, matching the pattern used by `profile:store`
+- **`errorMessage` on error events** — Error events now include a pre-extracted `errorMessage: string` field, avoiding the need to narrow the `error: unknown` field. New `extractErrorMessage()` helper exported from `@device-router/types`
+- **New rendering hints** — Three new hints: `limitVideoQuality` (slow connection or low battery), `useSystemFonts` (low-end device or slow connection), `disablePrefetch` (slow connection or low battery)
+- **Probe retry logic** — New `runProbeWithRetry()` function with exponential backoff and jitter. Exported from `@device-router/probe` as an ESM-only export (does not affect the IIFE bundle size)
 
 ## 0.4.0 (2026-02-24)
 

docs/api/types.md

@@ -85,6 +85,10 @@ if (isBotSignals(signals)) {
 }
 ```
 
+### `extractErrorMessage(err: unknown): string`
+
+Extracts a string message from an unknown error value. Returns `err.message` for `Error` instances, otherwise `String(err)`.
+
 ### `classifyFromHeaders(headers): DeviceTiers`
 
 Classifies device capabilities from HTTP request headers (User-Agent and Client Hints). Useful for first-request classification before the probe has run.
@@ -225,8 +229,14 @@ type DeviceRouterEvent =
       durationMs: number;
     }
   | { type: 'profile:store'; sessionToken: string; signals: StoredSignals; durationMs: number }
-  | { type: 'bot:reject'; sessionToken: string; signals: RawSignals }
-  | { type: 'error'; error: unknown; phase: 'middleware' | 'endpoint'; sessionToken?: string };
+  | { type: 'bot:reject'; sessionToken: string; signals: RawSignals; durationMs: number }
+  | {
+      type: 'error';
+      error: unknown;
+      errorMessage: string;
+      phase: 'middleware' | 'endpoint';
+      sessionToken?: string;
+    };
 ```
 
 ### `OnEventCallback`

docs/getting-started.md

@@ -369,3 +369,6 @@ Based on device tiers, the middleware provides boolean rendering hints:
 - `useImagePlaceholders` — Show placeholders instead of full images
 - `preferServerRendering` — Favor SSR over client-side rendering
 - `disable3dEffects` — Disable WebGL/3D content (no GPU or software renderer)
+- `limitVideoQuality` — Serve lower resolution video, skip HD streams
+- `useSystemFonts` — Skip loading custom web fonts
+- `disablePrefetch` — Don't speculatively fetch resources

docs/profile-schema.md

@@ -76,3 +76,6 @@ The full classified result attached to requests by the middleware.
 | `useImagePlaceholders`  | `boolean` | Slow connection (2g/3g)                                |
 | `preferServerRendering` | `boolean` | Low-end device                                         |
 | `disable3dEffects`      | `boolean` | No GPU or software renderer                            |
+| `limitVideoQuality`     | `boolean` | Slow connection or low battery                         |
+| `useSystemFonts`        | `boolean` | Low-end device or slow connection                      |
+| `disablePrefetch`       | `boolean` | Slow connection or low battery                         |

examples/shared/demo-template.ts

@@ -20,6 +20,9 @@ export function renderDemoPage({
           useImagePlaceholders: true,
           preferServerRendering: true,
           disable3dEffects: true,
+          limitVideoQuality: true,
+          useSystemFonts: true,
+          disablePrefetch: true,
         }
       : forceParam === 'full'
         ? {
@@ -29,6 +32,9 @@ export function renderDemoPage({
             useImagePlaceholders: false,
             preferServerRendering: false,
             disable3dEffects: false,
+            limitVideoQuality: false,
+            useSystemFonts: false,
+            disablePrefetch: false,
           }
         : profile?.hints;
 

packages/middleware-express/src/__tests__/endpoint.test.ts

@@ -9,6 +9,9 @@ function createMockStorage(): StorageAdapter {
     set: vi.fn().mockResolvedValue(undefined),
     delete: vi.fn().mockResolvedValue(undefined),
     exists: vi.fn().mockResolvedValue(false),
+    clear: vi.fn().mockResolvedValue(undefined),
+    count: vi.fn().mockResolvedValue(0),
+    keys: vi.fn().mockResolvedValue([]),
   };
 }
 
@@ -302,6 +305,7 @@ describe('createProbeEndpoint', () => {
       const event = botEvents[0] as Extract<DeviceRouterEvent, { type: 'bot:reject' }>;
       expect(typeof event.sessionToken).toBe('string');
       expect(event.signals).toEqual({});
+      expect(typeof event.durationMs).toBe('number');
     });
 
     it('emits error event on storage failure', async () => {
@@ -323,6 +327,7 @@ describe('createProbeEndpoint', () => {
       expect(event.phase).toBe('endpoint');
       expect(event.error).toBeInstanceOf(Error);
       expect((event.error as Error).message).toBe('Redis down');
+      expect(event.errorMessage).toBe('Redis down');
       expect(res.status).toHaveBeenCalledWith(500);
     });
 

packages/middleware-express/src/__tests__/middleware.test.ts

@@ -14,6 +14,9 @@ function createMockStorage(): StorageAdapter {
       store.delete(token);
     }),
     exists: vi.fn(async (token: string) => store.has(token)),
+    clear: vi.fn(async () => store.clear()),
+    count: vi.fn(async () => store.size),
+    keys: vi.fn(async () => [...store.keys()]),
     _store: store,
   } as StorageAdapter & { _store: Map<string, DeviceProfile> };
 }
@@ -395,6 +398,7 @@ describe('createMiddleware', () => {
       expect(event.phase).toBe('middleware');
       expect(event.error).toBeInstanceOf(Error);
       expect((event.error as Error).message).toBe('Storage down');
+      expect(event.errorMessage).toBe('Storage down');
       expect(next).toHaveBeenCalledWith(expect.any(Error));
     });
 

packages/middleware-express/src/endpoint.ts

@@ -1,7 +1,7 @@
 import type { Request, Response } from 'express';
 import type { StorageAdapter } from '@device-router/storage';
 import type { DeviceProfile, RawSignals, OnEventCallback } from '@device-router/types';
-import { isValidSignals, isBotSignals, emitEvent } from '@device-router/types';
+import { isValidSignals, isBotSignals, emitEvent, extractErrorMessage } from '@device-router/types';
 import { randomUUID } from 'node:crypto';
 
 export interface EndpointOptions {
@@ -29,6 +29,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
     let sessionToken: string | undefined;
     try {
       const signals = req.body as unknown;
+      const validationStart = performance.now();
 
       if (!isValidSignals(signals)) {
         res.status(400).json({ ok: false, error: 'Invalid probe payload' });
@@ -39,7 +40,8 @@ export function createProbeEndpoint(options: EndpointOptions) {
       sessionToken = existingToken || randomUUID();
 
       if (rejectBots && isBotSignals(signals)) {
-        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals });
+        const durationMs = performance.now() - validationStart;
+        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals, durationMs });
         res.status(403).json({ ok: false, error: 'Bot detected' });
         return;
       }
@@ -83,6 +85,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'endpoint',
         sessionToken,
       });

packages/middleware-express/src/middleware.ts

@@ -6,6 +6,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  extractErrorMessage,
   validateThresholds,
 } from '@device-router/types';
 import type {
@@ -111,6 +112,7 @@ export function createMiddleware(options: MiddlewareOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'middleware',
         sessionToken: req.cookies?.[cookieName] as string | undefined,
       });