@toggld/node 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as FlagMetadata, i as EvaluationContext, n as ToggldClientOptions, o as FlagValue, r as ErrorCode, s as Reason, t as EvaluationDetails } from "./types-RmWNnA7-.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-CPtRV5-5.mjs";
 
 //#region src/index.d.ts
 /**
@@ -9,8 +9,19 @@ import { a as FlagMetadata, i as EvaluationContext, n as ToggldClientOptions, o
 declare class ToggldClient {
   #private;
   private constructor();
-  /** Create a client. Resolves once the underlying runtime is ready. */
+  /**
+   * Create a client. Resolves once the underlying runtime is ready — and, in
+   * local mode, once the first flag snapshot has synced (or `readyTimeoutMs`,
+   * default 5 s, has elapsed; the client then serves caller defaults with
+   * `PROVIDER_NOT_READY` while sync keeps retrying in the background).
+   */
   static create(options: ToggldClientOptions): Promise<ToggldClient>;
+  /**
+   * Resolves once the client has flag data to evaluate with (immediately in
+   * remote mode). Useful if `create` resolved on the ready timeout and you
+   * want to await sync explicitly.
+   */
+  ready(): 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). */
@@ -27,4 +38,4 @@ declare class ToggldClient {
   close(): Promise<void>;
 }
 //#endregion
-export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type FlagMetadata, type FlagValue, type Reason, ToggldClient, type ToggldClientOptions };
+export { type ErrorCode, type EvaluationContext, type EvaluationDetails, type EvaluationMode, type FlagMetadata, type FlagValue, type Reason, type SyncOptions, ToggldClient, type ToggldClientOptions };

package/dist/index.mjs

@@ -1,23 +1,27 @@
-import { n as layer, t as ToggldClient$1 } from "./core-zMjaOru1.mjs";
-import { ManagedRuntime } from "effect";
+import { n as layer, t as ToggldClient$1 } from "./core-DBVGNtur.mjs";
+import { Duration, Effect, ManagedRuntime } from "effect";
 //#region src/index.ts
 /**
 * `@toggld/node` — the default entry: a plain Promise API.
 *
-* Remote flag evaluation over the server's OFREP endpoints, with **no Effect in
-* any signature**. Internally it runs the Effect implementation from `./effect`
-* under a `ManagedRuntime`.
+* Flag evaluation with **no Effect in any signature**. Internally it runs the
+* Effect implementation from `./effect` under a `ManagedRuntime`.
 *
 * ```ts
 * import { ToggldClient } from "@toggld/node"
 *
-* const client = await ToggldClient.create({ sdkKey, endpoint })
+* // Local evaluation (recommended for long-lived servers): flag definitions
+* // sync in the background and every evaluation is in-process — microseconds,
+* // zero server requests.
+* const client = await ToggldClient.create({ sdkKey, endpoint, mode: "local" })
 * const on = await client.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
 * await client.close()
 * ```
 *
-* Evaluation never throws: any failure resolves to the supplied default value,
-* with the reason/error available via the `*Details` methods.
+* Omitting `mode` keeps the default **remote** evaluation (each call asks the
+* flag API over OFREP). Evaluation never throws: any failure resolves to the
+* supplied default value, with the reason/error available via the `*Details`
+* methods.
 */
 /**
 * A Toggld client backed by a private Effect runtime. Create one with {@link
@@ -31,10 +35,26 @@ var ToggldClient = class ToggldClient {
 		this.#runtime = runtime;
 		this.#client = client;
 	}
-	/** Create a client. Resolves once the underlying runtime is ready. */
+	/**
+	* Create a client. Resolves once the underlying runtime is ready — and, in
+	* local mode, once the first flag snapshot has synced (or `readyTimeoutMs`,
+	* default 5 s, has elapsed; the client then serves caller defaults with
+	* `PROVIDER_NOT_READY` while sync keeps retrying in the background).
+	*/
 	static async create(options) {
 		const runtime = ManagedRuntime.make(layer(options));
-		return new ToggldClient(runtime, await runtime.runPromise(ToggldClient$1));
+		const client = await runtime.runPromise(ToggldClient$1);
+		const readyTimeoutMs = options.sync?.readyTimeoutMs ?? 5e3;
+		await runtime.runPromise(client.ready.pipe(Effect.timeout(Duration.millis(readyTimeoutMs)), Effect.ignore));
+		return new ToggldClient(runtime, client);
+	}
+	/**
+	* Resolves once the client has flag data to evaluate with (immediately in
+	* remote mode). Useful if `create` resolved on the ready timeout and you
+	* want to await sync explicitly.
+	*/
+	ready() {
+		return this.#runtime.runPromise(this.#client.ready);
 	}
 	/** Resolve a flag, returning full details with an untyped (JSON) value. */
 	evaluate(key, defaultValue, context) {

package/dist/{core-zMjaOru1.mjs → src-CCPvsrli.mjs}

@@ -1,16 +1,4 @@
-import { Context, Duration, Effect, Layer, Schema } from "effect";
-import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
-//#region ../spec/src/index.ts
-/** True when `value` is assignable to a flag declared as `type`. */
-const valueMatchesType = (value, type) => {
-	switch (type) {
-		case "boolean": return typeof value === "boolean";
-		case "string": return typeof value === "string";
-		case "number": return typeof value === "number" && Number.isFinite(value);
-		case "object": return typeof value === "object" && value !== null;
-	}
-};
-//#endregion
+import { Schema } from "effect";
 //#region ../schema/src/audit.ts
 /**
 * Audit log wire contract (ADR-0009). Every management/control-plane mutation is
@@ -36,6 +24,9 @@ const AuditAction = Schema.Literals([
 	"flag.create",
 	"flag.update",
 	"flag.delete",
+	"segment.create",
+	"segment.update",
+	"segment.delete",
 	"environment.create",
 	"environment.delete",
 	"apiKey.create",
@@ -46,6 +37,7 @@ const AuditAction = Schema.Literals([
 /** The kind of resource an event concerns; pairs with `resourceId`. */
 const AuditResourceType = Schema.Literals([
 	"flag",
+	"segment",
 	"environment",
 	"apiKey",
 	"tenant"
@@ -102,6 +94,15 @@ const CreateEnvironmentInput = Schema.Struct({
 	key: Schema.String.check(Schema.isMinLength(1)),
 	name: Schema.String.check(Schema.isMinLength(1))
 });
+Schema.Struct({
+	id: Schema.String,
+	tenantId: Schema.String,
+	/** The single environment this token is scoped to. */
+	environmentId: Schema.String,
+	/** The full token value — intentionally exposed; it is non-secret. */
+	token: Schema.String,
+	createdAt: Schema.String
+});
 /**
 * Public view of an API key — safe to list. Never includes the secret token or
 * its hash; only a non-secret prefix for human identification.
@@ -232,6 +233,29 @@ Schema.ErrorClass("ApiKeyNotFound")({
 	keyId: Schema.String,
 	message: Schema.String
 });
+Schema.ErrorClass("SegmentNotFound")({
+	_tag: Schema.tag("SegmentNotFound"),
+	segmentKey: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("SegmentAlreadyExists")({
+	_tag: Schema.tag("SegmentAlreadyExists"),
+	segmentKey: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("SegmentValidationError")({
+	_tag: Schema.tag("SegmentValidationError"),
+	segmentKey: Schema.String,
+	issues: Schema.Array(Schema.String),
+	message: Schema.String
+});
+Schema.ErrorClass("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
 /**
@@ -287,12 +311,19 @@ const ServeRollout = Schema.Struct({
 	splits: Schema.Array(Split)
 });
 const Serve = Schema.Union([ServeVariant, ServeRollout]);
+/** A reference to a reusable {@link Segment} from a targeting rule (ADR-0006). */
+const SegmentRef = Schema.Struct({
+	segment: Schema.String,
+	negate: Schema.optionalKey(Schema.Boolean)
+});
 /** An ordered targeting rule. The first rule whose conditions all match wins. */
 const Rule = Schema.Struct({
 	id: Schema.String,
 	description: Schema.optionalKey(Schema.String),
 	/** ANDed conditions. An empty list always matches (useful as a catch-all). */
 	conditions: Schema.Array(Condition),
+	/** Reusable segments, ANDed with `conditions` (ADR-0006). */
+	segments: Schema.optionalKey(Schema.Array(SegmentRef)),
 	serve: Serve
 });
 /**
@@ -320,6 +351,35 @@ const Flag = Schema.Struct({
 	createdAt: Schema.String,
 	updatedAt: Schema.String
 });
+/** How a segment's enumerated member list is distributed for evaluation. */
+const SegmentListMode = Schema.Literals([
+	"none",
+	"inline",
+	"remote"
+]);
+/** A single segment membership rule: ANDed conditions, no `serve` (ADR-0006). */
+const SegmentRule = Schema.Struct({
+	id: Schema.String,
+	description: Schema.optionalKey(Schema.String),
+	conditions: Schema.Array(Condition)
+});
+/**
+* A reusable audience definition as it rides the sync bundle (ADR-0006). Inline
+* member keys are present only for `inline` segments; `remote` segments omit
+* them and resolve via a backing-store lookup.
+*/
+const Segment = Schema.Struct({
+	key: Schema.String,
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	keyAttribute: Schema.String,
+	rules: Schema.Array(SegmentRule),
+	listMode: SegmentListMode,
+	members: Schema.optionalKey(Schema.Array(Schema.String)),
+	version: Schema.Number,
+	createdAt: Schema.String,
+	updatedAt: Schema.String
+});
 /**
 * Freeform organization labels for a flag (ADR-0008). A flag may carry any
 * number; they group/filter flags in the dashboard and have **no** effect on
@@ -433,117 +493,79 @@ Schema.Struct({
 	metadata: Schema.optionalKey(FlagMetadata),
 	tags: Schema.optionalKey(Tags)
 });
+Schema.Struct({
+	key: Schema.String,
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	keyAttribute: Schema.String,
+	rules: Schema.Array(SegmentRule),
+	listMode: Segment.fields.listMode,
+	/** Number of enumerated members in the list (0 for a rules-only segment). */
+	memberCount: Schema.Number,
+	version: Schema.Number,
+	/** Keys of the flags whose targeting references this segment, in any environment. */
+	usedBy: Schema.Array(Schema.String),
+	createdAt: Schema.String,
+	updatedAt: Schema.String
+});
+Schema.Struct({
+	key: Schema.String.check(Schema.isMinLength(1)),
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	/** Defaults to `targetingKey` server-side when omitted. */
+	keyAttribute: Schema.optionalKey(Schema.String),
+	rules: Schema.optionalKey(Schema.Array(SegmentRule))
+});
+Schema.Struct({
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	keyAttribute: Schema.optionalKey(Schema.String),
+	rules: Schema.optionalKey(Schema.Array(SegmentRule))
+});
+Schema.Struct({
+	add: Schema.optionalKey(Schema.Array(Schema.String)),
+	remove: Schema.optionalKey(Schema.Array(Schema.String))
+});
+/** One enumerated member of a segment's list. */
+const SegmentMember = Schema.Struct({
+	key: Schema.String,
+	addedAt: Schema.String
+});
+Schema.Struct({
+	members: Schema.Array(SegmentMember),
+	/** Total members matching the (optional) query — the count line in the UI. */
+	total: Schema.Number
+});
 //#endregion
-//#region src/internal/core.ts
+//#region ../schema/src/sync.ts
 /**
-* The Effect core of the Toggld Node SDK — a remote-evaluation client over the
-* server's OFREP endpoints.
-*
-* This is the canonical implementation; `../index.ts` (the plain Promise API) is
-* a thin facade that runs this under a `ManagedRuntime`. The SDK performs **no
-* local evaluation** — every call hits the flag API, which evaluates the flag
-* against the supplied context and returns the resolved value (OpenFeature
-* "remote evaluation"). Local in-process evaluation via `@toggld/engine` is a
-* later milestone (see ADR-0001).
+* Definition-sync wire schemas (ADR-0001 §4): the versioned full snapshot the
+* sync surface serves to locally-evaluating SDKs, and the messages exchanged on
+* the live sync stream. Like the OFREP schemas, these are shared by the server
+* (producer) and `@toggld/node` (consumer) so the contract cannot drift.
 *
-* OpenFeature semantics: evaluation never throws. Any failure — network error,
-* timeout, unknown flag, a server-reported error, or a value whose type doesn't
-* match the requested getter — resolves to the caller's default value with the
-* details carrying `reason: "ERROR"` and an `errorCode`.
+* `version` is opaque and equality-compared (ADR-0005 phase 1); the ordered
+* `config_version` lands in this same field later without a wire change.
 */
-const DEFAULT_TIMEOUT_MS = 5e3;
-const isBoolean = (v) => typeof v === "boolean";
-const isString = (v) => typeof v === "string";
-const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
-const isObject = (v) => valueMatchesType(v, "object");
-const okDetails = (key, s) => ({
-	flagKey: key,
-	value: s.value,
-	variant: s.variant,
-	reason: s.reason,
-	errorCode: void 0,
-	errorMessage: void 0,
-	flagMetadata: s.metadata ?? {}
-});
-const wireErrorDetails = (fallback, e) => ({
-	flagKey: e.key,
-	value: fallback,
-	variant: void 0,
-	reason: "ERROR",
-	errorCode: e.errorCode,
-	errorMessage: e.errorDetails,
-	flagMetadata: e.metadata ?? {}
-});
-const errorDetails = (key, value, errorCode, errorMessage, flagMetadata = {}) => ({
-	flagKey: key,
-	value,
-	variant: void 0,
-	reason: "ERROR",
-	errorCode,
-	errorMessage,
-	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);
-/** Map a transport/decoding failure to an OpenFeature error code. */
-const codeFor = (e) => typeof e === "object" && e !== null && "_tag" in e && e._tag === "SchemaError" ? "PARSE_ERROR" : "GENERAL";
-/**
-* 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.
-*/
-var ToggldClient = class extends Context.Service()("@toggld/node/ToggldClient") {};
-const make = (options) => Effect.gen(function* () {
-	const base = yield* HttpClient.HttpClient;
-	const timeout = Duration.millis(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-	const http = base.pipe(HttpClient.mapRequest(HttpClientRequest.prependUrl(options.endpoint)), HttpClient.mapRequest(HttpClientRequest.bearerToken(options.sdkKey)));
-	const mergedContext = (context) => ({
-		...options.defaultContext,
-		...context
-	});
-	const decode = HttpClientResponse.schemaBodyJson;
-	const evaluate = (key, defaultValue, context) => Effect.gen(function* () {
-		const request = HttpClientRequest.post(`/ofrep/v1/evaluate/flags/${encodeURIComponent(key)}`).pipe(HttpClientRequest.bodyJsonUnsafe({ context: mergedContext(context) }));
-		const response = yield* http.execute(request);
-		return yield* HttpClientResponse.matchStatus(response, {
-			"2xx": (r) => Effect.map(decode(OfrepSuccess)(r), (s) => okDetails(key, s)),
-			"4xx": (r) => Effect.map(decode(OfrepFailure)(r), (e) => wireErrorDetails(defaultValue, e)),
-			orElse: (r) => Effect.succeed(errorDetails(key, defaultValue, "GENERAL", `Unexpected response status ${r.status}`))
-		});
-	}).pipe(Effect.timeout(timeout), Effect.catch((error) => Effect.succeed(errorDetails(key, defaultValue, codeFor(error), describe(error)))));
-	const evaluateAll = (context) => Effect.gen(function* () {
-		const request = HttpClientRequest.post("/ofrep/v1/evaluate/flags").pipe(HttpClientRequest.bodyJsonUnsafe({ context: mergedContext(context) }));
-		const response = yield* http.execute(request);
-		return (yield* HttpClientResponse.matchStatus(response, {
-			"2xx": (r) => decode(OfrepBulkResponse)(r),
-			orElse: (r) => Effect.fail(/* @__PURE__ */ new Error(`Unexpected response status ${r.status}`))
-		})).flags.map((entry) => "errorCode" in entry ? wireErrorDetails(null, entry) : okDetails(entry.key, entry));
-	}).pipe(Effect.timeout(timeout), Effect.catch(() => Effect.succeed([])));
-	/** 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;
-		if (guard(d.value)) return d;
-		return errorDetails(key, defaultValue, "TYPE_MISMATCH", `Flag '${key}' value is not of type ${type}`, d.flagMetadata);
-	});
-	const valueOf = (details) => Effect.map(details, (d) => d.value);
-	return {
-		evaluate,
-		evaluateAll,
-		getBooleanDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "boolean", isBoolean),
-		getBooleanValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "boolean", isBoolean)),
-		getStringDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "string", isString),
-		getStringValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "string", isString)),
-		getNumberDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "number", isNumber),
-		getNumberValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "number", isNumber)),
-		getObjectDetails: (key, defaultValue, context) => typed(key, defaultValue, context, "object", isObject),
-		getObjectValue: (key, defaultValue, context) => valueOf(typed(key, defaultValue, context, "object", isObject))
-	};
-});
-/** 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;
+/** A versioned full snapshot of one environment's resolved flag set. */
+const FlagSnapshot = Schema.Struct({
+	version: Schema.String,
+	flags: Schema.Array(Flag),
+	/** Segment definitions referenced by the flags (ADR-0006). */
+	segments: Schema.optionalKey(Schema.Array(Segment))
+});
+/** Server→client: the current snapshot (connect greeting and change pushes). */
+const SyncSnapshotMessage = Schema.Struct({
+	type: Schema.Literal("snapshot"),
+	version: Schema.String,
+	flags: Schema.Array(Flag),
+	segments: Schema.optionalKey(Schema.Array(Segment))
+});
 /**
-* A self-contained `Layer` providing {@link ToggldClient} — it wires its own
-* HTTP backend, so Effect users need only provide this one layer.
+* Every server→client sync-stream message. A single-member union today; the
+* `type` discriminant is the extension point.
 */
-const layer = (options) => Layer.effect(ToggldClient, make(options)).pipe(Layer.provide(httpLayer(options.fetch)));
+const SyncServerMessage = Schema.Union([SyncSnapshotMessage]);
+Schema.Struct({ type: Schema.Literal("resync") });
 //#endregion
-export { layer as n, ToggldClient as t };
+export { OfrepSuccess as a, OfrepFailure as i, SyncServerMessage as n, OfrepBulkResponse as r, FlagSnapshot as t };

package/dist/types-CPtRV5-5.d.mts

@@ -0,0 +1,163 @@
+//#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
+ * "object" typed flags.
+ */
+type FlagValue = null | boolean | number | string | ReadonlyArray<FlagValue> | {
+  readonly [key: string]: FlagValue;
+};
+/**
+ * Flag metadata: "arbitrary properties, with keys of type string, and values of
+ * type boolean, string, or number." (Requirement 2.2.10)
+ */
+type MetadataValue = string | number | boolean;
+type FlagMetadata = {
+  readonly [key: string]: MetadataValue;
+};
+/**
+ * An OpenFeature evaluation context: an optional `targetingKey` identifying the
+ * subject (Requirement 3.1.1) plus arbitrary custom JSON-valued attributes
+ * (Requirement 3.1.2).
+ */
+type EvaluationContext = {
+  readonly [attribute: string]: FlagValue;
+};
+/**
+ * Resolution reasons. (Requirement 2.2.5)
+ */
+type Reason = "STATIC" | "DEFAULT" | "TARGETING_MATCH" | "SPLIT" | "CACHED" | "DISABLED" | "UNKNOWN" | "STALE" | "ERROR";
+/**
+ * OpenFeature error codes.
+ * @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.
+ *
+ * - `"remote"` — every evaluation is an HTTP request to the flag API's OFREP
+ *   endpoints; the server evaluates and returns the value.
+ * - `"local"` — the client backgrounds a **definition sync** (a snapshot fetch
+ *   plus a live WebSocket stream with polling fallback) and evaluates flags
+ *   **in-process** with the bundled engine: zero server requests per
+ *   evaluation, microsecond latency, identical resolutions to the server. The
+ *   mode for long-lived servers.
+ */
+type EvaluationMode = "remote" | "local";
+/** Tuning for the background definition sync (`mode: "local"`). */
+interface SyncOptions {
+  /**
+   * How updates reach the client.
+   *
+   * - `"ws"` (default) — a live WebSocket stream (`/sync/v1/stream`) pushes a
+   *   fresh snapshot on every change, with the snapshot poll below as a
+   *   safety net (it also serves runtimes where the stream is unavailable —
+   *   the client degrades to polling automatically).
+   * - `"poll"` — no stream; only the periodic snapshot poll.
+   */
+  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.
+   */
+  readonly pollIntervalMs?: number;
+  /**
+   * How long `ToggldClient.create` waits for the first snapshot before
+   * resolving anyway, in milliseconds. Default `5000`. A client that isn't
+   * ready evaluates to caller defaults (`PROVIDER_NOT_READY`) while sync keeps
+   * retrying in the background.
+   */
+  readonly readyTimeoutMs?: number;
+  /**
+   * Custom `WebSocket` constructor for the stream transport. Defaults to the
+   * global `WebSocket` (Node ≥ 22). Useful for tests or proxies.
+   */
+  readonly webSocketConstructor?: typeof globalThis.WebSocket;
+  /**
+   * Evaluate from a local snapshot **file** instead of syncing over the network
+   * (ADR-0013) — for local development, offline runs, CI, or pinning a known
+   * ruleset. The file is a `FlagSnapshot` on disk; generate one with `npx
+   * @toggld/node pull`. A file-backed client makes no network requests and needs
+   * no reachable endpoint, key, or stream.
+   *
+   * The path is resolved highest-precedence first:
+   *
+   *   1. the `TOGGLD_FLAGS_FILE` environment variable (always wins, so a deployed
+   *      app can be redirected at a file with no code change),
+   *   2. this option when given a string path,
+   *   3. `./toggld.flags.json` when this is `true`.
+   *
+   * The file is **watched**: edits are adopted live, no restart. The poll
+   * interval above doubles as a re-read safety net (and picks the file up if it
+   * is created after the client starts).
+   */
+  readonly file?: string | boolean;
+}
+/** Configuration for a {@link https://toggld.io Toggld} client. */
+interface ToggldClientOptions {
+  /**
+   * An **evaluation** (or management) API key, sent as `Authorization: Bearer
+   * <sdkKey>`. The key is scoped to one tenant + environment server-side, so a
+   * client always evaluates against exactly that environment. Network local
+   * evaluation requires a secret key (`ffk_…`) — public browser tokens cannot
+   * read flag definitions.
+   *
+   * Optional **only** for a file-backed client ({@link SyncOptions.file}), which
+   * reads its snapshot from disk and never authenticates. Required for remote
+   * and network-synced local evaluation.
+   */
+  readonly sdkKey?: string;
+  /**
+   * Base URL of the flag API, e.g. `https://toggld-api.example.workers.dev` or
+   * `http://localhost:3000` in local development. No trailing path — the client
+   * appends the OFREP and sync routes (`/ofrep/v1/...`, `/sync/v1/...`).
+   *
+   * Optional **only** for a file-backed client ({@link SyncOptions.file}); it
+   * makes no requests. Required for remote and network-synced local evaluation.
+   */
+  readonly endpoint?: string;
+  /**
+   * Evaluation mode. Defaults to `"remote"`; prefer `"local"` on long-lived
+   * servers. See {@link EvaluationMode}.
+   */
+  readonly mode?: EvaluationMode;
+  /** Background sync tuning for `mode: "local"`. Ignored in remote mode. */
+  readonly sync?: SyncOptions;
+  /**
+   * Attributes merged into the evaluation context of **every** request, under
+   * any per-call context (per-call attributes win on key collision). Handy for
+   * process-wide dimensions such as `region` or `serviceVersion`.
+   */
+  readonly defaultContext?: EvaluationContext;
+  /** Per-request timeout in milliseconds. Default `5000`. */
+  readonly timeoutMs?: number;
+  /**
+   * Custom `fetch` implementation. Defaults to the global `fetch`. Useful for
+   * tests, proxies, or injecting retries/instrumentation.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * The outcome of evaluating a single flag — OpenFeature "evaluation details"
+ * with a value typed to the requested flag type. Mirrors {@link
+ * https://openfeature.dev/specification/sections/evaluation-details}.
+ *
+ * On any abnormal evaluation (network failure, unknown flag, type mismatch, a
+ * server-reported error) the call still resolves: `value` holds the caller's
+ * default, `reason` is `"ERROR"`, and `errorCode`/`errorMessage` describe what
+ * went wrong. Evaluation never throws.
+ */
+interface EvaluationDetails<T extends FlagValue> {
+  readonly flagKey: string;
+  readonly value: T;
+  readonly variant: string | undefined;
+  readonly reason: Reason;
+  readonly errorCode: ErrorCode | undefined;
+  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.1.0",
+  "version": "0.3.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",
@@ -22,6 +22,9 @@
   "files": [
     "dist"
   ],
+  "bin": {
+    "toggld": "./dist/cli.mjs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -41,8 +44,11 @@
   },
   "devDependencies": {
     "tsdown": "^0.22.2",
+    "typescript": "5.8.3",
     "unrun": "^0.3.1",
+    "@toggld/engine": "0.1.0",
     "@toggld/schema": "0.1.0",
+    "@toggld/server": "0.1.0",
     "@toggld/spec": "0.1.0"
   },
   "scripts": {