@toggld/node 0.2.0 → 0.3.0

package/dist/effect.d.mts

@@ -1,4 +1,4 @@
-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-DItF1mIU.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";
 import { Context, Effect, Layer } from "effect";
 
 //#region src/internal/core.d.ts

package/dist/effect.mjs

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

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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-DItF1mIU.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
 /**

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as layer, t as ToggldClient$1 } from "./core-Bx0PVoEm.mjs";
+import { n as layer, t as ToggldClient$1 } from "./core-DBVGNtur.mjs";
 import { Duration, Effect, ManagedRuntime } from "effect";
 //#region src/index.ts
 /**
@@ -44,10 +44,8 @@ var ToggldClient = class ToggldClient {
 	static async create(options) {
 		const runtime = ManagedRuntime.make(layer(options));
 		const client = await runtime.runPromise(ToggldClient$1);
-		if (options.mode === "local") {
-			const readyTimeoutMs = options.sync?.readyTimeoutMs ?? 5e3;
-			await runtime.runPromise(client.ready.pipe(Effect.timeout(Duration.millis(readyTimeoutMs)), Effect.ignore));
-		}
+		const readyTimeoutMs = options.sync?.readyTimeoutMs ?? 5e3;
+		await runtime.runPromise(client.ready.pipe(Effect.timeout(Duration.millis(readyTimeoutMs)), Effect.ignore));
 		return new ToggldClient(runtime, client);
 	}
 	/**

package/dist/src-CCPvsrli.mjs

@@ -0,0 +1,571 @@
+import { Schema } from "effect";
+//#region ../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
+* over `GET /api/v1/audit-log`. Evaluation (OFREP) reads are deliberately *not*
+* audited — this is a record of configuration *changes*, not traffic.
+*/
+/** Who performed the change. See the server's `Actor` for how each id is sourced. */
+const AuditActor = Schema.Struct({
+	type: Schema.Literals([
+		"apiKey",
+		"user",
+		"service"
+	]),
+	id: Schema.String
+});
+/**
+* Closed vocabulary of audited actions — a closed set (not free text) so filters
+* and downstream exports stay stable as resources are added. `flag.update` covers
+* both replace (PUT) and patch (PATCH); the before/after states show what moved.
+*/
+const AuditAction = Schema.Literals([
+	"flag.create",
+	"flag.update",
+	"flag.delete",
+	"segment.create",
+	"segment.update",
+	"segment.delete",
+	"environment.create",
+	"environment.delete",
+	"apiKey.create",
+	"apiKey.revoke",
+	"tenant.create",
+	"tenant.update"
+]);
+/** The kind of resource an event concerns; pairs with `resourceId`. */
+const AuditResourceType = Schema.Literals([
+	"flag",
+	"segment",
+	"environment",
+	"apiKey",
+	"tenant"
+]);
+Schema.Struct({
+	id: Schema.String,
+	/** Owning tenant; null only for control-plane events (tenant provisioning). */
+	tenantId: Schema.NullOr(Schema.String),
+	/** The environment touched; null for tenant-wide / definition-level / control-plane events. */
+	environmentId: Schema.NullOr(Schema.String),
+	actor: AuditActor,
+	action: AuditAction,
+	resourceType: AuditResourceType,
+	/** Flag key, environment id, API-key id, or tenant id. */
+	resourceId: Schema.String,
+	before: Schema.NullOr(Schema.Unknown),
+	after: Schema.NullOr(Schema.Unknown),
+	/** Non-authoritative request context (request id, source ip, …); empty in v0. */
+	metadata: Schema.Record(Schema.String, Schema.Unknown),
+	/** ISO 8601 timestamp the change was recorded. */
+	occurredAt: Schema.String
+});
+//#endregion
+//#region ../schema/src/auth.ts
+/**
+* Authorization role carried by an API key.
+*
+* - `management` — full CRUD on the tenant's flags, plus evaluation.
+* - `evaluation` — read-only evaluation (OFREP) of the tenant's flags.
+*/
+const Role = Schema.Literals(["management", "evaluation"]);
+Schema.Struct({
+	id: Schema.String,
+	name: Schema.String,
+	createdAt: 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
+	* opaque number — the web app owns the plan→limit mapping and pushes changes
+	* over the control plane (provision + PATCH). Enforced in `FlagService.create`.
+	*/
+	flagLimit: Schema.NullOr(Schema.Int)
+});
+Schema.Struct({
+	id: Schema.String,
+	tenantId: Schema.String,
+	/** Stable slug, 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({
+	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.
+*/
+const ApiKeyInfo = Schema.Struct({
+	id: Schema.String,
+	tenantId: Schema.String,
+	/** The single environment this key is scoped to. */
+	environmentId: Schema.String,
+	name: Schema.optionalKey(Schema.String),
+	role: Role,
+	prefix: Schema.String,
+	createdAt: Schema.String
+});
+Schema.Struct({
+	...ApiKeyInfo.fields,
+	token: Schema.String
+});
+Schema.Struct({
+	id: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1))),
+	name: Schema.String.check(Schema.isMinLength(1)),
+	environments: Schema.optionalKey(Schema.Array(CreateEnvironmentInput)),
+	/** Flag cap for the new tenant; omitted → the free-tier default (10). */
+	flagLimit: Schema.optionalKey(Schema.Int)
+});
+Schema.Struct({
+	name: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1))),
+	flagLimit: Schema.optionalKey(Schema.NullOr(Schema.Int))
+});
+Schema.Struct({
+	role: Role,
+	name: Schema.optionalKey(Schema.String),
+	environment: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1)))
+});
+//#endregion
+//#region ../schema/src/value.ts
+/**
+* The OpenFeature flag value types. Every flag declares one of these; variant
+* values and resolved values are validated against it.
+*
+* @see https://openfeature.dev/specification/types
+*/
+const FlagType = Schema.Literals([
+	"boolean",
+	"string",
+	"number",
+	"object"
+]);
+/**
+* A resolved flag value. OpenFeature permits `boolean | string | number |
+* structure`; we store the union as JSON, which also covers arrays and null
+* for "object" typed flags.
+*/
+const FlagValue = Schema.Json;
+/**
+* Flag metadata: "a structure supporting the definition of arbitrary
+* properties, with keys of type string, and values of type boolean, string,
+* or number." (Requirement 2.2.10)
+*/
+const MetadataValue = Schema.Union([
+	Schema.String,
+	Schema.Finite,
+	Schema.Boolean
+]);
+const FlagMetadata = Schema.Record(Schema.String, MetadataValue);
+//#endregion
+//#region ../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")({
+	_tag: Schema.tag("FlagNotFound"),
+	flagKey: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("FlagAlreadyExists")({
+	_tag: Schema.tag("FlagAlreadyExists"),
+	flagKey: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("FlagValidationError")({
+	_tag: Schema.tag("FlagValidationError"),
+	flagKey: Schema.String,
+	issues: Schema.Array(Schema.String),
+	message: Schema.String
+});
+Schema.ErrorClass("FlagLimitExceeded")({
+	_tag: Schema.tag("FlagLimitExceeded"),
+	/** The tenant's current flag cap. */
+	limit: Schema.Int,
+	/** How many flags the tenant has now (>= limit). */
+	current: Schema.Int,
+	message: Schema.String
+});
+Schema.ErrorClass("Unauthorized")({
+	_tag: Schema.tag("Unauthorized"),
+	message: Schema.String
+});
+Schema.ErrorClass("Forbidden")({
+	_tag: Schema.tag("Forbidden"),
+	message: Schema.String
+});
+Schema.ErrorClass("TenantNotFound")({
+	_tag: Schema.tag("TenantNotFound"),
+	tenantId: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("TenantAlreadyExists")({
+	_tag: Schema.tag("TenantAlreadyExists"),
+	tenantId: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("EnvironmentNotFound")({
+	_tag: Schema.tag("EnvironmentNotFound"),
+	environment: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("EnvironmentAlreadyExists")({
+	_tag: Schema.tag("EnvironmentAlreadyExists"),
+	environment: Schema.String,
+	message: Schema.String
+});
+Schema.ErrorClass("ApiKeyNotFound")({
+	_tag: Schema.tag("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
+/**
+* Operators usable in a targeting condition. Comparisons coerce sensibly:
+* numeric operators require numbers, string operators require strings, and
+* `in`/`notIn` test membership in an array literal.
+*/
+const Operator = Schema.Literals([
+	"eq",
+	"ne",
+	"in",
+	"notIn",
+	"lt",
+	"lte",
+	"gt",
+	"gte",
+	"contains",
+	"startsWith",
+	"endsWith",
+	"exists",
+	"notExists"
+]);
+/**
+* A single targeting condition tested against an attribute of the evaluation
+* context (e.g. `targetingKey`, `email`, `plan`). All conditions in a rule are
+* ANDed together.
+*/
+const Condition = Schema.Struct({
+	attribute: Schema.String,
+	operator: Operator,
+	/** Comparison operand. Ignored for `exists`/`notExists`. */
+	value: Schema.optionalKey(FlagValue)
+});
+/** A weighted slice of a percentage rollout. */
+const Split = Schema.Struct({
+	variant: Schema.String,
+	/** Relative weight; the engine normalises weights across all splits. */
+	weight: Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0))
+});
+/** Serve a single fixed variant when the rule matches → `TARGETING_MATCH`. */
+const ServeVariant = Schema.Struct({
+	type: Schema.Literal("variant"),
+	variant: Schema.String
+});
+/**
+* Serve a deterministic percentage rollout when the rule matches → `SPLIT`.
+* Bucketing is consistent for a given subject (`bucketBy`, default
+* `targetingKey`) so a subject always lands in the same slice.
+*/
+const ServeRollout = Schema.Struct({
+	type: Schema.Literal("rollout"),
+	bucketBy: Schema.optionalKey(Schema.String),
+	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
+});
+/**
+* A feature flag definition.
+*
+* Evaluation order: if `enabled` is false → serve `offVariant` (default
+* `defaultVariant`) with reason `DISABLED`; otherwise walk `targeting` in
+* order and serve the first matching rule (`TARGETING_MATCH`/`SPLIT`); if no
+* rule matches, serve `defaultVariant` with reason `STATIC`.
+*/
+const Flag = Schema.Struct({
+	key: Schema.String,
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	type: FlagType,
+	enabled: Schema.Boolean,
+	/** Named values; every served variant name must be a key here. */
+	variants: Schema.Record(Schema.String, FlagValue),
+	/** Variant served on a normal evaluation with no targeting match. */
+	defaultVariant: Schema.String,
+	/** Variant served when the flag is disabled. Defaults to `defaultVariant`. */
+	offVariant: Schema.optionalKey(Schema.String),
+	targeting: Schema.Array(Rule),
+	metadata: FlagMetadata,
+	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
+* evaluation. Deliberately separate from the spec `Flag` (and `metadata`) so
+* they never reach the OFREP wire or the engine.
+*/
+const Tags = Schema.Array(Schema.String.check(Schema.isMinLength(1)));
+Schema.Struct({
+	...Flag.fields,
+	tags: Tags
+});
+//#endregion
+//#region ../schema/src/resolution.ts
+/**
+* Resolution reasons. The provider "SHOULD populate the resolution details
+* structure's reason field with STATIC, DEFAULT, TARGETING_MATCH, SPLIT,
+* CACHED, DISABLED, UNKNOWN, STALE, ERROR or some other string."
+* (Requirement 2.2.5)
+*/
+const Reason = Schema.Literals([
+	"STATIC",
+	"DEFAULT",
+	"TARGETING_MATCH",
+	"SPLIT",
+	"CACHED",
+	"DISABLED",
+	"UNKNOWN",
+	"STALE",
+	"ERROR"
+]);
+/**
+* OpenFeature error codes.
+* @see https://openfeature.dev/specification/types
+*/
+const ErrorCode = Schema.Literals([
+	"PROVIDER_NOT_READY",
+	"PROVIDER_FATAL",
+	"FLAG_NOT_FOUND",
+	"PARSE_ERROR",
+	"TYPE_MISMATCH",
+	"TARGETING_KEY_MISSING",
+	"INVALID_CONTEXT",
+	"GENERAL"
+]);
+Schema.Struct({ context: Schema.optionalKey(EvaluationContext) });
+/** A successful single/bulk evaluation result. */
+const OfrepSuccess = Schema.Struct({
+	key: Schema.String,
+	value: FlagValue,
+	reason: Reason,
+	variant: Schema.optionalKey(Schema.String),
+	metadata: Schema.optionalKey(FlagMetadata)
+});
+/** A per-flag failure embedded in a bulk response. */
+const OfrepFailure = Schema.Struct({
+	key: Schema.String,
+	errorCode: ErrorCode,
+	errorDetails: Schema.optionalKey(Schema.String),
+	metadata: Schema.optionalKey(FlagMetadata)
+});
+/** Bulk evaluation response: a mixed list of successes and failures. */
+const OfrepBulkResponse = Schema.Struct({
+	flags: Schema.Array(Schema.Union([OfrepSuccess, OfrepFailure])),
+	metadata: Schema.optionalKey(FlagMetadata)
+});
+Schema.ErrorClass("OfrepFlagNotFound")({
+	key: Schema.String,
+	errorCode: Schema.Literal("FLAG_NOT_FOUND"),
+	errorDetails: Schema.optionalKey(Schema.String)
+});
+Schema.ErrorClass("OfrepEvaluationError")({
+	key: Schema.String,
+	errorCode: ErrorCode,
+	errorDetails: Schema.optionalKey(Schema.String)
+});
+Schema.Struct({
+	key: Schema.String.check(Schema.isMinLength(1)),
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	type: FlagType,
+	enabled: Schema.optionalKey(Schema.Boolean),
+	variants: Schema.Record(Schema.String, FlagValue),
+	defaultVariant: Schema.String,
+	offVariant: Schema.optionalKey(Schema.String),
+	targeting: Schema.optionalKey(Schema.Array(Rule)),
+	metadata: Schema.optionalKey(FlagMetadata),
+	/** Freeform organization labels (ADR-0008). Normalized server-side. */
+	tags: Schema.optionalKey(Tags)
+});
+Schema.Struct({
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	type: FlagType,
+	enabled: Schema.optionalKey(Schema.Boolean),
+	variants: Schema.Record(Schema.String, FlagValue),
+	defaultVariant: Schema.String,
+	offVariant: Schema.optionalKey(Schema.String),
+	targeting: Schema.optionalKey(Schema.Array(Rule)),
+	metadata: Schema.optionalKey(FlagMetadata),
+	tags: Schema.optionalKey(Tags)
+});
+Schema.Struct({
+	name: Schema.optionalKey(Schema.String),
+	description: Schema.optionalKey(Schema.String),
+	type: Schema.optionalKey(FlagType),
+	enabled: Schema.optionalKey(Schema.Boolean),
+	variants: Schema.optionalKey(Schema.Record(Schema.String, FlagValue)),
+	defaultVariant: Schema.optionalKey(Schema.String),
+	offVariant: Schema.optionalKey(Schema.String),
+	targeting: Schema.optionalKey(Schema.Array(Rule)),
+	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 ../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
+* the live sync stream. Like the OFREP schemas, these are shared by the server
+* (producer) and `@toggld/node` (consumer) so the contract cannot drift.
+*
+* `version` is opaque and equality-compared (ADR-0005 phase 1); the ordered
+* `config_version` lands in this same field later without a wire change.
+*/
+/** 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))
+});
+/**
+* Every server→client sync-stream message. A single-member union today; the
+* `type` discriminant is the extension point.
+*/
+const SyncServerMessage = Schema.Union([SyncSnapshotMessage]);
+Schema.Struct({ type: Schema.Literal("resync") });
+//#endregion
+export { OfrepSuccess as a, OfrepFailure as i, SyncServerMessage as n, OfrepBulkResponse as r, FlagSnapshot as t };

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

@@ -76,23 +76,49 @@ interface SyncOptions {
    * 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. Local evaluation
-   * requires a secret key (`ffk_…`) — public browser tokens cannot read flag
-   * definitions.
+   * 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;
+  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;
+  readonly endpoint?: string;
   /**
    * Evaluation mode. Defaults to `"remote"`; prefer `"local"` on long-lived
    * servers. See {@link EvaluationMode}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toggld/node",
-  "version": "0.2.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",
     ".": {