@core-sdk/feature-flags-sdk 0.1.1 → 0.3.0

package/README.md

@@ -0,0 +1,56 @@
+# @core-sdk/feature-flags-sdk
+
+HTTP client + in-memory TTL cache for feature flag definitions; evaluation uses [`@core-sdk/feature-flags-core`](https://www.npmjs.com/package/@core-sdk/feature-flags-core) on the client.
+
+- **Node:** 18+
+- **Module:** ESM (`"type": "module"`)
+
+## Install
+
+```bash
+npm install @core-sdk/feature-flags-sdk
+```
+
+## PostHog-style `identify` (one-shot context)
+
+Call **`identify`** once after login (or when profile is known). Stored fields are merged into every **`evaluate` / `evaluateAsync` / `isEnabled`** call. Per-flag overrides win on key clashes.
+
+```js
+import { FeatureFlagsClient } from "@core-sdk/feature-flags-sdk";
+
+const client = new FeatureFlagsClient({
+  baseUrl: "https://flag-api.example.com",
+  projectKey: "my-project",
+});
+
+await client.bootstrap();
+
+client.identify(profile.userId, {
+  email: profile.email,
+  accountId: profile.accountId,
+});
+
+// Uses merged context (email, accountId, userId = profile.userId)
+const on = await client.isEnabled("new-checkout");
+
+// Flag-specific props override the base for this call only
+const promo = await client.isEnabled("promo-banner", { channelId: "web" });
+```
+
+- **`reset()`** clears the identified person; evaluation uses `{}` again until the next `identify`.
+- **`distinctIdKey`** (optional, default `userId`): which context key receives the first `identify` argument. Match your portal rule `field` names.
+
+Until **`identify`** is called, `isEnabled("x")` uses an empty context (`{}`). Rules that require user fields therefore evaluate to **false** for logged-out users—no extra anonymous id layer is needed.
+
+## API routes
+
+The client calls:
+
+- `GET {baseUrl}/projects/{projectKey}/flags`
+- `GET {baseUrl}/projects/{projectKey}/flags/{flagKey}`
+- `GET .../flags/{flagKey}/history`
+- `GET .../flags/{flagKey}/versions/{version}`
+
+## License
+
+See your organization’s license terms.

package/dist/client.d.ts

@@ -4,7 +4,26 @@ export declare class FeatureFlagsClient {
     private readonly config;
     private readonly fetchImpl;
     private readonly cache;
+    /** Merged evaluation base from `identify` (empty until then). */
+    private personBase;
+    private identifiedDistinctId;
+    private identifiedTraits;
     constructor(config: FeatureFlagsSdkConfig);
+    private distinctIdKey;
+    private rebuildPersonBase;
+    /**
+     * Merge stored person context with per-call overrides (override wins on key clash).
+     */
+    private mergeContext;
+    /**
+     * Set person traits once (PostHog-style). First argument is written to `distinctIdKey` (default `userId`)
+     * and wins over the same key in `traits` if present.
+     */
+    identify(distinctId: string, traits?: EvaluationContext): void;
+    /**
+     * Clear identified person; evaluation base becomes `{}` until `identify` is called again.
+     */
+    reset(): void;
     private headers;
     private parseJson;
     /**

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAiBpB,qBAAa,kBAAkB;IAIjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAE7B,MAAM,EAAE,qBAAqB;YAO5C,OAAO;YAQP,SAAS;IAUvB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsB/C;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA2BtE,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB;IAUf,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,kBAAkB,CAAC;IAQxB,SAAS,CACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,OAAO,CAAC;IAUnB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAanD;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc1E,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;CAOnC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAiBpB,qBAAa,kBAAkB;IAQjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,iEAAiE;IACjE,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,oBAAoB,CAAuB;IACnD,OAAO,CAAC,gBAAgB,CAAyB;gBAEpB,MAAM,EAAE,qBAAqB;IAQ1D,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAE,iBAAsB,GAAG,IAAI;IAMlE;;OAEG;IACH,KAAK,IAAI,IAAI;YAMC,OAAO;YAQP,SAAS;IAUvB;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsB/C;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IA2BtE,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,kBAAkB;IAUf,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,kBAAkB,CAAC;IAQxB,SAAS,CACb,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,OAAO,CAAC;IAUnB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAanD;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc1E,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;CAOnC"}

package/dist/client.js

@@ -19,10 +19,52 @@ export class FeatureFlagsClient {
     config;
     fetchImpl;
     cache;
+    /** Merged evaluation base from `identify` (empty until then). */
+    personBase = {};
+    identifiedDistinctId = null;
+    identifiedTraits = {};
     constructor(config) {
         this.config = config;
         this.fetchImpl = config.fetchImpl ?? defaultFetch();
         this.cache = new TtlMemoryCache(config.cacheTtlMs ?? 60_000);
+        this.rebuildPersonBase();
+    }
+    distinctIdKey() {
+        return this.config.distinctIdKey ?? "userId";
+    }
+    rebuildPersonBase() {
+        if (this.identifiedDistinctId === null) {
+            this.personBase = {};
+            return;
+        }
+        const key = this.distinctIdKey();
+        this.personBase = {
+            ...this.identifiedTraits,
+            [key]: this.identifiedDistinctId,
+        };
+    }
+    /**
+     * Merge stored person context with per-call overrides (override wins on key clash).
+     */
+    mergeContext(extra) {
+        return { ...this.personBase, ...extra };
+    }
+    /**
+     * Set person traits once (PostHog-style). First argument is written to `distinctIdKey` (default `userId`)
+     * and wins over the same key in `traits` if present.
+     */
+    identify(distinctId, traits = {}) {
+        this.identifiedDistinctId = distinctId;
+        this.identifiedTraits = { ...traits };
+        this.rebuildPersonBase();
+    }
+    /**
+     * Clear identified person; evaluation base becomes `{}` until `identify` is called again.
+     */
+    reset() {
+        this.identifiedDistinctId = null;
+        this.identifiedTraits = {};
+        this.rebuildPersonBase();
     }
     async headers() {
         const extra = this.config.getHeaders ? await this.config.getHeaders() : {};
@@ -93,14 +135,14 @@ export class FeatureFlagsClient {
         if (!rec) {
             throw new Error(`Flag not in cache: ${flagKey}; call bootstrap() or getFlag() first`);
         }
-        return evaluateFlag(toDefinition(rec), context);
+        return evaluateFlag(toDefinition(rec), this.mergeContext(context));
     }
     async evaluateAsync(flagKey, context = {}) {
         const rec = (await this.getFlag(flagKey)) ?? this.cache.get(flagKey);
         if (!rec) {
             throw new Error(`Unknown flag: ${flagKey}`);
         }
-        return evaluateFlag(toDefinition(rec), context);
+        return evaluateFlag(toDefinition(rec), this.mergeContext(context));
     }
     async isEnabled(flagKey, context = {}) {
         try {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { FeatureFlagsClient } from "./client.js";
 export type { FeatureFlagRecord, FeatureFlagsSdkConfig, FlagListJson, HistoryEntryJson, HttpFetch, } from "./types.js";
-export type * from "@core-sdk/feature-flags-core";
+export type { EvaluationContext } from "@core-sdk/feature-flags-core";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,mBAAmB,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/types.d.ts

@@ -17,6 +17,11 @@ export interface FeatureFlagsSdkConfig {
     readonly getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
     /** Cache TTL for in-memory flag definitions (default 60_000) */
     readonly cacheTtlMs?: number;
+    /**
+     * Context key for `identify(distinctId, traits)` first argument (default `userId`).
+     * Align with declarative rule `field` names from your flag API.
+     */
+    readonly distinctIdKey?: string;
 }
 /** Loose API body — server may wrap in `{ data }`. */
 export type FlagListJson = unknown;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@core-sdk/feature-flags-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "HTTP client + cache for feature flags; uses @core-sdk/feature-flags-core for evaluation",
   "type": "module",
   "main": "./dist/index.js",