@voyant-travel/hono 0.109.1

package/dist/middleware/idempotency-key.d.ts

@@ -0,0 +1,97 @@
+import type { MiddlewareHandler } from "hono";
+import { type DbFactory, type VoyantBindings, type VoyantDb, type VoyantVariables } from "../types.js";
+/**
+ * Twenty-four hours, in milliseconds. Default TTL for stored idempotency
+ * keys. Tunable per middleware instance.
+ */
+export declare const DEFAULT_IDEMPOTENCY_TTL_MS: number;
+export interface IdempotencyKeyOptions {
+    /**
+     * Namespacing label so unrelated endpoints can safely accept overlapping
+     * client keys. Defaults to the request method + pathname when omitted.
+     */
+    scope?: string;
+    /**
+     * How long stored responses are replayable. Defaults to
+     * {@link DEFAULT_IDEMPOTENCY_TTL_MS}.
+     */
+    ttlMs?: number;
+    /**
+     * Whether the header is required. When `true`, requests without the header
+     * are rejected with 400. Defaults to `false` so existing clients keep
+     * working through a deprecation window.
+     */
+    required?: boolean;
+    /**
+     * Query parameters that affect the response contract and should be included
+     * in the idempotency fingerprint alongside the request body. Reusing the
+     * same key with different fingerprinted query values returns 409 instead of
+     * replaying a response captured under different request semantics.
+     */
+    fingerprintSearchParams?: readonly string[];
+    /**
+     * Optional callback that, given the response body that's about to be
+     * stored, returns a `referenceId` (typically the booking id). Used for
+     * operational queries to correlate replays with the underlying entity.
+     */
+    extractReferenceId?: (body: unknown) => string | null | undefined;
+    /**
+     * Whether successful JSON responses are replayable. Disable for
+     * endpoints whose response carries session-bound bearer secrets.
+     */
+    replayResponses?: boolean;
+    /**
+     * Include the caller/session/IP in the `(scope, key)` namespace.
+     * Enabled by default so client-chosen keys cannot replay another
+     * caller's response on anonymous or shared public surfaces.
+     */
+    scopeWithCaller?: boolean;
+    /** Maximum request body bytes the middleware may buffer. Defaults to 10 MiB. */
+    maxBodyBytes?: number;
+}
+interface ContextWithIdempotency {
+    idempotencyKey?: string;
+    idempotencyReplayed?: boolean;
+}
+declare module "hono" {
+    interface ContextVariableMap extends ContextWithIdempotency {
+    }
+}
+/**
+ * Idempotency-Key middleware.
+ *
+ * On request:
+ * - reads the `Idempotency-Key` header
+ * - if absent and `required` is false, passes through
+ * - if absent and `required` is true, returns 400
+ * - looks up `(scope, key)` in `idempotency_keys`:
+ *   - hit + same body hash → returns the stored response (replay)
+ *   - hit + different body hash → returns 409 (conflict)
+ *   - miss → runs the handler, then stores the response on the way out
+ *
+ * The handler's response body is captured by cloning the response. The
+ * `Idempotency-Key` and a `Idempotency-Replayed: true` header are echoed
+ * on replay so callers can detect replays in client-side logging.
+ *
+ * The middleware reads the `db` instance off the request context (set by
+ * the `db` middleware that ships with `createApp`) — caller is responsible
+ * for ordering this middleware after `db`.
+ */
+export declare function idempotencyKey<TBindings extends object = VoyantBindings, TVariables extends {
+    db: VoyantDb;
+} = VoyantVariables>(options?: IdempotencyKeyOptions): MiddlewareHandler<{
+    Bindings: TBindings;
+    Variables: TVariables;
+}>;
+/**
+ * Sweep expired idempotency rows. Call from a daily cron.
+ *
+ * If `dbFactory` returns a `DisposableDb` (e.g. a per-call Neon
+ * WebSocket Pool), the sweep awaits `dispose()` before returning so
+ * the connection closes cleanly inside the cron handler.
+ */
+export declare function purgeExpiredIdempotencyKeys<TBindings extends VoyantBindings>(dbFactory: DbFactory<TBindings>, env: TBindings): Promise<{
+    removed: number;
+}>;
+export {};
+//# sourceMappingURL=idempotency-key.d.ts.map

package/dist/middleware/idempotency-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-key.d.ts","sourceRoot":"","sources":["../../src/middleware/idempotency-key.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAC7C,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,aAAa,CAAA;AAKpB;;;GAGG;AACH,eAAO,MAAM,0BAA0B,QAAsB,CAAA;AAmB7D,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACjE;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,UAAU,sBAAsB;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,kBAAmB,SAAQ,sBAAsB;KAAG;CAC/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,SAAS,MAAM,GAAG,cAAc,EACzC,UAAU,SAAS;IAAE,EAAE,EAAE,QAAQ,CAAA;CAAE,GAAG,eAAe,EAErD,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,UAAU,CAAA;CACtB,CAAC,CA4ID;AAwED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAAC,SAAS,SAAS,cAAc,EAChF,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,EAC/B,GAAG,EAAE,SAAS,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAW9B"}

package/dist/middleware/idempotency-key.js

@@ -0,0 +1,235 @@
+import { infraIdempotencyKeysTable } from "@voyant-travel/db/schema/infra";
+import { and, eq, lt } from "drizzle-orm";
+import { resolveDbFactoryResult, } from "../types.js";
+import { RequestValidationError } from "../validation.js";
+import { DEFAULT_REQUEST_BODY_LIMIT_BYTES } from "./body-size.js";
+import { clientIpKey } from "./rate-limit.js";
+/**
+ * Twenty-four hours, in milliseconds. Default TTL for stored idempotency
+ * keys. Tunable per middleware instance.
+ */
+export const DEFAULT_IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
+const HEADER_NAME = "Idempotency-Key";
+/**
+ * Hashes a UTF-8 string with SHA-256 and returns the hex digest. Uses Web
+ * Crypto so the middleware works in Cloudflare Workers and Node.
+ */
+async function sha256Hex(value) {
+    const data = new TextEncoder().encode(value);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    const bytes = new Uint8Array(digest);
+    let out = "";
+    for (const byte of bytes) {
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+/**
+ * Idempotency-Key middleware.
+ *
+ * On request:
+ * - reads the `Idempotency-Key` header
+ * - if absent and `required` is false, passes through
+ * - if absent and `required` is true, returns 400
+ * - looks up `(scope, key)` in `idempotency_keys`:
+ *   - hit + same body hash → returns the stored response (replay)
+ *   - hit + different body hash → returns 409 (conflict)
+ *   - miss → runs the handler, then stores the response on the way out
+ *
+ * The handler's response body is captured by cloning the response. The
+ * `Idempotency-Key` and a `Idempotency-Replayed: true` header are echoed
+ * on replay so callers can detect replays in client-side logging.
+ *
+ * The middleware reads the `db` instance off the request context (set by
+ * the `db` middleware that ships with `createApp`) — caller is responsible
+ * for ordering this middleware after `db`.
+ */
+export function idempotencyKey(options = {}) {
+    const ttlMs = options.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS;
+    return async (c, next) => {
+        if (c.req.method === "OPTIONS")
+            return next();
+        const headerKey = c.req.header(HEADER_NAME) ?? c.req.header(HEADER_NAME.toLowerCase());
+        if (!headerKey) {
+            if (options.required) {
+                return c.json({ error: `${HEADER_NAME} header is required for this endpoint` }, 400);
+            }
+            return next();
+        }
+        if (headerKey.length > 255) {
+            return c.json({ error: `${HEADER_NAME} must be 255 characters or fewer` }, 400);
+        }
+        const requestUrl = new URL(c.req.url);
+        const baseScope = options.scope ?? `${c.req.method} ${requestUrl.pathname}`;
+        const scope = options.scopeWithCaller === false ? baseScope : buildCallerScopedKey(c, baseScope);
+        const rawBody = await readBoundedBody(c, options.maxBodyBytes ?? DEFAULT_REQUEST_BODY_LIMIT_BYTES);
+        const bodyHash = await sha256Hex(buildFingerprintInput(rawBody, requestUrl, options.fingerprintSearchParams));
+        // The `db` middleware always unwraps a `DisposableDb` to a plain
+        // `VoyantDb` before storing on context, so this cast is safe.
+        const db = c.get("db");
+        if (!db) {
+            throw new Error("idempotencyKey middleware requires `db` on the request context. Mount `db()` (or `createApp`) before this middleware.");
+        }
+        // Look up an existing record. If the (scope, key) was used recently we
+        // either replay or 409.
+        const [existing] = await db
+            .select()
+            .from(infraIdempotencyKeysTable)
+            .where(and(eq(infraIdempotencyKeysTable.scope, scope), eq(infraIdempotencyKeysTable.key, headerKey)))
+            .limit(1);
+        if (existing) {
+            if (existing.expiresAt < new Date()) {
+                // The row is past its TTL — clean it up and proceed as if missed.
+                await db
+                    .delete(infraIdempotencyKeysTable)
+                    .where(eq(infraIdempotencyKeysTable.id, existing.id));
+            }
+            else if (existing.bodyHash !== bodyHash) {
+                return c.json({
+                    error: `${HEADER_NAME} ${headerKey} was previously used with a different request body`,
+                }, 409);
+            }
+            else {
+                c.set("idempotencyKey", headerKey);
+                c.set("idempotencyReplayed", true);
+                const replayed = c.json(existing.responseBody, existing.responseStatus);
+                replayed.headers.set("Idempotency-Replayed", "true");
+                replayed.headers.set("Idempotency-Key", headerKey);
+                return replayed;
+            }
+        }
+        // Re-attach the body so downstream handlers can re-parse it. Hono's
+        // `c.req.text()` consumed the original; rebuild a Request whose body
+        // matches what we hashed.
+        c.req.raw = new Request(c.req.raw, { body: rawBody });
+        c.set("idempotencyKey", headerKey);
+        c.set("idempotencyReplayed", false);
+        await next();
+        // Capture the response without consuming the original.
+        const response = c.res;
+        if (!response)
+            return;
+        const cloned = response.clone();
+        let parsedBody = null;
+        try {
+            const text = await cloned.text();
+            parsedBody = text.length > 0 ? JSON.parse(text) : null;
+        }
+        catch {
+            // Non-JSON responses are not stored — idempotency replay only works
+            // for JSON endpoints. Pass through silently.
+            return;
+        }
+        // Only persist successful, replayable responses (2xx). 4xx/5xx leave
+        // the slot open so the client can retry with a corrected body.
+        if (response.status < 200 || response.status >= 300)
+            return;
+        if (options.replayResponses === false)
+            return;
+        const referenceId = options.extractReferenceId?.(parsedBody) ??
+            pickStringField(parsedBody, ["bookingId", "id"]) ??
+            null;
+        try {
+            await db
+                .insert(infraIdempotencyKeysTable)
+                .values({
+                scope,
+                key: headerKey,
+                bodyHash,
+                responseStatus: response.status,
+                responseBody: parsedBody,
+                referenceId,
+                expiresAt: new Date(Date.now() + ttlMs),
+            })
+                .onConflictDoNothing({
+                target: [infraIdempotencyKeysTable.scope, infraIdempotencyKeysTable.key],
+            });
+            // Echo the header so callers can confirm idempotent storage.
+            c.res = new Response(c.res.body, {
+                status: c.res.status,
+                statusText: c.res.statusText,
+                headers: new Headers(c.res.headers),
+            });
+            c.res.headers.set("Idempotency-Key", headerKey);
+        }
+        catch {
+            // Best-effort storage. If the write fails we still return the
+            // response — duplicate-detection just degrades to "no protection
+            // for this request." Logging is the deployment's responsibility.
+        }
+    };
+}
+async function readBoundedBody(c, maxBytes) {
+    const contentLength = c.req.header("content-length");
+    if (contentLength) {
+        const size = Number(contentLength);
+        if (Number.isFinite(size) && size > maxBytes) {
+            throw new RequestValidationError("Request body too large", { maxBytes });
+        }
+    }
+    const body = await c.req.text();
+    if (new TextEncoder().encode(body).byteLength > maxBytes) {
+        throw new RequestValidationError("Request body too large", { maxBytes });
+    }
+    return body;
+}
+function buildCallerScopedKey(c, baseScope) {
+    const stableCaller = pickContextString(c, "apiKeyId") ??
+        pickContextString(c, "apiTokenId") ??
+        pickContextString(c, "sessionId") ??
+        pickContextString(c, "userId");
+    if (stableCaller)
+        return `${baseScope}:caller:${stableCaller}`;
+    return `${baseScope}:ip:${clientIpKey(c)}`;
+}
+function pickContextString(c, key) {
+    const value = c.get(key);
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function buildFingerprintInput(rawBody, url, searchParamKeys) {
+    if (!searchParamKeys?.length)
+        return rawBody;
+    const queryFingerprint = searchParamKeys.map((key) => [key, url.searchParams.getAll(key).sort()]);
+    return JSON.stringify({
+        body: rawBody,
+        query: queryFingerprint,
+    });
+}
+function pickStringField(body, keys) {
+    if (!body || typeof body !== "object")
+        return null;
+    const obj = body;
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+        // Common shape: `{ data: { id: ... } }`
+        if (key === "id" && obj.data && typeof obj.data === "object") {
+            const nested = obj.data.id;
+            if (typeof nested === "string" && nested.length > 0)
+                return nested;
+        }
+    }
+    return null;
+}
+/**
+ * Sweep expired idempotency rows. Call from a daily cron.
+ *
+ * If `dbFactory` returns a `DisposableDb` (e.g. a per-call Neon
+ * WebSocket Pool), the sweep awaits `dispose()` before returning so
+ * the connection closes cleanly inside the cron handler.
+ */
+export async function purgeExpiredIdempotencyKeys(dbFactory, env) {
+    const { db, dispose } = resolveDbFactoryResult(dbFactory(env));
+    try {
+        const rows = await db
+            .delete(infraIdempotencyKeysTable)
+            .where(lt(infraIdempotencyKeysTable.expiresAt, new Date()))
+            .returning();
+        return { removed: rows.length };
+    }
+    finally {
+        if (dispose)
+            await dispose();
+    }
+}

package/dist/middleware/index.d.ts

@@ -0,0 +1,14 @@
+export { requireAuth } from "./auth.js";
+export { DEFAULT_REQUEST_BODY_LIMIT_BYTES, type RequestBodyLimitOptions, requestBodyLimit, } from "./body-size.js";
+export { cors } from "./cors.js";
+export { db } from "./db.js";
+export { errorBoundary, handleApiError, requestId } from "./error-boundary.js";
+export { DEFAULT_IDEMPOTENCY_TTL_MS, type IdempotencyKeyOptions, idempotencyKey, purgeExpiredIdempotencyKeys, } from "./idempotency-key.js";
+export { consoleLoggerProvider, logger } from "./logger.js";
+export { type AnalyticsEngineDatasetLike, DB_METRICS_CONTEXT_KEY, type MetricsMiddlewareOptions, metrics, type RequestDbMetrics, withQueryCounting, } from "./metrics.js";
+export { type PublicCacheOptions, publicResponseCache, resetPublicCacheStateForTests, } from "./public-cache.js";
+export { type CloudflareRateLimiterBinding, clientIpKey, createCloudflareRateLimitStore, createKvRateLimitStore, createMemoryRateLimitStore, enforceRateLimit, LIVE_LIMITS, type RateLimitConfig, type RateLimitPolicy, type RateLimitRequestContext, type RateLimitResult, type RateLimitRule, type RateLimitStore, rateLimit, resolveRateLimitStore, } from "./rate-limit.js";
+export { requireActor } from "./require-actor.js";
+export { requirePermission } from "./require-permission.js";
+export { type SecurityHeadersOptions, securityHeaders } from "./security-headers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EACL,gCAAgC,EAChC,KAAK,uBAAuB,EAC5B,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EACL,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,cAAc,EACd,2BAA2B,GAC5B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EACL,KAAK,0BAA0B,EAC/B,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,OAAO,EACP,KAAK,gBAAgB,EACrB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,4BAA4B,EACjC,WAAW,EACX,8BAA8B,EAC9B,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,SAAS,EACT,qBAAqB,GACtB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/middleware/index.js

@@ -0,0 +1,13 @@
+export { requireAuth } from "./auth.js";
+export { DEFAULT_REQUEST_BODY_LIMIT_BYTES, requestBodyLimit, } from "./body-size.js";
+export { cors } from "./cors.js";
+export { db } from "./db.js";
+export { errorBoundary, handleApiError, requestId } from "./error-boundary.js";
+export { DEFAULT_IDEMPOTENCY_TTL_MS, idempotencyKey, purgeExpiredIdempotencyKeys, } from "./idempotency-key.js";
+export { consoleLoggerProvider, logger } from "./logger.js";
+export { DB_METRICS_CONTEXT_KEY, metrics, withQueryCounting, } from "./metrics.js";
+export { publicResponseCache, resetPublicCacheStateForTests, } from "./public-cache.js";
+export { clientIpKey, createCloudflareRateLimitStore, createKvRateLimitStore, createMemoryRateLimitStore, enforceRateLimit, LIVE_LIMITS, rateLimit, resolveRateLimitStore, } from "./rate-limit.js";
+export { requireActor } from "./require-actor.js";
+export { requirePermission } from "./require-permission.js";
+export { securityHeaders } from "./security-headers.js";

package/dist/middleware/logger.d.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareHandler } from "hono";
+import type { LoggerProvider } from "../types.js";
+export declare const consoleLoggerProvider: LoggerProvider;
+export declare function logger(provider?: LoggerProvider): MiddlewareHandler;
+//# sourceMappingURL=logger.d.ts.map

package/dist/middleware/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/middleware/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,qBAAqB,EAAE,cAInC,CAAA;AAUD,wBAAgB,MAAM,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,iBAAiB,CAanE"}

package/dist/middleware/logger.js

@@ -0,0 +1,27 @@
+export const consoleLoggerProvider = {
+    log(entry) {
+        console.log(`${entry.method} ${entry.path} → ${entry.status} (${entry.durationMs}ms)`);
+    },
+};
+function logPath(c) {
+    const routePath = c.req.routePath;
+    if (routePath && routePath !== "/*")
+        return routePath;
+    return c.req.path
+        .replace(/(\/accountant\/)[^/]+/g, "$1[token]")
+        .replace(/(\/download\/)[^/]+/g, "$1[token]");
+}
+export function logger(provider) {
+    const log = provider ?? consoleLoggerProvider;
+    return async (c, next) => {
+        const start = Date.now();
+        await next();
+        const durationMs = Date.now() - start;
+        log.log({
+            method: c.req.method,
+            path: logPath(c),
+            status: c.res.status,
+            durationMs,
+        });
+    };
+}

package/dist/middleware/metrics.d.ts

@@ -0,0 +1,55 @@
+import type { MiddlewareHandler } from "hono";
+import type { VoyantVariables } from "../types.js";
+/**
+ * Structural shape of a Workers Analytics Engine dataset binding —
+ * declared locally so `@voyant-travel/hono` needs no `@cloudflare/workers-types`
+ * dependency.
+ */
+export interface AnalyticsEngineDatasetLike {
+    writeDataPoint(point: {
+        blobs?: string[];
+        doubles?: number[];
+        indexes?: string[];
+    }): void;
+}
+/** Per-request db-query counter, populated by the db middleware. */
+export interface RequestDbMetrics {
+    queries: number;
+}
+export declare const DB_METRICS_CONTEXT_KEY = "__voyantDbMetrics";
+export interface MetricsMiddlewareOptions {
+    /**
+     * Resolve the Analytics Engine dataset from bindings. Defaults to
+     * `env.METRICS`. Returning undefined makes the middleware a no-op for
+     * that request (deployments without the binding pay ~nothing).
+     */
+    dataset?: (env: unknown) => AnalyticsEngineDatasetLike | undefined;
+}
+/**
+ * Per-request metrics → Workers Analytics Engine (RFC voyant#1687 Phase
+ * 3.4, the in-worker half — the platform dispatcher's DISPATCH_METRICS
+ * dataset already records hostname/plan/cache/duration per dispatch;
+ * this adds what only the worker can see: the matched route pattern,
+ * the db query count, and in-worker cache hits).
+ *
+ * One data point per request:
+ * - blobs:   [method, routePattern, surface, cacheStatus]
+ * - doubles: [durationMs, status, dbQueryCount]
+ * - indexes: [routePattern]  (AE sampling key — per-route analysis)
+ *
+ * `writeDataPoint` is fire-and-forget and never throws into the
+ * request; a missing binding short-circuits before timing overhead.
+ */
+export declare function metrics(options?: MetricsMiddlewareOptions): MiddlewareHandler<{
+    Variables: Pick<VoyantVariables, typeof DB_METRICS_CONTEXT_KEY>;
+}>;
+/**
+ * Wrap a drizzle client so top-level query-initiating calls increment
+ * the request counter. Counts `select/insert/update/delete/execute/
+ * transaction/query` invocations — a transaction counts as ONE (its
+ * inner statements run on the tx handle, which is not wrapped). An
+ * approximation by design: the goal is spotting N+1 routes and
+ * subrequest-budget pressure, not exact accounting.
+ */
+export declare function withQueryCounting<TDb extends object>(db: TDb, counter: RequestDbMetrics): TDb;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/middleware/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/middleware/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,cAAc,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAA;CAC1F;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,eAAO,MAAM,sBAAsB,sBAAsB,CAAA;AAEzD,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,0BAA0B,GAAG,SAAS,CAAA;CACnE;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,wBAA6B,GAAG,iBAAiB,CAAC;IACjF,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,sBAAsB,CAAC,CAAA;CAChE,CAAC,CAiCD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,GAAG,GAAG,CA4B7F"}

package/dist/middleware/metrics.js

@@ -0,0 +1,94 @@
+export const DB_METRICS_CONTEXT_KEY = "__voyantDbMetrics";
+function surfaceOf(path) {
+    if (path.startsWith("/v1/admin/"))
+        return "admin";
+    if (path.startsWith("/v1/public/"))
+        return "public";
+    if (path.startsWith("/v1/"))
+        return "legacy";
+    return "other";
+}
+/**
+ * Per-request metrics → Workers Analytics Engine (RFC voyant#1687 Phase
+ * 3.4, the in-worker half — the platform dispatcher's DISPATCH_METRICS
+ * dataset already records hostname/plan/cache/duration per dispatch;
+ * this adds what only the worker can see: the matched route pattern,
+ * the db query count, and in-worker cache hits).
+ *
+ * One data point per request:
+ * - blobs:   [method, routePattern, surface, cacheStatus]
+ * - doubles: [durationMs, status, dbQueryCount]
+ * - indexes: [routePattern]  (AE sampling key — per-route analysis)
+ *
+ * `writeDataPoint` is fire-and-forget and never throws into the
+ * request; a missing binding short-circuits before timing overhead.
+ */
+export function metrics(options = {}) {
+    const resolveDataset = options.dataset ??
+        ((env) => env?.METRICS);
+    return async (c, next) => {
+        const dataset = resolveDataset(c.env);
+        if (!dataset || typeof dataset.writeDataPoint !== "function") {
+            return next();
+        }
+        const counter = { queries: 0 };
+        c.set(DB_METRICS_CONTEXT_KEY, counter);
+        const start = Date.now();
+        try {
+            await next();
+        }
+        finally {
+            const durationMs = Date.now() - start;
+            const routePattern = c.req.routePath ?? c.req.path;
+            const status = c.res?.status ?? 0;
+            const cacheStatus = c.res?.headers.get("x-voyant-cache") ?? "";
+            try {
+                dataset.writeDataPoint({
+                    blobs: [c.req.method, routePattern, surfaceOf(c.req.path), cacheStatus],
+                    doubles: [durationMs, status, counter.queries],
+                    indexes: [routePattern.slice(0, 96)],
+                });
+            }
+            catch {
+                // metrics are observability, never a request failure
+            }
+        }
+    };
+}
+/**
+ * Wrap a drizzle client so top-level query-initiating calls increment
+ * the request counter. Counts `select/insert/update/delete/execute/
+ * transaction/query` invocations — a transaction counts as ONE (its
+ * inner statements run on the tx handle, which is not wrapped). An
+ * approximation by design: the goal is spotting N+1 routes and
+ * subrequest-budget pressure, not exact accounting.
+ */
+export function withQueryCounting(db, counter) {
+    const counted = new Set([
+        "select",
+        "selectDistinct",
+        "insert",
+        "update",
+        "delete",
+        "execute",
+        "transaction",
+        "query",
+    ]);
+    return new Proxy(db, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value === "function" && typeof prop === "string" && counted.has(prop)) {
+                return (...args) => {
+                    counter.queries += 1;
+                    return value.apply(target, args);
+                };
+            }
+            if (typeof value === "function") {
+                // Preserve `this` for drizzle internals (incl. #private fields).
+                return value.bind(target);
+            }
+            void receiver;
+            return value;
+        },
+    });
+}

package/dist/middleware/public-cache.d.ts

@@ -0,0 +1,44 @@
+import type { MiddlewareHandler } from "hono";
+import type { VoyantBindings } from "../types.js";
+/**
+ * Options for {@link publicResponseCache}.
+ */
+export interface PublicCacheOptions {
+    /**
+     * Path prefixes eligible for caching. Defaults to the public API
+     * surface only — admin and legacy surfaces are never cached.
+     */
+    pathPrefixes?: string[];
+    /**
+     * Responses larger than this (in bytes, after text decoding) are not
+     * stored in the KV fallback. Protects isolate memory and KV value
+     * limits. Default 2 MiB. The Cache API path streams and is not
+     * subject to this guard.
+     */
+    maxKvBodyBytes?: number;
+}
+/** Test hook — resets the memoized Cache API probe state. */
+export declare function resetPublicCacheStateForTests(): void;
+/**
+ * Shared response cache for the public API surface.
+ *
+ * Fail-closed by design: a response is only ever cached when the route
+ * explicitly marked it shareable — `Cache-Control` containing `public`
+ * AND a positive `s-maxage` — and it carries no `Set-Cookie`. Routes
+ * emit `private`/`no-store` (or nothing) to opt out, so personalized
+ * endpoints under `/v1/public/*` (customer portal, verification) are
+ * never cached by accident.
+ *
+ * Cache hits are served before auth, the DB middleware, and the runtime
+ * bootstrap — a hit costs no Postgres connection, no session lookup,
+ * and no module-graph instantiation, which is the entire point under
+ * storefront load (#1686).
+ *
+ * Backend selection: Cache API (`caches.default`) where the runtime
+ * provides it; otherwise the `env.CACHE` KV binding when present;
+ * otherwise the middleware is a transparent no-op.
+ */
+export declare function publicResponseCache<TBindings extends VoyantBindings>(options?: PublicCacheOptions): MiddlewareHandler<{
+    Bindings: TBindings;
+}>;
+//# sourceMappingURL=public-cache.d.ts.map

package/dist/middleware/public-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-cache.d.ts","sourceRoot":"","sources":["../../src/middleware/public-cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAG7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AA6ED,6DAA6D;AAC7D,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AA0DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,SAAS,cAAc,EAClE,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,CAsE5C"}