@shelbyb/daywalker-sdk 0.3.0 → 0.4.1

package/dist/openfeature/shared.d.ts

@@ -10,7 +10,7 @@ type Detail<T> = {
     reason: Reason;
 };
 /**
- * OpenFeature context → DevPulse context. `targetingKey` becomes the key;
+ * OpenFeature context → DevPulse context. Dates become ISO 8601 strings. `targetingKey` becomes the key;
  * `kind` selects the context kind (default "user"); multi-kind contexts pass through.
  */
 export declare function toDevPulseContext(ctx: EvaluationContext): Record<string, unknown>;

package/dist/openfeature/shared.js

@@ -1,10 +1,30 @@
 import { ErrorCode, StandardResolutionReasons } from "@openfeature/core";
 /**
- * OpenFeature context → DevPulse context. `targetingKey` becomes the key;
+ * OpenFeature context values may be Dates; DevPulse compares RFC 3339 strings (or epoch ms) for
+ * `before`/`after`, so Dates become ISO strings at any depth (invalid Dates are dropped).
+ */
+function toJsonValue(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? undefined : v.toISOString();
+    if (Array.isArray(v))
+        return v.map(toJsonValue);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const [k, x] of Object.entries(v)) {
+            const j = toJsonValue(x);
+            if (j !== undefined)
+                out[k] = j;
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * OpenFeature context → DevPulse context. Dates become ISO 8601 strings. `targetingKey` becomes the key;
  * `kind` selects the context kind (default "user"); multi-kind contexts pass through.
  */
 export function toDevPulseContext(ctx) {
-    const { targetingKey, ...rest } = ctx;
+    const { targetingKey, ...rest } = toJsonValue(ctx);
     if (rest.kind === "multi")
         return rest;
     return { ...rest, kind: typeof rest.kind === "string" ? rest.kind : "user", key: targetingKey ?? rest.key };

package/dist/openfeature/web.js

@@ -20,9 +20,15 @@ export class DevPulseWebProvider {
         this.options = options;
     }
     async initialize(context) {
-        this.client = createClient(this.clientSideId, toDevPulseContext(context ?? {}), { ...this.options, withReasons: true });
-        this.client.on("change", (changes) => this.events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged: Object.keys(changes) }));
-        await this.client.waitForInitialization();
+        void this.client?.close(); // re-initialized: don't leak the previous client
+        const client = createClient(this.clientSideId, toDevPulseContext(context ?? {}), { ...this.options, withReasons: true });
+        this.client = client;
+        client.on("change", (changes) => this.events.emit(ProviderEvents.ConfigurationChanged, { flagsChanged: Object.keys(changes) }));
+        // Before initialization a failure rejects initialize() instead, which OpenFeature reports itself.
+        client.on("failed", (err) => client.isInitialized && this.events.emit(ProviderEvents.Error, { message: err?.message ?? "DevPulse client failed" }));
+        client.on("stale", (err) => this.events.emit(ProviderEvents.Stale, { message: err?.message ?? "DevPulse stream lost; serving last known flags" }));
+        client.on("recovered", () => this.events.emit(ProviderEvents.Ready));
+        await client.waitForInitialization();
     }
     async onContextChange(_old, next) {
         await this.client?.identify(toDevPulseContext(next));

package/dist/types.d.ts

@@ -15,7 +15,13 @@ export interface TokenPayload {
     offlineVerified?: boolean;
     [key: string]: unknown;
 }
-export type ValidateErrorCode = "EXPIRED" | "REVOKED" | "INVALID_TOKEN" | "RATE_LIMITED" | "NETWORK_ERROR" | "CONFIGURATION_ERROR" | string;
+export type ValidateErrorCode = "EXPIRED" | "REVOKED" | "INVALID_TOKEN" | "RATE_LIMITED" | "NETWORK_ERROR" | "SERVICE_UNAVAILABLE" | "CONFIGURATION_ERROR" | string;
+/**
+ * Failures that say nothing about the token: Daywalker Auth was unreachable, timed out, answered 5xx
+ * or answered with something that isn't a validation result. Both carry status 503 and are never cached;
+ * adapters should answer 503 rather than 401 for them.
+ */
+export declare const UNAVAILABLE_ERROR_CODES: readonly ValidateErrorCode[];
 export type ValidateResult = {
     ok: true;
     data: TokenPayload;
@@ -26,6 +32,9 @@ export type ValidateResult = {
     message: string;
     retryAfter?: number;
 };
+export interface PublicJwks {
+    keys: PublicJwk[];
+}
 export interface PublicJwk {
     kty: "OKP";
     crv: "Ed25519";
@@ -43,19 +52,38 @@ export interface SigningKey {
 export interface RetryOptions {
     maxRetries?: number;
     initialDelayMs?: number;
+    /** Cap on the exponential backoff delay. Default 30000ms. */
     maxDelayMs?: number;
     backoffFactor?: number;
     jitter?: boolean;
+    /**
+     * Longest `Retry-After` honored on a 429 (default 60000ms). A longer one is not waited out:
+     * the 429 response is returned to the caller.
+     */
+    maxRetryAfterMs?: number;
+    /**
+     * Retry after network errors / timeouts. Defaults to true only for GET, HEAD and OPTIONS (or when an
+     * `idempotencyKey` is given), since the server may already have processed a request whose response was lost.
+     */
+    retryNetworkErrors?: boolean;
 }
 export interface DaywalkerConfig {
     apiKey?: string;
     signingKey?: string | SigningKey;
+    /**
+     * Previous private key during rotation (env DAYWALKER_SIGNING_KEY_PREVIOUS). Never used to sign; its public
+     * JWK is published by `keys()` next to the current one so requests from instances still on the old key verify.
+     */
     previousSigningKey?: string | SigningKey;
     keyId?: string;
     serviceSlug?: string;
     domain?: string;
-    daywalkerPublicKey?: string | PublicJwk;
-    /** Expected `iss` of offline-verified JWT leases (env DAYWALKER_LEASE_ISSUER). Unchecked when unset. */
+    /** A JWK, a JWKS (`{ keys: [...] }`, selected by the lease's `kid`), PEM, or Base64 SPKI / raw key. */
+    daywalkerPublicKey?: string | PublicJwk | PublicJwks;
+    /**
+     * Expected `iss` of offline-verified JWT leases (env DAYWALKER_LEASE_ISSUER). Daywalker documents no fixed
+     * issuer, so `iss` is unchecked when unset; set it whenever leases from other issuers could share your key.
+     */
     leaseIssuer?: string;
     /** Must be https:// (http:// only for localhost). */
     authUrl?: string;
@@ -63,7 +91,10 @@ export interface DaywalkerConfig {
     /** Short cache for failed validations (not 429/network errors). Default 3000ms; 0 disables. */
     negativeCacheTtlMs?: number;
     maxRetries?: number;
+    /** Defaults for `fetch()` retries; per-request `init.retry` overrides individual fields. */
     retry?: RetryOptions;
+    /** Per-attempt timeout for requests to Daywalker Auth. Default 5000ms; 0 disables. */
+    timeoutMs?: number;
     fetch?: typeof fetch;
     env?: Record<string, string | undefined>;
 }
@@ -85,6 +116,7 @@ export interface SignedHeaders {
 }
 export interface SignRequestParams {
     method: string;
+    /** Request target path; a query string (`/a?b=1`) is split off and covered as "@query". */
     path: string;
     authority: string;
     body?: string | Uint8Array | null;
@@ -92,19 +124,39 @@ export interface SignRequestParams {
     created?: number;
     keyid?: string;
     alg?: string;
+    /** Sets `Authorization: Bearer <apiKey>` on the returned headers (not covered by the signature). */
     apiKey?: string;
+    /** Must be 1-128 of `[A-Za-z0-9_.-]` so it can't inject Signature-Input parameters. */
     nonce?: string;
 }
+/**
+ * Remembers verified request signatures until they expire. The default in-memory store is per process:
+ * deployments with several instances must pass a shared store (e.g. Redis `SET key 1 NX PX ttl`), or a
+ * signature replayed against another instance is accepted there.
+ */
+export interface ReplayStore {
+    /** True when `key` was recorded and has not expired yet. */
+    has(key: string): boolean | Promise<boolean>;
+    /**
+     * Atomically records `key` for `ttlMs` if it is absent. Returns false when the key is already present or
+     * the store can't take it (e.g. full); the signature is then rejected.
+     */
+    record(key: string, ttlMs: number): boolean | Promise<boolean>;
+}
 export interface VerifySignatureParams {
     method: string;
+    /** Request target path, including any query string (covered as "@query"). */
     path: string;
     authority: string;
     headers: Record<string, string | undefined> | Headers;
     body?: string | Uint8Array | null;
-    publicKey: PublicJwk | CryptoKey | string;
+    /** A JWK, a JWKS (selected by the signature's `keyid`), a CryptoKey, PEM or Base64 key. */
+    publicKey: PublicJwk | PublicJwks | CryptoKey | string;
     currentTime?: number;
     maxClockSkewSeconds?: number;
     replayCheck?: boolean;
+    /** Where verified signatures are remembered; defaults to a per-process in-memory cache. */
+    replayStore?: ReplayStore;
 }
 export interface VerifySignatureResult {
     valid: boolean;

package/dist/types.js

@@ -1,4 +1,10 @@
 import { redactSecrets } from "./crypto/encoding.js";
+/**
+ * Failures that say nothing about the token: Daywalker Auth was unreachable, timed out, answered 5xx
+ * or answered with something that isn't a validation result. Both carry status 503 and are never cached;
+ * adapters should answer 503 rather than 401 for them.
+ */
+export const UNAVAILABLE_ERROR_CODES = Object.freeze(["SERVICE_UNAVAILABLE", "NETWORK_ERROR"]);
 export class DaywalkerError extends Error {
     status;
     code;

package/docs/analytics.md

@@ -27,6 +27,6 @@ await analytics.shutdown();
 
 Add each flag's value to events (for breakdowns by variation) with `flags: client` where `client` is a `@shelbyb/daywalker-sdk/flags` instance (anything with `allFlags()`).
 
-Options: `autocapturePageviews` (default true), `flushAt` (20), `flushInterval` (2s browser / 10s Node), `maxQueueSize` (1000), `persistence` (`localStorage` | `memory`), `sessionTimeoutMinutes` (30), `respectDoNotTrack`, `optedOut` (consent), `captureFullUrls` (default false: URLs drop the fragment and all query parameters except `utm_*`, `gclid`, `fbclid`, `ref`), `onError`. `host` must be `https://` except on localhost.
+Options: `autocapturePageviews` (default true), `flushAt` (20), `flushInterval` (2s browser / 10s Node), `maxQueueSize` (1000), `persistence` (`localStorage` | `memory`), `sessionTimeoutMinutes` (30), `respectDoNotTrack`, `optedOut` (consent; opting out also drops events already queued), `captureFullUrls` (default false: URLs drop the fragment and all query parameters except `utm_*`, `gclid`, `fbclid`, `ref`), `sanitizePath` (rewrite paths that carry secrets, e.g. `(p) => p.replace(/^\/reset\/[^/]+/, "/reset/:token")`), `onError`. `host` must be `https://` except on localhost.
 
 Events are sent to `POST {host}/a/batch`, which also accepts PostHog's capture format.

package/docs/flags-node.md

@@ -46,4 +46,4 @@ See `@shelbyb/daywalker-sdk/flags/react` for the `Providers` component.
 
 ## API
 
-`variation` / `variationDetail` (async) and `variationSync` / `variationDetailSync`, typed helpers (`boolVariation`, …), `allFlagsState(context, { clientSideOnly, withReasons })`, `secureModeHash(context)`, `track`, `identify`, `on("ready" | "failed" | "update" | "update:<key>")`, `flush()`, `close()`.
+`variation` / `variationDetail` (async) and `variationSync` / `variationDetailSync`, typed helpers (`boolVariation`, …), `allFlagsState(context, { clientSideOnly, withReasons })` (`clientSideOnly` defaults to `true`, so server-only flags never reach a browser bootstrap), `secureModeHash(context)`, `track`, `identify`, `on("ready" | "failed" | "update" | "update:<key>" | "stale" | "recovered")`, `flush()`, `close()`.

package/docs/flags.md

@@ -43,6 +43,7 @@ Only flags marked **Available to client-side SDKs** are visible.
 | `sendEvents` | `true` | Analytics for insights and experiments |
 | `privateAttributes` / `allAttributesPrivate` | — | Attributes never sent to DevPulse |
 | `cache` | `false` | Persist the last flags in `localStorage` and use them while loading |
+| `offline` | `false` | Serve only `bootstrap`/cached values and open no connection (tests, server rendering) |
 
 ## Contexts
 
@@ -50,4 +51,4 @@ Single kind: `{ kind: "user", key: "u1", plan: "pro" }`. Multi-kind: `{ kind: "m
 
 ## API
 
-`variation(key, default)`, `variationDetail(key, default)`, `boolVariation` / `stringVariation` / `numberVariation` / `jsonVariation`, `allFlags()`, `identify(context)`, `track(key, data?, metricValue?)`, `on("ready" | "failed" | "change" | "change:<key>", fn)`, `flush()`, `close()`.
+`variation(key, default)`, `variationDetail(key, default)`, `boolVariation` / `stringVariation` / `numberVariation` / `jsonVariation`, `allFlags()`, `identify(context)`, `track(key, data?, metricValue?)`, `on("ready" | "failed" | "change" | "change:<key>" | "stale" | "recovered", fn)` (`stale`: the stream dropped and the last flags keep serving; `recovered`: it reconnected), `flush()`, `close()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Daywalker Auth service validation plus the DevPulse client SDKs (feature flags, OpenFeature, product analytics) in one zero-dependency package.",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,47 +8,58 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./next": {
       "types": "./dist/next.d.ts",
-      "import": "./dist/next.js"
+      "import": "./dist/next.js",
+      "default": "./dist/next.js"
     },
     "./middleware": {
       "types": "./dist/middleware.d.ts",
-      "import": "./dist/middleware.js"
+      "import": "./dist/middleware.js",
+      "default": "./dist/middleware.js"
     },
     "./express": {
       "types": "./dist/express.d.ts",
-      "import": "./dist/express.js"
+      "import": "./dist/express.js",
+      "default": "./dist/express.js"
     },
     "./flags": {
       "types": "./dist/flags/client.d.ts",
-      "import": "./dist/flags/client.js"
+      "import": "./dist/flags/client.js",
+      "default": "./dist/flags/client.js"
     },
     "./flags/node": {
       "types": "./dist/flags/node.d.ts",
-      "import": "./dist/flags/node.js"
+      "import": "./dist/flags/node.js",
+      "default": "./dist/flags/node.js"
     },
     "./flags/react": {
       "types": "./dist/flags/react.d.ts",
-      "import": "./dist/flags/react.js"
+      "import": "./dist/flags/react.js",
+      "default": "./dist/flags/react.js"
     },
     "./flags/engine": {
       "types": "./dist/flags/engine/index.d.ts",
-      "import": "./dist/flags/engine/index.js"
+      "import": "./dist/flags/engine/index.js",
+      "default": "./dist/flags/engine/index.js"
     },
     "./openfeature/server": {
       "types": "./dist/openfeature/server.d.ts",
-      "import": "./dist/openfeature/server.js"
+      "import": "./dist/openfeature/server.js",
+      "default": "./dist/openfeature/server.js"
     },
     "./openfeature/web": {
       "types": "./dist/openfeature/web.d.ts",
-      "import": "./dist/openfeature/web.js"
+      "import": "./dist/openfeature/web.js",
+      "default": "./dist/openfeature/web.js"
     },
     "./analytics": {
       "types": "./dist/analytics/index.d.ts",
-      "import": "./dist/analytics/index.js"
+      "import": "./dist/analytics/index.js",
+      "default": "./dist/analytics/index.js"
     }
   },
   "bin": {
@@ -56,7 +67,6 @@
   },
   "files": [
     "dist",
-    "assets",
     "docs",
     "README.md",
     "LICENSE"
@@ -68,6 +78,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --import tsx --test test/*.test.ts",
+    "lint:package": "publint --strict && attw --pack . --profile esm-only",
     "prepublishOnly": "npm test"
   },
   "publishConfig": {
@@ -81,12 +92,16 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
     "@openfeature/core": "^1.12.0",
     "@openfeature/server-sdk": "^1.23.0",
     "@openfeature/web-sdk": "^1.10.0",
     "@types/node": "^26.6.4",
     "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "publint": "^0.3.25",
     "react": "^19.3.0",
+    "react-dom": "^19.3.1",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   },
@@ -121,5 +136,8 @@
       "optional": true
     }
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "dependencies": {
+    "re2js": "2.8.6"
+  }
 }