@metamask-previews/remote-feature-flag-controller 1.2.0-preview-4e54ae1 → 1.3.0-preview-298fc547

package/CHANGELOG.md

@@ -7,8 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0]
+
 ### Changed
 
+- Improve user segmentation with BigInt-based random generation ([#5110](https://github.com/MetaMask/core/pull/5110))
+- Change getMetaMetricsId to only sync func type ([#5108](https://github.com/MetaMask/core/pull/5108))
 - Bump `@metamask/base-controller` from `^7.0.0` to `^7.1.0` ([#5079](https://github.com/MetaMask/core/pull/5079))
 
 ## [1.2.0]
@@ -38,7 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial release of the RemoteFeatureFlagController. ([#4931](https://github.com/MetaMask/core/pull/4931))
   - This controller manages the retrieval and caching of remote feature flags. It fetches feature flags from a remote API, caches them, and provides methods to access and manage these flags. The controller ensures that feature flags are refreshed based on a specified interval and handles cases where the controller is disabled or the network is unavailable.
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/remote-feature-flag-controller@1.2.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/remote-feature-flag-controller@1.3.0...HEAD
+[1.3.0]: https://github.com/MetaMask/core/compare/@metamask/remote-feature-flag-controller@1.2.0...@metamask/remote-feature-flag-controller@1.3.0
 [1.2.0]: https://github.com/MetaMask/core/compare/@metamask/remote-feature-flag-controller@1.1.0...@metamask/remote-feature-flag-controller@1.2.0
 [1.1.0]: https://github.com/MetaMask/core/compare/@metamask/remote-feature-flag-controller@1.0.0...@metamask/remote-feature-flag-controller@1.1.0
 [1.0.0]: https://github.com/MetaMask/core/releases/tag/@metamask/remote-feature-flag-controller@1.0.0

package/dist/utils/user-segmentation-utils.cjs

@@ -1,21 +1,62 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isFeatureFlagWithScopeValue = exports.generateDeterministicRandomNumber = void 0;
-/* eslint-disable no-bitwise */
+const uuid_1 = require("uuid");
+/**
+ * Converts a UUID string to a BigInt by removing dashes and converting to hexadecimal.
+ * @param uuid - The UUID string to convert
+ * @returns The UUID as a BigInt value
+ */
+function uuidStringToBigInt(uuid) {
+    return BigInt(`0x${uuid.replace(/-/gu, '')}`);
+}
+const MIN_UUID_V4 = '00000000-0000-4000-8000-000000000000';
+const MAX_UUID_V4 = 'ffffffff-ffff-4fff-bfff-ffffffffffff';
+const MIN_UUID_V4_BIGINT = uuidStringToBigInt(MIN_UUID_V4);
+const MAX_UUID_V4_BIGINT = uuidStringToBigInt(MAX_UUID_V4);
+const UUID_V4_VALUE_RANGE_BIGINT = MAX_UUID_V4_BIGINT - MIN_UUID_V4_BIGINT;
 /**
  * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.
  * This is useful for A/B testing and feature flag rollouts where we want
  * consistent group assignment for the same user.
- *
- * @param metaMetricsId - The unique identifier used to generate the deterministic random number
- * @returns A number between 0 and 1 that is deterministic for the given metaMetricsId
+ * @param metaMetricsId - The unique identifier used to generate the deterministic random number. Must be either:
+ * - A UUIDv4 string (e.g., '123e4567-e89b-12d3-a456-426614174000'
+ * - A hex string with '0x' prefix (e.g., '0x86bacb9b2bf9a7e8d2b147eadb95ac9aaa26842327cd24afc8bd4b3c1d136420')
+ * @returns A number between 0 and 1, deterministically generated from the input ID.
+ * The same input will always produce the same output.
  */
 function generateDeterministicRandomNumber(metaMetricsId) {
-    const hash = [...metaMetricsId].reduce((acc, char) => {
-        const chr = char.charCodeAt(0);
-        return ((acc << 5) - acc + chr) | 0;
-    }, 0);
-    return (hash >>> 0) / 0xffffffff;
+    if (!metaMetricsId) {
+        throw new Error('MetaMetrics ID cannot be empty');
+    }
+    let idValue;
+    let maxValue;
+    // uuidv4 format
+    if ((0, uuid_1.validate)(metaMetricsId)) {
+        if ((0, uuid_1.version)(metaMetricsId) !== 4) {
+            throw new Error(`Invalid UUID version. Expected v4, got v${(0, uuid_1.version)(metaMetricsId)}`);
+        }
+        idValue = uuidStringToBigInt(metaMetricsId) - MIN_UUID_V4_BIGINT;
+        maxValue = UUID_V4_VALUE_RANGE_BIGINT;
+    }
+    else {
+        // hex format with 0x prefix
+        if (!metaMetricsId.startsWith('0x')) {
+            throw new Error('Hex ID must start with 0x prefix');
+        }
+        const cleanId = metaMetricsId.slice(2);
+        const EXPECTED_HEX_LENGTH = 64; // 32 bytes = 64 hex characters
+        if (cleanId.length !== EXPECTED_HEX_LENGTH) {
+            throw new Error(`Invalid hex ID length. Expected ${EXPECTED_HEX_LENGTH} characters, got ${cleanId.length}`);
+        }
+        if (!/^[0-9a-f]+$/iu.test(cleanId)) {
+            throw new Error('Hex ID contains invalid characters');
+        }
+        idValue = BigInt(`0x${cleanId}`);
+        maxValue = BigInt(`0x${'f'.repeat(cleanId.length)}`);
+    }
+    // Use BigInt division first, then convert to number to maintain precision
+    return Number((idValue * BigInt(1000000)) / maxValue) / 1000000;
 }
 exports.generateDeterministicRandomNumber = generateDeterministicRandomNumber;
 /**

package/dist/utils/user-segmentation-utils.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"user-segmentation-utils.cjs","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":";;;AAIA,+BAA+B;AAC/B;;;;;;;GAOG;AACH,SAAgB,iCAAiC,CAC/C,aAAqB;IAErB,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEN,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;AACnC,CAAC;AATD,8EASC;AAED;;;;;;GAMG;AACI,MAAM,2BAA2B,GAAG,CACzC,WAAiB,EACqB,EAAE;IACxC,OAAO,CACL,OAAO,WAAW,KAAK,QAAQ;QAC/B,WAAW,KAAK,IAAI;QACpB,OAAO,IAAI,WAAW,CACvB,CAAC;AACJ,CAAC,CAAC;AARW,QAAA,2BAA2B,+BAQtC","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport type { FeatureFlagScopeValue } from '../remote-feature-flag-controller-types';\n\n/* eslint-disable no-bitwise */\n/**\n * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.\n * This is useful for A/B testing and feature flag rollouts where we want\n * consistent group assignment for the same user.\n *\n * @param metaMetricsId - The unique identifier used to generate the deterministic random number\n * @returns A number between 0 and 1 that is deterministic for the given metaMetricsId\n */\nexport function generateDeterministicRandomNumber(\n  metaMetricsId: string,\n): number {\n  const hash = [...metaMetricsId].reduce((acc, char) => {\n    const chr = char.charCodeAt(0);\n    return ((acc << 5) - acc + chr) | 0;\n  }, 0);\n\n  return (hash >>> 0) / 0xffffffff;\n}\n\n/**\n * Type guard to check if a value is a feature flag with scope.\n * Used to validate feature flag objects that contain scope-based configurations.\n *\n * @param featureFlag - The value to check if it's a feature flag with scope\n * @returns True if the value is a feature flag with scope, false otherwise\n */\nexport const isFeatureFlagWithScopeValue = (\n  featureFlag: Json,\n): featureFlag is FeatureFlagScopeValue => {\n  return (\n    typeof featureFlag === 'object' &&\n    featureFlag !== null &&\n    'scope' in featureFlag\n  );\n};\n"]}
+{"version":3,"file":"user-segmentation-utils.cjs","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":";;;AACA,+BAAwE;AAIxE;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,MAAM,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAC3D,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAC3D,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;AAC3D,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;AAC3D,MAAM,0BAA0B,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAE3E;;;;;;;;;GASG;AACH,SAAgB,iCAAiC,CAC/C,aAAqB;IAErB,IAAI,CAAC,aAAa,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;KACnD;IAED,IAAI,OAAe,CAAC;IACpB,IAAI,QAAgB,CAAC;IAErB,gBAAgB;IAChB,IAAI,IAAA,eAAY,EAAC,aAAa,CAAC,EAAE;QAC/B,IAAI,IAAA,cAAW,EAAC,aAAa,CAAC,KAAK,CAAC,EAAE;YACpC,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAA,cAAW,EAAC,aAAa,CAAC,EAAE,CACxE,CAAC;SACH;QACD,OAAO,GAAG,kBAAkB,CAAC,aAAa,CAAC,GAAG,kBAAkB,CAAC;QACjE,QAAQ,GAAG,0BAA0B,CAAC;KACvC;SAAM;QACL,4BAA4B;QAC5B,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;YACnC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;SACrD;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,mBAAmB,GAAG,EAAE,CAAC,CAAC,+BAA+B;QAE/D,IAAI,OAAO,CAAC,MAAM,KAAK,mBAAmB,EAAE;YAC1C,MAAM,IAAI,KAAK,CACb,mCAAmC,mBAAmB,oBAAoB,OAAO,CAAC,MAAM,EAAE,CAC3F,CAAC;SACH;QAED,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;YAClC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;SACvD;QAED,OAAO,GAAG,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QACjC,QAAQ,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;KACtD;IAED,0EAA0E;IAC1E,OAAO,MAAM,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,OAAS,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,OAAS,CAAC;AACtE,CAAC;AA5CD,8EA4CC;AAED;;;;;;GAMG;AACI,MAAM,2BAA2B,GAAG,CACzC,WAAiB,EACqB,EAAE;IACxC,OAAO,CACL,OAAO,WAAW,KAAK,QAAQ;QAC/B,WAAW,KAAK,IAAI;QACpB,OAAO,IAAI,WAAW,CACvB,CAAC;AACJ,CAAC,CAAC;AARW,QAAA,2BAA2B,+BAQtC","sourcesContent":["import type { Json } from '@metamask/utils';\nimport { validate as uuidValidate, version as uuidVersion } from 'uuid';\n\nimport type { FeatureFlagScopeValue } from '../remote-feature-flag-controller-types';\n\n/**\n * Converts a UUID string to a BigInt by removing dashes and converting to hexadecimal.\n * @param uuid - The UUID string to convert\n * @returns The UUID as a BigInt value\n */\nfunction uuidStringToBigInt(uuid: string): bigint {\n  return BigInt(`0x${uuid.replace(/-/gu, '')}`);\n}\n\nconst MIN_UUID_V4 = '00000000-0000-4000-8000-000000000000';\nconst MAX_UUID_V4 = 'ffffffff-ffff-4fff-bfff-ffffffffffff';\nconst MIN_UUID_V4_BIGINT = uuidStringToBigInt(MIN_UUID_V4);\nconst MAX_UUID_V4_BIGINT = uuidStringToBigInt(MAX_UUID_V4);\nconst UUID_V4_VALUE_RANGE_BIGINT = MAX_UUID_V4_BIGINT - MIN_UUID_V4_BIGINT;\n\n/**\n * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.\n * This is useful for A/B testing and feature flag rollouts where we want\n * consistent group assignment for the same user.\n * @param metaMetricsId - The unique identifier used to generate the deterministic random number. Must be either:\n * - A UUIDv4 string (e.g., '123e4567-e89b-12d3-a456-426614174000'\n * - A hex string with '0x' prefix (e.g., '0x86bacb9b2bf9a7e8d2b147eadb95ac9aaa26842327cd24afc8bd4b3c1d136420')\n * @returns A number between 0 and 1, deterministically generated from the input ID.\n * The same input will always produce the same output.\n */\nexport function generateDeterministicRandomNumber(\n  metaMetricsId: string,\n): number {\n  if (!metaMetricsId) {\n    throw new Error('MetaMetrics ID cannot be empty');\n  }\n\n  let idValue: bigint;\n  let maxValue: bigint;\n\n  // uuidv4 format\n  if (uuidValidate(metaMetricsId)) {\n    if (uuidVersion(metaMetricsId) !== 4) {\n      throw new Error(\n        `Invalid UUID version. Expected v4, got v${uuidVersion(metaMetricsId)}`,\n      );\n    }\n    idValue = uuidStringToBigInt(metaMetricsId) - MIN_UUID_V4_BIGINT;\n    maxValue = UUID_V4_VALUE_RANGE_BIGINT;\n  } else {\n    // hex format with 0x prefix\n    if (!metaMetricsId.startsWith('0x')) {\n      throw new Error('Hex ID must start with 0x prefix');\n    }\n\n    const cleanId = metaMetricsId.slice(2);\n    const EXPECTED_HEX_LENGTH = 64; // 32 bytes = 64 hex characters\n\n    if (cleanId.length !== EXPECTED_HEX_LENGTH) {\n      throw new Error(\n        `Invalid hex ID length. Expected ${EXPECTED_HEX_LENGTH} characters, got ${cleanId.length}`,\n      );\n    }\n\n    if (!/^[0-9a-f]+$/iu.test(cleanId)) {\n      throw new Error('Hex ID contains invalid characters');\n    }\n\n    idValue = BigInt(`0x${cleanId}`);\n    maxValue = BigInt(`0x${'f'.repeat(cleanId.length)}`);\n  }\n\n  // Use BigInt division first, then convert to number to maintain precision\n  return Number((idValue * BigInt(1_000_000)) / maxValue) / 1_000_000;\n}\n\n/**\n * Type guard to check if a value is a feature flag with scope.\n * Used to validate feature flag objects that contain scope-based configurations.\n *\n * @param featureFlag - The value to check if it's a feature flag with scope\n * @returns True if the value is a feature flag with scope, false otherwise\n */\nexport const isFeatureFlagWithScopeValue = (\n  featureFlag: Json,\n): featureFlag is FeatureFlagScopeValue => {\n  return (\n    typeof featureFlag === 'object' &&\n    featureFlag !== null &&\n    'scope' in featureFlag\n  );\n};\n"]}

package/dist/utils/user-segmentation-utils.d.cts

@@ -4,9 +4,11 @@ import type { FeatureFlagScopeValue } from "../remote-feature-flag-controller-ty
  * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.
  * This is useful for A/B testing and feature flag rollouts where we want
  * consistent group assignment for the same user.
- *
- * @param metaMetricsId - The unique identifier used to generate the deterministic random number
- * @returns A number between 0 and 1 that is deterministic for the given metaMetricsId
+ * @param metaMetricsId - The unique identifier used to generate the deterministic random number. Must be either:
+ * - A UUIDv4 string (e.g., '123e4567-e89b-12d3-a456-426614174000'
+ * - A hex string with '0x' prefix (e.g., '0x86bacb9b2bf9a7e8d2b147eadb95ac9aaa26842327cd24afc8bd4b3c1d136420')
+ * @returns A number between 0 and 1, deterministically generated from the input ID.
+ * The same input will always produce the same output.
  */
 export declare function generateDeterministicRandomNumber(metaMetricsId: string): number;
 /**

package/dist/utils/user-segmentation-utils.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"user-segmentation-utils.d.cts","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,oDAAgD;AAGrF;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,GACpB,MAAM,CAOR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,gBACzB,IAAI,yCAOlB,CAAC"}
+{"version":3,"file":"user-segmentation-utils.d.cts","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,oDAAgD;AAiBrF;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,GACpB,MAAM,CA0CR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,gBACzB,IAAI,yCAOlB,CAAC"}

package/dist/utils/user-segmentation-utils.d.mts

@@ -4,9 +4,11 @@ import type { FeatureFlagScopeValue } from "../remote-feature-flag-controller-ty
  * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.
  * This is useful for A/B testing and feature flag rollouts where we want
  * consistent group assignment for the same user.
- *
- * @param metaMetricsId - The unique identifier used to generate the deterministic random number
- * @returns A number between 0 and 1 that is deterministic for the given metaMetricsId
+ * @param metaMetricsId - The unique identifier used to generate the deterministic random number. Must be either:
+ * - A UUIDv4 string (e.g., '123e4567-e89b-12d3-a456-426614174000'
+ * - A hex string with '0x' prefix (e.g., '0x86bacb9b2bf9a7e8d2b147eadb95ac9aaa26842327cd24afc8bd4b3c1d136420')
+ * @returns A number between 0 and 1, deterministically generated from the input ID.
+ * The same input will always produce the same output.
  */
 export declare function generateDeterministicRandomNumber(metaMetricsId: string): number;
 /**

package/dist/utils/user-segmentation-utils.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"user-segmentation-utils.d.mts","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAE5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,oDAAgD;AAGrF;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,GACpB,MAAM,CAOR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,gBACzB,IAAI,yCAOlB,CAAC"}
+{"version":3,"file":"user-segmentation-utils.d.mts","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,wBAAwB;AAG5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,oDAAgD;AAiBrF;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,GACpB,MAAM,CA0CR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,gBACzB,IAAI,yCAOlB,CAAC"}

package/dist/utils/user-segmentation-utils.mjs

@@ -1,18 +1,59 @@
-/* eslint-disable no-bitwise */
+import { validate as uuidValidate, version as uuidVersion } from "uuid";
+/**
+ * Converts a UUID string to a BigInt by removing dashes and converting to hexadecimal.
+ * @param uuid - The UUID string to convert
+ * @returns The UUID as a BigInt value
+ */
+function uuidStringToBigInt(uuid) {
+    return BigInt(`0x${uuid.replace(/-/gu, '')}`);
+}
+const MIN_UUID_V4 = '00000000-0000-4000-8000-000000000000';
+const MAX_UUID_V4 = 'ffffffff-ffff-4fff-bfff-ffffffffffff';
+const MIN_UUID_V4_BIGINT = uuidStringToBigInt(MIN_UUID_V4);
+const MAX_UUID_V4_BIGINT = uuidStringToBigInt(MAX_UUID_V4);
+const UUID_V4_VALUE_RANGE_BIGINT = MAX_UUID_V4_BIGINT - MIN_UUID_V4_BIGINT;
 /**
  * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.
  * This is useful for A/B testing and feature flag rollouts where we want
  * consistent group assignment for the same user.
- *
- * @param metaMetricsId - The unique identifier used to generate the deterministic random number
- * @returns A number between 0 and 1 that is deterministic for the given metaMetricsId
+ * @param metaMetricsId - The unique identifier used to generate the deterministic random number. Must be either:
+ * - A UUIDv4 string (e.g., '123e4567-e89b-12d3-a456-426614174000'
+ * - A hex string with '0x' prefix (e.g., '0x86bacb9b2bf9a7e8d2b147eadb95ac9aaa26842327cd24afc8bd4b3c1d136420')
+ * @returns A number between 0 and 1, deterministically generated from the input ID.
+ * The same input will always produce the same output.
  */
 export function generateDeterministicRandomNumber(metaMetricsId) {
-    const hash = [...metaMetricsId].reduce((acc, char) => {
-        const chr = char.charCodeAt(0);
-        return ((acc << 5) - acc + chr) | 0;
-    }, 0);
-    return (hash >>> 0) / 0xffffffff;
+    if (!metaMetricsId) {
+        throw new Error('MetaMetrics ID cannot be empty');
+    }
+    let idValue;
+    let maxValue;
+    // uuidv4 format
+    if (uuidValidate(metaMetricsId)) {
+        if (uuidVersion(metaMetricsId) !== 4) {
+            throw new Error(`Invalid UUID version. Expected v4, got v${uuidVersion(metaMetricsId)}`);
+        }
+        idValue = uuidStringToBigInt(metaMetricsId) - MIN_UUID_V4_BIGINT;
+        maxValue = UUID_V4_VALUE_RANGE_BIGINT;
+    }
+    else {
+        // hex format with 0x prefix
+        if (!metaMetricsId.startsWith('0x')) {
+            throw new Error('Hex ID must start with 0x prefix');
+        }
+        const cleanId = metaMetricsId.slice(2);
+        const EXPECTED_HEX_LENGTH = 64; // 32 bytes = 64 hex characters
+        if (cleanId.length !== EXPECTED_HEX_LENGTH) {
+            throw new Error(`Invalid hex ID length. Expected ${EXPECTED_HEX_LENGTH} characters, got ${cleanId.length}`);
+        }
+        if (!/^[0-9a-f]+$/iu.test(cleanId)) {
+            throw new Error('Hex ID contains invalid characters');
+        }
+        idValue = BigInt(`0x${cleanId}`);
+        maxValue = BigInt(`0x${'f'.repeat(cleanId.length)}`);
+    }
+    // Use BigInt division first, then convert to number to maintain precision
+    return Number((idValue * BigInt(1000000)) / maxValue) / 1000000;
 }
 /**
  * Type guard to check if a value is a feature flag with scope.

package/dist/utils/user-segmentation-utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"user-segmentation-utils.mjs","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":"AAIA,+BAA+B;AAC/B;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC,CAC/C,aAAqB;IAErB,MAAM,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEN,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,WAAiB,EACqB,EAAE;IACxC,OAAO,CACL,OAAO,WAAW,KAAK,QAAQ;QAC/B,WAAW,KAAK,IAAI;QACpB,OAAO,IAAI,WAAW,CACvB,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import type { Json } from '@metamask/utils';\n\nimport type { FeatureFlagScopeValue } from '../remote-feature-flag-controller-types';\n\n/* eslint-disable no-bitwise */\n/**\n * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.\n * This is useful for A/B testing and feature flag rollouts where we want\n * consistent group assignment for the same user.\n *\n * @param metaMetricsId - The unique identifier used to generate the deterministic random number\n * @returns A number between 0 and 1 that is deterministic for the given metaMetricsId\n */\nexport function generateDeterministicRandomNumber(\n  metaMetricsId: string,\n): number {\n  const hash = [...metaMetricsId].reduce((acc, char) => {\n    const chr = char.charCodeAt(0);\n    return ((acc << 5) - acc + chr) | 0;\n  }, 0);\n\n  return (hash >>> 0) / 0xffffffff;\n}\n\n/**\n * Type guard to check if a value is a feature flag with scope.\n * Used to validate feature flag objects that contain scope-based configurations.\n *\n * @param featureFlag - The value to check if it's a feature flag with scope\n * @returns True if the value is a feature flag with scope, false otherwise\n */\nexport const isFeatureFlagWithScopeValue = (\n  featureFlag: Json,\n): featureFlag is FeatureFlagScopeValue => {\n  return (\n    typeof featureFlag === 'object' &&\n    featureFlag !== null &&\n    'scope' in featureFlag\n  );\n};\n"]}
+{"version":3,"file":"user-segmentation-utils.mjs","sourceRoot":"","sources":["../../src/utils/user-segmentation-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,OAAO,IAAI,WAAW,EAAE,aAAa;AAIxE;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,MAAM,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAC3D,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAC3D,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;AAC3D,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;AAC3D,MAAM,0BAA0B,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,UAAU,iCAAiC,CAC/C,aAAqB;IAErB,IAAI,CAAC,aAAa,EAAE;QAClB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;KACnD;IAED,IAAI,OAAe,CAAC;IACpB,IAAI,QAAgB,CAAC;IAErB,gBAAgB;IAChB,IAAI,YAAY,CAAC,aAAa,CAAC,EAAE;QAC/B,IAAI,WAAW,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE;YACpC,MAAM,IAAI,KAAK,CACb,2CAA2C,WAAW,CAAC,aAAa,CAAC,EAAE,CACxE,CAAC;SACH;QACD,OAAO,GAAG,kBAAkB,CAAC,aAAa,CAAC,GAAG,kBAAkB,CAAC;QACjE,QAAQ,GAAG,0BAA0B,CAAC;KACvC;SAAM;QACL,4BAA4B;QAC5B,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE;YACnC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;SACrD;QAED,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,mBAAmB,GAAG,EAAE,CAAC,CAAC,+BAA+B;QAE/D,IAAI,OAAO,CAAC,MAAM,KAAK,mBAAmB,EAAE;YAC1C,MAAM,IAAI,KAAK,CACb,mCAAmC,mBAAmB,oBAAoB,OAAO,CAAC,MAAM,EAAE,CAC3F,CAAC;SACH;QAED,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;YAClC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;SACvD;QAED,OAAO,GAAG,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QACjC,QAAQ,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;KACtD;IAED,0EAA0E;IAC1E,OAAO,MAAM,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,OAAS,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,OAAS,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,WAAiB,EACqB,EAAE;IACxC,OAAO,CACL,OAAO,WAAW,KAAK,QAAQ;QAC/B,WAAW,KAAK,IAAI;QACpB,OAAO,IAAI,WAAW,CACvB,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import type { Json } from '@metamask/utils';\nimport { validate as uuidValidate, version as uuidVersion } from 'uuid';\n\nimport type { FeatureFlagScopeValue } from '../remote-feature-flag-controller-types';\n\n/**\n * Converts a UUID string to a BigInt by removing dashes and converting to hexadecimal.\n * @param uuid - The UUID string to convert\n * @returns The UUID as a BigInt value\n */\nfunction uuidStringToBigInt(uuid: string): bigint {\n  return BigInt(`0x${uuid.replace(/-/gu, '')}`);\n}\n\nconst MIN_UUID_V4 = '00000000-0000-4000-8000-000000000000';\nconst MAX_UUID_V4 = 'ffffffff-ffff-4fff-bfff-ffffffffffff';\nconst MIN_UUID_V4_BIGINT = uuidStringToBigInt(MIN_UUID_V4);\nconst MAX_UUID_V4_BIGINT = uuidStringToBigInt(MAX_UUID_V4);\nconst UUID_V4_VALUE_RANGE_BIGINT = MAX_UUID_V4_BIGINT - MIN_UUID_V4_BIGINT;\n\n/**\n * Generates a deterministic random number between 0 and 1 based on a metaMetricsId.\n * This is useful for A/B testing and feature flag rollouts where we want\n * consistent group assignment for the same user.\n * @param metaMetricsId - The unique identifier used to generate the deterministic random number. Must be either:\n * - A UUIDv4 string (e.g., '123e4567-e89b-12d3-a456-426614174000'\n * - A hex string with '0x' prefix (e.g., '0x86bacb9b2bf9a7e8d2b147eadb95ac9aaa26842327cd24afc8bd4b3c1d136420')\n * @returns A number between 0 and 1, deterministically generated from the input ID.\n * The same input will always produce the same output.\n */\nexport function generateDeterministicRandomNumber(\n  metaMetricsId: string,\n): number {\n  if (!metaMetricsId) {\n    throw new Error('MetaMetrics ID cannot be empty');\n  }\n\n  let idValue: bigint;\n  let maxValue: bigint;\n\n  // uuidv4 format\n  if (uuidValidate(metaMetricsId)) {\n    if (uuidVersion(metaMetricsId) !== 4) {\n      throw new Error(\n        `Invalid UUID version. Expected v4, got v${uuidVersion(metaMetricsId)}`,\n      );\n    }\n    idValue = uuidStringToBigInt(metaMetricsId) - MIN_UUID_V4_BIGINT;\n    maxValue = UUID_V4_VALUE_RANGE_BIGINT;\n  } else {\n    // hex format with 0x prefix\n    if (!metaMetricsId.startsWith('0x')) {\n      throw new Error('Hex ID must start with 0x prefix');\n    }\n\n    const cleanId = metaMetricsId.slice(2);\n    const EXPECTED_HEX_LENGTH = 64; // 32 bytes = 64 hex characters\n\n    if (cleanId.length !== EXPECTED_HEX_LENGTH) {\n      throw new Error(\n        `Invalid hex ID length. Expected ${EXPECTED_HEX_LENGTH} characters, got ${cleanId.length}`,\n      );\n    }\n\n    if (!/^[0-9a-f]+$/iu.test(cleanId)) {\n      throw new Error('Hex ID contains invalid characters');\n    }\n\n    idValue = BigInt(`0x${cleanId}`);\n    maxValue = BigInt(`0x${'f'.repeat(cleanId.length)}`);\n  }\n\n  // Use BigInt division first, then convert to number to maintain precision\n  return Number((idValue * BigInt(1_000_000)) / maxValue) / 1_000_000;\n}\n\n/**\n * Type guard to check if a value is a feature flag with scope.\n * Used to validate feature flag objects that contain scope-based configurations.\n *\n * @param featureFlag - The value to check if it's a feature flag with scope\n * @returns True if the value is a feature flag with scope, false otherwise\n */\nexport const isFeatureFlagWithScopeValue = (\n  featureFlag: Json,\n): featureFlag is FeatureFlagScopeValue => {\n  return (\n    typeof featureFlag === 'object' &&\n    featureFlag !== null &&\n    'scope' in featureFlag\n  );\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask-previews/remote-feature-flag-controller",
-  "version": "1.2.0-preview-4e54ae1",
+  "version": "1.3.0-preview-298fc547",
   "description": "The RemoteFeatureFlagController manages the retrieval and caching of remote feature flags",
   "keywords": [
     "MetaMask",