@shelbyb/daywalker-sdk 0.3.0 → 0.4.0

package/dist/flags/engine/operators.js

@@ -1,12 +1,43 @@
+import { RE2JS } from "re2js";
 import { compareSemVer, parseSemVer } from "./semver.js";
-const regexCache = new Map();
-/** `matches` limits: longer inputs or patterns never match. */
+/** `matches` limits: longer inputs or patterns never match (same limits as the DevPulse server). */
 export const MAX_MATCH_INPUT_LENGTH = 1024;
 export const MAX_MATCH_PATTERN_LENGTH = 500;
-let warnedUnsafePattern = false;
+/** Server-parity aliases (`@devpulse/flag-engine` names). */
+export const MAX_PATTERN_LENGTH = MAX_MATCH_PATTERN_LENGTH;
+export const MAX_MATCH_INPUT = MAX_MATCH_INPUT_LENGTH;
+const regexCache = new Map();
+/**
+ * Compile a user-supplied pattern with RE2 (linear-time matching, no backtracking), so no
+ * pattern can stall the process however it's written (ReDoS), and every SDK agrees with the
+ * DevPulse server on what matches. RE2 has no backreferences or lookaround; patterns using
+ * them don't compile and return null (never match).
+ */
+export function compilePattern(pattern) {
+    if (!regexCache.has(pattern)) {
+        let re = null;
+        if (pattern.length <= MAX_MATCH_PATTERN_LENGTH) {
+            try {
+                re = RE2JS.compile(pattern);
+            }
+            catch {
+                re = null;
+            }
+        }
+        if (regexCache.size > 1000)
+            regexCache.clear();
+        regexCache.set(pattern, re);
+    }
+    return regexCache.get(pattern);
+}
+/** Whether a `matches` pattern is accepted: bounded length and valid RE2 syntax. */
+export function isSafePattern(pattern) {
+    return compilePattern(pattern) !== null;
+}
 /**
- * Conservative ReDoS heuristic: a group that contains a quantifier or alternation and is itself
- * repeated (`(a+)+`, `(a*)*`, `(a|aa)+`, `(?:x+y)*`, `(a+){2,}`). Character classes and escapes are skipped.
+ * @deprecated No longer used: `matches` runs on RE2, which is immune to ReDoS. Kept for
+ * backwards compatibility. Conservative heuristic for a group that contains a quantifier or
+ * alternation and is itself repeated (`(a+)+`, `(a|aa)+`, `(a+){2,}`).
  */
 export function hasNestedQuantifier(pattern) {
     const stack = []; // per open group: contains a quantifier / alternation
@@ -40,29 +71,6 @@ export function hasNestedQuantifier(pattern) {
     }
     return false;
 }
-function regex(pattern) {
-    if (!regexCache.has(pattern)) {
-        let re = null;
-        if (pattern.length > MAX_MATCH_PATTERN_LENGTH || hasNestedQuantifier(pattern)) {
-            if (!warnedUnsafePattern) {
-                warnedUnsafePattern = true;
-                console.warn("DevPulse: a `matches` pattern was too long or had nested quantifiers and is treated as no match");
-            }
-        }
-        else {
-            try {
-                re = new RegExp(pattern);
-            }
-            catch {
-                re = null;
-            }
-        }
-        if (regexCache.size > 1000)
-            regexCache.clear();
-        regexCache.set(pattern, re);
-    }
-    return regexCache.get(pattern);
-}
 /** RFC 3339 timestamp or Unix milliseconds → epoch ms. */
 export function parseTime(v) {
     if (typeof v === "number" && Number.isFinite(v))
@@ -97,11 +105,9 @@ export function applyOperator(op, actual, expected) {
         case "contains":
             return typeof actual === "string" && typeof expected === "string" && actual.includes(expected);
         case "matches": {
-            if (typeof actual !== "string" || typeof expected !== "string")
-                return false;
-            if (actual.length > MAX_MATCH_INPUT_LENGTH)
+            if (typeof actual !== "string" || typeof expected !== "string" || actual.length > MAX_MATCH_INPUT_LENGTH)
                 return false;
-            return regex(expected)?.test(actual) ?? false;
+            return compilePattern(expected)?.test(actual) ?? false;
         }
         case "lessThan":
         case "lessThanOrEqual":

package/dist/flags/node.d.ts

@@ -1,7 +1,9 @@
 import { EventEmitter } from "node:events";
 import { type ContextInput, type EvaluationDetail, type FlagConfig, type FlagValue, type SegmentConfig } from "./engine/index.js";
-import { type Logger } from "./common/index.js";
-export type { ContextInput, EvaluationDetail, FlagValue, Logger };
+import { SDK_VERSION, type Logger } from "./common/index.js";
+import type { FlagSet } from "./client.js";
+export type { ContextInput, EvaluationDetail, FlagSet, FlagValue, Logger };
+export { SDK_VERSION };
 export interface NodeClientOptions {
     /** Base URL of your DevPulse deployment (https required except on localhost). */
     baseUrl: string;
@@ -26,17 +28,24 @@ export interface NodeClientOptions {
 export interface AllFlagsState {
     valid: boolean;
     values: Record<string, FlagValue>;
-    /** Pass to the browser SDK's `bootstrap` option for flicker-free SSR. */
-    toJSON(): Record<string, {
-        value: FlagValue;
-        variation: number | null;
-        version: number;
-        reason?: unknown;
-    }>;
+    /** Pass to the browser SDK's `bootstrap` option for flicker-free SSR (same shape as the client endpoint). */
+    toJSON(): FlagSet;
+}
+export interface AllFlagsStateOptions {
+    /**
+     * Only flags marked "available to client-side SDKs" (default true), so the result is safe to
+     * embed in HTML. Pass false to include every flag, e.g. for server-side use only.
+     */
+    clientSideOnly?: boolean;
+    /** Include evaluation reasons (always included for experiments). */
+    withReasons?: boolean;
 }
 /**
  * Server-side client. One instance per process and SDK key.
  *
+ * Events: "ready", "failed" (fatal, e.g. an invalid SDK key), "update" / "update:<key>",
+ * "stale" (connection lost; the last data keeps serving) and "recovered".
+ *
  *   const client = init(process.env.DEVPULSE_SDK_KEY!, { baseUrl });
  *   await client.waitForInitialization({ timeoutMs: 5000 });
  *   const enabled = await client.variation("new-checkout", { key: user.id, email: user.email }, false);
@@ -54,6 +63,7 @@ export declare class DevPulseNodeClient extends EventEmitter {
     private resolveReady;
     private rejectReady;
     private streamFailures;
+    private stale;
     private readonly logger;
     private readonly base;
     constructor(sdkKey: string, options: NodeClientOptions);
@@ -65,6 +75,8 @@ export declare class DevPulseNodeClient extends EventEmitter {
     private applyPut;
     private emitUpdate;
     private markReady;
+    /** "stale" when updates stop arriving (flags keep serving the last data), "recovered" when they resume. */
+    private setStale;
     private fail;
     waitForInitialization(opts?: {
         timeoutMs?: number;
@@ -80,13 +92,13 @@ export declare class DevPulseNodeClient extends EventEmitter {
     numberVariation(key: string, context: ContextInput, defaultValue: number): Promise<number>;
     jsonVariation<T extends FlagValue>(key: string, context: ContextInput, defaultValue: T): Promise<T>;
     /**
-     * Evaluate every flag for a context, e.g. to bootstrap a browser client
+     * Evaluate every client-side flag for a context, e.g. to bootstrap a browser client
      * during server rendering. Doesn't record analytics.
+     *
+     *   const state = await client.allFlagsState(context);
+     *   createClient(id, context, { baseUrl, bootstrap: state.toJSON() });
      */
-    allFlagsState(context: ContextInput, opts?: {
-        clientSideOnly?: boolean;
-        withReasons?: boolean;
-    }): Promise<AllFlagsState>;
+    allFlagsState(context: ContextInput, opts?: AllFlagsStateOptions): Promise<AllFlagsState>;
     /** Secure mode hash for a context, for the browser SDK's `hash` option. */
     secureModeHash(context: ContextInput): string;
     track(key: string, context: ContextInput, data?: unknown, metricValue?: number): void;

package/dist/flags/node.js

@@ -1,11 +1,15 @@
 import { createHmac } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { Evaluator, MemoryStore, evaluateFlag, parseContext } from "./engine/index.js";
-import { EventProcessor, SseClient, noopLogger } from "./common/index.js";
+import { EventProcessor, SDK_VERSION, SseClient, noopLogger } from "./common/index.js";
 import { assertSecureUrl } from "../config.js";
+export { SDK_VERSION };
 /**
  * Server-side client. One instance per process and SDK key.
  *
+ * Events: "ready", "failed" (fatal, e.g. an invalid SDK key), "update" / "update:<key>",
+ * "stale" (connection lost; the last data keeps serving) and "recovered".
+ *
  *   const client = init(process.env.DEVPULSE_SDK_KEY!, { baseUrl });
  *   await client.waitForInitialization({ timeoutMs: 5000 });
  *   const enabled = await client.variation("new-checkout", { key: user.id, email: user.email }, false);
@@ -23,6 +27,7 @@ export class DevPulseNodeClient extends EventEmitter {
     resolveReady;
     rejectReady;
     streamFailures = 0;
+    stale = false;
     logger;
     base;
     constructor(sdkKey, options) {
@@ -61,16 +66,20 @@ export class DevPulseNodeClient extends EventEmitter {
             this.startStreaming();
     }
     headers() {
-        return { authorization: this.sdkKey, "user-agent": "DevPulseNode/0.1.0" };
+        return { authorization: this.sdkKey, "user-agent": `DevPulseNode/${SDK_VERSION}` };
     }
     startStreaming() {
         this.stream = new SseClient({
             url: `${this.base}/sdk/v1/server/stream`,
             headers: () => this.headers(),
             fetch: this.options.fetch,
+            browser: false,
+            // Full rulesets (segments with big target lists) can be large.
+            maxEventSize: 64 * 1024 * 1024,
             onOpen: () => {
                 this.streamFailures = 0;
                 this.stopPolling();
+                this.setStale(false);
             },
             onEvent: (ev) => this.onStreamEvent(ev.type, ev.data),
             onError: (err) => {
@@ -79,6 +88,9 @@ export class DevPulseNodeClient extends EventEmitter {
                     this.fail(new Error("Invalid SDK key"));
                     return false;
                 }
+                // While polling, the poll result decides whether data is stale.
+                if (!this.poller)
+                    this.setStale(true, err);
                 // After repeated failures, poll so data stays fresh while we keep retrying the stream.
                 if (++this.streamFailures >= 3)
                     this.startPolling();
@@ -94,17 +106,21 @@ export class DevPulseNodeClient extends EventEmitter {
         const poll = async () => {
             try {
                 const res = await (this.options.fetch ?? fetch)(`${this.base}/sdk/v1/server/flags`, { headers: { ...this.headers(), ...(this.etag ? { "if-none-match": this.etag } : {}) } });
-                if (res.status === 304)
+                if (res.status === 304) {
+                    this.setStale(false);
                     return this.markReady();
+                }
                 if (res.status === 401 || res.status === 403)
                     return this.fail(new Error("Invalid SDK key"));
                 if (!res.ok)
                     throw new Error(`Poll failed with ${res.status}`);
                 this.etag = res.headers.get("etag");
                 this.applyPut((await res.json()));
+                this.setStale(false);
             }
             catch (err) {
                 this.logger.warn("DevPulse poll failed", err);
+                this.setStale(true, err);
             }
         };
         this.poller = setInterval(poll, interval);
@@ -163,6 +179,16 @@ export class DevPulseNodeClient extends EventEmitter {
         this.resolveReady();
         this.emit("ready");
     }
+    /** "stale" when updates stop arriving (flags keep serving the last data), "recovered" when they resume. */
+    setStale(stale, err) {
+        if (!this.initialized || this.stale === stale)
+            return;
+        this.stale = stale;
+        if (stale)
+            this.emit("stale", err);
+        else
+            this.emit("recovered");
+    }
     fail(err) {
         if (!this.initialized)
             this.rejectReady(err);
@@ -173,7 +199,12 @@ export class DevPulseNodeClient extends EventEmitter {
         const ready = this.ready.then(() => this);
         if (!opts.timeoutMs)
             return ready;
-        return Promise.race([ready, new Promise((_, rej) => setTimeout(() => rej(new Error("DevPulse initialization timed out")), opts.timeoutMs).unref?.())]);
+        let timer;
+        const timeout = new Promise((_, rej) => {
+            // Not unref'd: someone is awaiting it. Cleared as soon as either side settles.
+            timer = setTimeout(() => rej(new Error("DevPulse initialization timed out")), opts.timeoutMs);
+        });
+        return Promise.race([ready, timeout]).finally(() => clearTimeout(timer));
     }
     get isInitialized() {
         return this.initialized;
@@ -217,10 +248,14 @@ export class DevPulseNodeClient extends EventEmitter {
         return this.variation(key, context, defaultValue);
     }
     /**
-     * Evaluate every flag for a context, e.g. to bootstrap a browser client
+     * Evaluate every client-side flag for a context, e.g. to bootstrap a browser client
      * during server rendering. Doesn't record analytics.
+     *
+     *   const state = await client.allFlagsState(context);
+     *   createClient(id, context, { baseUrl, bootstrap: state.toJSON() });
      */
     async allFlagsState(context, opts = {}) {
+        const clientSideOnly = opts.clientSideOnly ?? true;
         let ctx;
         try {
             ctx = parseContext(context);
@@ -231,10 +266,19 @@ export class DevPulseNodeClient extends EventEmitter {
         const evaluator = new Evaluator(this.store);
         const state = {};
         for (const f of this.store.flags.values()) {
-            if (opts.clientSideOnly && !f.clientSide)
+            if (f.deleted || (clientSideOnly && !f.clientSide))
                 continue;
             const { detail } = evaluator.evaluate(f, ctx);
-            state[f.key] = { value: detail.value, variation: detail.variationIndex, version: f.version, ...(opts.withReasons ? { reason: detail.reason } : {}) };
+            // Same shape as the DevPulse client endpoint, so client-side analytics and experiments keep working.
+            const inExperiment = "inExperiment" in detail.reason && !!detail.reason.inExperiment;
+            state[f.key] = {
+                value: detail.value,
+                variation: detail.variationIndex,
+                version: f.version,
+                ...(opts.withReasons || inExperiment ? { reason: detail.reason } : {}),
+                ...(f.trackEvents || inExperiment ? { trackEvents: true } : {}),
+                ...(inExperiment ? { trackReason: true } : {}),
+            };
         }
         return { valid: this.initialized, values: Object.fromEntries(Object.entries(state).map(([k, v]) => [k, v.value])), toJSON: () => state };
     }

package/dist/flags/react.d.ts

@@ -10,9 +10,11 @@ export interface DevPulseProviderProps {
     children: ReactNode;
 }
 /**
- * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming)
- * no network connection is opened; flags come from `options.bootstrap`, so the
- * first client render matches the server HTML. Changing `context` calls identify().
+ * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming) and during the
+ * first client render, an offline client serves `options.bootstrap` and makes no requests, so
+ * hydration matches the server HTML. The live client is created (and closed) in an effect,
+ * which keeps StrictMode's simulated unmount from leaving a closed client behind. Changing
+ * `context` calls identify().
  */
 export declare function DevPulseProvider({ clientSideId, context, options, client: external, children }: DevPulseProviderProps): import("react").JSX.Element;
 export declare function useDevPulseClient(): DevPulseClient;
@@ -23,5 +25,5 @@ export declare function useFlagDetail<T extends FlagValue>(key: string, defaultV
 export declare function useFlags(): Record<string, FlagValue>;
 /** True once flags have loaded (always true when bootstrapped). */
 export declare function useFlagsReady(): boolean;
-/** Track a custom event for metrics and experiments. */
+/** Track a custom event for metrics and experiments. Stable across renders (safe in effect deps). */
 export declare function useTrack(): (key: string, data?: unknown, metricValue?: number) => void;

package/dist/flags/react.js

@@ -1,26 +1,47 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { createClient } from "./client.js";
 const ClientContext = createContext(null);
 const isBrowser = typeof window !== "undefined";
 /**
- * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming)
- * no network connection is opened; flags come from `options.bootstrap`, so the
- * first client render matches the server HTML. Changing `context` calls identify().
+ * Provides a DevPulse client to the tree. On the server (SSR/RSC streaming) and during the
+ * first client render, an offline client serves `options.bootstrap` and makes no requests, so
+ * hydration matches the server HTML. The live client is created (and closed) in an effect,
+ * which keeps StrictMode's simulated unmount from leaving a closed client behind. Changing
+ * `context` calls identify().
  */
 export function DevPulseProvider({ clientSideId, context, options, client: external, children }) {
-    const [client] = useState(() => external ?? createClient(clientSideId, context, isBrowser ? options : { ...options, streaming: false, sendEvents: false, bootstrap: options.bootstrap ?? {} }));
     const contextJson = JSON.stringify(context);
-    const first = useRef(true);
+    // Render-time stand-in: no network, timers or listeners, so creating it during render is safe.
+    // No localStorage cache either, so the first client render matches the server HTML.
+    const [placeholder] = useState(() => createClient(clientSideId, context, { ...options, offline: true, sendEvents: false, cache: false }));
+    const [owned, setOwned] = useState(null);
+    const latest = useRef({ contextJson, options });
+    latest.current = { contextJson, options };
     useEffect(() => {
-        if (first.current) {
-            first.current = false;
+        if (external || !isBrowser)
             return;
-        }
-        void client.identify(JSON.parse(contextJson));
-    }, [client, contextJson]);
-    useEffect(() => () => void (!external && client.close()), [client, external]);
-    return _jsx(ClientContext.Provider, { value: client, children: children });
+        const c = createClient(clientSideId, JSON.parse(latest.current.contextJson), latest.current.options);
+        setOwned(c);
+        return () => {
+            void c.close();
+            setOwned((cur) => (cur === c ? null : cur));
+        };
+    }, [external, clientSideId]);
+    const live = external ?? owned;
+    const seen = useRef({ client: null, contextJson });
+    useEffect(() => {
+        if (!live || live.isClosed)
+            return;
+        const prev = seen.current;
+        seen.current = { client: live, contextJson };
+        // A client we just created already has the current context; an injected one is taken as is.
+        const changed = prev.client === live ? prev.contextJson !== contextJson : live === owned && JSON.stringify(live.getContext()) !== contextJson;
+        if (changed)
+            void live.identify(JSON.parse(contextJson)).catch(() => undefined);
+    }, [live, owned, contextJson]);
+    return _jsx(ClientContext.Provider, { value: live ?? placeholder, children: children });
 }
 export function useDevPulseClient() {
     const client = useContext(ClientContext);
@@ -39,8 +60,17 @@ export function useFlagDetail(key, defaultValue) {
     // Snapshot is the serialized value so useSyncExternalStore sees stable identities.
     const snapshot = () => JSON.stringify(client.allFlags()[key] ?? null);
     const serialized = useSyncExternalStore(subscribe, snapshot, snapshot);
-    // Record the evaluation (analytics) once per distinct value.
-    return useMemo(() => client.variationDetail(key, JSON.parse(defaultJson)), [client, key, defaultJson, serialized]); // eslint-disable-line react-hooks/exhaustive-deps
+    const detail = useMemo(() => client.peekVariationDetail(key, JSON.parse(defaultJson)), [client, key, defaultJson, serialized]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Record the evaluation (analytics) after commit, once per distinct result: renders can be
+    // repeated or thrown away (StrictMode, concurrent rendering), effects re-run in StrictMode.
+    const recorded = useRef(null);
+    useEffect(() => {
+        if (recorded.current === detail)
+            return;
+        recorded.current = detail;
+        client.recordEvaluation(key, JSON.parse(defaultJson), detail);
+    }, [client, key, defaultJson, detail]);
+    return detail;
 }
 /** All flag values; re-renders when any flag changes. */
 export function useFlags() {
@@ -55,8 +85,8 @@ export function useFlagsReady() {
     const subscribe = useMemo(() => (cb) => client.on("ready", cb), [client]);
     return useSyncExternalStore(subscribe, () => client.isInitialized, () => client.isInitialized);
 }
-/** Track a custom event for metrics and experiments. */
+/** Track a custom event for metrics and experiments. Stable across renders (safe in effect deps). */
 export function useTrack() {
     const client = useDevPulseClient();
-    return (key, data, metricValue) => client.track(key, data, metricValue);
+    return useCallback((key, data, metricValue) => client.track(key, data, metricValue), [client]);
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { Daywalker, createDaywalker, daywalker, } from "./client.js";
-export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, } from "./types.js";
-export type { DaywalkerConfig, RateLimitWindow, TokenPayload, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, PublicJwk, SigningKey, } from "./types.js";
-export { resolveConfig, publicHostname, assertSecureUrl, } from "./config.js";
+export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATION_CACHE_ENTRIES, } from "./client.js";
+export type { DaywalkerFetchInit, } from "./client.js";
+export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
+export type { DaywalkerConfig, RateLimitWindow, TokenPayload, ValidateErrorCode, ValidateResult, RetryOptions, SelfCheckResult, PublicJwk, PublicJwks, SigningKey, } from "./types.js";
+export { resolveConfig, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
 export type { ResolvedConfig, } from "./config.js";
-export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
-export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, } from "./crypto/index.js";
+export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
+export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, ReplayStore, } from "./crypto/index.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Daywalker, createDaywalker, daywalker, } from "./client.js";
-export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, } from "./types.js";
-export { resolveConfig, publicHostname, assertSecureUrl, } from "./config.js";
-export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";
+export { Daywalker, createDaywalker, daywalker, MAX_RETRY_AFTER_MS, MAX_VALIDATION_CACHE_ENTRIES, } from "./client.js";
+export { DaywalkerError, DaywalkerAuthError, DaywalkerRateLimitError, UNAVAILABLE_ERROR_CODES, } from "./types.js";
+export { resolveConfig, publicHostname, assertSecureUrl, DEFAULT_TIMEOUT_MS, } from "./config.js";
+export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, computeContentDigest, sha256Base64, sha256Base64Url, calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, maskSecret, redactSecrets, } from "./crypto/index.js";

package/dist/middleware.d.ts

@@ -1,4 +1,22 @@
 import { Daywalker } from "./client.js";
+import type { ValidateResult } from "./types.js";
+type ValidateFailure = Extract<ValidateResult, {
+    ok: false;
+}>;
+export interface AuthFailureResponse {
+    /** 401 bad/expired/missing token, 429 rate limited, 500 server misconfiguration, 503 auth service unavailable. */
+    status: 401 | 429 | 500 | 503;
+    error: string;
+    message: string;
+    retryAfter?: number;
+}
+/**
+ * Maps a failed validation to the HTTP status an adapter should answer with. Outages (5xx,
+ * network errors, SERVICE_UNAVAILABLE) become 503 rather than 401 so clients retry instead of
+ * discarding a valid token; configuration errors become a 500 without their (internal) details.
+ * Shared by the Next, Web/Hono and Express adapters.
+ */
+export declare function toAuthFailureResponse(result: ValidateFailure): AuthFailureResponse;
 export interface DaywalkerMiddlewareOptions {
     client?: Daywalker;
     serviceSlug?: string;

package/dist/middleware.js

@@ -1,4 +1,30 @@
 import { daywalker } from "./client.js";
+/** Error codes that mean Daywalker Auth itself could not be reached or is degraded. */
+const UNAVAILABLE_ERROR_CODES = new Set(["NETWORK_ERROR", "SERVICE_UNAVAILABLE"]);
+/**
+ * Maps a failed validation to the HTTP status an adapter should answer with. Outages (5xx,
+ * network errors, SERVICE_UNAVAILABLE) become 503 rather than 401 so clients retry instead of
+ * discarding a valid token; configuration errors become a 500 without their (internal) details.
+ * Shared by the Next, Web/Hono and Express adapters.
+ */
+export function toAuthFailureResponse(result) {
+    const retryAfter = result.retryAfter && result.retryAfter > 0 ? result.retryAfter : undefined;
+    if (result.error === "CONFIGURATION_ERROR") {
+        return { status: 500, error: "CONFIGURATION_ERROR", message: "Authentication is not configured correctly on this server." };
+    }
+    if (result.status === 429 || result.error === "RATE_LIMITED") {
+        return { status: 429, error: "RATE_LIMITED", message: result.message || "Rate limit exceeded", retryAfter };
+    }
+    if (result.status >= 500 || result.status === 0 || UNAVAILABLE_ERROR_CODES.has(result.error)) {
+        return {
+            status: 503,
+            error: UNAVAILABLE_ERROR_CODES.has(result.error) ? result.error : "SERVICE_UNAVAILABLE",
+            message: "Daywalker Auth is temporarily unavailable. Please retry.",
+            retryAfter,
+        };
+    }
+    return { status: 401, error: result.error || "INVALID_TOKEN", message: result.message || "Unauthorized" };
+}
 /**
  * Standard Web / Hono compatible middleware.
  * Works with Hono, standard Web Request/Response routers, and middleware pipelines.
@@ -46,13 +72,8 @@ export function daywalkerAuth(options = {}) {
         }
         const result = await client.validateToken(token, { serviceSlug });
         if (!result.ok) {
-            const status = result.status === 429 ? 429 : 401;
-            const body = {
-                error: result.error,
-                message: result.message,
-                retryAfter: result.retryAfter,
-            };
-            const headers = result.retryAfter ? { "Retry-After": String(result.retryAfter) } : undefined;
+            const { status, ...body } = toAuthFailureResponse(result);
+            const headers = body.retryAfter ? { "Retry-After": String(body.retryAfter) } : undefined;
             if (typeof c?.json === "function") {
                 return c.json(body, status, headers);
             }

package/dist/next.d.ts

@@ -7,26 +7,55 @@ import type { TokenPayload } from "./types.js";
  */
 export declare const SERVER_ACTION_ID_PATTERN: RegExp;
 export declare const DEFAULT_BYPASS_PATHS: string[];
-/** File extensions treated as static assets (outside /api/) and passed through without auth. */
+/**
+ * A suggested value for the opt-in `staticFileExtensions` option. It is NOT applied by default:
+ * an extension says nothing about whether a route is public (`/users/123.js` can be a dynamic page).
+ * Prefer excluding public files with Next's `matcher` (see `createDaywalkerMiddleware`).
+ */
 export declare const STATIC_FILE_EXTENSIONS: RegExp;
 /**
- * Static assets that skip auth: Next's build output and image optimizer, the favicon, and files with
- * an allowlisted extension. `/_next/data/` (getServerSideProps JSON) and `/api/*` are never static.
+ * Decodes and normalizes a URL pathname the way a router sees it: percent-decoded once, `//`
+ * collapsed and `.`/`..` segments resolved. Returns null (never bypass auth) for malformed
+ * encoding, encoded slashes/backslashes, raw backslashes or control characters.
+ */
+export declare function normalizePathname(pathname: string): string | null;
+/**
+ * Static assets that skip auth: Next's build output (`/_next/static/`), image optimizer
+ * (`/_next/image`) and `/favicon.ico`. Files matching `staticFileExtensions` are included only when
+ * that list is passed explicitly. The path is decoded and normalized first; `/_next/data/`
+ * (getServerSideProps JSON) and `/api` / `/api/*` are never static.
  */
-export declare function isStaticAssetPath(pathname: string): boolean;
+export declare function isStaticAssetPath(pathname: string, staticFileExtensions?: RegExp | readonly string[]): boolean;
 export interface NextMiddlewareOptions {
     client?: Daywalker;
     serviceSlug?: string;
+    /**
+     * Public paths that skip auth (exact match or `path/` prefix, compared against the decoded,
+     * normalized pathname). Defaults to `DEFAULT_BYPASS_PATHS`. Prefer Next's `matcher` config to keep
+     * public routes from reaching the middleware at all.
+     */
     bypassPaths?: string[];
+    /**
+     * Opt-in: also skip auth for (non-`/api`, non-`/_next/`) paths ending in one of these extensions,
+     * e.g. `STATIC_FILE_EXTENSIONS` or `["png", "css"]`. Off by default, because a dynamic route such
+     * as `/users/[id]` also answers `/users/123.js`. Prefer a `matcher` that excludes `public/` files.
+     */
+    staticFileExtensions?: RegExp | readonly string[];
     errorPath?: string;
     homePath?: string;
+    /** Only enforce auth on `/api` and `/api/*`; other routes pass through. */
     protectApiOnly?: boolean;
     validateServerActions?: boolean;
+    /** When set, requests whose Host header is missing or not listed get a 403. */
     allowedHosts?: string[];
 }
+/** Options for the Next.js 16+ `proxy.ts` aliases (identical to `NextMiddlewareOptions`). */
+export type NextProxyOptions = NextMiddlewareOptions;
 /**
  * Sanitizes open redirect path parameter (`from`).
- * Prevents protocol-relative URLs (`//evil.com`), backslashes (`/\evil.com`), and control characters.
+ * Accepts only same-origin relative paths: rejects protocol-relative URLs (`//evil.com`), any
+ * backslash, whitespace or control character (browsers strip tabs/newlines, so `/\t/evil.com` would
+ * become `//evil.com`), and anything that resolves to another origin.
  */
 export declare function sanitizeRedirectPath(path: string): string | null;
 /**
@@ -38,14 +67,17 @@ export declare function sanitizeRedirectPath(path: string): string | null;
  * 3. Per-request token auth: requests without `Authorization: Bearer` / `x-api-token` get 401
  * 4. Distinct handling for API routes (JSON + CORS) vs UI pages (redirect to `errorPath` with `from`)
  *
+ * Only `/_next/static/`, `/_next/image`, `/favicon.ico` and `bypassPaths` skip auth by default.
+ * Exclude other public files with Next's `matcher` (recommended) or opt into `staticFileExtensions`.
+ *
  * Example:
- *   // middleware.ts
+ *   // middleware.ts (Next.js 16+: proxy.ts, `export const proxy = createDaywalkerProxy();`)
  *   import { createDaywalkerMiddleware } from "@shelbyb/daywalker-sdk/next";
  *
  *   export const middleware = createDaywalkerMiddleware();
  *
  *   export const config = {
- *     matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+ *     matcher: ["/((?!_next/static|_next/image|favicon.ico|images/).*)"],
  *   };
  */
 export declare function createDaywalkerMiddleware(options?: NextMiddlewareOptions): (request: Request) => Promise<Response>;
@@ -58,7 +90,8 @@ export declare function createDaywalkerServiceHealthMiddleware(options?: NextMid
 /**
  * Next.js App Router route handler wrapper with Daywalker token validation.
  * Extracts `Authorization: Bearer <token>` or `x-api-token`, validates via client,
- * returns 401/429 JSON response on error, or passes validated `auth` payload in context.
+ * returns a JSON error on failure (401 bad token, 429 rate limited, 503 Daywalker Auth unavailable,
+ * 500 misconfiguration), or passes validated `auth` payload in context.
  *
  * Example:
  *   // app/api/protected/route.ts
@@ -74,3 +107,14 @@ export declare function withDaywalkerAuth<Context extends Record<string, unknown
     client?: Daywalker;
     serviceSlug?: string;
 }): (req: Request, context?: Context) => Promise<Response>;
+/**
+ * Next.js 16 renamed `middleware.ts` to `proxy.ts` (export `proxy` instead of `middleware`).
+ * These aliases are identical to the `*Middleware` factories, which remain supported:
+ *
+ *   // proxy.ts
+ *   import { createDaywalkerProxy } from "@shelbyb/daywalker-sdk/next";
+ *   export const proxy = createDaywalkerProxy();
+ *   export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+ */
+export declare const createDaywalkerProxy: typeof createDaywalkerMiddleware;
+export declare const createDaywalkerServiceHealthProxy: typeof createDaywalkerServiceHealthMiddleware;