@frontegg/entitlements-javascript-commons 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/rules/tests/rule.evaluator.spec.ts

@@ -0,0 +1,135 @@
+import { ConditionLogicEnum, Rule, RuleEvaluationResultEnum, TreatmentEnum } from '../types';
+import { createRuleEvaluator } from '../rule.evaluator';
+import { OperationEnum } from '../../operations/types';
+
+describe('RuleEvaluator', () => {
+  it('should return RuleEvaluationResultEnum.Insufficient when conditions are invalid', () => {
+    const rule: Rule = {
+      treatment: TreatmentEnum.True,
+      conditions: [
+        {
+          attribute: 'test',
+          op: 'not supported' as any,
+          value: { list: ['test'] },
+          negate: false,
+        },
+      ],
+      conditionLogic: ConditionLogicEnum.And,
+    };
+
+    const ruleEvaluator = createRuleEvaluator({ rule });
+    const result = ruleEvaluator({});
+
+    expect(result).toEqual(RuleEvaluationResultEnum.Insufficient);
+  });
+
+  it('should return RuleEvaluationResultEnum.Insufficient when no (valid) condition passes validation', () => {
+    const rule: Rule = {
+      treatment: TreatmentEnum.True,
+      conditions: [
+        {
+          attribute: 'attribute',
+          op: OperationEnum.StartsWith,
+          value: { list: ['test'] },
+          negate: false,
+        },
+        {
+          attribute: 'attribute',
+          op: OperationEnum.Contains,
+          value: { list: ['test'] },
+          negate: false,
+        },
+      ],
+      conditionLogic: ConditionLogicEnum.And,
+    };
+
+    const ruleEvaluator = createRuleEvaluator({ rule });
+    const result = ruleEvaluator({ attribute: '1' });
+
+    expect(result).toEqual(RuleEvaluationResultEnum.Insufficient);
+  });
+
+  it('should return RuleEvaluationResultEnum.Insufficient when some (valid) conditions pass validation', () => {
+    const rule: Rule = {
+      treatment: TreatmentEnum.True,
+      conditions: [
+        {
+          attribute: 'attribute',
+          op: OperationEnum.StartsWith,
+          value: { list: ['test'] },
+          negate: false,
+        },
+        {
+          attribute: 'attribute',
+          op: OperationEnum.Contains,
+          value: { list: ['test'] },
+          negate: false,
+        },
+      ],
+      conditionLogic: ConditionLogicEnum.And,
+    };
+
+    const ruleEvaluator = createRuleEvaluator({ rule });
+    const result = ruleEvaluator({ attribute: 'te' });
+
+    expect(result).toEqual(RuleEvaluationResultEnum.Insufficient);
+  });
+
+  it('should return RuleEvaluationResultEnum.Treatable when all (valid) conditions pass validation', () => {
+    const rule: Rule = {
+      treatment: TreatmentEnum.True,
+      conditions: [
+        {
+          attribute: 'attribute',
+          op: OperationEnum.InList,
+          value: { list: ['test'] },
+          negate: false,
+        },
+        {
+          attribute: 'attribute',
+          op: OperationEnum.Contains,
+          value: { list: ['test'] },
+          negate: false,
+        },
+      ],
+      conditionLogic: ConditionLogicEnum.And,
+    };
+
+    const ruleEvaluator = createRuleEvaluator({ rule });
+    const result = ruleEvaluator({ attribute: 'test' });
+
+    expect(result).toEqual(RuleEvaluationResultEnum.Treatable);
+  });
+
+  it('should return RuleEvaluationResultEnum.Treatable when all (valid) conditions pass validation', () => {
+    const rule: Rule = {
+      treatment: TreatmentEnum.True,
+      conditions: [
+        {
+          attribute: 'attribute',
+          op: OperationEnum.InList,
+          value: { list: ['test'] },
+          negate: false,
+        },
+        {
+          attribute: 'attribute',
+          op: OperationEnum.Contains,
+          value: { list: ['not'] },
+          negate: true,
+        },
+        {
+          attribute: 'numeric',
+          op: OperationEnum.Equal,
+          value: { number: 2 },
+          negate: false,
+        },
+      ],
+      conditionLogic: ConditionLogicEnum.And,
+    };
+
+    const ruleEvaluator = createRuleEvaluator({ rule });
+    const result = ruleEvaluator({ attribute: 'test', numeric: 2 });
+
+    expect(result).toEqual(RuleEvaluationResultEnum.Treatable);
+  });
+});

package/src/rules/types.ts

@@ -0,0 +1,27 @@
+import { Condition } from '../conditions';
+
+export interface Rule {
+  conditionLogic: ConditionLogicEnum.And;
+  conditions: Condition[];
+  treatment: TreatmentEnum;
+}
+
+export enum ConditionLogicEnum {
+  And = 'and',
+}
+
+export enum TreatmentEnum {
+  True = 'true',
+  False = 'false',
+}
+
+export enum RuleEvaluationResultEnum {
+  Treatable = 'treatable',
+  Insufficient = 'insufficient',
+}
+
+export interface CreateRuleEvaluatorPayload {
+  rule: Rule;
+}
+
+export type RuleEvaluator = (attributes: Record<string, unknown>) => RuleEvaluationResultEnum;

package/src/user-entitlements/attributes.utils.ts

@@ -0,0 +1,44 @@
+import { flatten } from 'flat';
+import { Attributes, JwtAttributes, FronteggAttributes } from './types';
+
+/**
+ *  Merges both `custom` and `jwt` records, map Frontegg attributes and modifies record keys with corrisponding prefixes
+ *
+ *  Example:
+ *  Input: { 'custom': { 'customAttribute': 'someValue' }, 'jwt': { 'email': 'user@email.com', other: 'some-vaule' } }
+ *  Output: { 'customAttribute': 'someValue', 'frontegg.email': 'user@email.com', 'jwt.email': 'user@email.com', 'jwt.other': 'some-vaule' }
+ */
+export function prepareAttributes(
+  attributes: Attributes = {},
+  customFronteggAttributesMapper?: (jwtAttributes: JwtAttributes) => FronteggAttributes,
+): Record<string, unknown> {
+  const { custom = {}, jwt = {} } = attributes;
+  const flatJwtAttributes = flatten<JwtAttributes, JwtAttributes>(jwt);
+  const fronteggAttributes = customFronteggAttributesMapper
+    ? customFronteggAttributesMapper(jwt)
+    : defaultFronteggAttributesMapper(jwt);
+  const fronteggAttributesPrefix = 'frontegg.';
+  const jwtAttributesPrefix = 'jwt.';
+
+  return {
+    ...custom,
+    ...modifyObjectKeysWithPrefix(fronteggAttributes, fronteggAttributesPrefix),
+    ...modifyObjectKeysWithPrefix(flatJwtAttributes, jwtAttributesPrefix),
+  };
+}
+
+export function defaultFronteggAttributesMapper(jwt: JwtAttributes): FronteggAttributes {
+  return {
+    email: jwt.email as string,
+    emailVerified: jwt.email_verified as boolean,
+    tenantId: jwt.tenantId as string,
+    userId: jwt.userId as string,
+  };
+}
+
+export function modifyObjectKeysWithPrefix(object: Record<string, unknown>, prefix: string): Record<string, unknown> {
+  return Object.keys(object).reduce((modifiedObject, currentKey) => {
+    modifiedObject[`${prefix}${currentKey}`] = object[currentKey];
+    return modifiedObject;
+  }, {});
+}

package/src/user-entitlements/index.ts

@@ -0,0 +1,3 @@
+export * from './is-entitled.evaluator';
+export * from './types';
+export * from './attributes.utils';

package/src/user-entitlements/is-entitled.evaluator.ts

@@ -0,0 +1,82 @@
+import {
+  EntitlementResult,
+  NotEntitledJustification,
+  NO_EXPIRATION_TIME,
+  UserEntitlementsContext,
+  Attributes,
+} from './types';
+
+import { evaluateFeatureFlag } from '../feature-flags';
+import { prepareAttributes } from './attributes.utils';
+import { TreatmentEnum } from '../rules';
+export function evaluateIsEntitledToFeature(
+  featureKey: string,
+  userEntitlementsContext: UserEntitlementsContext,
+  attributes: Attributes = {},
+): EntitlementResult {
+  const feature = userEntitlementsContext.features[featureKey];
+  let hasExpired = false;
+  if (feature && feature.expireTime !== null) {
+    hasExpired = feature.expireTime !== NO_EXPIRATION_TIME && feature.expireTime < Date.now();
+
+    if (!hasExpired) {
+      return { isEntitled: true };
+    }
+  }
+
+  if (feature && feature.featureFlag) {
+    const preparedAttributes = prepareAttributes(attributes);
+    const { treatment } = evaluateFeatureFlag(feature.featureFlag, preparedAttributes);
+    if (treatment === TreatmentEnum.True) {
+      return { isEntitled: true };
+    }
+  }
+
+  return {
+    isEntitled: false,
+    justification: hasExpired ? NotEntitledJustification.BUNDLE_EXPIRED : NotEntitledJustification.MISSING_FEATURE,
+  };
+}
+
+export function evaluateIsEntitledToPermissions(
+  permissionKey: string,
+  userEntitlementsContext: UserEntitlementsContext,
+  attributes?: Attributes,
+): EntitlementResult {
+  const permission = userEntitlementsContext.permissions[permissionKey];
+
+  if (!permission) {
+    return { isEntitled: false, justification: NotEntitledJustification.MISSING_PERMISSION };
+  }
+
+  const linkedFeatures = getLinkedFeatures(permissionKey, userEntitlementsContext);
+
+  if (!linkedFeatures.length) {
+    return { isEntitled: true };
+  }
+
+  let hasExpired = false;
+
+  for (const featureKey of linkedFeatures) {
+    const { isEntitled, justification } = evaluateIsEntitledToFeature(featureKey, userEntitlementsContext, attributes);
+
+    if (isEntitled) {
+      return { isEntitled: true };
+    }
+
+    if (justification === NotEntitledJustification.BUNDLE_EXPIRED) {
+      hasExpired = true;
+    }
+  }
+
+  return {
+    isEntitled: false,
+    justification: hasExpired ? NotEntitledJustification.BUNDLE_EXPIRED : NotEntitledJustification.MISSING_FEATURE,
+  };
+}
+
+function getLinkedFeatures(permissionKey: string, userEntitlementsContext: UserEntitlementsContext): string[] {
+  return Object.keys(userEntitlementsContext.features).filter((featureKey) =>
+    userEntitlementsContext.features[featureKey].linkedPermissions.includes(permissionKey),
+  );
+}

package/src/user-entitlements/tests/attributes.utils.spec.ts

@@ -0,0 +1,76 @@
+import * as AttributesUtils from '../attributes.utils';
+import { Attributes, FronteggAttributes, JwtAttributes } from '../types';
+import { flatten } from 'flat';
+describe('prepareAttributes', () => {
+  test('given custom & jwt attributes, expected is merged & flatten attributes record', () => {
+    const attributes: Attributes = {
+      custom: {
+        customAttribute: 'some-value',
+      },
+      jwt: {
+        userId: 'user-1',
+        tenantId: 'tenant-1',
+        email: 'test@email.com',
+        email_verified: true,
+        dummyAttribute: 'dummy',
+      },
+    };
+
+    const expectedPreparedAttributes = {
+      customAttribute: 'some-value',
+      'frontegg.userId': 'user-1',
+      'frontegg.tenantId': 'tenant-1',
+      'frontegg.email': 'test@email.com',
+      'frontegg.emailVerified': true,
+      'jwt.userId': 'user-1',
+      'jwt.tenantId': 'tenant-1',
+      'jwt.email': 'test@email.com',
+      'jwt.email_verified': true,
+      'jwt.dummyAttribute': 'dummy',
+    };
+
+    const preparedAttributes = AttributesUtils.prepareAttributes(attributes);
+
+    expect(preparedAttributes).toEqual(expectedPreparedAttributes);
+  });
+});
+
+describe('defaultFronteggAttributesMapper', () => {
+  test('given jwt-attributes, expected mapped frontegg-attributes', async () => {
+    const jwtAttributes: JwtAttributes = {
+      userId: 'user-1',
+      tenantId: 'tenant-1',
+      email: 'test@email.com',
+      email_verified: true,
+      dummyAttribute: 'dummy',
+    };
+
+    const expectedFronteggAttributes: FronteggAttributes = {
+      userId: 'user-1',
+      tenantId: 'tenant-1',
+      email: 'test@email.com',
+      emailVerified: true,
+    };
+
+    const mappedAttributes = AttributesUtils.defaultFronteggAttributesMapper(jwtAttributes);
+
+    expect(mappedAttributes).toEqual(expectedFronteggAttributes);
+  });
+});
+
+describe('modifyObjectKeysWithPrefix', () => {
+  test('given object and prefix, object keys should altered with prefix', async () => {
+    const prefix = 'test.';
+    const obj = {
+      property: 'value',
+    };
+
+    const expectedModifiedObject = {
+      'test.property': 'value',
+    };
+
+    const modifiedObject = AttributesUtils.modifyObjectKeysWithPrefix(obj, prefix);
+
+    expect(modifiedObject).toEqual(expectedModifiedObject);
+  });
+});

package/src/user-entitlements/tests/is-entitled.evaluator.spec.ts

@@ -0,0 +1,298 @@
+import * as IsEntitledEvaluators from '../is-entitled.evaluator';
+import * as FeatureFlagEvalutor from '../../feature-flags/feature-flag.evaluator';
+import * as AttributesUtils from '../attributes.utils';
+import { TreatmentEnum } from '../../rules';
+import { EntitlementResult, NotEntitledJustification, NO_EXPIRATION_TIME, UserEntitlementsContext } from '../types';
+import { FeatureFlag } from '../../feature-flags/types';
+
+const mockFeatureFlag: FeatureFlag = {
+  on: true,
+  defaultTreatment: TreatmentEnum.True,
+  offTreatment: TreatmentEnum.False,
+  rules: [],
+};
+const truthyEntitlementResult: EntitlementResult = {
+  isEntitled: true,
+};
+const falsyEntitlementResultMissingFeature: EntitlementResult = {
+  isEntitled: false,
+  justification: NotEntitledJustification.MISSING_FEATURE,
+};
+const falsyEntitlementResultBundleExpired: EntitlementResult = {
+  isEntitled: false,
+  justification: NotEntitledJustification.BUNDLE_EXPIRED,
+};
+const falsyEntitlementResultMissingPermission: EntitlementResult = {
+  isEntitled: false,
+  justification: NotEntitledJustification.MISSING_PERMISSION,
+};
+describe('evaluateIsEntitledToFeature', () => {
+  beforeAll(() => {
+    jest.spyOn(AttributesUtils, 'prepareAttributes').mockReturnValue({ testAttribute: 'test-value' });
+  });
+  describe('entitled', () => {
+    describe('feature-flag evaluated truthy', () => {
+      beforeAll(async () => {
+        jest.spyOn(FeatureFlagEvalutor, 'evaluateFeatureFlag').mockReturnValue({ treatment: TreatmentEnum.True });
+      });
+
+      test('feature granted with valid expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: new Date().getTime() + 3600,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+      test('feature granted with expired expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: new Date().getTime() - 3600,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+      test('feature granted with no expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: NO_EXPIRATION_TIME,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+      test('feature has not been granted', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: null,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+    });
+    describe('feature-flag evaluated falsy', () => {
+      beforeAll(async () => {
+        jest.spyOn(FeatureFlagEvalutor, 'evaluateFeatureFlag').mockReturnValue({ treatment: TreatmentEnum.False });
+      });
+      test('feature granted with no expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: NO_EXPIRATION_TIME,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+      test('feature granted with valid expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: Date.now() + 3600,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+    });
+    describe('no feature flag', () => {
+      test('feature granted with no expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: NO_EXPIRATION_TIME,
+              linkedPermissions: [],
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+      test('feature granted with valid expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: Date.now() + 3600,
+              linkedPermissions: [],
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(truthyEntitlementResult);
+      });
+    });
+  });
+
+  describe('not entitled', () => {
+    describe('feature-flag evaluated falsy', () => {
+      beforeAll(async () => {
+        jest.spyOn(FeatureFlagEvalutor, 'evaluateFeatureFlag').mockReturnValue({ treatment: TreatmentEnum.False });
+      });
+      test('feature has not been granted', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: null,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(falsyEntitlementResultMissingFeature);
+      });
+      test('feature granted with expired expiration date', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {
+            'test-feature': {
+              expireTime: Date.now() - 3600,
+              linkedPermissions: [],
+              featureFlag: mockFeatureFlag,
+            },
+          },
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(falsyEntitlementResultBundleExpired);
+      });
+    });
+
+    describe('no feature', () => {
+      test('feature does not exist', async () => {
+        const userEntitlementContext: UserEntitlementsContext = {
+          features: {},
+          permissions: {},
+        };
+        const result = IsEntitledEvaluators.evaluateIsEntitledToFeature('test-feature', userEntitlementContext, {});
+
+        expect(result).toEqual(falsyEntitlementResultMissingFeature);
+      });
+    });
+  });
+});
+
+describe('evaluateIsEntitledToPermission', () => {
+  describe('entitled', () => {
+    test('permission granted, no linked feature/s to it', async () => {
+      const userEntitlementContext: UserEntitlementsContext = {
+        features: {},
+        permissions: { 'test.permission': true },
+      };
+      const result = IsEntitledEvaluators.evaluateIsEntitledToPermissions(
+        'test.permission',
+        userEntitlementContext,
+        {},
+      );
+
+      expect(result).toEqual(truthyEntitlementResult);
+    });
+    test('permission granted with linked feature/s, feature is entitled', async () => {
+      jest.spyOn(IsEntitledEvaluators, 'evaluateIsEntitledToFeature').mockReturnValue({ isEntitled: true });
+
+      const userEntitlementContext: UserEntitlementsContext = {
+        features: { 'test-feature': { expireTime: NO_EXPIRATION_TIME, linkedPermissions: ['test.permission'] } },
+        permissions: { 'test.permission': true },
+      };
+
+      const result = IsEntitledEvaluators.evaluateIsEntitledToPermissions(
+        'test.permission',
+        userEntitlementContext,
+        {},
+      );
+
+      expect(result).toEqual(truthyEntitlementResult);
+    });
+  });
+
+  describe('not entitled', () => {
+    test('permission not granted', async () => {
+      const userEntitlementContext: UserEntitlementsContext = {
+        features: {},
+        permissions: {},
+      };
+      const result = IsEntitledEvaluators.evaluateIsEntitledToPermissions(
+        'test.permission',
+        userEntitlementContext,
+        {},
+      );
+
+      expect(result).toEqual(falsyEntitlementResultMissingPermission);
+    });
+    test('permission granted with linked feature/s, no feature is entiteld', async () => {
+      jest
+        .spyOn(IsEntitledEvaluators, 'evaluateIsEntitledToFeature')
+        .mockReturnValue({ isEntitled: false, justification: NotEntitledJustification.MISSING_FEATURE });
+
+      const userEntitlementContext: UserEntitlementsContext = {
+        features: { 'test-feature': { expireTime: null, linkedPermissions: ['test.permission'] } },
+        permissions: { 'test.permission': true },
+      };
+
+      const result = IsEntitledEvaluators.evaluateIsEntitledToPermissions(
+        'test.permission',
+        userEntitlementContext,
+        {},
+      );
+
+      expect(result).toEqual(falsyEntitlementResultMissingFeature);
+    });
+    test('permission granted with linked feature/s, no feature is entiteld with expired bundle', async () => {
+      jest
+        .spyOn(IsEntitledEvaluators, 'evaluateIsEntitledToFeature')
+        .mockReturnValue({ isEntitled: false, justification: NotEntitledJustification.BUNDLE_EXPIRED });
+    });
+
+    const userEntitlementContext: UserEntitlementsContext = {
+      features: { 'test-feature': { expireTime: Date.now() - 3600, linkedPermissions: ['test.permission'] } },
+      permissions: { 'test.permission': true },
+    };
+
+    const result = IsEntitledEvaluators.evaluateIsEntitledToPermissions('test.permission', userEntitlementContext, {});
+
+    expect(result).toEqual(falsyEntitlementResultBundleExpired);
+  });
+});