@toggld/node 0.2.0 → 0.4.0

package/dist/{types-DItF1mIU.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;
   /**
@@ -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}.
@@ -100,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
@@ -133,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.2.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",
@@ -22,6 +22,9 @@
   "files": [
     "dist"
   ],
+  "bin": {
+    "toggld": "./dist/cli.mjs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -37,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",