@shelbyb/daywalker-sdk 0.1.4 → 0.3.0

package/dist/openfeature/web.js

@@ -0,0 +1,50 @@
+import { OpenFeatureEventEmitter, ProviderEvents } from "@openfeature/web-sdk";
+import { createClient } from "../flags/client.js";
+import { toDevPulseContext, toResolution, typeCheck } from "./shared.js";
+/**
+ * OpenFeature provider for browsers, backed by @shelbyb/daywalker-sdk/flags. Flag
+ * values update in real time and emit PROVIDER_CONFIGURATION_CHANGED.
+ *
+ *   await OpenFeature.setContext({ targetingKey: user.id });
+ *   await OpenFeature.setProviderAndWait(new DevPulseWebProvider(clientSideId, { baseUrl }));
+ */
+export class DevPulseWebProvider {
+    clientSideId;
+    options;
+    metadata = { name: "devpulse" };
+    runsOn = "client";
+    events = new OpenFeatureEventEmitter();
+    client = null;
+    constructor(clientSideId, options) {
+        this.clientSideId = clientSideId;
+        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();
+    }
+    async onContextChange(_old, next) {
+        await this.client?.identify(toDevPulseContext(next));
+    }
+    async onClose() {
+        await this.client?.close();
+    }
+    resolve(key, def, type) {
+        if (!this.client)
+            return toResolution({ value: def, variationIndex: null, reason: { kind: "ERROR", errorKind: "CLIENT_NOT_READY" } });
+        return toResolution(typeCheck(this.client.variationDetail(key, def), type, def));
+    }
+    resolveBooleanEvaluation(key, def, _ctx, _logger) {
+        return this.resolve(key, def, "boolean");
+    }
+    resolveStringEvaluation(key, def, _ctx, _logger) {
+        return this.resolve(key, def, "string");
+    }
+    resolveNumberEvaluation(key, def, _ctx, _logger) {
+        return this.resolve(key, def, "number");
+    }
+    resolveObjectEvaluation(key, def, _ctx, _logger) {
+        return this.resolve(key, def, "object");
+    }
+}

package/dist/types.d.ts

@@ -55,6 +55,9 @@ export interface DaywalkerConfig {
     serviceSlug?: string;
     domain?: string;
     daywalkerPublicKey?: string | PublicJwk;
+    /** Expected `iss` of offline-verified JWT leases (env DAYWALKER_LEASE_ISSUER). Unchecked when unset. */
+    leaseIssuer?: string;
+    /** Must be https:// (http:// only for localhost). */
     authUrl?: string;
     cacheTtlMs?: number;
     /** Short cache for failed validations (not 429/network errors). Default 3000ms; 0 disables. */

package/docs/analytics.md

@@ -0,0 +1,32 @@
+# @shelbyb/daywalker-sdk/analytics
+
+Product analytics for browsers and Node: events, automatic page views (including client-side navigation), sessions, identify, super properties and feature-flag properties.
+
+```sh
+npm install @shelbyb/daywalker-sdk
+```
+
+```ts
+import { createAnalytics } from "@shelbyb/daywalker-sdk/analytics";
+
+const analytics = createAnalytics({ writeKey: "dpa_…", host: "https://devpulse.example.com" });
+
+analytics.capture("project_created", { template: "nextjs" });
+analytics.identify(user.id, { email: user.email, plan: user.plan }); // merges the anonymous history
+analytics.register({ app_version: "2.4.0" }); // sent with every event
+analytics.reset(); // on logout
+```
+
+Server-side (Node), pass who did it and flush before exit:
+
+```ts
+const analytics = createAnalytics({ writeKey: process.env.DEVPULSE_WRITE_KEY!, host: "https://devpulse.example.com" });
+analytics.capture("invoice_paid", { amount: 49 }, { distinctId: customer.id });
+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.
+
+Events are sent to `POST {host}/a/batch`, which also accepts PostHog's capture format.

package/docs/flags-node.md

@@ -0,0 +1,49 @@
+# @shelbyb/daywalker-sdk/flags/node
+
+Server-side feature flags for Node.js from [DevPulse](https://github.com/shelbyb/devpulse). The SDK downloads your flag rules once, keeps them current over a streaming connection, and evaluates locally, so `variation()` adds no network latency.
+
+```bash
+npm install @shelbyb/daywalker-sdk
+```
+
+```ts
+import { init } from "@shelbyb/daywalker-sdk/flags/node";
+
+export const flags = init(process.env.DEVPULSE_SDK_KEY!, { baseUrl: "https://devpulse.example.com" });
+await flags.waitForInitialization({ timeoutMs: 5000 });
+
+const context = { kind: "user", key: user.id, email: user.email, plan: user.plan };
+if (await flags.variation("new-checkout", context, false)) {
+  // …
+}
+
+flags.on("update:new-checkout", () => console.log("new-checkout changed"));
+flags.track("checkout-completed", context, undefined, order.total);
+```
+
+Create one client per process and reuse it. Call `await flags.close()` on shutdown to flush analytics.
+
+## Next.js (App Router): bootstrap the browser without a flicker
+
+```tsx
+// app/layout.tsx (Server Component)
+import { flags } from "@/lib/flags";
+import { Providers } from "./providers";
+
+export default async function Layout({ children }) {
+  const context = await currentUserContext();
+  const bootstrap = (await flags.allFlagsState(context, { clientSideOnly: true })).toJSON();
+  const hash = flags.secureModeHash(context); // if secure mode is on
+  return <Providers context={context} bootstrap={bootstrap} hash={hash}>{children}</Providers>;
+}
+```
+
+See `@shelbyb/daywalker-sdk/flags/react` for the `Providers` component.
+
+## Options
+
+`baseUrl`, `stream` (default `true`; falls back to polling if streaming keeps failing), `pollIntervalMs` (≥ 30s), `sendEvents`, `privateAttributes`, `allAttributesPrivate`, `offline`, `initialData` (fixtures for tests), `logger`.
+
+## 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()`.

package/docs/flags-react.md

@@ -0,0 +1,35 @@
+# @shelbyb/daywalker-sdk/flags/react
+
+React provider and hooks for [DevPulse](https://github.com/shelbyb/devpulse) feature flags. Components re-render when the flags they read change, in real time.
+
+```bash
+npm install @shelbyb/daywalker-sdk
+```
+
+```tsx
+"use client";
+import { DevPulseProvider, useFlag, useTrack } from "@shelbyb/daywalker-sdk/flags/react";
+
+export function Providers({ context, bootstrap, hash, children }) {
+  return (
+    <DevPulseProvider
+      clientSideId={process.env.NEXT_PUBLIC_DEVPULSE_CLIENT_ID!}
+      context={context}
+      options={{ baseUrl: process.env.NEXT_PUBLIC_DEVPULSE_URL!, bootstrap, hash }}
+    >
+      {children}
+    </DevPulseProvider>
+  );
+}
+
+function Checkout() {
+  const newCheckout = useFlag("new-checkout", false);
+  const track = useTrack();
+  return newCheckout ? <NewCheckout onDone={(total) => track("checkout-completed", undefined, total)} /> : <OldCheckout />;
+}
+```
+
+- **SSR / React Server Components:** pass `bootstrap` from `@shelbyb/daywalker-sdk/flags/node`'s `allFlagsState(context, { clientSideOnly: true }).toJSON()`. The server render and first client render then match, with no loading flicker. No network connection is opened during server rendering.
+- Changing the `context` prop calls `identify()`.
+
+Hooks: `useFlag(key, default)`, `useFlagDetail(key, default)`, `useFlags()`, `useFlagsReady()`, `useTrack()`, `useDevPulseClient()`.

package/docs/flags.md

@@ -0,0 +1,53 @@
+# @shelbyb/daywalker-sdk/flags
+
+Feature flags for browsers (and any JavaScript client) from [DevPulse](https://github.com/shelbyb/devpulse). Flag changes arrive in real time over Server-Sent Events, typically within tens of milliseconds of a change in the dashboard.
+
+```bash
+npm install @shelbyb/daywalker-sdk
+```
+
+```ts
+import { createClient } from "@shelbyb/daywalker-sdk/flags";
+
+const client = createClient(
+  "YOUR_CLIENT_SIDE_ID", // Project → Environments & keys
+  { kind: "user", key: user.id, email: user.email },
+  { baseUrl: "https://devpulse.example.com" },
+);
+
+await client.waitForInitialization({ timeoutMs: 3000 });
+
+if (client.variation("new-checkout", false)) showNewCheckout();
+
+// React to changes made in the dashboard, live
+client.on("change:new-checkout", (enabled) => (enabled ? showNewCheckout() : showOldCheckout()));
+
+// Metrics and experiments
+client.track("checkout-completed", { items: 3 }, 129.5);
+
+// After login
+await client.identify({ kind: "user", key: newUser.id });
+```
+
+Only flags marked **Available to client-side SDKs** are visible.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `baseUrl` | — | Your DevPulse URL |
+| `streaming` | `true` | Real-time updates (SSE). `false` fetches once |
+| `bootstrap` | — | Initial values, e.g. from `@shelbyb/daywalker-sdk/flags/node`'s `allFlagsState().toJSON()` |
+| `hash` | — | Secure mode hash (`HMAC-SHA256(sdkKey, contextKey)`), computed on your server |
+| `withReasons` | `false` | Include evaluation reasons for `variationDetail()` |
+| `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 |
+
+## Contexts
+
+Single kind: `{ kind: "user", key: "u1", plan: "pro" }`. Multi-kind: `{ kind: "multi", user: { key: "u1" }, organization: { key: "acme" } }`.
+
+## 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()`.

package/docs/openfeature.md

@@ -0,0 +1,30 @@
+# @shelbyb/daywalker-sdk/openfeature
+
+[OpenFeature](https://openfeature.dev) providers for DevPulse. Use the vendor-neutral OpenFeature API and swap providers without touching application code.
+
+```bash
+npm install @shelbyb/daywalker-sdk @openfeature/server-sdk   # servers
+npm install @shelbyb/daywalker-sdk @openfeature/web-sdk      # browsers
+```
+
+```ts
+// Server
+import { OpenFeature } from "@openfeature/server-sdk";
+import { DevPulseServerProvider } from "@shelbyb/daywalker-sdk/openfeature/server";
+
+await OpenFeature.setProviderAndWait(new DevPulseServerProvider(process.env.DEVPULSE_SDK_KEY!, { baseUrl }));
+const client = OpenFeature.getClient();
+const enabled = await client.getBooleanValue("new-checkout", false, { targetingKey: user.id, plan: "pro" });
+```
+
+```ts
+// Browser
+import { OpenFeature } from "@openfeature/web-sdk";
+import { DevPulseWebProvider } from "@shelbyb/daywalker-sdk/openfeature/web";
+
+await OpenFeature.setContext({ targetingKey: user.id });
+await OpenFeature.setProviderAndWait(new DevPulseWebProvider(clientSideId, { baseUrl }));
+OpenFeature.getClient().getBooleanValue("new-checkout", false);
+```
+
+`targetingKey` maps to the context key, and a `kind` attribute selects the context kind (default `user`). Flag changes emit `PROVIDER_CONFIGURATION_CHANGED`. Reasons map to OpenFeature's standard reasons: `TARGETING_MATCH`, `SPLIT`, `DEFAULT`, `DISABLED`, `ERROR`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shelbyb/daywalker-sdk",
-  "version": "0.1.4",
-  "description": "Validate Daywalker API tokens and make domain-signed calls to Daywalker Auth from any service.",
+  "version": "0.3.0",
+  "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",
   "types": "./dist/index.d.ts",
@@ -21,6 +21,34 @@
     "./express": {
       "types": "./dist/express.d.ts",
       "import": "./dist/express.js"
+    },
+    "./flags": {
+      "types": "./dist/flags/client.d.ts",
+      "import": "./dist/flags/client.js"
+    },
+    "./flags/node": {
+      "types": "./dist/flags/node.d.ts",
+      "import": "./dist/flags/node.js"
+    },
+    "./flags/react": {
+      "types": "./dist/flags/react.d.ts",
+      "import": "./dist/flags/react.js"
+    },
+    "./flags/engine": {
+      "types": "./dist/flags/engine/index.d.ts",
+      "import": "./dist/flags/engine/index.js"
+    },
+    "./openfeature/server": {
+      "types": "./dist/openfeature/server.d.ts",
+      "import": "./dist/openfeature/server.js"
+    },
+    "./openfeature/web": {
+      "types": "./dist/openfeature/web.d.ts",
+      "import": "./dist/openfeature/web.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics/index.d.ts",
+      "import": "./dist/analytics/index.js"
     }
   },
   "bin": {
@@ -29,6 +57,7 @@
   "files": [
     "dist",
     "assets",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -52,19 +81,45 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^22.13.5",
-    "typescript": "^5.9.3",
-    "tsx": "^4.23.15"
+    "@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",
+    "react": "^19.3.0",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
   },
   "keywords": [
-    "daywalker",
     "api-token",
     "authentication",
+    "daywalker",
+    "devpulse",
     "ed25519",
+    "feature-flags",
+    "openfeature",
+    "product-analytics",
     "request-signing"
   ],
   "homepage": "https://auth.daywalker.dev/docs",
   "bugs": {
     "url": "https://github.com/Shelbyb/daywalker-sdk/issues"
-  }
+  },
+  "peerDependencies": {
+    "@openfeature/server-sdk": "^1.17.0",
+    "@openfeature/web-sdk": "^1.5.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@openfeature/server-sdk": {
+      "optional": true
+    },
+    "@openfeature/web-sdk": {
+      "optional": true
+    }
+  },
+  "sideEffects": false
 }