@techdentalkart/features 2.0.1

package/dist/nest/index.d.ts

@@ -0,0 +1,44 @@
+import { type CanActivate, type DynamicModule, type Type } from "@nestjs/common";
+import { type SetupOptions } from "../index";
+import { type FeatureContext, type Flag, type FlagSet } from "../context";
+export interface NestFeaturesOptions {
+    /** Turn the incoming request into the facts a rule may use. The only code a repo writes. */
+    context: (req: any) => FeatureContext | Promise<FeatureContext>;
+    /** Passed to setupFeatures once. Usually nothing: FEATURES_* variables decide. */
+    setup?: SetupOptions;
+    /**
+     * Serve `GET <controller>` returning `{ flags, ttlSeconds, evaluatedAt, exposure }` for the app / a browser.
+     * Give the full path (this repo has no global prefix, e.g. "customer/api/v1/features") or false.
+     */
+    controller?: string | false;
+    /**
+     * Serve `POST <exposures>` that forwards the app's exposure batches to the engine.
+     * Default: `<controller>` with the last segment replaced by "exposures"; false to disable.
+     */
+    exposures?: string | false;
+    /** Guards for those routes, e.g. an optional-auth guard so anonymous callers get defaults. */
+    guards?: Type<CanActivate>[];
+    /** How long clients may keep the answer. Default 300. */
+    ttlSeconds?: number;
+    /** Modules the guards or the context builder need (e.g. the AuthModule that provides an auth guard's service). */
+    imports?: DynamicModule["imports"];
+}
+/** Inject this anywhere: `constructor(private readonly features: FeaturesService)`. */
+export declare class FeaturesService {
+    private readonly options;
+    constructor(options: NestFeaturesOptions);
+    /** The context for this request, as the repo's builder defines it. Never throws: a failed builder means anonymous. */
+    context(req: any): Promise<FeatureContext>;
+    /** One flag for this request. A use: an experiment variant returned here is reported as an exposure. */
+    get(name: string, req: any): Promise<Flag>;
+    isEnabled(name: string, req: any): Promise<boolean>;
+    /** Every flag for this request, no exposures (the app reports when it shows something). */
+    all(req: any): Promise<FlagSet>;
+}
+/**
+ * One line in app.module.ts:
+ *   FeaturesModule.forRoot({ context: (req) => contextFromCustomer(req.customer, req.headers), controller: "customer/api/v1/features", guards: [OptionalRESTAuthGuard] })
+ */
+export declare class FeaturesModule {
+    static forRoot(options: NestFeaturesOptions): DynamicModule;
+}

package/dist/nest/index.js

@@ -0,0 +1,124 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var FeaturesModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeaturesModule = exports.FeaturesService = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../index");
+const context_1 = require("../context");
+const OPTIONS = "DENTALKART_FEATURES_OPTIONS";
+/** Inject this anywhere: `constructor(private readonly features: FeaturesService)`. */
+let FeaturesService = class FeaturesService {
+    constructor(options) {
+        this.options = options;
+    }
+    /** The context for this request, as the repo's builder defines it. Never throws: a failed builder means anonymous. */
+    async context(req) {
+        try {
+            return await this.options.context(req);
+        }
+        catch {
+            return {};
+        }
+    }
+    /** One flag for this request. A use: an experiment variant returned here is reported as an exposure. */
+    get(name, req) { return this.context(req).then((c) => index_1.features.get(name, c)); }
+    isEnabled(name, req) { return this.context(req).then((c) => index_1.features.isEnabled(name, c)); }
+    /** Every flag for this request, no exposures (the app reports when it shows something). */
+    all(req) { return this.context(req).then((c) => index_1.features.all(c)); }
+};
+exports.FeaturesService = FeaturesService;
+exports.FeaturesService = FeaturesService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], FeaturesService);
+/**
+ * One line in app.module.ts:
+ *   FeaturesModule.forRoot({ context: (req) => contextFromCustomer(req.customer, req.headers), controller: "customer/api/v1/features", guards: [OptionalRESTAuthGuard] })
+ */
+let FeaturesModule = FeaturesModule_1 = class FeaturesModule {
+    static forRoot(options) {
+        (0, index_1.setupFeatures)(options.setup);
+        const controllers = [];
+        if (options.controller) {
+            let FeaturesController = class FeaturesController {
+                constructor(svc) {
+                    this.svc = svc;
+                }
+                async list(req) {
+                    const ctx = await this.svc.context(req);
+                    const unit = (0, context_1.unitOf)(ctx);
+                    return {
+                        flags: await index_1.features.all(ctx),
+                        ttlSeconds: options.ttlSeconds ?? 300,
+                        evaluatedAt: new Date().toISOString(),
+                        // who the caller is for exposure reporting, so the app never has to work it out
+                        exposure: unit ? { unit: unit.unit, unitType: unit.unitType, platform: ctx.platform } : null,
+                    };
+                }
+            };
+            __decorate([
+                (0, common_1.Get)(),
+                __param(0, (0, common_1.Req)()),
+                __metadata("design:type", Function),
+                __metadata("design:paramtypes", [Object]),
+                __metadata("design:returntype", Promise)
+            ], FeaturesController.prototype, "list", null);
+            FeaturesController = __decorate([
+                (0, common_1.Controller)(options.controller),
+                __metadata("design:paramtypes", [FeaturesService])
+            ], FeaturesController);
+            if (options.guards?.length)
+                (0, common_1.UseGuards)(...options.guards)(FeaturesController);
+            controllers.push(FeaturesController);
+            const exposuresPath = options.exposures === undefined ? options.controller.replace(/[^/]+$/, "exposures") : options.exposures;
+            if (exposuresPath) {
+                let ExposuresController = class ExposuresController {
+                    async receive(body) {
+                        await (0, index_1.forwardExposures)(body);
+                    }
+                };
+                __decorate([
+                    (0, common_1.Post)(),
+                    (0, common_1.HttpCode)(204),
+                    __param(0, (0, common_1.Body)()),
+                    __metadata("design:type", Function),
+                    __metadata("design:paramtypes", [Object]),
+                    __metadata("design:returntype", Promise)
+                ], ExposuresController.prototype, "receive", null);
+                ExposuresController = __decorate([
+                    (0, common_1.Controller)(exposuresPath)
+                ], ExposuresController);
+                if (options.guards?.length)
+                    (0, common_1.UseGuards)(...options.guards)(ExposuresController);
+                controllers.push(ExposuresController);
+            }
+        }
+        return {
+            module: FeaturesModule_1,
+            imports: options.imports ?? [],
+            controllers,
+            providers: [
+                { provide: OPTIONS, useValue: options },
+                { provide: FeaturesService, useFactory: (o) => new FeaturesService(o), inject: [OPTIONS] },
+            ],
+            exports: [FeaturesService],
+        };
+    }
+};
+exports.FeaturesModule = FeaturesModule;
+exports.FeaturesModule = FeaturesModule = FeaturesModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], FeaturesModule);

package/dist/next/index.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import { type SetupOptions } from "../index";
+import { type FeatureContext, type FlagSet } from "../context";
+/** What a repo's context builder receives: the request's cookies and headers, already read. */
+export interface RequestFacts {
+    cookie: (name: string) => string | undefined;
+    header: (name: string) => string | undefined;
+}
+export interface NextFeaturesOptions {
+    /** Turn this request into the facts a rule may use. The only code a repo writes. */
+    context: (req: RequestFacts) => FeatureContext | Promise<FeatureContext>;
+    /** Passed to setupFeatures once. Usually nothing: FEATURES_* variables decide. */
+    setup?: SetupOptions;
+    /**
+     * The app's own route that receives browser exposures and forwards them to the engine.
+     * Default "/api/exposures"; mount `exposuresRoute` there. Set false to never report from the browser.
+     */
+    exposuresPath?: string | false;
+    /**
+     * QA escape hatch: `?flags=area.feature:on,other.flag:off` forces flags for one request when the
+     * middleware forwards it as the `x-flags-override` header. Default: allowed unless NODE_ENV is
+     * production AND NEXT_PUBLIC_ENV is "live". Set false to disable everywhere.
+     */
+    allowOverrides?: boolean;
+}
+/** Parse "a.b:on,c.d:off" onto a FlagSet. Exported for tests. */
+export declare function applyOverrides(flags: FlagSet, raw: string | undefined | null): FlagSet;
+/**
+ * Everything a Next.js repo needs, from one call in `lib/features.ts`:
+ *
+ *   export const { getFlags, FeaturesProvider, exposuresRoute } = createNextFeatures({ context: async (req) => ({ ... }) });
+ *
+ * - `getFlags()`        every flag for this visitor, resolved once per request (React.cache), never throws
+ * - `FeaturesProvider`  server component for the root layout; hands the set (and who the visitor is) to the client tree
+ * - `exposuresRoute`    `export const POST = exposuresRoute;` in app/api/exposures/route.ts
+ * Then any client component reads a typed hook from the app's entry (`@dentalkart/features/website`) or
+ * `useFlag("area.feature")` from `@dentalkart/features/react`.
+ */
+export declare function createNextFeatures(opts: NextFeaturesOptions): {
+    getFlags: () => Promise<FlagSet>;
+    FeaturesProvider: ({ children }: {
+        children: React.ReactNode;
+    }) => Promise<React.JSX.Element>;
+    exposuresRoute: (request: Request) => Promise<Response>;
+};

package/dist/next/index.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyOverrides = applyOverrides;
+exports.createNextFeatures = createNextFeatures;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const headers_1 = require("next/headers");
+const index_1 = require("../index");
+const context_1 = require("../context");
+const react_2 = require("../react");
+/** Parse "a.b:on,c.d:off" onto a FlagSet. Exported for tests. */
+function applyOverrides(flags, raw) {
+    if (!raw)
+        return flags;
+    const out = { ...flags };
+    for (const part of raw.split(",")) {
+        const i = part.lastIndexOf(":");
+        if (i <= 0)
+            continue;
+        const name = part.slice(0, i).trim(), state = part.slice(i + 1).trim();
+        if (state === "on")
+            out[name] = { ...(out[name] ?? {}), on: true };
+        else if (state === "off")
+            out[name] = { on: false };
+    }
+    return out;
+}
+/**
+ * Everything a Next.js repo needs, from one call in `lib/features.ts`:
+ *
+ *   export const { getFlags, FeaturesProvider, exposuresRoute } = createNextFeatures({ context: async (req) => ({ ... }) });
+ *
+ * - `getFlags()`        every flag for this visitor, resolved once per request (React.cache), never throws
+ * - `FeaturesProvider`  server component for the root layout; hands the set (and who the visitor is) to the client tree
+ * - `exposuresRoute`    `export const POST = exposuresRoute;` in app/api/exposures/route.ts
+ * Then any client component reads a typed hook from the app's entry (`@dentalkart/features/website`) or
+ * `useFlag("area.feature")` from `@dentalkart/features/react`.
+ */
+function createNextFeatures(opts) {
+    (0, index_1.setupFeatures)(opts.setup);
+    const overridesAllowed = opts.allowOverrides ?? !(process.env.NODE_ENV === "production" && process.env.NEXT_PUBLIC_ENV === "live");
+    const exposuresPath = opts.exposuresPath === undefined ? "/api/exposures" : opts.exposuresPath;
+    const getContext = (0, react_1.cache)(async () => {
+        try {
+            const c = await (0, headers_1.cookies)();
+            const h = await (0, headers_1.headers)();
+            const req = { cookie: (n) => c.get(n)?.value, header: (n) => h.get(n) ?? undefined };
+            return await opts.context(req);
+        }
+        catch {
+            return {};
+        }
+    });
+    const getFlags = (0, react_1.cache)(async () => {
+        try {
+            const ctx = await getContext();
+            const flags = await index_1.features.all(ctx);
+            if (!overridesAllowed)
+                return flags;
+            const h = await (0, headers_1.headers)();
+            return applyOverrides(flags, h.get("x-flags-override"));
+        }
+        catch {
+            return {};
+        }
+    });
+    async function FeaturesProvider({ children }) {
+        const [initial, ctx] = await Promise.all([getFlags(), getContext()]);
+        const unit = (0, context_1.unitOf)(ctx);
+        const exposure = exposuresPath && unit
+            ? {
+                endpoint: exposuresPath,
+                unit: unit.unit,
+                unitType: unit.unitType,
+                platform: typeof ctx.platform === "string" ? ctx.platform : "web",
+                attrs: dimensions(ctx),
+            }
+            : undefined;
+        return (0, jsx_runtime_1.jsx)(react_2.FeaturesProvider, { initial: initial, exposure: exposure, children: children });
+    }
+    /** Route handler: `export const POST = exposuresRoute;` */
+    async function exposuresRoute(request) {
+        try {
+            const body = await request.json();
+            await (0, index_1.forwardExposures)(body);
+        }
+        catch { /* a bad batch is ignored, never an error for the visitor */ }
+        return new Response(null, { status: 204 });
+    }
+    return { getFlags, FeaturesProvider, exposuresRoute };
+}
+function dimensions(ctx) {
+    const out = {};
+    for (const k of ["deviceType", "customerType", "speciality", "groupCode", "state", "district", "instadent"]) {
+        const v = ctx[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    if (typeof ctx.pincode === "string" && ctx.pincode.length >= 3)
+        out.pincodePrefix = ctx.pincode.slice(0, 3);
+    return Object.keys(out).length ? out : undefined;
+}

package/dist/providers/file.d.ts

@@ -0,0 +1,18 @@
+import { type FeatureContext, type Flag, type FlagSet } from "../context";
+import type { Provider } from "./provider";
+/**
+ * Laptop / CI source: flags from a JSON file, re-read when it changes. No rules, no context: what is
+ * in the file is what every visitor gets.
+ *   { "ims.approvals": true, "pricing.markup": 3, "ims.maintenance_banner": { "enabled": true, "message": "..." } }
+ */
+export declare class FileProvider implements Provider {
+    private readonly path;
+    readonly name = "file";
+    private cache;
+    constructor(path: string);
+    ready(): Promise<void>;
+    private readAll;
+    get(name: string, _ctx: FeatureContext): Flag;
+    all(_ctx: FeatureContext): FlagSet;
+    stop(): void;
+}

package/dist/providers/file.js

@@ -0,0 +1,76 @@
+"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.FileProvider = void 0;
+const fs = __importStar(require("fs"));
+const context_1 = require("../context");
+/**
+ * Laptop / CI source: flags from a JSON file, re-read when it changes. No rules, no context: what is
+ * in the file is what every visitor gets.
+ *   { "ims.approvals": true, "pricing.markup": 3, "ims.maintenance_banner": { "enabled": true, "message": "..." } }
+ */
+class FileProvider {
+    constructor(path) {
+        this.path = path;
+        this.name = "file";
+        this.cache = null;
+    }
+    async ready() { }
+    readAll() {
+        try {
+            const mtime = fs.statSync(this.path).mtimeMs;
+            if (!this.cache || this.cache.mtime !== mtime) {
+                this.cache = { mtime, flags: JSON.parse(fs.readFileSync(this.path, "utf8")) };
+            }
+            return this.cache.flags;
+        }
+        catch {
+            return {};
+        }
+    }
+    get(name, _ctx) {
+        const flags = this.readAll();
+        const v = flags[name] ?? flags[name.replace(/\./g, "_")];
+        return v === undefined ? context_1.OFF : (0, context_1.toFlag)(v);
+    }
+    all(_ctx) {
+        const out = {};
+        for (const [k, v] of Object.entries(this.readAll()))
+            out[k.includes(".") ? k : k.replace("_", ".")] = (0, context_1.toFlag)(v);
+        return out;
+    }
+    stop() { }
+}
+exports.FileProvider = FileProvider;

package/dist/providers/growthbook.d.ts

@@ -0,0 +1,46 @@
+import { type FeatureResult } from "@growthbook/growthbook";
+import { type FeatureContext, type Flag, type FlagSet } from "../context";
+import type { Provider } from "./provider";
+export interface GrowthBookProviderOptions {
+    /** the experiments engine, e.g. https://adminapis.dentalkart.com/experiments */
+    apiHost: string;
+    /** one per surface and environment, created in the admin's Feature Management settings */
+    clientKey: string;
+    /** how often the rules are re-fetched; default 60 s */
+    refreshMs?: number;
+    /** per-fetch timeout; default 3 s */
+    fetchTimeoutMs?: number;
+    /** where the last good rules file is kept for cold starts while the engine is down; default os.tmpdir() */
+    cacheDir?: string;
+    log?: (msg: string) => void;
+}
+/**
+ * Rules from the experiments engine, evaluated in memory. One HTTP GET a minute per process, zero
+ * network per request. The last good payload is also written to disk so a task that starts while the
+ * engine is down still serves the previous rules instead of turning everything off.
+ */
+export declare class GrowthBookProvider implements Provider {
+    private readonly opts;
+    readonly name = "growthbook";
+    readonly endpoint: string;
+    readonly cacheFile: string;
+    private readonly client;
+    private timer;
+    private first;
+    private loaded;
+    private warned;
+    constructor(opts: GrowthBookProviderOptions);
+    ready(): Promise<void>;
+    /** Fetch the rules once. Errors are swallowed: the previous payload stays in force. */
+    refresh(): Promise<void>;
+    /** Evaluate one flag. Also returns the raw engine result so callers can report an exposure. */
+    evaluate(name: string, ctx: FeatureContext): {
+        flag: Flag;
+        result: FeatureResult | null;
+    };
+    get(name: string, ctx: FeatureContext): Flag;
+    all(ctx: FeatureContext): FlagSet;
+    stop(): void;
+    private loadFromDisk;
+    private saveToDisk;
+}

package/dist/providers/growthbook.js

@@ -0,0 +1,143 @@
+"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.GrowthBookProvider = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const growthbook_1 = require("@growthbook/growthbook");
+const context_1 = require("../context");
+/**
+ * Rules from the experiments engine, evaluated in memory. One HTTP GET a minute per process, zero
+ * network per request. The last good payload is also written to disk so a task that starts while the
+ * engine is down still serves the previous rules instead of turning everything off.
+ */
+class GrowthBookProvider {
+    constructor(opts) {
+        this.opts = opts;
+        this.name = "growthbook";
+        this.client = new growthbook_1.GrowthBookClient();
+        this.timer = null;
+        this.loaded = false;
+        this.warned = false;
+        this.endpoint = `${opts.apiHost.replace(/\/+$/, "")}/api/features/${encodeURIComponent(opts.clientKey)}`;
+        this.cacheFile = path.join(opts.cacheDir ?? os.tmpdir(), `dentalkart-features-${safe(opts.clientKey)}.json`);
+        this.loadFromDisk();
+        this.first = this.refresh();
+        this.timer = setInterval(() => void this.refresh(), opts.refreshMs ?? 60000);
+        this.timer.unref?.();
+    }
+    ready() { return this.first; }
+    /** Fetch the rules once. Errors are swallowed: the previous payload stays in force. */
+    async refresh() {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), this.opts.fetchTimeoutMs ?? 3000);
+        try {
+            const res = await fetch(this.endpoint, { signal: controller.signal, headers: { accept: "application/json" } });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const payload = (await res.json());
+            if (!payload || typeof payload !== "object" || !("features" in payload))
+                throw new Error("not a rules payload");
+            await this.client.setPayload(payload);
+            this.loaded = true;
+            this.warned = false;
+            this.saveToDisk(payload);
+        }
+        catch (err) {
+            if (!this.warned) {
+                this.warned = true;
+                this.opts.log?.(`[features] rules fetch failed (${err?.message ?? err}); ${this.loaded ? "using the last good rules" : "everything off until the engine answers"}`);
+            }
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    /** Evaluate one flag. Also returns the raw engine result so callers can report an exposure. */
+    evaluate(name, ctx) {
+        if (!this.loaded)
+            return { flag: context_1.OFF, result: null };
+        const scoped = this.client.createScopedInstance({ attributes: (0, context_1.toAttributes)(ctx) });
+        const result = scoped.evalFeature(name);
+        return { flag: withExperiment((0, context_1.toFlag)(result.value), result), result };
+    }
+    get(name, ctx) { return this.evaluate(name, ctx).flag; }
+    all(ctx) {
+        const out = {};
+        if (!this.loaded)
+            return out;
+        const scoped = this.client.createScopedInstance({ attributes: (0, context_1.toAttributes)(ctx) });
+        for (const key of Object.keys(this.client.getFeatures())) {
+            const result = scoped.evalFeature(key);
+            out[key] = withExperiment((0, context_1.toFlag)(result.value), result);
+        }
+        return out;
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.client.destroy();
+    }
+    loadFromDisk() {
+        try {
+            const payload = JSON.parse(fs.readFileSync(this.cacheFile, "utf8"));
+            if (payload && typeof payload === "object" && "features" in payload) {
+                this.client.initSync({ payload });
+                this.loaded = true;
+            }
+        }
+        catch { /* no cache yet */ }
+    }
+    saveToDisk(payload) {
+        try {
+            const tmp = `${this.cacheFile}.${process.pid}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify(payload));
+            fs.renameSync(tmp, this.cacheFile);
+        }
+        catch { /* read-only file system: fine */ }
+    }
+}
+exports.GrowthBookProvider = GrowthBookProvider;
+function withExperiment(flag, result) {
+    const exp = result.experimentResult;
+    if (!exp?.inExperiment || !result.experiment)
+        return flag;
+    // Result.key is the variation's key; the experiment's tracking key lives on the Experiment itself.
+    return { ...flag, experimentId: result.experiment.key, variationId: exp.variationId };
+}
+const safe = (s) => s.replace(/[^a-zA-Z0-9_-]/g, "_");

package/dist/providers/off.d.ts

@@ -0,0 +1,10 @@
+import { type FeatureContext, type Flag, type FlagSet } from "../context";
+import type { Provider } from "./provider";
+/** Every flag is off. Unit tests, emergencies, and any task without FEATURES_SOURCE. */
+export declare class OffProvider implements Provider {
+    readonly name = "off";
+    ready(): Promise<void>;
+    get(_name: string, _ctx: FeatureContext): Flag;
+    all(_ctx: FeatureContext): FlagSet;
+    stop(): void;
+}

package/dist/providers/off.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OffProvider = void 0;
+const context_1 = require("../context");
+/** Every flag is off. Unit tests, emergencies, and any task without FEATURES_SOURCE. */
+class OffProvider {
+    constructor() {
+        this.name = "off";
+    }
+    async ready() { }
+    get(_name, _ctx) { return context_1.OFF; }
+    all(_ctx) { return {}; }
+    stop() { }
+}
+exports.OffProvider = OffProvider;

package/dist/providers/provider.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureContext, Flag, FlagSet } from "../context";
+/** Where flags come from. Evaluation is synchronous once `ready()` has resolved. */
+export interface Provider {
+    readonly name: string;
+    /** Resolves once the first rules are loaded (or the attempt gave up). Never rejects. */
+    ready(): Promise<void>;
+    get(name: string, ctx: FeatureContext): Flag;
+    all(ctx: FeatureContext): FlagSet;
+    stop(): void;
+}

package/dist/providers/provider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });