@toggld/node 0.3.0 → 0.4.0

package/README.md

@@ -16,9 +16,10 @@ Two evaluation modes:
   evaluation" over the OFREP endpoints).
 - **Local** (`mode: "local"`) — recommended for long-lived servers. Flag
   definitions sync in the background (a snapshot fetch plus a live WebSocket
-  stream, with polling fallback) and every evaluation runs **in-process** on
-  the bundled engine: microsecond latency, zero server requests per
-  evaluation, and changes pushed to your process within milliseconds. Requires
+  stream where supported, with polling fallback) and every evaluation runs **in-process** on
+  the bundled engine without a server request per evaluation. Workers currently
+  uses polling for definition updates. Cache freshness, polling intervals, and
+  network conditions affect when changed definitions arrive. Requires
   a secret SDK key (`ffk_…`) — public browser tokens cannot read rulesets. See
   [ADR-0012](../../docs/adr/0012-definition-sync-and-local-evaluation.md). Local
   mode can also read its snapshot from a **file** instead of the network — see
@@ -96,12 +97,17 @@ scope.
 | `timeoutMs`      | `number`              | `5000`           | Per-request timeout.                                             |
 | `fetch`          | `typeof fetch`        | `globalThis.fetch` | Custom fetch (tests, proxies, instrumentation).               |
 
-In local mode `create` resolves once the first snapshot has synced (or after
-`sync.readyTimeoutMs`); until a snapshot arrives, evaluations return your
-defaults with `errorCode: "PROVIDER_NOT_READY"` and sync keeps retrying.
-`client.ready()` awaits sync explicitly. Updates arrive as WebSocket pushes
-within milliseconds of a management change; on runtimes where the stream is
-unavailable the client polls instead, automatically.
+In local mode, `create` waits for the first snapshot or `sync.readyTimeoutMs`.
+Until a snapshot arrives, evaluations return your defaults with
+`errorCode: "PROVIDER_NOT_READY"`, and sync keeps retrying. `client.ready()` waits
+for the first snapshot without a timeout.
+
+Changes on the connected Node instance normally arrive through WebSocket pushes.
+The SDK also polls every 30 seconds, even while the stream stays healthy.
+Polling recovers writes from other instances and announcements that the bounded
+server buffer drops. With healthy requests, the conservative bound is
+`sync.pollIntervalMs + 2 * timeoutMs`, plus scheduling delays, or 40 seconds by default.
+The [Node sync guide](../../docs/node-sync.md) defines the assumptions and deployment requirements.
 
 ### How fast is local mode?
 
@@ -160,3 +166,53 @@ error, or a value whose type doesn't match the requested getter, the call
 resolves to your **default value**. The `*Details` methods carry `reason:
 "ERROR"` and an OpenFeature `errorCode` (`FLAG_NOT_FOUND`, `TYPE_MISMATCH`,
 `TARGETING_KEY_MISSING`, `PARSE_ERROR`, `GENERAL`, …) describing what happened.
+
+
+## Evaluation telemetry
+
+In network-synced local mode, the SDK collects evaluation counts automatically.
+It groups counts by flag, variant, result reason, and UTC minute. The SDK sends
+batches to `POST /v1/telemetry` every 30 seconds and during `close()`.
+Evaluation calls do not wait for these requests. Both SDK APIs use this reporter.
+
+The SDK reports engine results for known flags, including engine errors.
+It excludes unknown flags, calls before readiness, and errors from typed getters.
+Each bulk evaluation counts each flag once. The SDK sends no user identities,
+evaluation context, values, or metadata. Remote mode relies on server collection.
+File-based mode sends no telemetry, even when credentials are present.
+
+```ts
+const client = await ToggldClient.create({
+  endpoint,
+  sdkKey,
+  mode: "local",
+  telemetry: { flushIntervalMs: 30_000 },
+})
+
+await client.getBooleanValue("checkout", false, { targetingKey: "user-123" })
+await client.flushTelemetry()
+await client.close()
+```
+
+Set `telemetry: false` to disable reporting. Use `flushTelemetry()` to send counts
+before the next interval. Effect users can yield `client.flushTelemetry` and close
+the layer scope to flush remaining counts. A flush failure leaves the batch
+queued for the next attempt. Retries keep the same batch ID to prevent duplicate
+counts after a lost response.
+
+The SDK holds at most 10,000 active groups and 10,000 groups awaiting retry.
+If the active buffer fills, the SDK drops new groups. Each request contains at
+most 1,000 groups. Each count stops at 1,000,000,000. Keys and variants longer
+than 256 characters do not produce telemetry. Process crashes can lose buffered
+counts. Closing the client limits its final telemetry attempt to `timeoutMs`,
+which defaults to five seconds. Counts remain approximate.
+
+
+The integration suite can use Postgres for the complete SDK-to-storage path.
+It creates tenants and flags, so use a disposable database. From the repository
+root, set `DATABASE_URL` to that database and run the command below. The test
+server applies migrations before it starts.
+
+```bash
+TOGGLD_TEST_POSTGRES=1 DATABASE_URL=postgres://postgres:postgres@localhost:55439/toggld pnpm --filter @toggld/node exec vitest run test/telemetry.test.ts
+```

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as FlagSnapshot } from "./src-CCPvsrli.mjs";
+import { t as FlagSnapshot } from "./src-B_M-Oix8.mjs";
 import { Effect, Schema } from "effect";
 import { readFile, writeFile } from "node:fs/promises";
-//#region src/internal/cli.ts
+// src/internal/cli.ts
 /**
 * The `toggld` CLI (ADR-0013). Today it has one command:
 *
@@ -115,7 +115,7 @@ Options for "pull":
 
 Point a local-mode client at the file with TOGGLD_FLAGS_FILE or
 { sync: { file: "<path>" } }.`;
-const BOOLEAN_FLAGS = new Set([
+const BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
 	"force",
 	"f",
 	"help",
@@ -223,8 +223,7 @@ const runMain = async (argv) => {
 };
 const asString = (v) => typeof v === "string" && v.length > 0 ? v : void 0;
 const short = (version) => version.length > 12 ? `${version.slice(0, 12)}…` : version;
-//#endregion
-//#region src/cli.ts
+// src/cli.ts
 /**
 * The `toggld` executable. All logic lives in `./internal/cli.ts` (so tests can
 * call it without spawning a process); this is just the entry that runs it.
@@ -233,5 +232,4 @@ runMain(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
 	console.error(error);
 	process.exit(1);
 });
-//#endregion
 export {};

package/dist/{core-DBVGNtur.mjs → core-CezJWPV4.mjs}

@@ -1,10 +1,10 @@
-import { a as OfrepSuccess, i as OfrepFailure, n as SyncServerMessage, r as OfrepBulkResponse, t as FlagSnapshot } from "./src-CCPvsrli.mjs";
-import { Context, Deferred, Duration, Effect, Layer, Schema } from "effect";
+import { a as OfrepSuccess, i as OfrepFailure, n as SyncServerMessage, r as OfrepBulkResponse, t as FlagSnapshot } from "./src-B_M-Oix8.mjs";
+import { Context, Deferred, Duration, Effect, Layer, Schema, Semaphore } from "effect";
 import { readFile, watch } from "node:fs/promises";
 import { basename, dirname } from "node:path";
-import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
-import { Socket } from "effect/unstable/socket";
-//#region ../spec/src/index.ts
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { Socket } from "effect/socket";
+// ../spec/src/index.ts
 /** True when `value` is assignable to a flag declared as `type`. */
 const valueMatchesType = (value, type) => {
 	switch (type) {
@@ -56,8 +56,7 @@ const Resolution = {
 		flagMetadata: args.flagMetadata ?? {}
 	})
 };
-//#endregion
-//#region ../engine/src/hash.ts
+// ../engine/src/hash.ts
 /**
 * MurmurHash3 (x86, 32-bit). A fast, well-distributed, non-cryptographic hash.
 * Used to deterministically bucket a subject into a percentage rollout slice so
@@ -115,8 +114,7 @@ const BUCKET_SCALE = 1e4;
 const bucketFor = (flagKey, ruleId, subject) => {
 	return murmur3(`${flagKey}:${ruleId}:${subject}`) % BUCKET_SCALE;
 };
-//#endregion
-//#region ../engine/src/targeting.ts
+// ../engine/src/targeting.ts
 const asNumber = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
 const asString = (v) => typeof v === "string" ? v : void 0;
 /** Evaluates a single condition against the context. */
@@ -234,8 +232,7 @@ const deepEqual = (a, b) => {
 	}
 	return false;
 };
-//#endregion
-//#region ../engine/src/evaluate.ts
+// ../engine/src/evaluate.ts
 /**
 * Looks up a variant's value and returns a successful resolution, or an
 * abnormal `GENERAL` resolution if the variant is not declared (a
@@ -287,8 +284,65 @@ const evaluateFlag = (flag, ctx, isMemberOf) => {
 	}
 	return serveVariant(flag, flag.defaultVariant, "STATIC");
 };
-//#endregion
-//#region src/internal/core.ts
+// src/internal/telemetry.ts
+const startTelemetry = (http, options) => Effect.gen(function* () {
+	const instanceId = crypto.randomUUID();
+	const lock = yield* Semaphore.make(1);
+	const interval = options.telemetry === false ? 3e4 : options.telemetry?.flushIntervalMs ?? 3e4;
+	const timeout = Duration.millis(options.timeoutMs ?? 5e3);
+	let cells = /* @__PURE__ */ new Map();
+	let pending = [];
+	const flush = lock.withPermit(Effect.gen(function* () {
+		for (let pass = 0; pass < 2; pass++) {
+			if (pending.length === 0) {
+				const rollups = [...cells.values()];
+				cells = /* @__PURE__ */ new Map();
+				for (let i = 0; i < rollups.length; i += 1e3) pending.push({
+					sdkInstanceId: instanceId,
+					windowId: crypto.randomUUID(),
+					rollups: rollups.slice(i, i + 1e3)
+				});
+			}
+			while (pending.length > 0) {
+				if (!(yield* Effect.gen(function* () {
+					const response = yield* http.execute(HttpClientRequest.post("/v1/telemetry").pipe(HttpClientRequest.bodyJsonUnsafe(pending[0])));
+					return response.status >= 200 && response.status < 300;
+				}).pipe(Effect.timeout(timeout), Effect.catchCause(() => Effect.succeed(false))))) return;
+				pending.shift();
+			}
+		}
+	}));
+	yield* Effect.addFinalizer(() => flush.pipe(Effect.timeout(timeout), Effect.catchCause(() => Effect.void)));
+	yield* Effect.forkScoped(Effect.forever(Effect.sleep(Duration.millis(Number.isFinite(interval) && interval > 0 ? interval : 3e4)).pipe(Effect.andThen(flush))));
+	return {
+		flush,
+		record: (flagKey, resolution) => {
+			if (flagKey.length === 0 || flagKey.length > 256 || (resolution.variant?.length ?? 0) > 256) return;
+			const variant = resolution.variant ?? "";
+			const bucketStart = (/* @__PURE__ */ new Date(Math.floor(Date.now() / 6e4) * 6e4)).toISOString();
+			const key = JSON.stringify([
+				flagKey,
+				variant,
+				resolution.reason,
+				bucketStart
+			]);
+			const cell = cells.get(key);
+			if (cell) {
+				if (cell.count < 1e9) cells.set(key, {
+					...cell,
+					count: cell.count + 1
+				});
+			} else if (cells.size < 1e4) cells.set(key, {
+				flagKey,
+				variant,
+				reason: resolution.reason,
+				bucketStart,
+				count: 1
+			});
+		}
+	};
+});
+// src/internal/core.ts
 /**
 * The Effect core of the Toggld Node SDK.
 *
@@ -342,19 +396,19 @@ const errorDetails = (key, value, errorCode, errorMessage, flagMetadata = {}) =>
 	reason: "ERROR",
 	errorCode,
 	errorMessage,
-	flagMetadata
+	flagMetadata: { ...flagMetadata }
 });
 /** Map an engine {@link Resolution} to evaluation details, OpenFeature-style:
 * an abnormal resolution serves the **caller's** default, not the engine's
 * internal fallback — exactly what the remote wire does on a 400. */
 const resolutionDetails = (key, resolution, fallback) => resolution.errorCode !== void 0 ? errorDetails(key, fallback, resolution.errorCode, resolution.errorMessage ?? "", resolution.flagMetadata) : {
 	flagKey: key,
-	value: resolution.value,
+	value: typeof resolution.value === "object" && resolution.value !== null ? structuredClone(resolution.value) : resolution.value,
 	variant: resolution.variant,
 	reason: resolution.reason,
 	errorCode: void 0,
 	errorMessage: void 0,
-	flagMetadata: resolution.flagMetadata
+	flagMetadata: { ...resolution.flagMetadata }
 };
 /** A readable message for an arbitrary thrown/failed value. */
 const describe = (e) => typeof e === "object" && e !== null && "message" in e && typeof e.message === "string" ? e.message : String(e);
@@ -398,7 +452,7 @@ const toStreamUrl = (endpoint) => {
 	url.pathname = url.pathname.replace(/\/$/, "") + "/sync/v1/stream";
 	return url.toString();
 };
-const makeSnapshotStore = (mergedContext) => Effect.gen(function* () {
+const makeSnapshotStore = (mergedContext, record) => Effect.gen(function* () {
 	let current;
 	let epoch = 0;
 	const firstSnapshot = yield* Deferred.make();
@@ -429,14 +483,20 @@ const makeSnapshotStore = (mergedContext) => Effect.gen(function* () {
 		const flag = state.byKey.get(key);
 		if (flag === void 0) return errorDetails(key, defaultValue, "FLAG_NOT_FOUND", `Flag '${key}' not found`);
 		const ctx = mergedContext(context);
-		return resolutionDetails(key, evaluateFlag(flag, ctx, memberOf(state, ctx)), defaultValue);
+		const resolution = evaluateFlag(flag, ctx, memberOf(state, ctx));
+		record(key, resolution);
+		return resolutionDetails(key, resolution, defaultValue);
 	});
 	const evaluateAll = (context) => Effect.sync(() => {
 		const state = current;
 		if (state === void 0) return [];
 		const ctx = mergedContext(context);
 		const isMemberOf = memberOf(state, ctx);
-		return state.flags.map((flag) => resolutionDetails(flag.key, evaluateFlag(flag, ctx, isMemberOf), null));
+		return state.flags.map((flag) => {
+			const resolution = evaluateFlag(flag, ctx, isMemberOf);
+			record(flag.key, resolution);
+			return resolutionDetails(flag.key, resolution, null);
+		});
 	});
 	return {
 		adopt,
@@ -495,9 +555,14 @@ const startNetworkSource = (options, http, store, timeout) => Effect.gen(functio
 			openTimeout: timeout
 		});
 		yield* Effect.forever(Effect.gen(function* () {
-			yield* socket.runRaw(handleMessage, { onOpen: Effect.sync(() => {
+			yield* Effect.scoped(Effect.gen(function* () {
+				const pull = yield* Socket.readerString(socket);
 				consecutiveFailures = 0;
-			}) }).pipe(Effect.ignore);
+				while (true) {
+					const messages = yield* pull;
+					for (const message of messages) yield* handleMessage(message);
+				}
+			})).pipe(Effect.ignore);
 			consecutiveFailures++;
 			const base = Math.min(3e4, 1e3 * 2 ** Math.min(consecutiveFailures - 1, 5));
 			yield* Effect.sleep(Duration.millis(base * (.5 + Math.random() * .5)));
@@ -517,8 +582,8 @@ const startFileSource = (path, store, options) => Effect.gen(function* () {
 	const decodeSnapshot = Schema.decodeUnknownEffect(FlagSnapshot);
 	let lastError;
 	const readOnce = Effect.gen(function* () {
-		const text = yield* Effect.tryPromise(() => readFile(path, "utf8"));
-		const snapshot = yield* decodeSnapshot(JSON.parse(text));
+		const json = yield* Effect.tryPromise(async () => JSON.parse(await readFile(path, "utf8")));
+		const snapshot = yield* decodeSnapshot(json);
 		lastError = void 0;
 		if (store.version() === snapshot.version) return;
 		yield* store.adopt(snapshot);
@@ -572,8 +637,8 @@ const startFileSource = (path, store, options) => Effect.gen(function* () {
 			yield* Effect.sleep(Duration.millis(500));
 		}
 	});
+	yield* Effect.forkScoped(watchLoop, { startImmediately: true });
 	yield* Effect.forkScoped(ticker);
-	yield* Effect.forkScoped(watchLoop);
 });
 /**
 * Resolve a local flag-file path, or `undefined` for network sync. Highest
@@ -592,8 +657,8 @@ const resolveFilePath = (options) => {
 * Assemble the local-mode evaluation surface, choosing the file source when a
 * path resolves (env var or `sync.file`) and the network source otherwise.
 */
-const makeLocal = (options, http, mergedContext, timeout) => Effect.gen(function* () {
-	const store = yield* makeSnapshotStore(mergedContext);
+const makeLocal = (options, http, mergedContext, timeout, record) => Effect.gen(function* () {
+	const store = yield* makeSnapshotStore(mergedContext, record);
 	const filePath = resolveFilePath(options);
 	if (filePath !== void 0) yield* startFileSource(filePath, store, options);
 	else yield* startNetworkSource(options, http, store, timeout);
@@ -607,7 +672,12 @@ const make = (options) => Effect.gen(function* () {
 		...options.defaultContext,
 		...context
 	});
-	const { evaluate, evaluateAll, ready } = options.mode === "local" || resolveFilePath(options) !== void 0 ? yield* makeLocal(options, http, mergedContext, timeout) : makeRemote(http, mergedContext, timeout);
+	const local = options.mode === "local" || resolveFilePath(options) !== void 0;
+	const telemetry = local && resolveFilePath(options) === void 0 && options.telemetry !== false ? yield* startTelemetry(http, options) : {
+		record: (_key, _resolution) => {},
+		flush: Effect.void
+	};
+	const { evaluate, evaluateAll, ready } = local ? yield* makeLocal(options, http, mergedContext, timeout, telemetry.record) : makeRemote(http, mergedContext, timeout);
 	/** Resolve, then enforce the requested value type (else `TYPE_MISMATCH`). */
 	const typed = (key, defaultValue, context, type, guard) => Effect.map(evaluate(key, defaultValue, context), (d) => {
 		if (d.errorCode !== void 0) return d;
@@ -617,6 +687,7 @@ const make = (options) => Effect.gen(function* () {
 	const valueOf = (details) => Effect.map(details, (d) => d.value);
 	return {
 		ready,
+		flushTelemetry: telemetry.flush,
 		evaluate,
 		evaluateAll,
 		getBooleanDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "boolean", isBoolean),
@@ -632,7 +703,7 @@ const make = (options) => Effect.gen(function* () {
 /** The HttpClient layer, optionally backed by a caller-supplied `fetch`. */
 const httpLayer = (fetchImpl) => fetchImpl ? FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch, fetchImpl))) : FetchHttpClient.layer;
 /** The WebSocket constructor for the sync stream, optionally caller-supplied. */
-const webSocketLayer = (ctor) => ctor ? Layer.succeed(Socket.WebSocketConstructor, (url, protocols) => new ctor(url, protocols)) : Socket.layerWebSocketConstructorGlobal;
+const webSocketLayer = (ctor) => ctor ? Layer.succeed(Socket.WebSocketConstructor, (url, options) => new ctor(url, typeof options === "object" && !Array.isArray(options) ? options.protocols : options)) : Socket.layerWebSocketConstructorGlobal;
 /**
 * A self-contained `Layer` providing {@link ToggldClient} — it wires its own
 * HTTP and WebSocket backends, so Effect users need only provide this one
@@ -640,5 +711,4 @@ const webSocketLayer = (ctor) => ctor ? Layer.succeed(Socket.WebSocketConstructo
 * closing it (e.g. `ManagedRuntime.dispose`) stops sync and closes the stream.
 */
 const layer = (options) => Layer.effect(ToggldClient, make(options)).pipe(Layer.provide(httpLayer(options.fetch)), Layer.provide(webSocketLayer(options.sync?.webSocketConstructor)));
-//#endregion
 export { layer as n, ToggldClient as t };

package/dist/effect.d.mts

@@ -1,7 +1,5 @@
-import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-CPtRV5-5.mjs";
+import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-hdTQWEM5.mjs";
 import { Context, Effect, Layer } from "effect";
-
-//#region src/internal/core.d.ts
 /** The evaluation surface of a Toggld client. Every method is non-failing. */
 interface ToggldClientShape {
   /**
@@ -10,6 +8,8 @@ interface ToggldClientShape {
    * resolve to the caller's default with `PROVIDER_NOT_READY`.
    */
   readonly ready: Effect.Effect<void>;
+  /** Send buffered telemetry. Failed windows remain queued for retry. */
+  readonly flushTelemetry: Effect.Effect<void>;
   /** Resolve a flag, returning full details with an untyped (JSON) value. */
   readonly evaluate: (key: string, defaultValue: FlagValue, context?: EvaluationContext) => Effect.Effect<EvaluationDetails<FlagValue>>;
   /** Resolve every flag for the environment (one request in remote mode; in-process in local mode). */
@@ -28,13 +28,12 @@ declare const ToggldClient_base: Context.ServiceClass<ToggldClient, "@toggld/nod
  * The Toggld client as an Effect service. Build a {@link layer} from options and
  * compose it into your runtime, then `yield* ToggldClient` to evaluate flags.
  */
-declare class ToggldClient extends ToggldClient_base {}
+export declare class ToggldClient extends ToggldClient_base {}
 /**
  * A self-contained `Layer` providing {@link ToggldClient} — it wires its own
  * HTTP and WebSocket backends, so Effect users need only provide this one
  * layer. In local mode the background sync fibers live in the layer's scope:
  * closing it (e.g. `ManagedRuntime.dispose`) stops sync and closes the stream.
  */
-declare const layer: (options: ToggldClientOptions) => Layer.Layer<ToggldClient>;
-//#endregion
-export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type EvaluationMode, type FlagMetadata, type FlagValue, type Reason, type SyncOptions, ToggldClient, type ToggldClientOptions, type ToggldClientShape, layer };
+export declare const layer: (options: ToggldClientOptions) => Layer.Layer<ToggldClient>;
+export type { ErrorCode, EvaluationContext, EvaluationDetails, EvaluationMode, FlagMetadata, FlagValue, Reason, SyncOptions, ToggldClientOptions, ToggldClientShape };

package/dist/effect.mjs

@@ -1,2 +1 @@
-import { n as layer, t as ToggldClient } from "./core-DBVGNtur.mjs";
-export { ToggldClient, layer };
+export { t as ToggldClient, n as layer } from "./core-CezJWPV4.mjs";

package/dist/index.d.mts

@@ -1,12 +1,10 @@
-import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-CPtRV5-5.mjs";
-
-//#region src/index.d.ts
+import { a as ErrorCode, c as FlagValue, i as ToggldClientOptions, l as Reason, n as EvaluationMode, o as EvaluationContext, r as SyncOptions, s as FlagMetadata, t as EvaluationDetails } from "./types-hdTQWEM5.mjs";
 /**
  * A Toggld client backed by a private Effect runtime. Create one with {@link
  * ToggldClient.create} and {@link ToggldClient.close} it on shutdown to release
  * the runtime.
  */
-declare class ToggldClient {
+export declare class ToggldClient {
   #private;
   private constructor();
   /**
@@ -22,6 +20,8 @@ declare class ToggldClient {
    * want to await sync explicitly.
    */
   ready(): Promise<void>;
+  /** Send buffered counts without failing evaluations. Failed windows remain queued. */
+  flushTelemetry(): Promise<void>;
   /** Resolve a flag, returning full details with an untyped (JSON) value. */
   evaluate(key: string, defaultValue: FlagValue, context?: EvaluationContext): Promise<EvaluationDetails<FlagValue>>;
   /** Resolve every flag for the environment in one request (OFREP bulk). */
@@ -37,5 +37,4 @@ declare class ToggldClient {
   /** Dispose the underlying runtime. The client is unusable afterwards. */
   close(): Promise<void>;
 }
-//#endregion
-export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type EvaluationMode, type FlagMetadata, type FlagValue, type Reason, type SyncOptions, ToggldClient, type ToggldClientOptions };
+export type { ErrorCode, EvaluationContext, EvaluationDetails, EvaluationMode, FlagMetadata, FlagValue, Reason, SyncOptions, ToggldClientOptions };

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { n as layer, t as ToggldClient$1 } from "./core-DBVGNtur.mjs";
+import { n as layer, t as ToggldClient$1 } from "./core-CezJWPV4.mjs";
 import { Duration, Effect, ManagedRuntime } from "effect";
-//#region src/index.ts
+// src/index.ts
 /**
 * `@toggld/node` — the default entry: a plain Promise API.
 *
@@ -56,6 +56,10 @@ var ToggldClient = class ToggldClient {
 	ready() {
 		return this.#runtime.runPromise(this.#client.ready);
 	}
+	/** Send buffered counts without failing evaluations. Failed windows remain queued. */
+	flushTelemetry() {
+		return this.#runtime.runPromise(this.#client.flushTelemetry);
+	}
 	/** Resolve a flag, returning full details with an untyped (JSON) value. */
 	evaluate(key, defaultValue, context) {
 		return this.#runtime.runPromise(this.#client.evaluate(key, defaultValue, context));
@@ -93,5 +97,4 @@ var ToggldClient = class ToggldClient {
 		return this.#runtime.dispose();
 	}
 };
-//#endregion
 export { ToggldClient };

package/dist/{src-CCPvsrli.mjs → src-B_M-Oix8.mjs}

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-//#region ../schema/src/audit.ts
+// ../schema/src/audit.ts
 /**
 * Audit log wire contract (ADR-0009). Every management/control-plane mutation is
 * recorded as one append-only {@link AuditEvent}; a tenant reads its own trail
@@ -27,12 +27,14 @@ const AuditAction = Schema.Literals([
 	"segment.create",
 	"segment.update",
 	"segment.delete",
+	"environment.update",
 	"environment.create",
 	"environment.delete",
 	"apiKey.create",
 	"apiKey.revoke",
 	"tenant.create",
-	"tenant.update"
+	"tenant.update",
+	"tenant.delete"
 ]);
 /** The kind of resource an event concerns; pairs with `resourceId`. */
 const AuditResourceType = Schema.Literals([
@@ -60,8 +62,7 @@ Schema.Struct({
 	/** ISO 8601 timestamp the change was recorded. */
 	occurredAt: Schema.String
 });
-//#endregion
-//#region ../schema/src/auth.ts
+// ../schema/src/auth.ts
 /**
 * Authorization role carried by an API key.
 *
@@ -73,6 +74,7 @@ Schema.Struct({
 	id: Schema.String,
 	name: Schema.String,
 	createdAt: Schema.String,
+	defaultEnvironmentId: Schema.optional(Schema.NullOr(Schema.String)),
 	/**
 	* Max number of flag *definitions* the tenant may hold; `null` = unlimited.
 	* The free tier is 10 (the DB column default). The flag API treats this as an
@@ -84,16 +86,26 @@ Schema.Struct({
 Schema.Struct({
 	id: Schema.String,
 	tenantId: Schema.String,
-	/** Stable slug, unique within the tenant (e.g. `production`). */
+	isProduction: Schema.optional(Schema.Boolean),
+	isDefault: Schema.optional(Schema.Boolean),
+	/** Key, unique within the tenant (e.g. `production`). */
 	key: Schema.String,
 	name: Schema.String,
 	createdAt: Schema.String
 });
 /** Body for creating an environment (POST /admin/v1/tenants/:tenantId/environments). */
 const CreateEnvironmentInput = Schema.Struct({
+	isProduction: Schema.optional(Schema.Boolean),
+	makeDefault: Schema.optional(Schema.Boolean),
 	key: Schema.String.check(Schema.isMinLength(1)),
 	name: Schema.String.check(Schema.isMinLength(1))
 });
+Schema.Struct({
+	key: Schema.optional(Schema.String.check(Schema.isMinLength(1))),
+	name: Schema.optional(Schema.String.check(Schema.isMinLength(1))),
+	isProduction: Schema.optional(Schema.Boolean),
+	makeDefault: Schema.optional(Schema.Boolean)
+});
 Schema.Struct({
 	id: Schema.String,
 	tenantId: Schema.String,
@@ -137,8 +149,7 @@ Schema.Struct({
 	name: Schema.optionalKey(Schema.String),
 	environment: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1)))
 });
-//#endregion
-//#region ../schema/src/value.ts
+// ../schema/src/value.ts
 /**
 * The OpenFeature flag value types. Every flag declares one of these; variant
 * values and resolved values are validated against it.
@@ -168,31 +179,39 @@ const MetadataValue = Schema.Union([
 	Schema.Boolean
 ]);
 const FlagMetadata = Schema.Record(Schema.String, MetadataValue);
-//#endregion
-//#region ../schema/src/context.ts
+// ../schema/src/context.ts
 /**
 * An OpenFeature evaluation context: an optional `targetingKey` "identifying
 * the subject of the flag evaluation" (Requirement 3.1.1) plus arbitrary
 * custom fields (Requirement 3.1.2). We accept any JSON-valued attributes.
 */
 const EvaluationContext = Schema.Record(Schema.String, FlagValue);
-Schema.ErrorClass("FlagNotFound")({
+Schema.Error("EnvironmentConflict")({
+	_tag: Schema.tag("EnvironmentConflict"),
+	message: Schema.String
+});
+Schema.Error("FlagNotFound")({
 	_tag: Schema.tag("FlagNotFound"),
 	flagKey: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("FlagAlreadyExists")({
+Schema.Error("FlagConflict")({
+	_tag: Schema.tag("FlagConflict"),
+	flagKey: Schema.String,
+	message: Schema.String
+});
+Schema.Error("FlagAlreadyExists")({
 	_tag: Schema.tag("FlagAlreadyExists"),
 	flagKey: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("FlagValidationError")({
+Schema.Error("FlagValidationError")({
 	_tag: Schema.tag("FlagValidationError"),
 	flagKey: Schema.String,
 	issues: Schema.Array(Schema.String),
 	message: Schema.String
 });
-Schema.ErrorClass("FlagLimitExceeded")({
+Schema.Error("FlagLimitExceeded")({
 	_tag: Schema.tag("FlagLimitExceeded"),
 	/** The tenant's current flag cap. */
 	limit: Schema.Int,
@@ -200,64 +219,73 @@ Schema.ErrorClass("FlagLimitExceeded")({
 	current: Schema.Int,
 	message: Schema.String
 });
-Schema.ErrorClass("Unauthorized")({
+Schema.Error("Unauthorized")({
 	_tag: Schema.tag("Unauthorized"),
 	message: Schema.String
 });
-Schema.ErrorClass("Forbidden")({
+Schema.Error("Forbidden")({
 	_tag: Schema.tag("Forbidden"),
 	message: Schema.String
 });
-Schema.ErrorClass("TenantNotFound")({
+Schema.Error("TenantNotFound")({
 	_tag: Schema.tag("TenantNotFound"),
 	tenantId: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("TenantAlreadyExists")({
+Schema.Error("TenantNotEmpty")({
+	_tag: Schema.tag("TenantNotEmpty"),
+	tenantId: Schema.String,
+	message: Schema.String
+});
+Schema.Error("TenantAlreadyExists")({
 	_tag: Schema.tag("TenantAlreadyExists"),
 	tenantId: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("EnvironmentNotFound")({
+Schema.Error("EnvironmentNotFound")({
 	_tag: Schema.tag("EnvironmentNotFound"),
 	environment: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("EnvironmentAlreadyExists")({
+Schema.Error("EnvironmentAlreadyExists")({
 	_tag: Schema.tag("EnvironmentAlreadyExists"),
 	environment: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("ApiKeyNotFound")({
+Schema.Error("ApiKeyNotFound")({
 	_tag: Schema.tag("ApiKeyNotFound"),
 	keyId: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("SegmentNotFound")({
+Schema.Error("SegmentNotFound")({
 	_tag: Schema.tag("SegmentNotFound"),
 	segmentKey: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("SegmentAlreadyExists")({
+Schema.Error("SegmentAlreadyExists")({
 	_tag: Schema.tag("SegmentAlreadyExists"),
 	segmentKey: Schema.String,
 	message: Schema.String
 });
-Schema.ErrorClass("SegmentValidationError")({
+Schema.Error("SegmentConflict")({
+	_tag: Schema.tag("SegmentConflict"),
+	segmentKey: Schema.String,
+	message: Schema.String
+});
+Schema.Error("SegmentValidationError")({
 	_tag: Schema.tag("SegmentValidationError"),
 	segmentKey: Schema.String,
 	issues: Schema.Array(Schema.String),
 	message: Schema.String
 });
-Schema.ErrorClass("SegmentReferenced")({
+Schema.Error("SegmentReferenced")({
 	_tag: Schema.tag("SegmentReferenced"),
 	segmentKey: Schema.String,
 	/** Keys of the flags whose targeting still references the segment. */
 	flagKeys: Schema.Array(Schema.String),
 	message: Schema.String
 });
-//#endregion
-//#region ../schema/src/flag.ts
+// ../schema/src/flag.ts
 /**
 * Operators usable in a targeting condition. Comparisons coerce sensibly:
 * numeric operators require numbers, string operators require strings, and
@@ -389,10 +417,10 @@ const Segment = Schema.Struct({
 const Tags = Schema.Array(Schema.String.check(Schema.isMinLength(1)));
 Schema.Struct({
 	...Flag.fields,
-	tags: Tags
+	tags: Tags,
+	version: Schema.String
 });
-//#endregion
-//#region ../schema/src/resolution.ts
+// ../schema/src/resolution.ts
 /**
 * Resolution reasons. The provider "SHOULD populate the resolution details
 * structure's reason field with STATIC, DEFAULT, TARGETING_MATCH, SPLIT,
@@ -445,12 +473,12 @@ const OfrepBulkResponse = Schema.Struct({
 	flags: Schema.Array(Schema.Union([OfrepSuccess, OfrepFailure])),
 	metadata: Schema.optionalKey(FlagMetadata)
 });
-Schema.ErrorClass("OfrepFlagNotFound")({
+Schema.Error("OfrepFlagNotFound")({
 	key: Schema.String,
 	errorCode: Schema.Literal("FLAG_NOT_FOUND"),
 	errorDetails: Schema.optionalKey(Schema.String)
 });
-Schema.ErrorClass("OfrepEvaluationError")({
+Schema.Error("OfrepEvaluationError")({
 	key: Schema.String,
 	errorCode: ErrorCode,
 	errorDetails: Schema.optionalKey(Schema.String)
@@ -470,6 +498,7 @@ Schema.Struct({
 	tags: Schema.optionalKey(Tags)
 });
 Schema.Struct({
+	expectedVersion: Schema.optionalKey(Schema.String),
 	name: Schema.optionalKey(Schema.String),
 	description: Schema.optionalKey(Schema.String),
 	type: FlagType,
@@ -482,6 +511,7 @@ Schema.Struct({
 	tags: Schema.optionalKey(Tags)
 });
 Schema.Struct({
+	expectedVersion: Schema.optionalKey(Schema.String),
 	name: Schema.optionalKey(Schema.String),
 	description: Schema.optionalKey(Schema.String),
 	type: Schema.optionalKey(FlagType),
@@ -517,6 +547,8 @@ Schema.Struct({
 	rules: Schema.optionalKey(Schema.Array(SegmentRule))
 });
 Schema.Struct({
+	/** Reject a stale definition draft when supplied. */
+	expectedVersion: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
 	name: Schema.optionalKey(Schema.String),
 	description: Schema.optionalKey(Schema.String),
 	keyAttribute: Schema.optionalKey(Schema.String),
@@ -536,8 +568,7 @@ Schema.Struct({
 	/** Total members matching the (optional) query — the count line in the UI. */
 	total: Schema.Number
 });
-//#endregion
-//#region ../schema/src/sync.ts
+// ../schema/src/sync.ts
 /**
 * Definition-sync wire schemas (ADR-0001 §4): the versioned full snapshot the
 * sync surface serves to locally-evaluating SDKs, and the messages exchanged on
@@ -567,5 +598,41 @@ const SyncSnapshotMessage = Schema.Struct({
 */
 const SyncServerMessage = Schema.Union([SyncSnapshotMessage]);
 Schema.Struct({ type: Schema.Literal("resync") });
-//#endregion
+// ../schema/src/telemetry.ts
+const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+const EvaluationRollup = Schema.Struct({
+	flagKey: Identifier,
+	variant: Schema.String.check(Schema.isMaxLength(256)),
+	reason: Reason,
+	bucketStart: Schema.String.check(Schema.makeFilter((s) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:00\.000Z$/.test(s) && Number.isFinite(Date.parse(s)) && new Date(s).toISOString() === s)),
+	count: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+		minimum: 1,
+		maximum: 1e9
+	}))
+});
+Schema.Struct({
+	sdkInstanceId: Identifier,
+	windowId: Identifier,
+	rollups: Schema.Array(EvaluationRollup).check(Schema.isMinLength(1), Schema.isMaxLength(1e3))
+});
+Schema.Struct({
+	range: Schema.Literals([
+		"1h",
+		"24h",
+		"7d"
+	]),
+	from: Schema.String,
+	to: Schema.String,
+	total: Schema.Number,
+	errors: Schema.Number,
+	lastEvaluatedAt: Schema.NullOr(Schema.String),
+	timeline: Schema.Array(Schema.Struct({
+		bucketStart: Schema.String,
+		count: Schema.Number
+	})),
+	variants: Schema.Array(Schema.Struct({
+		variant: Schema.String,
+		count: Schema.Number
+	}))
+});
 export { OfrepSuccess as a, OfrepFailure as i, SyncServerMessage as n, OfrepBulkResponse as r, FlagSnapshot as t };

package/dist/{types-CPtRV5-5.d.mts → types-hdTQWEM5.d.mts}

@@ -1,4 +1,3 @@
-//#region ../spec/src/index.d.ts
 /**
  * A resolved flag value. OpenFeature permits `boolean | string | number |
  * structure`; we model the union as JSON, which also covers arrays and null for
@@ -32,8 +31,6 @@ type Reason = "STATIC" | "DEFAULT" | "TARGETING_MATCH" | "SPLIT" | "CACHED" | "D
  * @see https://openfeature.dev/specification/types
  */
 type ErrorCode = "PROVIDER_NOT_READY" | "PROVIDER_FATAL" | "FLAG_NOT_FOUND" | "PARSE_ERROR" | "TYPE_MISMATCH" | "TARGETING_KEY_MISSING" | "INVALID_CONTEXT" | "GENERAL";
-//#endregion
-//#region src/internal/types.d.ts
 /**
  * How the client resolves flags.
  *
@@ -59,9 +56,12 @@ interface SyncOptions {
    */
   readonly transport?: "ws" | "poll";
   /**
-   * Interval between snapshot polls in milliseconds. Default `30000`. Until
-   * the first snapshot arrives, the client retries faster (exponential from
-   * 250 ms) so cold starts aren't gated on this interval.
+   * Delay after each snapshot poll, in milliseconds. Default `30000`.
+   * Polling stays active while the stream is healthy to recover changes from
+   * other Node instances and dropped announcements. With successful reads,
+   * allow this delay plus two request timeouts and scheduling delays.
+   * Use a positive, finite value. Until the first snapshot arrives, the client
+   * retries faster (exponential from 250 ms).
    */
   readonly pollIntervalMs?: number;
   /**
@@ -126,6 +126,10 @@ interface ToggldClientOptions {
   readonly mode?: EvaluationMode;
   /** Background sync tuning for `mode: "local"`. Ignored in remote mode. */
   readonly sync?: SyncOptions;
+  /** Local network evaluations report grouped counts by default. Set false to disable. */
+  readonly telemetry?: false | {
+    readonly flushIntervalMs?: number;
+  };
   /**
    * Attributes merged into the evaluation context of **every** request, under
    * any per-call context (per-call attributes win on key collision). Handy for
@@ -159,5 +163,4 @@ interface EvaluationDetails<T extends FlagValue> {
   readonly errorMessage: string | undefined;
   readonly flagMetadata: FlagMetadata;
 }
-//#endregion
 export { ErrorCode as a, FlagValue as c, ToggldClientOptions as i, Reason as l, EvaluationMode as n, EvaluationContext as o, SyncOptions as r, FlagMetadata as s, EvaluationDetails as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toggld/node",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Toggld SDK for Node.js — local flag evaluation with a background definition sync. Plain Promise API by default; native Effect API via @toggld/node/effect.",
   "license": "Apache-2.0",
   "homepage": "https://toggld.io",
@@ -40,11 +40,11 @@
     "access": "public"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.78"
+    "effect": "4.0.6"
   },
   "devDependencies": {
-    "tsdown": "^0.22.2",
-    "typescript": "5.8.3",
+    "tsdown": "^0.23.2",
+    "typescript": "6.0.3",
     "unrun": "^0.3.1",
     "@toggld/engine": "0.1.0",
     "@toggld/schema": "0.1.0",