@techdentalkart/features 2.0.1

package/README.md

@@ -0,0 +1,167 @@
+# @techdentalkart/features
+
+Feature flags and experiments for every Dentalkart repo. One package, one object, one hook. The rules that decide
+who sees what live in the admin panel (**Feature Management & A/B Testing**); this package only asks and answers.
+End users never see flag names.
+
+```ts
+type Flag = { on: boolean; value?: string | number | boolean; experimentId?: string; variationId?: number }
+          & Record<string, string | number | boolean | undefined>;   // JSON flags spread their attributes
+type FlagSet = Record<string, Flag>;                                  // keyed by "area.feature"
+```
+
+| Flag type in the admin | What you get |
+|---|---|
+| On / off | `{ on }` |
+| Number (a percent, a limit) | `{ on: value !== 0, value }` |
+| Text (a message) | `{ on: value !== "", value }` |
+| JSON | `{ on: enabled ?? true, ...attributes }` |
+| decided by an experiment | the same, plus `experimentId` and `variationId` |
+
+Unknown flag, engine down, `FEATURES_SOURCE` unset: `{ on: false }`. Never `undefined`, never throws.
+Flags are **discovered**, not declared: nothing in a repo lists flag names. The only place a name appears is the
+line that uses it.
+
+## Install
+
+```bash
+npm i @techdentalkart/features
+```
+
+That is the whole setup. The package is published to npmjs.com, so there is no registry file, no
+token and nothing to configure — on a laptop or in CI. It is also mirrored to the
+feature-management project's own GitLab registry, which is what `publishConfig` points at.
+
+## Next.js (website, Institute Management): one file, one line, one route
+
+```ts
+// lib/features.ts — the only flag file in the repo
+import { createNextFeatures } from "@techdentalkart/features/next";
+import { websiteContext } from "@techdentalkart/features/website";   // or instituteContext from ./institute-management
+
+export const { getFlags, FeaturesProvider, exposuresRoute } = createNextFeatures({
+  context: async ({ cookie, header }) => websiteContext({
+    anonymousId: header("x-dk-vid") ?? cookie("dk_vid"),   // minted in middleware.ts, the unit of every experiment
+    pincode: cookie("pincode"),
+    userAgent: header("user-agent"),
+    customer: await fetchCustomer(cookie("token")),         // this repo's own HTTP call, or omit when signed out
+  }),
+});
+```
+```tsx
+// app/layout.tsx
+import { FeaturesProvider } from "@/lib/features";
+<FeaturesProvider>{children}</FeaturesProvider>
+
+// app/api/exposures/route.ts — browsers report "I saw variant B" here; it is forwarded to the engine
+export { exposuresRoute as POST } from "@/lib/features";
+```
+```tsx
+// where a price is shown
+import { usePricingVariant } from "@techdentalkart/features/website";
+const pricing = usePricingVariant();            // { percent, experimentId?, variationId?, apply(price) }
+const shown = pricing.apply(sellingPrice);
+
+// where payment starts
+import { usePaymentBlock } from "@techdentalkart/features/website";
+const { blocked, message } = usePaymentBlock();
+```
+No fetch in the browser for rules: flags are resolved once per request on the server and travel down with the
+render. Server components and handlers call `await getFlags()`. Reading a flag that an experiment decided reports
+the exposure once the component is on screen (never during server rendering).
+
+## What each app declares, in the package
+
+| Entry | Sends to the rules (context keys) | Reads back (typed hooks) |
+|---|---|---|
+| `@techdentalkart/features/website` | `anonymousId userId email isLoggedIn isStaff isBot customerType speciality groupCode noOfOrders pincode district state platform deviceType instadent` via `websiteContext(facts)` | `usePricingVariant()`, `useMarkedUpPrice(price)`, `usePaymentBlock()`, `useStockTicker()` |
+| `@techdentalkart/features/institute-management` | `targetingKey userId email isLoggedIn isStaff role collegeId collegeSlug departmentId isDemo platform` via `instituteContext(session)` | `useApprovals()`, `useRequisitions()`, `useMaintenanceBanner()` |
+
+Adding a flag to an app = one hook in that app's entry, then use it. The rule that decides who gets it is
+written in the admin panel.
+
+## NestJS (customer-service, cart-service and the other services): one line
+
+```ts
+// app.module.ts
+FeaturesModule.forRoot({
+  context: (req) => contextFromCustomer(req.customer, req.headers),   // ~40 lines, lives in features.context.ts
+  controller: "customer/api/v1/features",                             // GET → { flags, ttlSeconds, evaluatedAt, exposure }
+  guards: [OptionalRESTAuthGuard],                                     // anonymous callers get defaults
+})                                                                     // also POST customer/api/v1/exposures for the app
+```
+```ts
+constructor(private readonly features: FeaturesService) {}
+if (await this.features.isEnabled("checkout.v2", req)) { ... }
+const f = await this.features.get("pricing.markup", req);   // { on, value, experimentId?, variationId? }
+```
+`get` / `isEnabled` are a *use* of the flag (the service decides something with it), so an experiment variant they
+return is reported as an exposure. `all` is a hand-off to the app and reports nothing.
+
+## React Native (the app): one provider
+
+```tsx
+<FeaturesProvider fetch={() => api.get("/features")} storage={AsyncStorage}
+                  exposure={{ endpoint: `${API}/exposures`, unit: deviceId, unitType: "deviceId", platform: Platform.OS, surface: "mobile-app" }}
+                  resume={(cb) => { const s = AppState.addEventListener("change", (st) => st === "active" && cb()); return () => s.remove(); }}>
+```
+`useFlag("checkout.v2").on` in screens. Refreshes every 5 minutes and on foreground, keeps the last good answer.
+
+## Plain Node (scripts, jobs)
+
+```ts
+import { setupFeatures, features } from "@techdentalkart/features";
+setupFeatures();                                          // FEATURES_* variables decide
+await features.get("area.feature", { targetingKey: "job" });
+```
+
+## Configuration: environment variables on the task
+
+| Variable | Meaning |
+|---|---|
+| `FEATURES_SOURCE` | `growthbook` on real tasks; `file` on a laptop; unset = everything off, no network (logged as an error on a production task) |
+| `FEATURES_API_HOST` | the experiments engine, e.g. `https://adminapis.dentalkart.com/experiments` (laptop: `http://localhost:3100`, see `local-engine/`) |
+| `FEATURES_CLIENT_KEY` | this surface + environment's key from the admin's Feature Management settings |
+| `FEATURES_ENV` | `staging` or `production`, stamped on exposures |
+| `FEATURES_SURFACE` | `website`, `institute-management`, `customer-service`, `mobile-app`, stamped on exposures |
+| `FEATURES_EXPOSURES_SECRET` | shared secret for server → engine exposure batches; unset = exposures are not sent |
+| `FEATURES_FILE` | for `file`: path to a JSON of `{ "area.feature": true | 3 | "text" | { "enabled": true, "message": "..." } }` |
+
+Rules are fetched once a minute per process and evaluated in memory: zero network per request. The last good
+rules are also kept on disk, so a task that starts while the engine is down serves the previous rules.
+
+## Context keys a rule may use
+
+Same names everywhere; a rule written for the website works in the app if the app sends the same key.
+
+`anonymousId` · `userId` · `email` · `isLoggedIn` · `isStaff` · `isBot` · `platform` · `appVersion` · `appBuild` ·
+`deviceId` · `deviceType` · `instadent` · `customerType` · `speciality` · `groupCode` · `noOfOrders` ·
+`isCreditEligible` · `hasGstin` · `createdAt` · `gender` · `registrationType` · `role` · `collegeId` ·
+`pincode` · `district` · `state` · `city` · `country` · `checkoutPincode`
+
+Rollouts and experiments are hashed on `anonymousId` (the `dk_vid` cookie on the web, the device id in the
+app), so a visitor keeps the same variant before and after signing in. `customerType` and `speciality` are free
+text in the database: trim, collapse spaces and lowercase them before sending; rules are written in lowercase.
+
+## Naming
+
+- Flags: `area.feature`, lowercase, one decision per flag: `checkout.pincode_offer`, `ims.approvals`, `pricing.markup`.
+- Attributes of JSON flags: lowercase, one word where possible: `message`, `audience`, `limit`.
+- Reserved keys on a Flag: `on`, `value`, `experimentId`, `variationId`.
+
+## On a laptop
+
+```bash
+cd local-engine && docker compose up -d && ./setup.sh     # the real engine + its admin API on :3100
+FEATURES_SOURCE=growthbook FEATURES_API_HOST=http://localhost:3100 FEATURES_CLIENT_KEY=<website staging key> npm run dev
+```
+or `FEATURES_SOURCE=file FEATURES_FILE=./features.local.json` for a plain file with no rules.
+On staging, `?flags=area.feature:on` forces a flag for one request when the middleware forwards it as the
+`x-flags-override` header. Off on live.
+
+## Adding a flag
+
+1. Create it in the admin panel, default off. A flag nothing reads is harmless.
+2. Use it: `useFlag("area.feature")` or `features.get("area.feature", ctx)`. Render nothing when off.
+3. Merge. Nothing changes until a rule turns it on.
+4. When the feature is permanent, delete the check and then the flag.

package/dist/context.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The facts a rule may look at. Same names in every repo and in every rule in the admin's
+ * Feature Management screens. Build it once per request in your repo's `lib/features.ts`
+ * (or the service's context builder); nothing else in the repo touches it.
+ */
+export interface FeatureContext {
+    /** the unit rollouts and experiments are hashed on: the first-party anonymous id (dk_vid cookie, app device id) */
+    anonymousId?: string;
+    /** legacy alias: used as the hash unit when anonymousId is absent */
+    targetingKey?: string;
+    userId?: string;
+    email?: string;
+    isLoggedIn?: boolean;
+    isStaff?: boolean;
+    platform?: "web" | "android" | "ios" | "ims" | string;
+    appVersion?: string;
+    appBuild?: number;
+    /** Institute Management */
+    role?: string;
+    collegeId?: string;
+    /** customers (website, app), named exactly as customer-service sends them */
+    customerType?: string;
+    speciality?: string;
+    groupCode?: string;
+    noOfOrders?: number;
+    isCreditEligible?: boolean;
+    hasGstin?: boolean;
+    createdAt?: string;
+    gender?: string;
+    registrationType?: string;
+    /** place: where the visitor browses from */
+    country?: string;
+    state?: string;
+    district?: string;
+    city?: string;
+    pincode?: string;
+    /** place: the shipping address chosen at checkout (only the cart service knows it) */
+    checkoutPincode?: string;
+    /** device */
+    deviceId?: string;
+    deviceType?: "desktop" | "mobile" | "phone" | "tablet" | string;
+    instadent?: boolean;
+    /** any other scalar a surface wants to expose to rules; objects are dropped before evaluation */
+    [key: string]: string | number | boolean | undefined;
+}
+export type Scalar = string | number | boolean;
+/**
+ * One flag as every repo sees it: `on`, the raw `value` for number/text flags, the attributes of a
+ * JSON flag when it is on, and `experimentId` / `variationId` when an experiment decided it.
+ * Unknown flag, engine down, source off: `{ on: false }`. Never undefined, never throws.
+ */
+export type Flag = {
+    on: boolean;
+    value?: Scalar;
+    experimentId?: string;
+    variationId?: number;
+} & Record<string, Scalar | undefined>;
+/** Every flag the visitor can see, keyed by `area.feature`. Discovered from the engine, never declared in code. */
+export type FlagSet = Record<string, Flag>;
+export declare const OFF: Flag;
+/**
+ * Evaluated value -> Flag.
+ *   boolean        -> { on }
+ *   number         -> { on: value !== 0, value }
+ *   string         -> { on: value !== "", value }
+ *   object         -> { on: enabled ?? true, ...scalar attributes }   (`enabled` and `_`-prefixed keys dropped)
+ *   null/undefined -> { on: false }
+ */
+export declare function toFlag(value: unknown): Flag;
+/** The unit an exposure is attributed to, and which kind it is. */
+export declare function unitOf(ctx: FeatureContext): {
+    unit: string;
+    unitType: string;
+} | null;
+/**
+ * FeatureContext -> engine attributes. Undefined values and objects are dropped. `id` is set to the
+ * unit so rules that do not name a hash attribute still stick per visitor.
+ */
+export declare function toAttributes(ctx: FeatureContext): Record<string, Scalar>;

package/dist/context.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OFF = void 0;
+exports.toFlag = toFlag;
+exports.unitOf = unitOf;
+exports.toAttributes = toAttributes;
+exports.OFF = Object.freeze({ on: false });
+/**
+ * Evaluated value -> Flag.
+ *   boolean        -> { on }
+ *   number         -> { on: value !== 0, value }
+ *   string         -> { on: value !== "", value }
+ *   object         -> { on: enabled ?? true, ...scalar attributes }   (`enabled` and `_`-prefixed keys dropped)
+ *   null/undefined -> { on: false }
+ */
+function toFlag(value) {
+    if (typeof value === "boolean")
+        return value ? { on: true } : exports.OFF;
+    if (typeof value === "number")
+        return { on: value !== 0, value };
+    if (typeof value === "string")
+        return { on: value !== "", value };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return exports.OFF;
+    const r = value;
+    const on = r.enabled === undefined ? true : !!r.enabled;
+    if (!on)
+        return exports.OFF;
+    const out = { on: true };
+    for (const [k, v] of Object.entries(r)) {
+        if (k === "enabled" || k.startsWith("_"))
+            continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+            out[k] = v;
+    }
+    return out;
+}
+/** The unit an exposure is attributed to, and which kind it is. */
+function unitOf(ctx) {
+    if (ctx.anonymousId)
+        return { unit: String(ctx.anonymousId), unitType: "anonymousId" };
+    if (ctx.targetingKey)
+        return { unit: String(ctx.targetingKey), unitType: "targetingKey" };
+    if (ctx.userId)
+        return { unit: String(ctx.userId), unitType: "userId" };
+    if (ctx.deviceId)
+        return { unit: String(ctx.deviceId), unitType: "deviceId" };
+    return null;
+}
+/**
+ * FeatureContext -> engine attributes. Undefined values and objects are dropped. `id` is set to the
+ * unit so rules that do not name a hash attribute still stick per visitor.
+ */
+function toAttributes(ctx) {
+    const out = {};
+    for (const [k, v] of Object.entries(ctx)) {
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+            out[k] = v;
+    }
+    const unit = unitOf(ctx);
+    if (unit && out.id === undefined)
+        out.id = unit.unit;
+    return out;
+}

package/dist/exposures.d.ts

@@ -0,0 +1,59 @@
+import type { Scalar } from "./context";
+/** One "this visitor saw this variant" event. What the results are computed from. */
+export interface Exposure {
+    experimentId: string;
+    variationId: number;
+    /** the id the experiment was hashed on */
+    unit: string;
+    unitType: string;
+    /** ISO time the visitor was exposed */
+    ts: string;
+    platform?: string;
+    /** which app reported it: website, institute-management, customer-service, mobile-app */
+    surface?: string;
+    env?: string;
+    /** a few scalar facts for dimension breakdowns; never email or anything personal */
+    attrs?: Record<string, Scalar>;
+}
+export type ExposureSender = (batch: Exposure[]) => Promise<void> | void;
+export interface ExposureQueueOptions {
+    send: ExposureSender;
+    /** how long a batch may wait before it is sent; default 5 s */
+    flushMs?: number;
+    /** send as soon as this many are waiting; default 100 */
+    maxBatch?: number;
+    /** the same unit + experiment + variation is reported once per this window; default 24 h */
+    dedupeTtlMs?: number;
+    /** upper bound on remembered keys; oldest are forgotten first; default 50k */
+    maxKeys?: number;
+}
+/**
+ * Dedupes and batches exposures, then hands batches to `send`. Never throws into the caller:
+ * a failed send is logged once and the batch dropped (an exposure is not worth a request failing).
+ * Works in Node, the browser and React Native (timers only).
+ */
+export declare class ExposureQueue {
+    private readonly opts;
+    private waiting;
+    private seen;
+    private timer;
+    private readonly flushMs;
+    private readonly maxBatch;
+    private readonly dedupeTtlMs;
+    private readonly maxKeys;
+    private warned;
+    constructor(opts: ExposureQueueOptions);
+    /** Queue one exposure. Returns false when it was already reported inside the dedupe window. */
+    record(e: Exposure): boolean;
+    get size(): number;
+    /** Send everything waiting now. */
+    flush(): Promise<void>;
+    stop(): void;
+}
+/**
+ * Sender that POSTs `{ exposures: [...] }` as JSON. On the server: to the engine with the shared
+ * secret. In the browser / app: to the surface's own route (e.g. `/api/exposures`), no secret.
+ */
+export declare function httpSender(url: string, secret?: string, timeoutMs?: number): ExposureSender;
+/** Basic shape check for a batch received over HTTP from a browser or app. */
+export declare function parseExposureBatch(body: unknown, max?: number): Exposure[];

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { OFF, toFlag, type FeatureContext, type Flag, type FlagSet } from "./context";
+import { ExposureQueue, httpSender, parseExposureBatch, type Exposure, type ExposureSender } from "./exposures";
+import { FileProvider } from "./providers/file";
+import { GrowthBookProvider } from "./providers/growthbook";
+import { OffProvider } from "./providers/off";
+export type { FeatureContext, Flag, FlagSet, Scalar } from "./context";
+export type { Exposure, ExposureSender } from "./exposures";
+export { GrowthBookProvider, FileProvider, OffProvider, ExposureQueue, httpSender, parseExposureBatch, OFF, toFlag };
+export interface SetupOptions {
+    /** growthbook | file | off. Default FEATURES_SOURCE, else "off": a task without it makes no network calls. */
+    source?: "growthbook" | "file" | "off";
+    /** the experiments engine; default FEATURES_API_HOST */
+    apiHost?: string;
+    /** this surface + environment's key; default FEATURES_CLIENT_KEY */
+    clientKey?: string;
+    /** staging | production, stamped on exposures; default FEATURES_ENV */
+    environment?: string;
+    /** which app this is (website, institute-management, customer-service, mobile-app); default FEATURES_SURFACE */
+    surface?: string;
+    /** for source=file; default FEATURES_FILE or ./features.local.json */
+    file?: string;
+    /** rules refresh interval in ms; default 60 000 */
+    refreshMs?: number;
+    /**
+     * Where server-side exposures go. Default: POST `${apiHost}/dentalkart/exposures` with
+     * FEATURES_EXPOSURES_SECRET when that variable is set; nothing otherwise. Pass a function to
+     * capture them yourself (tests), or false to disable.
+     */
+    exposures?: ExposureSender | {
+        url: string;
+        secret?: string;
+    } | false;
+    log?: (msg: string) => void;
+}
+/** Call once at startup. Idempotent. Never throws: on any problem falls back to "off". */
+export declare function setupFeatures(opts?: SetupOptions): void;
+/** Report that a visitor was actually shown an experiment variant. Deduped, batched, never throws. */
+export declare function recordExposure(flag: Flag, ctx: FeatureContext, attrs?: Record<string, string | number | boolean>): boolean;
+/** Forward a batch that a browser or app posted to this server's own exposures route. */
+export declare function forwardExposures(body: unknown): Promise<number>;
+/** Send whatever is waiting (call on shutdown). */
+export declare const flushExposures: () => Promise<void>;
+/**
+ * The API every repo uses. Flag names are `area.feature`. Every answer is safe: a missing flag,
+ * a dead engine or source=off gives `{ on: false }` / `false` / `{}`.
+ *
+ * `get` and `isEnabled` are a *use* of the flag (a service deciding something), so an experiment
+ * variant they return is reported as an exposure. `all` is a hand-off to a page or an app; the
+ * browser reports the exposure when a component actually reads the flag.
+ */
+export declare const features: {
+    get: (name: string, ctx?: FeatureContext) => Promise<Flag>;
+    isEnabled: (name: string, ctx?: FeatureContext) => Promise<boolean>;
+    /** Every flag for one context, no exposures. Nothing in a repo has to list flag names to get them here. */
+    all: (ctx?: FeatureContext) => Promise<FlagSet>;
+    /** Which source is active: growthbook | file | off. */
+    source: () => string;
+};
+export type { Exposure as ExposureEvent };

package/dist/index.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.features = exports.flushExposures = exports.toFlag = exports.OFF = exports.parseExposureBatch = exports.httpSender = exports.ExposureQueue = exports.OffProvider = exports.FileProvider = exports.GrowthBookProvider = void 0;
+exports.setupFeatures = setupFeatures;
+exports.recordExposure = recordExposure;
+exports.forwardExposures = forwardExposures;
+const context_1 = require("./context");
+Object.defineProperty(exports, "OFF", { enumerable: true, get: function () { return context_1.OFF; } });
+Object.defineProperty(exports, "toFlag", { enumerable: true, get: function () { return context_1.toFlag; } });
+const exposures_1 = require("./exposures");
+Object.defineProperty(exports, "ExposureQueue", { enumerable: true, get: function () { return exposures_1.ExposureQueue; } });
+Object.defineProperty(exports, "httpSender", { enumerable: true, get: function () { return exposures_1.httpSender; } });
+Object.defineProperty(exports, "parseExposureBatch", { enumerable: true, get: function () { return exposures_1.parseExposureBatch; } });
+const file_1 = require("./providers/file");
+Object.defineProperty(exports, "FileProvider", { enumerable: true, get: function () { return file_1.FileProvider; } });
+const growthbook_1 = require("./providers/growthbook");
+Object.defineProperty(exports, "GrowthBookProvider", { enumerable: true, get: function () { return growthbook_1.GrowthBookProvider; } });
+const off_1 = require("./providers/off");
+Object.defineProperty(exports, "OffProvider", { enumerable: true, get: function () { return off_1.OffProvider; } });
+let provider = new off_1.OffProvider();
+let queue = null;
+let stamp = {};
+/** Call once at startup. Idempotent. Never throws: on any problem falls back to "off". */
+function setupFeatures(opts = {}) {
+    const env = process.env;
+    const source = opts.source ?? env.FEATURES_SOURCE ?? "off";
+    const log = opts.log ?? ((m) => console.warn(m));
+    provider.stop();
+    queue?.stop();
+    queue = null;
+    stamp = { surface: opts.surface ?? env.FEATURES_SURFACE, env: opts.environment ?? env.FEATURES_ENV };
+    try {
+        if (source === "growthbook") {
+            const apiHost = opts.apiHost ?? env.FEATURES_API_HOST;
+            const clientKey = opts.clientKey ?? env.FEATURES_CLIENT_KEY;
+            if (!apiHost || !clientKey)
+                throw new Error("FEATURES_API_HOST and FEATURES_CLIENT_KEY are required for source=growthbook");
+            provider = new growthbook_1.GrowthBookProvider({ apiHost, clientKey, refreshMs: opts.refreshMs, log });
+            const sender = resolveSender(opts.exposures, apiHost, env.FEATURES_EXPOSURES_URL, env.FEATURES_EXPOSURES_SECRET);
+            if (sender)
+                queue = new exposures_1.ExposureQueue({ send: sender });
+        }
+        else if (source === "file") {
+            provider = new file_1.FileProvider(opts.file ?? env.FEATURES_FILE ?? "features.local.json");
+            const sender = typeof opts.exposures === "function" ? opts.exposures : null;
+            if (sender)
+                queue = new exposures_1.ExposureQueue({ send: sender });
+        }
+        else {
+            provider = new off_1.OffProvider();
+        }
+    }
+    catch (err) {
+        log(`[features] setup failed (${err?.message ?? err}); every flag is off`);
+        provider = new off_1.OffProvider();
+    }
+    if (source === "off" && env.NODE_ENV === "production") {
+        log("[features] FEATURES_SOURCE is not set on a production task: every flag is off");
+    }
+}
+function resolveSender(given, apiHost, urlFromEnv, secretFromEnv) {
+    if (given === false)
+        return null;
+    if (typeof given === "function")
+        return given;
+    if (given && typeof given === "object")
+        return (0, exposures_1.httpSender)(given.url, given.secret);
+    if (urlFromEnv)
+        return (0, exposures_1.httpSender)(urlFromEnv, secretFromEnv);
+    if (secretFromEnv)
+        return (0, exposures_1.httpSender)(`${apiHost.replace(/\/+$/, "")}/dentalkart/exposures`, secretFromEnv);
+    return null;
+}
+/** Report that a visitor was actually shown an experiment variant. Deduped, batched, never throws. */
+function recordExposure(flag, ctx, attrs) {
+    if (!queue || flag.experimentId === undefined || flag.variationId === undefined)
+        return false;
+    const unit = (0, context_1.unitOf)(ctx);
+    if (!unit)
+        return false;
+    return queue.record({
+        experimentId: flag.experimentId,
+        variationId: flag.variationId,
+        unit: unit.unit,
+        unitType: unit.unitType,
+        ts: new Date().toISOString(),
+        platform: typeof ctx.platform === "string" ? ctx.platform : undefined,
+        surface: stamp.surface,
+        env: stamp.env,
+        attrs: attrs ?? pickDimensions(ctx),
+    });
+}
+/** Forward a batch that a browser or app posted to this server's own exposures route. */
+async function forwardExposures(body) {
+    if (!queue)
+        return 0;
+    let n = 0;
+    for (const e of (0, exposures_1.parseExposureBatch)(body)) {
+        if (queue.record({ ...e, surface: e.surface ?? stamp.surface, env: e.env ?? stamp.env }))
+            n++;
+    }
+    return n;
+}
+/** Send whatever is waiting (call on shutdown). */
+const flushExposures = () => queue?.flush() ?? Promise.resolve();
+exports.flushExposures = flushExposures;
+const DIMENSIONS = ["platform", "deviceType", "customerType", "speciality", "groupCode", "state", "district", "instadent"];
+function pickDimensions(ctx) {
+    const out = {};
+    for (const k of DIMENSIONS) {
+        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;
+}
+/**
+ * The API every repo uses. Flag names are `area.feature`. Every answer is safe: a missing flag,
+ * a dead engine or source=off gives `{ on: false }` / `false` / `{}`.
+ *
+ * `get` and `isEnabled` are a *use* of the flag (a service deciding something), so an experiment
+ * variant they return is reported as an exposure. `all` is a hand-off to a page or an app; the
+ * browser reports the exposure when a component actually reads the flag.
+ */
+exports.features = {
+    get: async (name, ctx = {}) => {
+        try {
+            await provider.ready();
+            const flag = provider.get(name, ctx);
+            recordExposure(flag, ctx);
+            return flag;
+        }
+        catch {
+            return context_1.OFF;
+        }
+    },
+    isEnabled: async (name, ctx = {}) => (await exports.features.get(name, ctx)).on,
+    /** Every flag for one context, no exposures. Nothing in a repo has to list flag names to get them here. */
+    all: async (ctx = {}) => {
+        try {
+            await provider.ready();
+            return provider.all(ctx);
+        }
+        catch {
+            return {};
+        }
+    },
+    /** Which source is active: growthbook | file | off. */
+    source: () => provider.name,
+};

package/dist/institute-management/index.d.ts

@@ -0,0 +1,28 @@
+import type { FeatureContext } from "../context";
+/** The session fields a rule may target. Pass the iron-session data as is. */
+export interface InstituteSession {
+    userId?: string;
+    email?: string;
+    role?: string;
+    collegeId?: string;
+    collegeSlug?: string;
+    departmentId?: string | null;
+    isDemo?: boolean;
+}
+/** InstituteSession -> FeatureContext. Keys a rule sees: targetingKey, userId, email, isStaff, role,
+ *  collegeId, collegeSlug, departmentId, isDemo, platform. */
+export declare function instituteContext(s: InstituteSession): FeatureContext;
+export declare const IMS_FLAGS: {
+    /** entitlement: the order-approval flow */
+    readonly approvals: "ims.approvals";
+    /** release: internal requisitions */
+    readonly requisitions: "ims.requisitions";
+    /** kill switch: a banner with `message` on every page */
+    readonly maintenanceBanner: "ims.maintenance_banner";
+};
+export declare function useApprovals(): boolean;
+export declare function useRequisitions(): boolean;
+export declare function useMaintenanceBanner(): {
+    on: boolean;
+    message: string;
+};

package/dist/institute-management/index.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMS_FLAGS = void 0;
+exports.instituteContext = instituteContext;
+exports.useApprovals = useApprovals;
+exports.useRequisitions = useRequisitions;
+exports.useMaintenanceBanner = useMaintenanceBanner;
+// No "use client" here on purpose: the context builder runs on the server inside getFlags(), and a
+// client-marked module would turn it into a client reference that cannot be called there. The hooks
+// below still work in client components, which import this module across the boundary themselves.
+/**
+ * Institute Management's declarations: what it sends to the rules, and what it reads back.
+ * This is the only place flag names for Institute Management are written down.
+ *
+ * Engine key: `institute-management (production)` (the only place it runs).
+ */
+const react_1 = require("../react");
+/** InstituteSession -> FeatureContext. Keys a rule sees: targetingKey, userId, email, isStaff, role,
+ *  collegeId, collegeSlug, departmentId, isDemo, platform. */
+function instituteContext(s) {
+    return {
+        targetingKey: s.userId,
+        userId: s.userId,
+        isLoggedIn: !!s.userId,
+        platform: "ims",
+        role: s.role,
+        collegeId: s.collegeId,
+        collegeSlug: s.collegeSlug,
+        departmentId: s.departmentId ?? undefined,
+        email: s.email,
+        isStaff: !!s.email?.endsWith("@dentalkart.com"),
+        isDemo: !!s.isDemo,
+    };
+}
+exports.IMS_FLAGS = {
+    /** entitlement: the order-approval flow */
+    approvals: "ims.approvals",
+    /** release: internal requisitions */
+    requisitions: "ims.requisitions",
+    /** kill switch: a banner with `message` on every page */
+    maintenanceBanner: "ims.maintenance_banner",
+};
+function useApprovals() { return (0, react_1.useFlag)(exports.IMS_FLAGS.approvals).on; }
+function useRequisitions() { return (0, react_1.useFlag)(exports.IMS_FLAGS.requisitions).on; }
+function useMaintenanceBanner() {
+    const f = (0, react_1.useFlag)(exports.IMS_FLAGS.maintenanceBanner);
+    return { on: f.on, message: (typeof f.message === "string" && f.message) || "Some features are temporarily unavailable." };
+}