@techdentalkart/features 2.0.1

package/dist/react/index.d.ts

@@ -0,0 +1,50 @@
+import React from "react";
+import { type Flag, type FlagSet } from "../context";
+export type { Flag, FlagSet } from "../context";
+/** AsyncStorage, localStorage, or anything with the same two methods. */
+export interface FlagStorage {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+}
+/** Where a browser or app reports "this visitor saw this variant", and who the visitor is. */
+export interface ExposureReporting {
+    /** the surface's own route that forwards to the engine, e.g. `/api/exposures` or `customer/api/v1/exposures` */
+    endpoint: string;
+    /** the id experiments are hashed on (dk_vid on the web, the device id in the app) */
+    unit: string;
+    unitType?: string;
+    platform?: string;
+    surface?: string;
+    /** a few scalar facts for breakdowns (device type, customer type ...); never anything personal */
+    attrs?: Record<string, string | number | boolean>;
+}
+export interface FeaturesProviderProps {
+    /** Flags already resolved on the server for this visitor (Next.js). First paint is right, no flash. */
+    initial?: FlagSet;
+    /** How to fetch a fresh set (the app: `() => api.get("/features")`). */
+    fetch?: () => Promise<FlagSet | {
+        flags: FlagSet;
+    }>;
+    /** Refresh interval when `fetch` is given. Default 5 minutes. 0 disables the timer. */
+    refreshMs?: number;
+    /** Last-known-good across launches (the app: AsyncStorage). Optional. */
+    storage?: FlagStorage;
+    /** Subscribe to "app came back to the foreground"; return an unsubscribe. RN: AppState. Web: automatic. */
+    resume?: (onResume: () => void) => () => void;
+    /** Enables exposure reporting from `useFlag`. Omit and nothing is ever sent. */
+    exposure?: ExposureReporting;
+    children: React.ReactNode;
+}
+/**
+ * The one provider every React surface uses: Next client tree (fed by the server) and React Native
+ * (fed by `fetch`). Keeps the last good answer if a refresh fails. Flags are read with `useFlag(name)`.
+ */
+export declare function FeaturesProvider({ initial, fetch, refreshMs, storage, resume, exposure, children }: FeaturesProviderProps): React.JSX.Element;
+/**
+ * `{ on, ...attributes }` for one flag. `{ on: false }` when unknown, off, or outside the provider.
+ * Reading a flag that an experiment decided reports the exposure once the component is on screen
+ * (never during server rendering).
+ */
+export declare function useFlag(name: string): Flag;
+/** Every flag for this visitor. For code that must branch on several at once. No exposures. */
+export declare function useFlags(): FlagSet;

package/dist/react/index.js

@@ -0,0 +1,104 @@
+"use client";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeaturesProvider = FeaturesProvider;
+exports.useFlag = useFlag;
+exports.useFlags = useFlags;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const context_1 = require("../context");
+const exposures_1 = require("../exposures");
+const STORAGE_KEY = "dk_flags_v1";
+const FlagsContext = (0, react_1.createContext)({});
+const ReporterContext = (0, react_1.createContext)(null);
+/**
+ * The one provider every React surface uses: Next client tree (fed by the server) and React Native
+ * (fed by `fetch`). Keeps the last good answer if a refresh fails. Flags are read with `useFlag(name)`.
+ */
+function FeaturesProvider({ initial, fetch, refreshMs = 300000, storage, resume, exposure, children }) {
+    const [flags, setFlags] = (0, react_1.useState)(initial ?? {});
+    const alive = (0, react_1.useRef)(true);
+    // last-known-good from storage, only when nothing better was given
+    (0, react_1.useEffect)(() => {
+        if (initial || !storage)
+            return;
+        Promise.resolve(storage.getItem(STORAGE_KEY)).then((s) => {
+            if (s && alive.current) {
+                try {
+                    setFlags(JSON.parse(s));
+                }
+                catch { /* ignore a bad cache */ }
+            }
+        }).catch(() => { });
+    }, [initial, storage]);
+    (0, react_1.useEffect)(() => {
+        alive.current = true;
+        if (!fetch)
+            return;
+        const refresh = () => fetch().then((r) => {
+            const next = r?.flags ?? r;
+            if (!next || typeof next !== "object" || !alive.current)
+                return;
+            setFlags(next);
+            if (storage)
+                Promise.resolve(storage.setItem(STORAGE_KEY, JSON.stringify(next))).catch(() => { });
+        }).catch(() => { });
+        refresh();
+        const timer = refreshMs > 0 ? setInterval(refresh, refreshMs) : undefined;
+        let unsubscribe;
+        if (resume)
+            unsubscribe = resume(refresh);
+        else if (typeof document !== "undefined") {
+            const onVisible = () => { if (document.visibilityState === "visible")
+                refresh(); };
+            document.addEventListener("visibilitychange", onVisible);
+            unsubscribe = () => document.removeEventListener("visibilitychange", onVisible);
+        }
+        return () => { alive.current = false; if (timer)
+            clearInterval(timer); unsubscribe?.(); };
+    }, [fetch, refreshMs, storage, resume]);
+    // one queue per provider; recreated only when the endpoint or the visitor changes
+    const reporter = (0, react_1.useMemo)(() => {
+        if (!exposure)
+            return null;
+        const queue = new exposures_1.ExposureQueue({ send: (0, exposures_1.httpSender)(exposure.endpoint), flushMs: 2000 });
+        return (flag) => {
+            if (flag.experimentId === undefined || flag.variationId === undefined)
+                return;
+            const e = {
+                experimentId: flag.experimentId,
+                variationId: flag.variationId,
+                unit: exposure.unit,
+                unitType: exposure.unitType ?? "anonymousId",
+                ts: new Date().toISOString(),
+                platform: exposure.platform,
+                surface: exposure.surface,
+                attrs: exposure.attrs,
+            };
+            queue.record(e);
+        };
+    }, [exposure]);
+    const value = (0, react_1.useMemo)(() => flags, [flags]);
+    return ((0, jsx_runtime_1.jsx)(ReporterContext.Provider, { value: reporter, children: (0, jsx_runtime_1.jsx)(FlagsContext.Provider, { value: value, children: children }) }));
+}
+/**
+ * `{ on, ...attributes }` for one flag. `{ on: false }` when unknown, off, or outside the provider.
+ * Reading a flag that an experiment decided reports the exposure once the component is on screen
+ * (never during server rendering).
+ */
+function useFlag(name) {
+    const flag = (0, react_1.useContext)(FlagsContext)[name] ?? context_1.OFF;
+    const report = (0, react_1.useContext)(ReporterContext);
+    const experimentId = flag.experimentId;
+    const variationId = flag.variationId;
+    (0, react_1.useEffect)(() => {
+        if (report && experimentId !== undefined)
+            report(flag);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [report, name, experimentId, variationId]);
+    return flag;
+}
+/** Every flag for this visitor. For code that must branch on several at once. No exposures. */
+function useFlags() {
+    return (0, react_1.useContext)(FlagsContext);
+}

package/dist/website/index.d.ts

@@ -0,0 +1,55 @@
+import type { FeatureContext } from "../context";
+/** What a rule may target on the website. Build it once per request in `lib/features.ts` and pass it here. */
+export interface WebsiteFacts {
+    /** the signed-in customer, from `customers/me` with the visitor's own token; omit when signed out */
+    customer?: {
+        id?: number | string;
+        email?: string;
+        type?: string;
+        speciality?: string;
+        no_of_orders?: number;
+        group_code?: string;
+    } | null;
+    /** first-party anonymous id (the `dk_vid` cookie or the `x-dk-vid` header): the unit for rollouts and experiments */
+    anonymousId?: string;
+    /** the `pincode` cookie: where the visitor browses from */
+    pincode?: string;
+    /** district and state of that pincode, when the app has looked them up */
+    district?: string;
+    state?: string;
+    /** the User-Agent header, for deviceType and bots */
+    userAgent?: string;
+    /** the `x-instadent-mode` header */
+    instadent?: boolean;
+}
+/** WebsiteFacts -> FeatureContext. The keys a rule sees: anonymousId, userId, email, isLoggedIn, isStaff, isBot,
+ *  customerType, speciality, groupCode, noOfOrders, pincode, district, state, platform, deviceType, instadent. */
+export declare function websiteContext(f: WebsiteFacts): FeatureContext;
+/** The website's flags. Names here, nowhere else. */
+export declare const WEBSITE_FLAGS: {
+    /** number: percent added to the catalogue prices shown. Display only until the cart service reads the same flag. */
+    readonly priceMarkup: "pricing.markup";
+    /** kill switch by place: `message` explains why payment is paused. */
+    readonly paymentDisabled: "checkout.payment_disabled";
+    /** release: the market ticker strip in the header. */
+    readonly stockTicker: "header.stock_ticker";
+};
+export interface PricingVariant {
+    /** percent added to shown prices; 0 when no rule matched */
+    percent: number;
+    experimentId?: string;
+    variationId?: number;
+    /** a catalogue price as it should be shown to this visitor */
+    apply<T extends number | null | undefined>(price: T): T;
+}
+/** The pricing decision for this visitor. Reading it reports the experiment exposure. */
+export declare function usePricingVariant(): PricingVariant;
+/** A catalogue price as it should be shown to this visitor. Identity when no markup applies. */
+export declare function useMarkedUpPrice<T extends number | null | undefined>(price: T): T;
+/** Whether payment is paused for this visitor, and what to tell them. */
+export declare function usePaymentBlock(): {
+    blocked: boolean;
+    message: string;
+};
+/** Whether to show the header stock ticker. */
+export declare function useStockTicker(): boolean;

package/dist/website/index.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBSITE_FLAGS = void 0;
+exports.websiteContext = websiteContext;
+exports.usePricingVariant = usePricingVariant;
+exports.useMarkedUpPrice = useMarkedUpPrice;
+exports.usePaymentBlock = usePaymentBlock;
+exports.useStockTicker = useStockTicker;
+// 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.
+/**
+ * The website's declarations: what it sends to the rules, and what it reads back.
+ * This is the only place flag names for the website are written down.
+ *
+ * Engine keys: `website (staging)` for dk-frontend.dentalkart.com, `website (production)` for the live site.
+ */
+const react_1 = require("../react");
+/** Free-text columns: trim, collapse spaces, lowercase. Rules are written in lowercase. */
+const normalise = (v) => {
+    if (typeof v !== "string")
+        return undefined;
+    const s = v.trim().replace(/\s+/g, " ").toLowerCase();
+    return s || undefined;
+};
+const BOT = /bot|crawl|spider|slurp|facebookexternalhit|preview|headless/i;
+/** WebsiteFacts -> FeatureContext. The keys a rule sees: anonymousId, userId, email, isLoggedIn, isStaff, isBot,
+ *  customerType, speciality, groupCode, noOfOrders, pincode, district, state, platform, deviceType, instadent. */
+function websiteContext(f) {
+    const c = f.customer ?? undefined;
+    const userId = c?.id != null ? String(c.id) : undefined;
+    return {
+        anonymousId: f.anonymousId,
+        targetingKey: f.anonymousId ?? userId,
+        platform: "web",
+        deviceType: f.userAgent && /Mobi|Android|iPhone/i.test(f.userAgent) ? "mobile" : "desktop",
+        isBot: !!f.userAgent && BOT.test(f.userAgent),
+        instadent: !!f.instadent,
+        pincode: f.pincode?.trim() || undefined,
+        district: f.district,
+        state: f.state,
+        userId,
+        email: c?.email,
+        isLoggedIn: !!userId,
+        isStaff: !!c?.email?.toLowerCase().endsWith("@dentalkart.com"),
+        customerType: normalise(c?.type),
+        speciality: normalise(c?.speciality),
+        groupCode: normalise(c?.group_code) ?? (userId ? undefined : "not logged in"),
+        noOfOrders: typeof c?.no_of_orders === "number" ? c.no_of_orders : undefined,
+    };
+}
+/** The website's flags. Names here, nowhere else. */
+exports.WEBSITE_FLAGS = {
+    /** number: percent added to the catalogue prices shown. Display only until the cart service reads the same flag. */
+    priceMarkup: "pricing.markup",
+    /** kill switch by place: `message` explains why payment is paused. */
+    paymentDisabled: "checkout.payment_disabled",
+    /** release: the market ticker strip in the header. */
+    stockTicker: "header.stock_ticker",
+};
+/** The pricing decision for this visitor. Reading it reports the experiment exposure. */
+function usePricingVariant() {
+    const f = (0, react_1.useFlag)(exports.WEBSITE_FLAGS.priceMarkup);
+    const percent = f.on && typeof f.value === "number" && f.value > 0 ? f.value : 0;
+    return {
+        percent,
+        experimentId: f.experimentId,
+        variationId: f.variationId,
+        apply: (price) => typeof price !== "number" || percent === 0 ? price : (Math.round(price * (1 + percent / 100) * 100) / 100),
+    };
+}
+/** A catalogue price as it should be shown to this visitor. Identity when no markup applies. */
+function useMarkedUpPrice(price) {
+    return usePricingVariant().apply(price);
+}
+/** Whether payment is paused for this visitor, and what to tell them. */
+function usePaymentBlock() {
+    const f = (0, react_1.useFlag)(exports.WEBSITE_FLAGS.paymentDisabled);
+    return { blocked: f.on, message: (typeof f.message === "string" && f.message) || "Online payment is paused for your area right now." };
+}
+/** Whether to show the header stock ticker. */
+function useStockTicker() {
+    return (0, react_1.useFlag)(exports.WEBSITE_FLAGS.stockTicker).on;
+}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@techdentalkart/features",
+  "version": "2.0.1",
+  "description": "Dentalkart feature flags and experiments. One package, one object ({ on, value?, ...attributes, experimentId? }), one hook (useFlag). Same shape in every repo: Node, NestJS, Next.js, React Native. Rules come from the Feature Management & A/B Testing section of the admin panel.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./nest": {
+      "types": "./dist/nest/index.d.ts",
+      "default": "./dist/nest/index.js"
+    },
+    "./website": {
+      "types": "./dist/website/index.d.ts",
+      "default": "./dist/website/index.js"
+    },
+    "./institute-management": {
+      "types": "./dist/institute-management/index.d.ts",
+      "default": "./dist/institute-management/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "dist/react/index.d.ts"
+      ],
+      "next": [
+        "dist/next/index.d.ts"
+      ],
+      "nest": [
+        "dist/nest/index.d.ts"
+      ],
+      "website": [
+        "dist/website/index.d.ts"
+      ],
+      "institute-management": [
+        "dist/institute-management/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@growthbook/growthbook": "^1.7.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "next": ">=14",
+    "@nestjs/common": ">=8",
+    "reflect-metadata": ">=0.1.13"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "@nestjs/common": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.4.0",
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.0",
+    "next": "^14.1.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "@techdentalkart:registry": "https://gitlab.com/api/v4/projects/86582456/packages/npm/"
+  },
+  "license": "UNLICENSED"
+}