@lssm/lib.feature-flags 0.0.0-canary-20251210171026 → 0.0.0-canary-20251212004227

package/README.md

@@ -138,7 +138,7 @@ This module integrates with:
 
 - `@lssm/lib.identity-rbac` - User/org context for targeting
 - `@lssm/lib.analytics` - Evaluation tracking
-- `@lssm/modules.audit-trail` - Configuration changes
+- `@lssm/module.audit-trail` - Configuration changes
 
 ## Schema Contribution
 

package/dist/docs/feature-flags.docblock.js

@@ -0,0 +1,57 @@
+import{registerDocBlocks as e}from"@lssm/lib.contracts/docs";e([{id:`docs.feature-flags.overview`,title:`Feature Flags & Experiments`,summary:`Reusable, spec-first feature flag and experiment module with targeting, gradual rollout, multivariate variants, and evaluation logging.`,kind:`reference`,visibility:`public`,route:`/docs/feature-flags/overview`,tags:[`feature-flags`,`experiments`,`progressive-delivery`],body:`## What this module provides
+
+- **Entities**: FeatureFlag, FlagTargetingRule, Experiment, ExperimentAssignment, FlagEvaluation.
+- **Contracts**: create/update/delete/toggle/list/get flags; create/delete rules; evaluate flags; create/start/stop/get experiments.
+- **Events**: flag.created/updated/deleted/toggled, rule.created/deleted, experiment.created/started/stopped, flag.evaluated, experiment.variant_assigned.
+- **Evaluation Engine**: Deterministic evaluator with gradual rollout, rule priority, audience filters, and experiment bucketing.
+
+## How to use
+
+1) Compose schema
+ - Add \`featureFlagsSchemaContribution\` to your module composition.
+
+2) Register contracts/events
+ - Import exports from \`@lssm/lib.feature-flags\` into your spec registry.
+
+3) Evaluate at runtime
+ - Instantiate \`FlagEvaluator\` with a repository implementation and optional logger.
+ - Evaluate with context attributes (userId, orgId, plan, segment, sessionId, attributes).
+
+4) Wire observability
+ - Emit audit trail on config changes; emit \`flag.evaluated\` for analytics.
+
+## Usage example
+
+\`\`\`ts
+import {
+  FlagEvaluator,
+  InMemoryFlagRepository,
+} from '@lssm/lib.feature-flags';
+
+const repo = new InMemoryFlagRepository();
+repo.addFlag({
+  id: 'flag-1',
+  key: 'new_dashboard',
+  status: 'GRADUAL',
+  defaultValue: false,
+});
+
+const evaluator = new FlagEvaluator({ repository: repo });
+const result = await evaluator.evaluate('new_dashboard', {
+  userId: 'user-123',
+  orgId: 'org-456',
+  plan: 'pro',
+});
+
+if (result.enabled) {
+  // serve the new dashboard
+}
+\`\`\`,
+
+## Guardrails
+
+- Keep flag keys stable and human-readable; avoid PII in context.
+- Ensure experiments’ variant percentages sum to 100; default flag status to OFF.
+- Use org-scoped flags for multi-tenant isolation.
+- Log evaluations only when needed to control volume; prefer sampling for noisy paths.
+`}]);

package/dist/docs/index.js

@@ -0,0 +1 @@
+import"./feature-flags.docblock.js";

package/dist/index.js

@@ -1 +1 @@
-import{ExperimentCreatedEvent as e,ExperimentStartedEvent as t,ExperimentStoppedEvent as n,FeatureFlagEvents as r,FlagCreatedEvent as i,FlagDeletedEvent as a,FlagEvaluatedEvent as o,FlagToggledEvent as s,FlagUpdatedEvent as c,RuleCreatedEvent as l,RuleDeletedEvent as u,VariantAssignedEvent as d}from"./events.js";import{ExperimentAssignmentEntity as f,ExperimentEntity as p,ExperimentStatusEnum as m,FeatureFlagEntity as h,FlagEvaluationEntity as g,FlagStatusEnum as _,FlagTargetingRuleEntity as v,RuleOperatorEnum as y,featureFlagEntities as b,featureFlagsSchemaContribution as x}from"./entities/index.js";import{CreateExperimentContract as S,CreateFlagContract as C,CreateRuleContract as w,DeleteFlagContract as T,DeleteRuleContract as E,EvaluateFlagContract as D,EvaluationResultModel as O,ExperimentModel as k,FeatureFlagModel as A,GetExperimentContract as j,GetFlagContract as M,ListFlagsContract as N,StartExperimentContract as P,StopExperimentContract as F,TargetingRuleModel as I,ToggleFlagContract as L,UpdateFlagContract as R}from"./contracts/index.js";import{FlagEvaluator as z,InMemoryFlagRepository as B,evaluateRuleCondition as V,getSubjectId as H,hashToBucket as U}from"./evaluation/index.js";export{S as CreateExperimentContract,C as CreateFlagContract,w as CreateRuleContract,T as DeleteFlagContract,E as DeleteRuleContract,D as EvaluateFlagContract,O as EvaluationResultModel,f as ExperimentAssignmentEntity,e as ExperimentCreatedEvent,p as ExperimentEntity,k as ExperimentModel,t as ExperimentStartedEvent,m as ExperimentStatusEnum,n as ExperimentStoppedEvent,h as FeatureFlagEntity,r as FeatureFlagEvents,A as FeatureFlagModel,i as FlagCreatedEvent,a as FlagDeletedEvent,o as FlagEvaluatedEvent,g as FlagEvaluationEntity,z as FlagEvaluator,_ as FlagStatusEnum,v as FlagTargetingRuleEntity,s as FlagToggledEvent,c as FlagUpdatedEvent,j as GetExperimentContract,M as GetFlagContract,B as InMemoryFlagRepository,N as ListFlagsContract,l as RuleCreatedEvent,u as RuleDeletedEvent,y as RuleOperatorEnum,P as StartExperimentContract,F as StopExperimentContract,I as TargetingRuleModel,L as ToggleFlagContract,R as UpdateFlagContract,d as VariantAssignedEvent,V as evaluateRuleCondition,b as featureFlagEntities,x as featureFlagsSchemaContribution,H as getSubjectId,U as hashToBucket};
+import{ExperimentCreatedEvent as e,ExperimentStartedEvent as t,ExperimentStoppedEvent as n,FeatureFlagEvents as r,FlagCreatedEvent as i,FlagDeletedEvent as a,FlagEvaluatedEvent as o,FlagToggledEvent as s,FlagUpdatedEvent as c,RuleCreatedEvent as l,RuleDeletedEvent as u,VariantAssignedEvent as d}from"./events.js";import{ExperimentAssignmentEntity as f,ExperimentEntity as p,ExperimentStatusEnum as m,FeatureFlagEntity as h,FlagEvaluationEntity as g,FlagStatusEnum as _,FlagTargetingRuleEntity as v,RuleOperatorEnum as y,featureFlagEntities as b,featureFlagsSchemaContribution as x}from"./entities/index.js";import{CreateExperimentContract as S,CreateFlagContract as C,CreateRuleContract as w,DeleteFlagContract as T,DeleteRuleContract as E,EvaluateFlagContract as D,EvaluationResultModel as O,ExperimentModel as k,FeatureFlagModel as A,GetExperimentContract as j,GetFlagContract as M,ListFlagsContract as N,StartExperimentContract as P,StopExperimentContract as F,TargetingRuleModel as I,ToggleFlagContract as L,UpdateFlagContract as R}from"./contracts/index.js";import{FlagEvaluator as z,InMemoryFlagRepository as B,evaluateRuleCondition as V,getSubjectId as H,hashToBucket as U}from"./evaluation/index.js";import"./docs/index.js";export{S as CreateExperimentContract,C as CreateFlagContract,w as CreateRuleContract,T as DeleteFlagContract,E as DeleteRuleContract,D as EvaluateFlagContract,O as EvaluationResultModel,f as ExperimentAssignmentEntity,e as ExperimentCreatedEvent,p as ExperimentEntity,k as ExperimentModel,t as ExperimentStartedEvent,m as ExperimentStatusEnum,n as ExperimentStoppedEvent,h as FeatureFlagEntity,r as FeatureFlagEvents,A as FeatureFlagModel,i as FlagCreatedEvent,a as FlagDeletedEvent,o as FlagEvaluatedEvent,g as FlagEvaluationEntity,z as FlagEvaluator,_ as FlagStatusEnum,v as FlagTargetingRuleEntity,s as FlagToggledEvent,c as FlagUpdatedEvent,j as GetExperimentContract,M as GetFlagContract,B as InMemoryFlagRepository,N as ListFlagsContract,l as RuleCreatedEvent,u as RuleDeletedEvent,y as RuleOperatorEnum,P as StartExperimentContract,F as StopExperimentContract,I as TargetingRuleModel,L as ToggleFlagContract,R as UpdateFlagContract,d as VariantAssignedEvent,V as evaluateRuleCondition,b as featureFlagEntities,x as featureFlagsSchemaContribution,H as getSubjectId,U as hashToBucket};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.feature-flags",
-  "version": "0.0.0-canary-20251210171026",
+  "version": "0.0.0-canary-20251212004227",
   "description": "Feature flags and experiments module for ContractSpec applications",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -29,6 +29,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./contracts": "./src/contracts/index.ts",
+    "./docs": "./src/docs/index.ts",
+    "./docs/feature-flags.docblock": "./src/docs/feature-flags.docblock.ts",
     "./entities": "./src/entities/index.ts",
     "./evaluation": "./src/evaluation/index.ts",
     "./events": "./src/events.ts",
@@ -44,6 +46,8 @@
     "exports": {
       ".": "./dist/index.js",
       "./contracts": "./dist/contracts/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/feature-flags.docblock": "./dist/docs/feature-flags.docblock.js",
       "./entities": "./dist/entities/index.js",
       "./evaluation": "./dist/evaluation/index.js",
       "./events": "./dist/events.js",