@dr-sentry/sdk 1.1.0 → 1.2.0

package/dist/esm/sync.d.ts

@@ -0,0 +1,105 @@
+import { Flag } from './types.js';
+/** Timing knobs for the resilient sync engine. All values in milliseconds. */
+export interface SyncTiming {
+    /** Steady-state full-resync interval while the SSE stream is healthy. */
+    steadyIntervalMs: number;
+    /** Resync interval while the stream is down but the server is reachable. */
+    streamDownResyncMs: number;
+    /** First retry delay after a failed full fetch (escalates to max). */
+    retryInitialMs: number;
+    /** Cap on the escalating retry delay after repeated fetch failures. */
+    retryMaxMs: number;
+    /** No stream activity within this window marks the stream unhealthy. */
+    streamStaleAfterMs: number;
+}
+export declare const DEFAULT_SYNC_TIMING: SyncTiming;
+interface SyncManagerOptions {
+    /** Fetch the full flag set from the server. Throws on failure. */
+    fetchAll: () => Promise<Flag[]>;
+    /** Called with the authoritative full flag set after every successful sync. */
+    onSynced: (flags: Flag[]) => void;
+    timing?: Partial<SyncTiming>;
+    /** Returns epoch-ms; injectable for tests. Defaults to Date.now. */
+    now?: () => number;
+    log?: (msg: string) => void;
+}
+/**
+ * Drives full flag resynchronisation so the local copy is never out of sync
+ * with the server unless the connection is completely down.
+ *
+ * Cadence is chosen each tick from observed health:
+ *
+ *  - **Last fetch failed** → aggressive retry (escalating {@link SyncTiming.retryInitialMs}
+ *    → {@link SyncTiming.retryMaxMs}). Covers both boot and mid-flight outages:
+ *    "retry frequently until successful".
+ *  - **Stream healthy** (recent ping) → steady 10-minute safety-net resync;
+ *    SSE delivers individual changes in between.
+ *  - **Stream down but server reachable** → fast 30-second resync so flags
+ *    cannot drift while the realtime channel is dead.
+ *
+ * A stream reconnect triggers an immediate resync to recover any change events
+ * missed while disconnected.
+ */
+export declare class SyncManager {
+    private readonly fetchAll;
+    private readonly onSynced;
+    private readonly timing;
+    private readonly now;
+    private readonly log;
+    private timer;
+    private stopped;
+    private running;
+    private lastFetchOk;
+    private retryMs;
+    private streamConnected;
+    private lastStreamActivity;
+    private streamDropped;
+    /** Resolves once the first successful full sync completes. */
+    readonly firstSync: Promise<void>;
+    private resolveFirstSync;
+    constructor(options: SyncManagerOptions);
+    /** True once at least one full sync has succeeded. */
+    get isSynced(): boolean;
+    /**
+     * Begin the sync loop. Runs one sync immediately, then self-schedules.
+     * Returns when the loop is armed (does not wait for the first sync — await
+     * {@link firstSync} for that).
+     */
+    start(): void;
+    /**
+     * Seed the engine with an already-fetched flag set (e.g. the boot fetch) so
+     * it applies it via {@link SyncManagerOptions.onSynced} and schedules the
+     * next resync, avoiding an immediate duplicate fetch.
+     */
+    seed(flags: Flag[]): void;
+    /** Stop all scheduled syncs. */
+    stop(): void;
+    /**
+     * Record that the SSE stream connected.
+     *
+     * On a reconnect after a drop, resync immediately to recover change events
+     * missed while disconnected. The first-ever open is benign — boot already
+     * loaded the full set (via {@link seed} or the initial fetch) — so it only
+     * reschedules the next tick to reflect the now-healthy steady cadence
+     * instead of forcing a redundant fetch.
+     */
+    noteStreamOpen(): void;
+    /** Record inbound stream activity (heartbeat or data event). */
+    noteStreamActivity(): void;
+    /** Record that the SSE stream errored / closed. */
+    noteStreamError(): void;
+    private streamHealthy;
+    /** Force a resync as soon as possible without waiting for the next tick. */
+    private triggerNow;
+    /**
+     * Recompute the next tick's delay from current health without fetching.
+     * Used when stream health changes (e.g. the first open turns an unhealthy
+     * 30s cadence into the steady 10-minute one) but no immediate resync is
+     * warranted.
+     */
+    private reschedule;
+    private tick;
+    private schedule;
+}
+export {};
+//# sourceMappingURL=sync.d.ts.map

package/dist/esm/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,mBAAmB,EAAE,UAMjC,CAAC;AAEF,UAAU,kBAAkB;IAC1B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAwB;IAE5C,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,aAAa,CAAS;IAE9B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,CAAC,gBAAgB,CAAc;gBAE1B,OAAO,EAAE,kBAAkB;IAYvC,sDAAsD;IACtD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IASzB,gCAAgC;IAChC,IAAI,IAAI,IAAI;IAQZ;;;;;;;;OAQG;IACH,cAAc,IAAI,IAAI;IAWtB,gEAAgE;IAChE,kBAAkB,IAAI,IAAI;IAI1B,mDAAmD;IACnD,eAAe,IAAI,IAAI;IAKvB,OAAO,CAAC,aAAa;IAOrB,4EAA4E;IAC5E,OAAO,CAAC,UAAU;IASlB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;YASJ,IAAI;IAkBlB,OAAO,CAAC,QAAQ;CAkBjB"}

package/dist/esm/sync.js

@@ -0,0 +1,187 @@
+export const DEFAULT_SYNC_TIMING = {
+    steadyIntervalMs: 600_000, // 10 minutes — safety net while SSE keeps us live.
+    streamDownResyncMs: 30_000, // poll every 30s when the stream is dead.
+    retryInitialMs: 1_000,
+    retryMaxMs: 15_000,
+    streamStaleAfterMs: 30_000, // server pings every ~10s; 30s = three missed.
+};
+/**
+ * Drives full flag resynchronisation so the local copy is never out of sync
+ * with the server unless the connection is completely down.
+ *
+ * Cadence is chosen each tick from observed health:
+ *
+ *  - **Last fetch failed** → aggressive retry (escalating {@link SyncTiming.retryInitialMs}
+ *    → {@link SyncTiming.retryMaxMs}). Covers both boot and mid-flight outages:
+ *    "retry frequently until successful".
+ *  - **Stream healthy** (recent ping) → steady 10-minute safety-net resync;
+ *    SSE delivers individual changes in between.
+ *  - **Stream down but server reachable** → fast 30-second resync so flags
+ *    cannot drift while the realtime channel is dead.
+ *
+ * A stream reconnect triggers an immediate resync to recover any change events
+ * missed while disconnected.
+ */
+export class SyncManager {
+    fetchAll;
+    onSynced;
+    timing;
+    now;
+    log;
+    timer = null;
+    stopped = false;
+    running = false;
+    lastFetchOk = false;
+    retryMs;
+    streamConnected = false;
+    lastStreamActivity = 0;
+    streamDropped = false;
+    /** Resolves once the first successful full sync completes. */
+    firstSync;
+    resolveFirstSync;
+    constructor(options) {
+        this.fetchAll = options.fetchAll;
+        this.onSynced = options.onSynced;
+        this.timing = { ...DEFAULT_SYNC_TIMING, ...(options.timing ?? {}) };
+        this.now = options.now ?? Date.now;
+        this.log = options.log ?? (() => { });
+        this.retryMs = this.timing.retryInitialMs;
+        this.firstSync = new Promise((resolve) => {
+            this.resolveFirstSync = resolve;
+        });
+    }
+    /** True once at least one full sync has succeeded. */
+    get isSynced() {
+        return this.lastFetchOk;
+    }
+    /**
+     * Begin the sync loop. Runs one sync immediately, then self-schedules.
+     * Returns when the loop is armed (does not wait for the first sync — await
+     * {@link firstSync} for that).
+     */
+    start() {
+        if (this.stopped)
+            return;
+        void this.tick();
+    }
+    /**
+     * Seed the engine with an already-fetched flag set (e.g. the boot fetch) so
+     * it applies it via {@link SyncManagerOptions.onSynced} and schedules the
+     * next resync, avoiding an immediate duplicate fetch.
+     */
+    seed(flags) {
+        if (this.stopped)
+            return;
+        this.lastFetchOk = true;
+        this.retryMs = this.timing.retryInitialMs;
+        this.onSynced(flags);
+        this.resolveFirstSync();
+        this.schedule();
+    }
+    /** Stop all scheduled syncs. */
+    stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Record that the SSE stream connected.
+     *
+     * On a reconnect after a drop, resync immediately to recover change events
+     * missed while disconnected. The first-ever open is benign — boot already
+     * loaded the full set (via {@link seed} or the initial fetch) — so it only
+     * reschedules the next tick to reflect the now-healthy steady cadence
+     * instead of forcing a redundant fetch.
+     */
+    noteStreamOpen() {
+        this.streamConnected = true;
+        this.lastStreamActivity = this.now();
+        if (this.streamDropped) {
+            this.streamDropped = false;
+            this.triggerNow();
+        }
+        else {
+            this.reschedule();
+        }
+    }
+    /** Record inbound stream activity (heartbeat or data event). */
+    noteStreamActivity() {
+        this.lastStreamActivity = this.now();
+    }
+    /** Record that the SSE stream errored / closed. */
+    noteStreamError() {
+        this.streamConnected = false;
+        this.streamDropped = true;
+    }
+    streamHealthy() {
+        return (this.streamConnected &&
+            this.now() - this.lastStreamActivity <= this.timing.streamStaleAfterMs);
+    }
+    /** Force a resync as soon as possible without waiting for the next tick. */
+    triggerNow() {
+        if (this.stopped || this.running)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        void this.tick();
+    }
+    /**
+     * Recompute the next tick's delay from current health without fetching.
+     * Used when stream health changes (e.g. the first open turns an unhealthy
+     * 30s cadence into the steady 10-minute one) but no immediate resync is
+     * warranted.
+     */
+    reschedule() {
+        if (this.stopped || this.running)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.schedule();
+    }
+    async tick() {
+        if (this.stopped || this.running)
+            return;
+        this.running = true;
+        try {
+            const flags = await this.fetchAll();
+            this.lastFetchOk = true;
+            this.retryMs = this.timing.retryInitialMs;
+            this.onSynced(flags);
+            this.resolveFirstSync();
+        }
+        catch (err) {
+            this.lastFetchOk = false;
+            this.log(`full resync failed: ${String(err)}`);
+        }
+        finally {
+            this.running = false;
+            this.schedule();
+        }
+    }
+    schedule() {
+        if (this.stopped)
+            return;
+        let delay;
+        if (!this.lastFetchOk) {
+            delay = this.retryMs;
+            this.retryMs = Math.min(this.retryMs * 2, this.timing.retryMaxMs);
+        }
+        else if (this.streamHealthy()) {
+            delay = this.timing.steadyIntervalMs;
+        }
+        else {
+            delay = this.timing.streamDownResyncMs;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick();
+        }, delay);
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/esm/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/sync.ts"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -2,7 +2,7 @@
  * DeploySentry SDK type definitions.
  */
 /** Categories that classify the intent and lifecycle of a feature flag. */
-export type FlagCategory = 'release' | 'feature' | 'experiment' | 'ops' | 'permission';
+export type FlagCategory = 'release' | 'feature' | 'experiment' | 'ops' | 'permission' | 'envvar';
 /** Rich metadata attached to every feature flag. */
 export interface FlagMetadata {
     /** Categorisation that drives lifecycle policies. */
@@ -31,6 +31,40 @@ export interface Flag {
     /** ISO-8601 timestamp of the last update. */
     updatedAt: string;
 }
+/**
+ * Where an inspected flag's current value originated.
+ *
+ * - `server` — fetched live from the API and still within its cache TTL.
+ * - `cache`  — a previously-fetched server value whose TTL has elapsed but
+ *              is still being served (server currently unreachable).
+ * - `file`   — an offline file: a `mode: 'file'` config, or the offline
+ *              defaults loaded via `loadDefaults*()` used as a fallback.
+ * - `default`— no value from any source; callers receive their coded default.
+ */
+export type FlagSource = 'server' | 'cache' | 'file' | 'default';
+/**
+ * A read-only view of a single flag's resolved value and provenance,
+ * suitable for wiring into an admin or support panel. Produced by
+ * {@link DeploySentryClient.inspect}.
+ */
+export interface FlagInspection {
+    /** The flag key. */
+    key: string;
+    /** The currently-resolved value (parsed to its declared type). */
+    value: unknown;
+    /** The flag's value type. `unknown` when it cannot be determined. */
+    type: 'boolean' | 'integer' | 'number' | 'string' | 'json' | 'unknown';
+    /** Whether the flag is enabled in the resolved environment. */
+    enabled: boolean;
+    /** Where {@link value} came from. */
+    source: FlagSource;
+    /** Evaluation reason code (e.g. LIVE, CACHE, OFFLINE_FILE, OFFLINE_DEFAULT, DEFAULT). */
+    reason: string;
+    /** ISO-8601 timestamp the value was last fetched / loaded. Undefined for `default`. */
+    fetchedAt?: string;
+    /** True when {@link source} is `cache` and the entry is past its TTL. */
+    stale: boolean;
+}
 /** Contextual information sent with every evaluation request. */
 export interface EvaluationContext {
     /** Identifier of the user being evaluated. */
@@ -79,6 +113,49 @@ export interface ClientOptions {
     flagFilePath?: string;
     /** Called whenever the flag cache is refreshed from an SSE change event. */
     onFlagChange?: (flags: Flag[]) => void;
+    /**
+     * Path to a local JSON file where the SDK persists the last fully-synced
+     * flag set. When set, the client survives a server outage on boot by
+     * restoring this snapshot, and the resilient sync engine retries the initial
+     * fetch in the background until it succeeds instead of throwing. Omit to keep
+     * the legacy in-memory-only behaviour (boot fetch failure throws).
+     */
+    persistencePath?: string;
+    /**
+     * Steady-state full-resync interval in ms while the SSE stream is healthy.
+     * Default: 600_000 (10 minutes). When the stream goes quiet the engine
+     * resyncs far more aggressively regardless of this value.
+     */
+    resyncIntervalMs?: number;
+    /**
+     * Application UUID. Required when `reportStatus` is true. Distinct from
+     * `application` (the slug used for flag evaluation) because the status
+     * endpoint is keyed on the UUID.
+     */
+    applicationId?: string;
+    /** Enable the status reporter. Default: false. */
+    reportStatus?: boolean;
+    /** Interval in ms between status reports. Default: 30_000. 0 = send once on init. */
+    reportStatusIntervalMs?: number;
+    /** Override the auto-detected version string. */
+    reportStatusVersion?: string;
+    /** Commit SHA reported alongside the version. */
+    reportStatusCommitSha?: string;
+    /** Optional deploy-slot tag (`stable` / `canary`). */
+    reportStatusDeploySlot?: string;
+    /** Arbitrary tags attached to every report. */
+    reportStatusTags?: Record<string, string>;
+    /**
+     * Optional callback resolving the current health. If omitted the reporter
+     * sends `state: 'healthy'` on every tick (the "process alive" floor).
+     */
+    reportStatusHealthProvider?: () => HealthReport | Promise<HealthReport>;
+}
+/** Shape returned by a status reporter's health provider. */
+export interface HealthReport {
+    state: 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
+    score?: number;
+    reason?: string;
 }
 export interface FlagConfig {
     version: number;

package/dist/esm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr-sentry/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official Node.js SDK for the DeploySentry platform – feature flag evaluation with rich metadata",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",