@dr-sentry/sdk 1.1.0 → 1.1.1

package/dist/cjs/defaults.d.ts

@@ -0,0 +1,58 @@
+/**
+ * In-memory representation of one flag from an offline-defaults export.
+ *
+ * The SDK keeps a map from flag key → OfflineFlagDefault and consults it
+ * from {@link DeploySentryClient.evaluate} when the live API and the
+ * cache both fail.
+ */
+export interface OfflineFlagDefault {
+    key: string;
+    flagType: string;
+    defaultValue: string;
+    /** Map from env UUID → per-env state from the export. */
+    envStates: Record<string, {
+        enabled: boolean;
+        value: string;
+    }>;
+}
+/** Result of parsing a YAMLExport JSON payload. */
+export interface ParsedDefaults {
+    defaults: Map<string, OfflineFlagDefault>;
+    /**
+     * The env UUID matched at load time against the configured environment.
+     * When empty, no env match was found — lookups fall back to the flag's
+     * `defaultValue`.
+     */
+    envUUID: string;
+}
+/**
+ * Parse a YAMLExport JSON payload into an OfflineFlagDefault map.
+ *
+ * `environment` is the SDK's configured environment string. It is matched
+ * against the export's `environments[]` first by UUID, then by name
+ * (case-insensitive). The first match wins.
+ */
+export declare function parseDefaults(payload: unknown, environment: string): ParsedDefaults;
+/**
+ * Resolve the offline value for a flag key. Returns `undefined` when the
+ * flag is not in the loaded defaults. When an env override exists for the
+ * resolved env UUID, its `value` is returned; otherwise the flag's global
+ * `defaultValue` is returned.
+ */
+export declare function lookupOfflineDefault(defaults: Map<string, OfflineFlagDefault>, envUUID: string, key: string): {
+    value: string;
+    enabled: boolean;
+    flagType: string;
+} | undefined;
+/**
+ * Read a defaults JSON file from disk and return the parsed payload.
+ * Accepts either raw JSON or YAML based on the file extension.
+ */
+export declare function readDefaultsFile(path: string): Promise<unknown>;
+/**
+ * Coerce an offline default raw value into the requested TypeScript type.
+ * Mirrors the BoolValue / StringValue / IntValue helpers' coercion rules
+ * so offline defaults behave identically to live results.
+ */
+export declare function coerceOfflineValue<T>(raw: string, requested: 'bool' | 'string' | 'number' | 'json'): T | undefined;
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC1C;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAqCnF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACzC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAenE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,CAAC,GAAG,SAAS,CAyClH"}

package/dist/cjs/defaults.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDefaults = parseDefaults;
+exports.lookupOfflineDefault = lookupOfflineDefault;
+exports.readDefaultsFile = readDefaultsFile;
+exports.coerceOfflineValue = coerceOfflineValue;
+const fs = __importStar(require("fs/promises"));
+/**
+ * Parse a YAMLExport JSON payload into an OfflineFlagDefault map.
+ *
+ * `environment` is the SDK's configured environment string. It is matched
+ * against the export's `environments[]` first by UUID, then by name
+ * (case-insensitive). The first match wins.
+ */
+function parseDefaults(payload, environment) {
+    if (!payload || typeof payload !== 'object') {
+        throw new Error('deploysentry: defaults payload must be an object');
+    }
+    const exp = payload;
+    if (!Array.isArray(exp.flags)) {
+        throw new Error('deploysentry: defaults payload missing flags[] array');
+    }
+    let envUUID = '';
+    if (environment && Array.isArray(exp.environments)) {
+        for (const e of exp.environments) {
+            if (e.id === environment) {
+                envUUID = e.id;
+                break;
+            }
+        }
+        if (!envUUID) {
+            for (const e of exp.environments) {
+                if (e.name && e.name.toLowerCase() === environment.toLowerCase()) {
+                    envUUID = e.id;
+                    break;
+                }
+            }
+        }
+    }
+    const defaults = new Map();
+    for (const f of exp.flags) {
+        defaults.set(f.key, {
+            key: f.key,
+            flagType: f.flag_type,
+            defaultValue: f.default_value,
+            envStates: { ...(f.environments ?? {}) },
+        });
+    }
+    return { defaults, envUUID };
+}
+/**
+ * Resolve the offline value for a flag key. Returns `undefined` when the
+ * flag is not in the loaded defaults. When an env override exists for the
+ * resolved env UUID, its `value` is returned; otherwise the flag's global
+ * `defaultValue` is returned.
+ */
+function lookupOfflineDefault(defaults, envUUID, key) {
+    const d = defaults.get(key);
+    if (!d)
+        return undefined;
+    if (envUUID) {
+        const es = d.envStates[envUUID];
+        if (es && es.value !== '') {
+            return { value: es.value, enabled: es.enabled, flagType: d.flagType };
+        }
+        if (es) {
+            // Env state exists but value is empty — use flag default with this env's enabled flag.
+            return { value: d.defaultValue, enabled: es.enabled, flagType: d.flagType };
+        }
+    }
+    return { value: d.defaultValue, enabled: true, flagType: d.flagType };
+}
+/**
+ * Read a defaults JSON file from disk and return the parsed payload.
+ * Accepts either raw JSON or YAML based on the file extension.
+ */
+async function readDefaultsFile(path) {
+    const data = await fs.readFile(path, 'utf-8');
+    if (path.endsWith('.yaml') || path.endsWith('.yml')) {
+        // Lazy-load js-yaml so SDK consumers who never call this don't pay
+        // for the dependency at startup.
+        const yaml = await Promise.resolve().then(() => __importStar(require('js-yaml')));
+        return yaml.load(data);
+    }
+    return JSON.parse(data);
+}
+/**
+ * Coerce an offline default raw value into the requested TypeScript type.
+ * Mirrors the BoolValue / StringValue / IntValue helpers' coercion rules
+ * so offline defaults behave identically to live results.
+ */
+function coerceOfflineValue(raw, requested) {
+    switch (requested) {
+        case 'bool': {
+            // raw may be a JSON literal ("true", "false") OR a plain string ("true").
+            let s = raw;
+            if (raw.length >= 2 && raw[0] === '"' && raw[raw.length - 1] === '"') {
+                s = raw.slice(1, -1);
+            }
+            const lower = s.toLowerCase();
+            if (lower === 'true')
+                return true;
+            if (lower === 'false')
+                return false;
+            return undefined;
+        }
+        case 'string': {
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === 'string')
+                    return parsed;
+            }
+            catch {
+                // not JSON — treat raw as the string itself
+            }
+            return raw;
+        }
+        case 'number': {
+            const n = Number(raw);
+            if (Number.isFinite(n))
+                return n;
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === 'number' && Number.isFinite(parsed))
+                    return parsed;
+            }
+            catch {
+                /* ignore */
+            }
+            return undefined;
+        }
+        case 'json': {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+}
+//# sourceMappingURL=defaults.js.map

package/dist/cjs/defaults.js.map

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

package/dist/cjs/index.d.ts

@@ -25,5 +25,6 @@ export { FlagCache } from './cache';
 export { FlagStreamClient } from './streaming';
 export { loadFlagConfig } from './file-loader';
 export { evaluateLocal } from './local-evaluator';
-export type { ClientOptions, EvaluationContext, EvaluationResult, Flag, FlagCategory, FlagMetadata, FlagConfig, FlagConfigFlag, FlagConfigRule, FlagConfigEnvironment, ApiError, } from './types';
+export { StatusReporter, resolveVersion } from './status-reporter';
+export type { ClientOptions, EvaluationContext, EvaluationResult, Flag, FlagCategory, FlagInspection, FlagSource, FlagMetadata, FlagConfig, FlagConfigFlag, FlagConfigRule, FlagConfigEnvironment, ApiError, HealthReport, } from './types';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,QAAQ,GACT,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnE,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,IAAI,EACJ,YAAY,EACZ,cAAc,EACd,UAAU,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/cjs/index.js

@@ -22,7 +22,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.evaluateLocal = exports.loadFlagConfig = exports.FlagStreamClient = exports.FlagCache = exports.DeploySentryClient = void 0;
+exports.resolveVersion = exports.StatusReporter = exports.evaluateLocal = exports.loadFlagConfig = exports.FlagStreamClient = exports.FlagCache = exports.DeploySentryClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "DeploySentryClient", { enumerable: true, get: function () { return client_1.DeploySentryClient; } });
 var cache_1 = require("./cache");
@@ -33,4 +33,7 @@ var file_loader_1 = require("./file-loader");
 Object.defineProperty(exports, "loadFlagConfig", { enumerable: true, get: function () { return file_loader_1.loadFlagConfig; } });
 var local_evaluator_1 = require("./local-evaluator");
 Object.defineProperty(exports, "evaluateLocal", { enumerable: true, get: function () { return local_evaluator_1.evaluateLocal; } });
+var status_reporter_1 = require("./status-reporter");
+Object.defineProperty(exports, "StatusReporter", { enumerable: true, get: function () { return status_reporter_1.StatusReporter; } });
+Object.defineProperty(exports, "resolveVersion", { enumerable: true, get: function () { return status_reporter_1.resolveVersion; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,mCAA8C;AAArC,4GAAA,kBAAkB,OAAA;AAC3B,iCAAoC;AAA3B,kGAAA,SAAS,OAAA;AAClB,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA;AACzB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AACvB,qDAAkD;AAAzC,gHAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,mCAA8C;AAArC,4GAAA,kBAAkB,OAAA;AAC3B,iCAAoC;AAA3B,kGAAA,SAAS,OAAA;AAClB,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA;AACzB,6CAA+C;AAAtC,6GAAA,cAAc,OAAA;AACvB,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AACtB,qDAAmE;AAA1D,iHAAA,cAAc,OAAA;AAAE,iHAAA,cAAc,OAAA"}

package/dist/cjs/status-reporter.d.ts

@@ -0,0 +1,42 @@
+import type { HealthReport } from './types';
+/** Options passed to StatusReporter. Internal to the SDK. */
+export interface StatusReporterOptions {
+    baseURL: string;
+    apiKey: string;
+    applicationId: string;
+    intervalMs?: number;
+    version?: string;
+    commitSha?: string;
+    deploySlot?: string;
+    tags?: Record<string, string>;
+    healthProvider?: () => HealthReport | Promise<HealthReport>;
+    /** Injection seam for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injection seam for tests. */
+    warn?: (msg: string) => void;
+}
+/**
+ * Resolve the version the app should report, in this preference order:
+ * explicit config → standard env vars → `npm_package_version` → "unknown".
+ */
+export declare function resolveVersion(explicit?: string): string;
+/**
+ * StatusReporter posts periodic `POST /applications/:id/status` updates to
+ * DeploySentry on behalf of a DeploySentryClient. Failures are swallowed
+ * (logged via `warn`) so flag evaluation is never blocked by reporting.
+ */
+export declare class StatusReporter {
+    private readonly opts;
+    private timer;
+    private stopped;
+    private backoff;
+    constructor(options: StatusReporterOptions);
+    /** Fire one immediate report and (if intervalMs > 0) schedule repeats. */
+    start(): void;
+    /** Stop scheduling further reports. In-flight reports still resolve. */
+    stop(): void;
+    /** Send exactly one report. Public for tests and explicit callers. */
+    reportOnce(): Promise<void>;
+    private tick;
+}
+//# sourceMappingURL=status-reporter.d.ts.map

package/dist/cjs/status-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-reporter.d.ts","sourceRoot":"","sources":["../../src/status-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAiB5C,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5D,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gCAAgC;IAChC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CASxD;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAGyE;IAE9F,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAK;gBAER,OAAO,EAAE,qBAAqB;IAiB1C,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAKb,wEAAwE;IACxE,IAAI,IAAI,IAAI;IAQZ,sEAAsE;IAChE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAuCnB,IAAI;CA+BnB"}

package/dist/cjs/status-reporter.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatusReporter = void 0;
+exports.resolveVersion = resolveVersion;
+/** Environment variable names probed (in order) for the running version. */
+const VERSION_ENV_CHAIN = [
+    'APP_VERSION',
+    'GIT_SHA',
+    'GIT_COMMIT',
+    'SOURCE_COMMIT',
+    'RAILWAY_GIT_COMMIT_SHA',
+    'RENDER_GIT_COMMIT',
+    'VERCEL_GIT_COMMIT_SHA',
+    'HEROKU_SLUG_COMMIT',
+];
+const MIN_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 5 * 60_000;
+/**
+ * Resolve the version the app should report, in this preference order:
+ * explicit config → standard env vars → `npm_package_version` → "unknown".
+ */
+function resolveVersion(explicit) {
+    if (explicit && explicit.trim())
+        return explicit;
+    const env = typeof process !== 'undefined' && process.env ? process.env : {};
+    for (const name of VERSION_ENV_CHAIN) {
+        const v = env[name];
+        if (v && v.trim())
+            return v;
+    }
+    if (env.npm_package_version)
+        return env.npm_package_version;
+    return 'unknown';
+}
+/**
+ * StatusReporter posts periodic `POST /applications/:id/status` updates to
+ * DeploySentry on behalf of a DeploySentryClient. Failures are swallowed
+ * (logged via `warn`) so flag evaluation is never blocked by reporting.
+ */
+class StatusReporter {
+    opts;
+    timer = null;
+    stopped = false;
+    backoff = 0;
+    constructor(options) {
+        if (!options.baseURL)
+            throw new Error('baseURL is required');
+        if (!options.apiKey)
+            throw new Error('apiKey is required');
+        if (!options.applicationId)
+            throw new Error('applicationId is required');
+        const intervalMs = options.intervalMs ?? 30_000;
+        if (intervalMs < 0)
+            throw new Error('intervalMs must be >= 0');
+        this.opts = {
+            ...options,
+            baseURL: options.baseURL.replace(/\/+$/, ''),
+            apiKey: options.apiKey,
+            applicationId: options.applicationId,
+            intervalMs,
+            warn: options.warn ?? ((msg) => console.warn('[DeploySentry] ' + msg)),
+        };
+    }
+    /** Fire one immediate report and (if intervalMs > 0) schedule repeats. */
+    start() {
+        this.stopped = false;
+        void this.tick();
+    }
+    /** Stop scheduling further reports. In-flight reports still resolve. */
+    stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Send exactly one report. Public for tests and explicit callers. */
+    async reportOnce() {
+        const version = resolveVersion(this.opts.version);
+        let health = { state: 'healthy' };
+        if (this.opts.healthProvider) {
+            try {
+                health = await this.opts.healthProvider();
+            }
+            catch (err) {
+                health = { state: 'unknown', reason: String(err?.message ?? err) };
+            }
+        }
+        const body = {
+            version,
+            health: health.state,
+        };
+        if (health.score !== undefined)
+            body.health_score = health.score;
+        if (health.reason)
+            body.health_reason = health.reason;
+        if (this.opts.commitSha)
+            body.commit_sha = this.opts.commitSha;
+        if (this.opts.deploySlot)
+            body.deploy_slot = this.opts.deploySlot;
+        if (this.opts.tags && Object.keys(this.opts.tags).length)
+            body.tags = this.opts.tags;
+        const fetchImpl = this.opts.fetchImpl ?? fetch;
+        const url = `${this.opts.baseURL}/api/v1/applications/${encodeURIComponent(this.opts.applicationId)}/status`;
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `ApiKey ${this.opts.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw new Error(`status report failed: ${res.status} ${res.statusText}`);
+        }
+    }
+    async tick() {
+        if (this.stopped)
+            return;
+        try {
+            await this.reportOnce();
+            this.backoff = 0; // success — clear backoff
+        }
+        catch (err) {
+            this.opts.warn(`status report error: ${err.message}`);
+            if (this.backoff >= MAX_BACKOFF_MS) {
+                // Already at the ceiling. Reset so the next schedule falls back to
+                // intervalMs — otherwise a server that recovers mid-outage takes up
+                // to MAX_BACKOFF_MS (5m) to be noticed, regardless of how tight the
+                // operator configured intervalMs. On the next failure the 1s ladder
+                // restarts, so the short-outage behavior (quickly re-probe while
+                // the server is still down) is preserved.
+                this.backoff = 0;
+                this.opts.warn(`status reporter backoff reset; probing every ${this.opts.intervalMs}ms`);
+            }
+            else {
+                this.backoff = this.backoff === 0 ? MIN_BACKOFF_MS : Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+            }
+        }
+        if (this.stopped)
+            return;
+        if (this.opts.intervalMs === 0)
+            return; // startup-only
+        const nextDelay = this.backoff > 0 ? this.backoff : this.opts.intervalMs;
+        this.timer = setTimeout(() => void this.tick(), nextDelay);
+        // Allow Node to exit even when the timer is pending.
+        if (typeof this.timer.unref === 'function') {
+            this.timer.unref?.();
+        }
+    }
+}
+exports.StatusReporter = StatusReporter;
+//# sourceMappingURL=status-reporter.js.map

package/dist/cjs/status-reporter.js.map

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

package/dist/cjs/types.d.ts

@@ -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,35 @@ export interface ClientOptions {
     flagFilePath?: string;
     /** Called whenever the flag cache is refreshed from an SSE change event. */
     onFlagChange?: (flags: Flag[]) => void;
+    /**
+     * 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/cjs/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/dist/esm/cache.d.ts

@@ -1,4 +1,14 @@
 import { Flag } from './types.js';
+/** 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.
  *
@@ -21,6 +31,12 @@ export declare class FlagCache {
     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/esm/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,kDAAkD;IAClD,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IASrB,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;;;;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"}