@dr-sentry/sdk 1.1.0 → 1.2.0

package/README.md

@@ -40,6 +40,42 @@ const config = await client.jsonValue('rate-limits', { rpm: 100 });
 client.close();
 ```
 
+## Status reporting (optional)
+
+Enable `reportStatus` to have the SDK push version + health to DeploySentry automatically. No separate startup code needed — the SDK posts `POST /applications/:id/status` on init and on an interval.
+
+```typescript
+const client = new DeploySentryClient({
+  apiKey: process.env.DS_API_KEY!,
+  environment: 'production',
+  project: 'my-app',
+  application: 'my-web-app',
+
+  // Agentless status reporting
+  applicationId: process.env.DS_APPLICATION_ID!, // UUID of the app
+  reportStatus: true,
+  reportStatusIntervalMs: 30_000,                // default; 0 = startup-only
+  reportStatusVersion: process.env.APP_VERSION,   // optional override
+  reportStatusCommitSha: process.env.GIT_SHA,
+  reportStatusDeploySlot: process.env.DS_DEPLOY_SLOT, // "stable" | "canary"
+  reportStatusTags: { region: process.env.REGION ?? 'unknown' },
+  reportStatusHealthProvider: async () => ({
+    state: (await isDbUp()) ? 'healthy' : 'degraded',
+    score: 0.99,
+  }),
+});
+
+await client.initialize();
+```
+
+The API key must carry the `status:write` scope and be scoped to a single application + environment. When `reportStatus` is `true` but `applicationId` is omitted, the reporter logs a warning and is disabled — flag evaluation continues to work.
+
+Without a `reportStatusHealthProvider`, the SDK sends `health: "healthy"` on every tick ("process alive" floor). Supply a provider if your app can detect degradation (stale DB, downstream outages, etc.).
+
+Version auto-detection (when `reportStatusVersion` is omitted) checks these env vars in order: `APP_VERSION`, `GIT_SHA`, `GIT_COMMIT`, `SOURCE_COMMIT`, `RAILWAY_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, `VERCEL_GIT_COMMIT_SHA`, `HEROKU_SLUG_COMMIT`, `npm_package_version` — falling back to the literal string `"unknown"`.
+
+The first `/status` report with a version DeploySentry has not seen auto-creates a `mode=record` deployment with `source="app-push"`, so deploy history populates even without a Railway/Render/etc. webhook configured.
+
 ## Evaluation Context
 
 Pass targeting context with every evaluation:
@@ -62,7 +98,7 @@ Every flag carries structured metadata describing its purpose, ownership, and li
 ```typescript
 const result = await client.detail('new-checkout');
 
-console.log(result.metadata.category);   // 'release' | 'feature' | 'experiment' | 'ops' | 'permission'
+console.log(result.metadata.category);   // 'release' | 'feature' | 'experiment' | 'ops' | 'permission' | 'envvar'
 console.log(result.metadata.purpose);    // "Gradual rollout of new checkout flow"
 console.log(result.metadata.owners);     // ["payments-team", "jane@example.com"]
 console.log(result.metadata.isPermanent); // false
@@ -81,6 +117,7 @@ Flags are classified into categories that drive lifecycle policies:
 | `experiment` | A/B tests and experiments with defined end dates    |
 | `ops`        | Operational controls (kill switches, rate limits)   |
 | `permission` | Entitlement and access-control flags                |
+| `envvar`     | Non-secret environment variable tracking            |
 
 Query by category:
 
@@ -113,6 +150,36 @@ List all cached flags:
 const flags = client.allFlags();
 ```
 
+## Inspecting Flag Sources (admin / support view)
+
+`inspect()` returns a provenance-tagged snapshot of every flag the SDK currently knows about — drawn from all sources at once (live server cache, offline file config, and offline defaults). Each entry reports the resolved value, its type, **where the value came from**, an evaluation reason, and when it was last fetched. Wire it into an admin or support panel to see exactly what an application is serving and why.
+
+```typescript
+const view = client.inspect();
+// [
+//   {
+//     key: 'new-checkout',
+//     value: true,
+//     type: 'boolean',
+//     enabled: true,
+//     source: 'server',        // 'server' | 'cache' | 'file' | 'default'
+//     reason: 'LIVE',          // LIVE | CACHE | OFFLINE_FILE | OFFLINE_DEFAULT | DEFAULT
+//     fetchedAt: '2026-06-23T12:00:00.000Z',
+//     stale: false,            // true when a cached value is past its TTL
+//   },
+//   ...
+// ]
+```
+
+| `source` | Meaning |
+| --- | --- |
+| `server` | Fetched live from the API and still within its cache TTL. |
+| `cache` | A previously-fetched server value past its TTL, still served because the server is currently unreachable (`stale: true`). |
+| `file` | An offline file — a `mode: 'file'` config, or the offline defaults loaded via `loadDefaults*()` (the `reason` distinguishes `OFFLINE_FILE` vs `OFFLINE_DEFAULT`). |
+| `default` | No value from any source; callers receive their coded `defaultValue`. |
+
+`inspect()` is a read-only snapshot — it does not contact the server or evaluate targeting rules for a specific user.
+
 ## Register / Dispatch Pattern
 
 The register/dispatch pattern lets you centralize all flag-gated behavior in one place instead of scattering `if/else` checks throughout your codebase. Register named operations with their handlers and optional flag keys, then dispatch by operation name at the call site.
@@ -191,6 +258,37 @@ const value = await client.boolValue('any-flag', true);
 // Returns the default value: true
 ```
 
+## Offline Defaults
+
+For deployments where the SDK may briefly be unable to reach DeploySentry (CI runs without network, cold-start before SSE connects, air-gapped builds), commit a flag snapshot to your repo and load it as fallback. The SDK still prefers the live API; defaults only fire when both the API and the in-process cache are empty.
+
+Generate the snapshot with the CLI:
+
+```bash
+deploysentry flags export --application web --env production -f flags.json
+```
+
+Then load it after constructing the client:
+
+```typescript
+const client = new DeploySentryClient({
+  apiKey: process.env.DEPLOYSENTRY_API_KEY!,
+  environment: 'production',
+  project: 'my-app',
+  application: 'web',
+});
+await client.loadDefaultsFromFile('flags.json');
+// or sync from an already-parsed object:
+// client.loadDefaults(JSON.parse(fs.readFileSync('flags.json', 'utf-8')));
+```
+
+Evaluation order:
+
+1. **Live API** when reachable.
+2. **In-process cache** (entries from prior live calls).
+3. **Offline defaults** loaded above — picks the per-environment value matching your `environment` option (by UUID first, then by name, case-insensitive). Falls back to the flag's global `default_value` when no env matches.
+4. **Caller's `defaultValue`** when the flag isn't in the export.
+
 ## Configuration
 
 | Option         | Type     | Required | Default                        | Description                            |
@@ -207,15 +305,15 @@ const value = await client.boolValue('any-flag', true);
 
 ## Offline / File Mode
 
-The SDK can load flag configurations from a local YAML file instead of (or as fallback to) the server.
+The SDK can load flag configurations from a local YAML/JSON file. **The server is always the source of truth** — the exported file is a *backup/fallback only*. In production use `server-with-fallback`: the SDK reaches the server first on every evaluation and consults the local file only when the server (and the in-process cache) are unreachable. Pure `file` mode (no server contact) is intended for local development, CI, and testing — not for normal production operation.
 
 ### Modes
 
 | Mode | Behavior |
 | --- | --- |
-| `server` (default) | API calls + SSE streaming |
-| `file` | Load from YAML file, evaluate locally. No server contact. |
-| `server-with-fallback` | Try server first. If unavailable, fall back to YAML file. |
+| `server` (default) | API calls + SSE streaming. Server only. |
+| `file` | Load from local file, evaluate locally. **No server contact — dev/CI/testing only.** |
+| `server-with-fallback` | **Recommended for resilience.** Always try the server first; fall back to the local file only when the server is unreachable, then return to live as soon as it recovers. |
 
 ### Usage
 

package/dist/cjs/cache.d.ts

@@ -1,4 +1,14 @@
 import { Flag } from './types';
+/** A cache entry exposed for inspection, including staleness. */
+export interface CacheInspectionEntry {
+    flag: Flag;
+    /** Epoch-ms when the entry was last written. */
+    storedAt: number;
+    /** Epoch-ms when the entry's TTL elapses. */
+    expiresAt: number;
+    /** True when the TTL has elapsed but the entry is still held. */
+    stale: boolean;
+}
 /**
  * In-memory flag cache with per-entry TTL support.
  *
@@ -13,14 +23,31 @@ export declare class FlagCache {
      *                Defaults to 60 000 (1 minute).
      */
     constructor(ttlMs?: number);
-    /** Store or update a single flag in the cache. */
-    set(flag: Flag): void;
+    /**
+     * Store or update a single flag in the cache.
+     *
+     * Pass `durable: true` for flags drawn from a full server sync (or a restored
+     * disk snapshot) so they never expire — the resilient sync engine keeps them
+     * fresh and the local copy must remain serveable while the server is
+     * unreachable. Omit it for single-flag SSE updates, which inherit the TTL.
+     */
+    set(flag: Flag, opts?: {
+        durable?: boolean;
+    }): void;
     /** Bulk-insert flags, replacing any stale entries. */
-    setMany(flags: Flag[]): void;
+    setMany(flags: Flag[], opts?: {
+        durable?: boolean;
+    }): void;
     /** Retrieve a flag by key. Returns `undefined` if missing or expired. */
     get(key: string): Flag | undefined;
     /** Return all non-expired flags currently in the cache. */
     getAll(): Flag[];
+    /**
+     * Return every entry held in the cache — including stale (TTL-elapsed)
+     * entries — without evicting anything. For inspection / admin views only;
+     * read paths should use {@link get} / {@link getAll} which evict.
+     */
+    entries(): CacheInspectionEntry[];
     /** Remove a single key from the cache. */
     delete(key: string): void;
     /** Remove all expired entries. Returns the number of entries purged. */

package/dist/cjs/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAO/B;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;OAGG;gBACS,KAAK,GAAE,MAAe;IAIlC,kDAAkD;IAClD,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAOrB,sDAAsD;IACtD,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAM5B,yEAAyE;IACzE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAYlC,2DAA2D;IAC3D,MAAM,IAAI,IAAI,EAAE;IAehB,0CAA0C;IAC1C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,wEAAwE;IACxE,YAAY,IAAI,MAAM;IActB,uCAAuC;IACvC,KAAK,IAAI,IAAI;IAIb,8DAA8D;IAC9D,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAQ/B,iEAAiE;AACjE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,IAAI,CAAC;IACX,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;OAGG;gBACS,KAAK,GAAE,MAAe;IAIlC;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IASnD,sDAAsD;IACtD,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAM1D,yEAAyE;IACzE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAYlC,2DAA2D;IAC3D,MAAM,IAAI,IAAI,EAAE;IAehB;;;;OAIG;IACH,OAAO,IAAI,oBAAoB,EAAE;IAcjC,0CAA0C;IAC1C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,wEAAwE;IACxE,YAAY,IAAI,MAAM;IActB,uCAAuC;IACvC,KAAK,IAAI,IAAI;IAIb,8DAA8D;IAC9D,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/cjs/cache.js

@@ -17,17 +17,26 @@ class FlagCache {
     constructor(ttlMs = 60_000) {
         this.ttlMs = ttlMs;
     }
-    /** Store or update a single flag in the cache. */
-    set(flag) {
+    /**
+     * Store or update a single flag in the cache.
+     *
+     * Pass `durable: true` for flags drawn from a full server sync (or a restored
+     * disk snapshot) so they never expire — the resilient sync engine keeps them
+     * fresh and the local copy must remain serveable while the server is
+     * unreachable. Omit it for single-flag SSE updates, which inherit the TTL.
+     */
+    set(flag, opts) {
+        const now = Date.now();
         this.store.set(flag.key, {
             flag,
-            expiresAt: Date.now() + this.ttlMs,
+            storedAt: now,
+            expiresAt: opts?.durable || this.ttlMs <= 0 ? Infinity : now + this.ttlMs,
         });
     }
     /** Bulk-insert flags, replacing any stale entries. */
-    setMany(flags) {
+    setMany(flags, opts) {
         for (const flag of flags) {
-            this.set(flag);
+            this.set(flag, opts);
         }
     }
     /** Retrieve a flag by key. Returns `undefined` if missing or expired. */
@@ -55,6 +64,24 @@ class FlagCache {
         }
         return result;
     }
+    /**
+     * Return every entry held in the cache — including stale (TTL-elapsed)
+     * entries — without evicting anything. For inspection / admin views only;
+     * read paths should use {@link get} / {@link getAll} which evict.
+     */
+    entries() {
+        const now = Date.now();
+        const result = [];
+        for (const entry of this.store.values()) {
+            result.push({
+                flag: entry.flag,
+                storedAt: entry.storedAt,
+                expiresAt: entry.expiresAt,
+                stale: now > entry.expiresAt,
+            });
+        }
+        return result;
+    }
     /** Remove a single key from the cache. */
     delete(key) {
         this.store.delete(key);

package/dist/cjs/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":";;;AAOA;;;;;GAKG;AACH,MAAa,SAAS;IACH,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,KAAK,CAAS;IAE/B;;;OAGG;IACH,YAAY,QAAgB,MAAM;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,kDAAkD;IAClD,GAAG,CAAC,IAAU;QACZ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE;YACvB,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;SACnC,CAAC,CAAC;IACL,CAAC;IAED,sDAAsD;IACtD,OAAO,CAAC,KAAa;QACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC;IACpB,CAAC;IAED,2DAA2D;IAC3D,MAAM;QACJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAW,EAAE,CAAC;QAE1B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,0CAA0C;IAC1C,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,wEAAwE;IACxE,YAAY;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,MAAM,GAAG,CAAC,CAAC;QAEf,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,MAAM,EAAE,CAAC;YACX,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,uCAAuC;IACvC,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,8DAA8D;IAC9D,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AArFD,8BAqFC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cjs/client.d.ts

@@ -1,4 +1,4 @@
-import { ClientOptions, EvaluationContext, EvaluationResult, Flag, FlagCategory } from './types';
+import { ClientOptions, EvaluationContext, EvaluationResult, Flag, FlagCategory, FlagInspection } from './types';
 /**
  * DeploySentry feature-flag client.
  *
@@ -29,9 +29,19 @@ export declare class DeploySentryClient {
     private readonly onFlagChange?;
     private readonly cache;
     private streamClient;
+    private readonly persistence;
+    private readonly resyncIntervalMs?;
+    private syncManager;
     private _initialized;
     private flagConfig;
+    private offlineDefaults;
+    private offlineDefaultsEnvUUID;
+    private flagConfigLoadedAt?;
+    private offlineDefaultsLoadedAt?;
+    private flagsVersion;
     private registry;
+    private statusReporter;
+    private readonly statusReporterOptions;
     constructor(options: ClientOptions);
     /**
      * Fetch the initial flag set and open an SSE connection for real-time
@@ -40,6 +50,7 @@ export declare class DeploySentryClient {
     initialize(): Promise<void>;
     /** Tear down the SSE connection and release resources. */
     close(): void;
+    private startStatusReporter;
     /**
      * Clear the local cache and re-fetch all flags from the server.
      * Useful when session state may have changed and the client needs
@@ -69,10 +80,53 @@ export declare class DeploySentryClient {
     flagOwners(key: string): string[];
     /** Return every flag currently held in the local cache. */
     allFlags(): Flag[];
+    /**
+     * Return a provenance-tagged view of every flag the SDK currently knows
+     * about, drawn from all sources (live server cache, offline file config,
+     * and offline defaults). Each entry reports the resolved value, its type,
+     * the {@link FlagSource | source} it came from, an evaluation reason code,
+     * and when it was last fetched / loaded.
+     *
+     * Intended for wiring into an admin or support panel so operators can see
+     * exactly what value an application is serving and where it came from. This
+     * is a read-only snapshot — it does not contact the server or evaluate
+     * targeting rules for a specific user.
+     */
+    inspect(): FlagInspection[];
     register<T extends (...args: any[]) => any>(operation: string, handler: T, flagKey?: string): void;
     dispatch<T extends (...args: any[]) => any>(operation: string, _context?: EvaluationContext): T;
     private evaluate;
+    /**
+     * Load offline default values from a flag-export file. When the live API
+     * is unreachable and the cache has no entry, the SDK falls back to these
+     * defaults for {@link boolValue} / {@link stringValue} / {@link intValue}
+     * / {@link jsonValue} calls.
+     *
+     * Accepts the JSON (default) or YAML format produced by
+     * `deploysentry flags export`.
+     *
+     * Environment matching: the SDK matches the configured `environment`
+     * option against the export's `environments[]` first by UUID, then by
+     * name (case-insensitive). When a match is found, that env's per-flag
+     * `{enabled, value}` overrides the flag's global `default_value`.
+     *
+     * @example
+     * await client.loadDefaultsFromFile('flags.json');
+     */
+    loadDefaultsFromFile(path: string): Promise<void>;
+    /**
+     * Synchronous variant of {@link loadDefaultsFromFile} that accepts an
+     * already-parsed object (or a JSON string).
+     */
+    loadDefaults(payload: unknown): void;
     private fetchAllFlags;
+    /**
+     * The project's flag-set version last loaded from the server, or `null` if
+     * no successful server load has happened (offline/file mode, or boot before
+     * the first sync). The version advances on any change to the project's flag
+     * state, so it validates exactly which flag set the SDK is serving.
+     */
+    getFlagsVersion(): number | null;
     private fetchFlag;
     private post;
     private request;

package/dist/cjs/client.d.ts.map

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