@metamask/ramps-controller 17.1.0 → 17.2.0

package/dist/featureFlags.cjs

@@ -1,26 +1,116 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isHeadlessAllProvidersEnabled = exports.MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = void 0;
+exports.normalizeHeadlessProviderId = exports.getHeadlessProviderAllowlist = exports.isHeadlessAllProvidersEnabled = exports.getHeadlessAllProvidersMinimumVersion = exports.HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = exports.MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = void 0;
 /**
  * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers
- * expansion. A boolean flag: `true` widens the headless fiat quote path to
- * every provider class (native, in-app WebView aggregator, and
- * external-browser / custom-action); `false` or missing keeps the native-only
- * default. Exported so the flag registry and every consumer stay in sync on
- * the exact key string.
+ * expansion. Accepts two value forms:
+ *
+ * - The literal boolean `true` widens the headless fiat quote path to every
+ *   provider class (native, in-app WebView aggregator, and external-browser /
+ *   custom-action) with no provider restriction.
+ * - An object payload `{ enabled: true, featureVersion: "1", providerIds?: string[] }`
+ *   widens the same way, and additionally restricts the widened quote pick to
+ *   the listed provider ids (see {@link getHeadlessProviderAllowlist}).
+ *
+ * `false`, a missing flag, or any other value keeps the native-only default.
+ * Clients that only understand the boolean form coerce the object payload to
+ * "disabled" (native-only), so serving the object form can never turn the
+ * feature on for a client that cannot parse it. Exported so the flag registry
+ * and every consumer stay in sync on the exact key string.
  */
 exports.MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = 'moneyHeadlessAllProviders';
+/**
+ * Contract version of the object payload. An enabled payload whose
+ * `featureVersion` differs (or is absent) fails closed, so the payload's
+ * meaning can change in a future client without old clients misreading it.
+ * Mirrors the platform pattern used by `assetsUnifyState`.
+ */
+exports.HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = '1';
+/**
+ * Resolves the flag value with `localOverrides` (written by dev-only override
+ * screens) merged over `remoteFeatureFlags`, because not every published
+ * `RemoteFeatureFlagController` version folds overrides into
+ * `remoteFeatureFlags` state; when a version already does, the merge is a
+ * no-op.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it).
+ * @returns The merged flag value, or `undefined` when absent.
+ */
+function resolveFlagValue(remoteFeatureFlagState) {
+    const flags = {
+        ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),
+        ...(remoteFeatureFlagState?.localOverrides ?? {}),
+    };
+    return flags[exports.MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY];
+}
+/**
+ * Whether a flag value is the object payload form: a plain object (not an
+ * array) whose `enabled` is the literal boolean `true`. Anything else,
+ * including `{ enabled: false }` and objects without `enabled`, is not an
+ * enabled payload, so the flag fails closed.
+ *
+ * @param value - The merged flag value.
+ * @returns Whether the value is an enabled object payload.
+ */
+function isEnabledPayload(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.enabled === true &&
+        value.featureVersion === exports.HEADLESS_ALL_PROVIDERS_FEATURE_VERSION);
+}
+/**
+ * The `minimumVersion` carried by an enabled payload, or `undefined` for the
+ * boolean form, a disabled payload, or a malformed field. This package cannot
+ * compare app versions itself; mobile validates the value through its shared
+ * `validatedVersionGatedFeatureFlag` util, and the LaunchDarkly `versions`
+ * wrapper provides the server-side gate.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it).
+ * @returns The minimum app version the payload declares, or `undefined`.
+ */
+function getHeadlessAllProvidersMinimumVersion(remoteFeatureFlagState) {
+    const value = resolveFlagValue(remoteFeatureFlagState);
+    if (!isEnabledPayload(value)) {
+        return undefined;
+    }
+    const { minimumVersion } = value;
+    return typeof minimumVersion === 'string' && minimumVersion.trim() !== ''
+        ? minimumVersion
+        : undefined;
+}
+exports.getHeadlessAllProvidersMinimumVersion = getHeadlessAllProvidersMinimumVersion;
+/**
+ * Coerces a payload field into a provider-id list: keeps only string entries,
+ * trims them, and drops empties. An empty or malformed level is treated as
+ * "not provided" so resolution falls through to the next level rather than
+ * restricting to nothing; to force "nothing eligible" list a nonexistent id.
+ *
+ * @param value - The candidate `providerIds` / surface entry value.
+ * @returns The non-empty coerced list, or `undefined`.
+ */
+function coerceProviderIdList(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const ids = value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== '');
+    return ids.length > 0 ? ids : undefined;
+}
 /**
  * Whether the Headless Buy all-providers feature flag is enabled.
  *
  * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}
  * so the controller's quote widening and UI availability gates resolve the
- * flag identically. `localOverrides` (written by dev-only override screens)
- * are merged over `remoteFeatureFlags`, because not every published
- * `RemoteFeatureFlagController` version folds overrides into
- * `remoteFeatureFlags` state; when a version already does, the merge is a
- * no-op. Coerces defensively: only the literal boolean `true` enables, and
- * any other value (missing, string, object) resolves to `false`.
+ * flag identically. `localOverrides` are merged over `remoteFeatureFlags`
+ * (see {@link resolveFlagValue}). Coerces defensively: only the literal
+ * boolean `true` or an object payload whose `enabled` is the literal `true`
+ * enables; any other value (missing, string, number, array, `{ enabled:
+ * false }`) resolves to `false`.
  *
  * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
  * relevant subset of it). May be `null`/`undefined` before the controller is
@@ -29,11 +119,48 @@ exports.MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = 'moneyHeadlessAllProviders';
  * quote path.
  */
 function isHeadlessAllProvidersEnabled(remoteFeatureFlagState) {
-    const flags = {
-        ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),
-        ...(remoteFeatureFlagState?.localOverrides ?? {}),
-    };
-    return flags[exports.MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY] === true;
+    const value = resolveFlagValue(remoteFeatureFlagState);
+    return value === true || isEnabledPayload(value);
 }
 exports.isHeadlessAllProvidersEnabled = isHeadlessAllProvidersEnabled;
+/**
+ * The provider-id allowlist carried by the flag's object payload, or
+ * `undefined` when the widened pick should not be restricted.
+ *
+ * Returns the payload's top-level `providerIds` when non-empty and valid, or
+ * `undefined` (no restriction). The boolean `true` form, a disabled or
+ * malformed payload, and empty or all-invalid lists all resolve to
+ * `undefined`; unknown keys and non-string entries are ignored.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it). May be `null`/`undefined` before the controller is
+ * initialized.
+ * @returns The provider ids the widened pick is restricted to, or `undefined`
+ * for no restriction.
+ */
+function getHeadlessProviderAllowlist(remoteFeatureFlagState) {
+    const value = resolveFlagValue(remoteFeatureFlagState);
+    if (!isEnabledPayload(value)) {
+        return undefined;
+    }
+    return coerceProviderIdList(value.providerIds);
+}
+exports.getHeadlessProviderAllowlist = getHeadlessProviderAllowlist;
+/**
+ * Normalizes a provider id for allowlist matching only: trims, strips the
+ * canonical `/providers/` path prefix, and lowercases, so `/providers/moonpay`
+ * and `moonpay` match each other. Quote and catalog provider ids are matched
+ * as-is everywhere else; this exists solely so LaunchDarkly payload authors
+ * can use either id form. Not exported from the package index.
+ *
+ * @param id - A provider id in either the prefixed or bare form.
+ * @returns The normalized id used for allowlist comparison.
+ */
+function normalizeHeadlessProviderId(id) {
+    return id
+        .trim()
+        .replace(/^\/providers\//u, '')
+        .toLowerCase();
+}
+exports.normalizeHeadlessProviderId = normalizeHeadlessProviderId;
 //# sourceMappingURL=featureFlags.cjs.map

package/dist/featureFlags.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"featureFlags.cjs","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":";;;AAEA;;;;;;;GAOG;AACU,QAAA,qCAAqC,GAChD,2BAA2B,CAAC;AAa9B;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,6BAA6B,CAC3C,sBAAqE;IAErE,MAAM,KAAK,GAAiB;QAC1B,GAAG,CAAC,sBAAsB,EAAE,kBAAkB,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,sBAAsB,EAAE,cAAc,IAAI,EAAE,CAAC;KAClD,CAAC;IACF,OAAO,KAAK,CAAC,6CAAqC,CAAC,KAAK,IAAI,CAAC;AAC/D,CAAC;AARD,sEAQC","sourcesContent":["import type { FeatureFlags } from '@metamask/remote-feature-flag-controller';\n\n/**\n * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers\n * expansion. A boolean flag: `true` widens the headless fiat quote path to\n * every provider class (native, in-app WebView aggregator, and\n * external-browser / custom-action); `false` or missing keeps the native-only\n * default. Exported so the flag registry and every consumer stay in sync on\n * the exact key string.\n */\nexport const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY =\n  'moneyHeadlessAllProviders';\n\n/**\n * The subset of `RemoteFeatureFlagController` state that\n * {@link isHeadlessAllProvidersEnabled} reads. Structural so consumers can\n * pass the whole controller state (or `undefined` before initialization)\n * without depending on a specific controller version.\n */\nexport type HeadlessFeatureFlagsLookup = {\n  remoteFeatureFlags?: FeatureFlags;\n  localOverrides?: FeatureFlags;\n};\n\n/**\n * Whether the Headless Buy all-providers feature flag is enabled.\n *\n * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}\n * so the controller's quote widening and UI availability gates resolve the\n * flag identically. `localOverrides` (written by dev-only override screens)\n * are merged over `remoteFeatureFlags`, because not every published\n * `RemoteFeatureFlagController` version folds overrides into\n * `remoteFeatureFlags` state; when a version already does, the merge is a\n * no-op. Coerces defensively: only the literal boolean `true` enables, and\n * any other value (missing, string, object) resolves to `false`.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it). May be `null`/`undefined` before the controller is\n * initialized.\n * @returns Whether all provider classes are enabled for the headless fiat\n * quote path.\n */\nexport function isHeadlessAllProvidersEnabled(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): boolean {\n  const flags: FeatureFlags = {\n    ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),\n    ...(remoteFeatureFlagState?.localOverrides ?? {}),\n  };\n  return flags[MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY] === true;\n}\n"]}
+{"version":3,"file":"featureFlags.cjs","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,qCAAqC,GAChD,2BAA2B,CAAC;AAE9B;;;;;GAKG;AACU,QAAA,sCAAsC,GAAG,GAAG,CAAC;AAa1D;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB,CACvB,sBAAqE;IAErE,MAAM,KAAK,GAAiB;QAC1B,GAAG,CAAC,sBAAsB,EAAE,kBAAkB,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,sBAAsB,EAAE,cAAc,IAAI,EAAE,CAAC;KAClD,CAAC;IACF,OAAO,KAAK,CAAC,6CAAqC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,KAAuB;IAG/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,OAAO,KAAK,IAAI;QACtB,KAAK,CAAC,cAAc,KAAK,8CAAsC,CAChE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,qCAAqC,CACnD,sBAAqE;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IACvD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IACjC,OAAO,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE;QACvE,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAXD,sFAWC;AAED;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,KAAuB;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,KAAK;SACd,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;SAC7D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACnC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,6BAA6B,CAC3C,sBAAqE;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IACvD,OAAO,KAAK,KAAK,IAAI,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AALD,sEAKC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,4BAA4B,CAC1C,sBAAqE;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IACvD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AARD,oEAQC;AAED;;;;;;;;;GASG;AACH,SAAgB,2BAA2B,CAAC,EAAU;IACpD,OAAO,EAAE;SACN,IAAI,EAAE;SACN,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC;SAC9B,WAAW,EAAE,CAAC;AACnB,CAAC;AALD,kEAKC","sourcesContent":["import type { FeatureFlags } from '@metamask/remote-feature-flag-controller';\nimport type { Json } from '@metamask/utils';\n\n/**\n * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers\n * expansion. Accepts two value forms:\n *\n * - The literal boolean `true` widens the headless fiat quote path to every\n *   provider class (native, in-app WebView aggregator, and external-browser /\n *   custom-action) with no provider restriction.\n * - An object payload `{ enabled: true, featureVersion: \"1\", providerIds?: string[] }`\n *   widens the same way, and additionally restricts the widened quote pick to\n *   the listed provider ids (see {@link getHeadlessProviderAllowlist}).\n *\n * `false`, a missing flag, or any other value keeps the native-only default.\n * Clients that only understand the boolean form coerce the object payload to\n * \"disabled\" (native-only), so serving the object form can never turn the\n * feature on for a client that cannot parse it. Exported so the flag registry\n * and every consumer stay in sync on the exact key string.\n */\nexport const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY =\n  'moneyHeadlessAllProviders';\n\n/**\n * Contract version of the object payload. An enabled payload whose\n * `featureVersion` differs (or is absent) fails closed, so the payload's\n * meaning can change in a future client without old clients misreading it.\n * Mirrors the platform pattern used by `assetsUnifyState`.\n */\nexport const HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = '1';\n\n/**\n * The subset of `RemoteFeatureFlagController` state that\n * {@link isHeadlessAllProvidersEnabled} reads. Structural so consumers can\n * pass the whole controller state (or `undefined` before initialization)\n * without depending on a specific controller version.\n */\nexport type HeadlessFeatureFlagsLookup = {\n  remoteFeatureFlags?: FeatureFlags;\n  localOverrides?: FeatureFlags;\n};\n\n/**\n * Resolves the flag value with `localOverrides` (written by dev-only override\n * screens) merged over `remoteFeatureFlags`, because not every published\n * `RemoteFeatureFlagController` version folds overrides into\n * `remoteFeatureFlags` state; when a version already does, the merge is a\n * no-op.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it).\n * @returns The merged flag value, or `undefined` when absent.\n */\nfunction resolveFlagValue(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): Json | undefined {\n  const flags: FeatureFlags = {\n    ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),\n    ...(remoteFeatureFlagState?.localOverrides ?? {}),\n  };\n  return flags[MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY];\n}\n\n/**\n * Whether a flag value is the object payload form: a plain object (not an\n * array) whose `enabled` is the literal boolean `true`. Anything else,\n * including `{ enabled: false }` and objects without `enabled`, is not an\n * enabled payload, so the flag fails closed.\n *\n * @param value - The merged flag value.\n * @returns Whether the value is an enabled object payload.\n */\nfunction isEnabledPayload(value: Json | undefined): value is {\n  [key: string]: Json;\n} {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    !Array.isArray(value) &&\n    value.enabled === true &&\n    value.featureVersion === HEADLESS_ALL_PROVIDERS_FEATURE_VERSION\n  );\n}\n\n/**\n * The `minimumVersion` carried by an enabled payload, or `undefined` for the\n * boolean form, a disabled payload, or a malformed field. This package cannot\n * compare app versions itself; mobile validates the value through its shared\n * `validatedVersionGatedFeatureFlag` util, and the LaunchDarkly `versions`\n * wrapper provides the server-side gate.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it).\n * @returns The minimum app version the payload declares, or `undefined`.\n */\nexport function getHeadlessAllProvidersMinimumVersion(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): string | undefined {\n  const value = resolveFlagValue(remoteFeatureFlagState);\n  if (!isEnabledPayload(value)) {\n    return undefined;\n  }\n  const { minimumVersion } = value;\n  return typeof minimumVersion === 'string' && minimumVersion.trim() !== ''\n    ? minimumVersion\n    : undefined;\n}\n\n/**\n * Coerces a payload field into a provider-id list: keeps only string entries,\n * trims them, and drops empties. An empty or malformed level is treated as\n * \"not provided\" so resolution falls through to the next level rather than\n * restricting to nothing; to force \"nothing eligible\" list a nonexistent id.\n *\n * @param value - The candidate `providerIds` / surface entry value.\n * @returns The non-empty coerced list, or `undefined`.\n */\nfunction coerceProviderIdList(value: Json | undefined): string[] | undefined {\n  if (!Array.isArray(value)) {\n    return undefined;\n  }\n  const ids = value\n    .filter((entry): entry is string => typeof entry === 'string')\n    .map((entry) => entry.trim())\n    .filter((entry) => entry !== '');\n  return ids.length > 0 ? ids : undefined;\n}\n\n/**\n * Whether the Headless Buy all-providers feature flag is enabled.\n *\n * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}\n * so the controller's quote widening and UI availability gates resolve the\n * flag identically. `localOverrides` are merged over `remoteFeatureFlags`\n * (see {@link resolveFlagValue}). Coerces defensively: only the literal\n * boolean `true` or an object payload whose `enabled` is the literal `true`\n * enables; any other value (missing, string, number, array, `{ enabled:\n * false }`) resolves to `false`.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it). May be `null`/`undefined` before the controller is\n * initialized.\n * @returns Whether all provider classes are enabled for the headless fiat\n * quote path.\n */\nexport function isHeadlessAllProvidersEnabled(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): boolean {\n  const value = resolveFlagValue(remoteFeatureFlagState);\n  return value === true || isEnabledPayload(value);\n}\n\n/**\n * The provider-id allowlist carried by the flag's object payload, or\n * `undefined` when the widened pick should not be restricted.\n *\n * Returns the payload's top-level `providerIds` when non-empty and valid, or\n * `undefined` (no restriction). The boolean `true` form, a disabled or\n * malformed payload, and empty or all-invalid lists all resolve to\n * `undefined`; unknown keys and non-string entries are ignored.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it). May be `null`/`undefined` before the controller is\n * initialized.\n * @returns The provider ids the widened pick is restricted to, or `undefined`\n * for no restriction.\n */\nexport function getHeadlessProviderAllowlist(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): string[] | undefined {\n  const value = resolveFlagValue(remoteFeatureFlagState);\n  if (!isEnabledPayload(value)) {\n    return undefined;\n  }\n  return coerceProviderIdList(value.providerIds);\n}\n\n/**\n * Normalizes a provider id for allowlist matching only: trims, strips the\n * canonical `/providers/` path prefix, and lowercases, so `/providers/moonpay`\n * and `moonpay` match each other. Quote and catalog provider ids are matched\n * as-is everywhere else; this exists solely so LaunchDarkly payload authors\n * can use either id form. Not exported from the package index.\n *\n * @param id - A provider id in either the prefixed or bare form.\n * @returns The normalized id used for allowlist comparison.\n */\nexport function normalizeHeadlessProviderId(id: string): string {\n  return id\n    .trim()\n    .replace(/^\\/providers\\//u, '')\n    .toLowerCase();\n}\n"]}

package/dist/featureFlags.d.cts

@@ -1,13 +1,29 @@
 import type { FeatureFlags } from "@metamask/remote-feature-flag-controller";
 /**
  * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers
- * expansion. A boolean flag: `true` widens the headless fiat quote path to
- * every provider class (native, in-app WebView aggregator, and
- * external-browser / custom-action); `false` or missing keeps the native-only
- * default. Exported so the flag registry and every consumer stay in sync on
- * the exact key string.
+ * expansion. Accepts two value forms:
+ *
+ * - The literal boolean `true` widens the headless fiat quote path to every
+ *   provider class (native, in-app WebView aggregator, and external-browser /
+ *   custom-action) with no provider restriction.
+ * - An object payload `{ enabled: true, featureVersion: "1", providerIds?: string[] }`
+ *   widens the same way, and additionally restricts the widened quote pick to
+ *   the listed provider ids (see {@link getHeadlessProviderAllowlist}).
+ *
+ * `false`, a missing flag, or any other value keeps the native-only default.
+ * Clients that only understand the boolean form coerce the object payload to
+ * "disabled" (native-only), so serving the object form can never turn the
+ * feature on for a client that cannot parse it. Exported so the flag registry
+ * and every consumer stay in sync on the exact key string.
  */
 export declare const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = "moneyHeadlessAllProviders";
+/**
+ * Contract version of the object payload. An enabled payload whose
+ * `featureVersion` differs (or is absent) fails closed, so the payload's
+ * meaning can change in a future client without old clients misreading it.
+ * Mirrors the platform pattern used by `assetsUnifyState`.
+ */
+export declare const HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = "1";
 /**
  * The subset of `RemoteFeatureFlagController` state that
  * {@link isHeadlessAllProvidersEnabled} reads. Structural so consumers can
@@ -18,17 +34,28 @@ export type HeadlessFeatureFlagsLookup = {
     remoteFeatureFlags?: FeatureFlags;
     localOverrides?: FeatureFlags;
 };
+/**
+ * The `minimumVersion` carried by an enabled payload, or `undefined` for the
+ * boolean form, a disabled payload, or a malformed field. This package cannot
+ * compare app versions itself; mobile validates the value through its shared
+ * `validatedVersionGatedFeatureFlag` util, and the LaunchDarkly `versions`
+ * wrapper provides the server-side gate.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it).
+ * @returns The minimum app version the payload declares, or `undefined`.
+ */
+export declare function getHeadlessAllProvidersMinimumVersion(remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined): string | undefined;
 /**
  * Whether the Headless Buy all-providers feature flag is enabled.
  *
  * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}
  * so the controller's quote widening and UI availability gates resolve the
- * flag identically. `localOverrides` (written by dev-only override screens)
- * are merged over `remoteFeatureFlags`, because not every published
- * `RemoteFeatureFlagController` version folds overrides into
- * `remoteFeatureFlags` state; when a version already does, the merge is a
- * no-op. Coerces defensively: only the literal boolean `true` enables, and
- * any other value (missing, string, object) resolves to `false`.
+ * flag identically. `localOverrides` are merged over `remoteFeatureFlags`
+ * (see {@link resolveFlagValue}). Coerces defensively: only the literal
+ * boolean `true` or an object payload whose `enabled` is the literal `true`
+ * enables; any other value (missing, string, number, array, `{ enabled:
+ * false }`) resolves to `false`.
  *
  * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
  * relevant subset of it). May be `null`/`undefined` before the controller is
@@ -37,4 +64,31 @@ export type HeadlessFeatureFlagsLookup = {
  * quote path.
  */
 export declare function isHeadlessAllProvidersEnabled(remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined): boolean;
+/**
+ * The provider-id allowlist carried by the flag's object payload, or
+ * `undefined` when the widened pick should not be restricted.
+ *
+ * Returns the payload's top-level `providerIds` when non-empty and valid, or
+ * `undefined` (no restriction). The boolean `true` form, a disabled or
+ * malformed payload, and empty or all-invalid lists all resolve to
+ * `undefined`; unknown keys and non-string entries are ignored.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it). May be `null`/`undefined` before the controller is
+ * initialized.
+ * @returns The provider ids the widened pick is restricted to, or `undefined`
+ * for no restriction.
+ */
+export declare function getHeadlessProviderAllowlist(remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined): string[] | undefined;
+/**
+ * Normalizes a provider id for allowlist matching only: trims, strips the
+ * canonical `/providers/` path prefix, and lowercases, so `/providers/moonpay`
+ * and `moonpay` match each other. Quote and catalog provider ids are matched
+ * as-is everywhere else; this exists solely so LaunchDarkly payload authors
+ * can use either id form. Not exported from the package index.
+ *
+ * @param id - A provider id in either the prefixed or bare form.
+ * @returns The normalized id used for allowlist comparison.
+ */
+export declare function normalizeHeadlessProviderId(id: string): string;
 //# sourceMappingURL=featureFlags.d.cts.map

package/dist/featureFlags.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"featureFlags.d.cts","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iDAAiD;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,8BACrB,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAClC,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAC3C,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,OAAO,CAMT"}
+{"version":3,"file":"featureFlags.d.cts","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iDAAiD;AAG7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qCAAqC,8BACrB,CAAC;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAClC,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B,CAAC;AA4CF;;;;;;;;;;GAUG;AACH,wBAAgB,qCAAqC,CACnD,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,MAAM,GAAG,SAAS,CASpB;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,OAAO,CAGT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,MAAM,EAAE,GAAG,SAAS,CAMtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAK9D"}

package/dist/featureFlags.d.mts

@@ -1,13 +1,29 @@
 import type { FeatureFlags } from "@metamask/remote-feature-flag-controller";
 /**
  * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers
- * expansion. A boolean flag: `true` widens the headless fiat quote path to
- * every provider class (native, in-app WebView aggregator, and
- * external-browser / custom-action); `false` or missing keeps the native-only
- * default. Exported so the flag registry and every consumer stay in sync on
- * the exact key string.
+ * expansion. Accepts two value forms:
+ *
+ * - The literal boolean `true` widens the headless fiat quote path to every
+ *   provider class (native, in-app WebView aggregator, and external-browser /
+ *   custom-action) with no provider restriction.
+ * - An object payload `{ enabled: true, featureVersion: "1", providerIds?: string[] }`
+ *   widens the same way, and additionally restricts the widened quote pick to
+ *   the listed provider ids (see {@link getHeadlessProviderAllowlist}).
+ *
+ * `false`, a missing flag, or any other value keeps the native-only default.
+ * Clients that only understand the boolean form coerce the object payload to
+ * "disabled" (native-only), so serving the object form can never turn the
+ * feature on for a client that cannot parse it. Exported so the flag registry
+ * and every consumer stay in sync on the exact key string.
  */
 export declare const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = "moneyHeadlessAllProviders";
+/**
+ * Contract version of the object payload. An enabled payload whose
+ * `featureVersion` differs (or is absent) fails closed, so the payload's
+ * meaning can change in a future client without old clients misreading it.
+ * Mirrors the platform pattern used by `assetsUnifyState`.
+ */
+export declare const HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = "1";
 /**
  * The subset of `RemoteFeatureFlagController` state that
  * {@link isHeadlessAllProvidersEnabled} reads. Structural so consumers can
@@ -18,17 +34,28 @@ export type HeadlessFeatureFlagsLookup = {
     remoteFeatureFlags?: FeatureFlags;
     localOverrides?: FeatureFlags;
 };
+/**
+ * The `minimumVersion` carried by an enabled payload, or `undefined` for the
+ * boolean form, a disabled payload, or a malformed field. This package cannot
+ * compare app versions itself; mobile validates the value through its shared
+ * `validatedVersionGatedFeatureFlag` util, and the LaunchDarkly `versions`
+ * wrapper provides the server-side gate.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it).
+ * @returns The minimum app version the payload declares, or `undefined`.
+ */
+export declare function getHeadlessAllProvidersMinimumVersion(remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined): string | undefined;
 /**
  * Whether the Headless Buy all-providers feature flag is enabled.
  *
  * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}
  * so the controller's quote widening and UI availability gates resolve the
- * flag identically. `localOverrides` (written by dev-only override screens)
- * are merged over `remoteFeatureFlags`, because not every published
- * `RemoteFeatureFlagController` version folds overrides into
- * `remoteFeatureFlags` state; when a version already does, the merge is a
- * no-op. Coerces defensively: only the literal boolean `true` enables, and
- * any other value (missing, string, object) resolves to `false`.
+ * flag identically. `localOverrides` are merged over `remoteFeatureFlags`
+ * (see {@link resolveFlagValue}). Coerces defensively: only the literal
+ * boolean `true` or an object payload whose `enabled` is the literal `true`
+ * enables; any other value (missing, string, number, array, `{ enabled:
+ * false }`) resolves to `false`.
  *
  * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
  * relevant subset of it). May be `null`/`undefined` before the controller is
@@ -37,4 +64,31 @@ export type HeadlessFeatureFlagsLookup = {
  * quote path.
  */
 export declare function isHeadlessAllProvidersEnabled(remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined): boolean;
+/**
+ * The provider-id allowlist carried by the flag's object payload, or
+ * `undefined` when the widened pick should not be restricted.
+ *
+ * Returns the payload's top-level `providerIds` when non-empty and valid, or
+ * `undefined` (no restriction). The boolean `true` form, a disabled or
+ * malformed payload, and empty or all-invalid lists all resolve to
+ * `undefined`; unknown keys and non-string entries are ignored.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it). May be `null`/`undefined` before the controller is
+ * initialized.
+ * @returns The provider ids the widened pick is restricted to, or `undefined`
+ * for no restriction.
+ */
+export declare function getHeadlessProviderAllowlist(remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined): string[] | undefined;
+/**
+ * Normalizes a provider id for allowlist matching only: trims, strips the
+ * canonical `/providers/` path prefix, and lowercases, so `/providers/moonpay`
+ * and `moonpay` match each other. Quote and catalog provider ids are matched
+ * as-is everywhere else; this exists solely so LaunchDarkly payload authors
+ * can use either id form. Not exported from the package index.
+ *
+ * @param id - A provider id in either the prefixed or bare form.
+ * @returns The normalized id used for allowlist comparison.
+ */
+export declare function normalizeHeadlessProviderId(id: string): string;
 //# sourceMappingURL=featureFlags.d.mts.map

package/dist/featureFlags.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"featureFlags.d.mts","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iDAAiD;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,8BACrB,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAClC,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAC3C,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,OAAO,CAMT"}
+{"version":3,"file":"featureFlags.d.mts","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iDAAiD;AAG7E;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qCAAqC,8BACrB,CAAC;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAClC,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B,CAAC;AA4CF;;;;;;;;;;GAUG;AACH,wBAAgB,qCAAqC,CACnD,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,MAAM,GAAG,SAAS,CASpB;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,OAAO,CAGT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,sBAAsB,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GACpE,MAAM,EAAE,GAAG,SAAS,CAMtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAK9D"}

package/dist/featureFlags.mjs

@@ -1,23 +1,112 @@
 /**
  * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers
- * expansion. A boolean flag: `true` widens the headless fiat quote path to
- * every provider class (native, in-app WebView aggregator, and
- * external-browser / custom-action); `false` or missing keeps the native-only
- * default. Exported so the flag registry and every consumer stay in sync on
- * the exact key string.
+ * expansion. Accepts two value forms:
+ *
+ * - The literal boolean `true` widens the headless fiat quote path to every
+ *   provider class (native, in-app WebView aggregator, and external-browser /
+ *   custom-action) with no provider restriction.
+ * - An object payload `{ enabled: true, featureVersion: "1", providerIds?: string[] }`
+ *   widens the same way, and additionally restricts the widened quote pick to
+ *   the listed provider ids (see {@link getHeadlessProviderAllowlist}).
+ *
+ * `false`, a missing flag, or any other value keeps the native-only default.
+ * Clients that only understand the boolean form coerce the object payload to
+ * "disabled" (native-only), so serving the object form can never turn the
+ * feature on for a client that cannot parse it. Exported so the flag registry
+ * and every consumer stay in sync on the exact key string.
  */
 export const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = 'moneyHeadlessAllProviders';
+/**
+ * Contract version of the object payload. An enabled payload whose
+ * `featureVersion` differs (or is absent) fails closed, so the payload's
+ * meaning can change in a future client without old clients misreading it.
+ * Mirrors the platform pattern used by `assetsUnifyState`.
+ */
+export const HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = '1';
+/**
+ * Resolves the flag value with `localOverrides` (written by dev-only override
+ * screens) merged over `remoteFeatureFlags`, because not every published
+ * `RemoteFeatureFlagController` version folds overrides into
+ * `remoteFeatureFlags` state; when a version already does, the merge is a
+ * no-op.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it).
+ * @returns The merged flag value, or `undefined` when absent.
+ */
+function resolveFlagValue(remoteFeatureFlagState) {
+    const flags = {
+        ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),
+        ...(remoteFeatureFlagState?.localOverrides ?? {}),
+    };
+    return flags[MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY];
+}
+/**
+ * Whether a flag value is the object payload form: a plain object (not an
+ * array) whose `enabled` is the literal boolean `true`. Anything else,
+ * including `{ enabled: false }` and objects without `enabled`, is not an
+ * enabled payload, so the flag fails closed.
+ *
+ * @param value - The merged flag value.
+ * @returns Whether the value is an enabled object payload.
+ */
+function isEnabledPayload(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.enabled === true &&
+        value.featureVersion === HEADLESS_ALL_PROVIDERS_FEATURE_VERSION);
+}
+/**
+ * The `minimumVersion` carried by an enabled payload, or `undefined` for the
+ * boolean form, a disabled payload, or a malformed field. This package cannot
+ * compare app versions itself; mobile validates the value through its shared
+ * `validatedVersionGatedFeatureFlag` util, and the LaunchDarkly `versions`
+ * wrapper provides the server-side gate.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it).
+ * @returns The minimum app version the payload declares, or `undefined`.
+ */
+export function getHeadlessAllProvidersMinimumVersion(remoteFeatureFlagState) {
+    const value = resolveFlagValue(remoteFeatureFlagState);
+    if (!isEnabledPayload(value)) {
+        return undefined;
+    }
+    const { minimumVersion } = value;
+    return typeof minimumVersion === 'string' && minimumVersion.trim() !== ''
+        ? minimumVersion
+        : undefined;
+}
+/**
+ * Coerces a payload field into a provider-id list: keeps only string entries,
+ * trims them, and drops empties. An empty or malformed level is treated as
+ * "not provided" so resolution falls through to the next level rather than
+ * restricting to nothing; to force "nothing eligible" list a nonexistent id.
+ *
+ * @param value - The candidate `providerIds` / surface entry value.
+ * @returns The non-empty coerced list, or `undefined`.
+ */
+function coerceProviderIdList(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const ids = value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== '');
+    return ids.length > 0 ? ids : undefined;
+}
 /**
  * Whether the Headless Buy all-providers feature flag is enabled.
  *
  * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}
  * so the controller's quote widening and UI availability gates resolve the
- * flag identically. `localOverrides` (written by dev-only override screens)
- * are merged over `remoteFeatureFlags`, because not every published
- * `RemoteFeatureFlagController` version folds overrides into
- * `remoteFeatureFlags` state; when a version already does, the merge is a
- * no-op. Coerces defensively: only the literal boolean `true` enables, and
- * any other value (missing, string, object) resolves to `false`.
+ * flag identically. `localOverrides` are merged over `remoteFeatureFlags`
+ * (see {@link resolveFlagValue}). Coerces defensively: only the literal
+ * boolean `true` or an object payload whose `enabled` is the literal `true`
+ * enables; any other value (missing, string, number, array, `{ enabled:
+ * false }`) resolves to `false`.
  *
  * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
  * relevant subset of it). May be `null`/`undefined` before the controller is
@@ -26,10 +115,45 @@ export const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY = 'moneyHeadlessAllProviders'
  * quote path.
  */
 export function isHeadlessAllProvidersEnabled(remoteFeatureFlagState) {
-    const flags = {
-        ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),
-        ...(remoteFeatureFlagState?.localOverrides ?? {}),
-    };
-    return flags[MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY] === true;
+    const value = resolveFlagValue(remoteFeatureFlagState);
+    return value === true || isEnabledPayload(value);
+}
+/**
+ * The provider-id allowlist carried by the flag's object payload, or
+ * `undefined` when the widened pick should not be restricted.
+ *
+ * Returns the payload's top-level `providerIds` when non-empty and valid, or
+ * `undefined` (no restriction). The boolean `true` form, a disabled or
+ * malformed payload, and empty or all-invalid lists all resolve to
+ * `undefined`; unknown keys and non-string entries are ignored.
+ *
+ * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the
+ * relevant subset of it). May be `null`/`undefined` before the controller is
+ * initialized.
+ * @returns The provider ids the widened pick is restricted to, or `undefined`
+ * for no restriction.
+ */
+export function getHeadlessProviderAllowlist(remoteFeatureFlagState) {
+    const value = resolveFlagValue(remoteFeatureFlagState);
+    if (!isEnabledPayload(value)) {
+        return undefined;
+    }
+    return coerceProviderIdList(value.providerIds);
+}
+/**
+ * Normalizes a provider id for allowlist matching only: trims, strips the
+ * canonical `/providers/` path prefix, and lowercases, so `/providers/moonpay`
+ * and `moonpay` match each other. Quote and catalog provider ids are matched
+ * as-is everywhere else; this exists solely so LaunchDarkly payload authors
+ * can use either id form. Not exported from the package index.
+ *
+ * @param id - A provider id in either the prefixed or bare form.
+ * @returns The normalized id used for allowlist comparison.
+ */
+export function normalizeHeadlessProviderId(id) {
+    return id
+        .trim()
+        .replace(/^\/providers\//u, '')
+        .toLowerCase();
 }
 //# sourceMappingURL=featureFlags.mjs.map

package/dist/featureFlags.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"featureFlags.mjs","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAChD,2BAA2B,CAAC;AAa9B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,sBAAqE;IAErE,MAAM,KAAK,GAAiB;QAC1B,GAAG,CAAC,sBAAsB,EAAE,kBAAkB,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,sBAAsB,EAAE,cAAc,IAAI,EAAE,CAAC;KAClD,CAAC;IACF,OAAO,KAAK,CAAC,qCAAqC,CAAC,KAAK,IAAI,CAAC;AAC/D,CAAC","sourcesContent":["import type { FeatureFlags } from '@metamask/remote-feature-flag-controller';\n\n/**\n * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers\n * expansion. A boolean flag: `true` widens the headless fiat quote path to\n * every provider class (native, in-app WebView aggregator, and\n * external-browser / custom-action); `false` or missing keeps the native-only\n * default. Exported so the flag registry and every consumer stay in sync on\n * the exact key string.\n */\nexport const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY =\n  'moneyHeadlessAllProviders';\n\n/**\n * The subset of `RemoteFeatureFlagController` state that\n * {@link isHeadlessAllProvidersEnabled} reads. Structural so consumers can\n * pass the whole controller state (or `undefined` before initialization)\n * without depending on a specific controller version.\n */\nexport type HeadlessFeatureFlagsLookup = {\n  remoteFeatureFlags?: FeatureFlags;\n  localOverrides?: FeatureFlags;\n};\n\n/**\n * Whether the Headless Buy all-providers feature flag is enabled.\n *\n * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}\n * so the controller's quote widening and UI availability gates resolve the\n * flag identically. `localOverrides` (written by dev-only override screens)\n * are merged over `remoteFeatureFlags`, because not every published\n * `RemoteFeatureFlagController` version folds overrides into\n * `remoteFeatureFlags` state; when a version already does, the merge is a\n * no-op. Coerces defensively: only the literal boolean `true` enables, and\n * any other value (missing, string, object) resolves to `false`.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it). May be `null`/`undefined` before the controller is\n * initialized.\n * @returns Whether all provider classes are enabled for the headless fiat\n * quote path.\n */\nexport function isHeadlessAllProvidersEnabled(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): boolean {\n  const flags: FeatureFlags = {\n    ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),\n    ...(remoteFeatureFlagState?.localOverrides ?? {}),\n  };\n  return flags[MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY] === true;\n}\n"]}
+{"version":3,"file":"featureFlags.mjs","sourceRoot":"","sources":["../src/featureFlags.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAChD,2BAA2B,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,GAAG,CAAC;AAa1D;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB,CACvB,sBAAqE;IAErE,MAAM,KAAK,GAAiB;QAC1B,GAAG,CAAC,sBAAsB,EAAE,kBAAkB,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,sBAAsB,EAAE,cAAc,IAAI,EAAE,CAAC;KAClD,CAAC;IACF,OAAO,KAAK,CAAC,qCAAqC,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,KAAuB;IAG/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,KAAK,CAAC,OAAO,KAAK,IAAI;QACtB,KAAK,CAAC,cAAc,KAAK,sCAAsC,CAChE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qCAAqC,CACnD,sBAAqE;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IACvD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IACjC,OAAO,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE;QACvE,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,KAAuB;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,KAAK;SACd,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC;SAC7D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;IACnC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,sBAAqE;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IACvD,OAAO,KAAK,KAAK,IAAI,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,4BAA4B,CAC1C,sBAAqE;IAErE,MAAM,KAAK,GAAG,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IACvD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAAU;IACpD,OAAO,EAAE;SACN,IAAI,EAAE;SACN,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC;SAC9B,WAAW,EAAE,CAAC;AACnB,CAAC","sourcesContent":["import type { FeatureFlags } from '@metamask/remote-feature-flag-controller';\nimport type { Json } from '@metamask/utils';\n\n/**\n * Remote (LaunchDarkly) feature flag key for the Headless Buy all-providers\n * expansion. Accepts two value forms:\n *\n * - The literal boolean `true` widens the headless fiat quote path to every\n *   provider class (native, in-app WebView aggregator, and external-browser /\n *   custom-action) with no provider restriction.\n * - An object payload `{ enabled: true, featureVersion: \"1\", providerIds?: string[] }`\n *   widens the same way, and additionally restricts the widened quote pick to\n *   the listed provider ids (see {@link getHeadlessProviderAllowlist}).\n *\n * `false`, a missing flag, or any other value keeps the native-only default.\n * Clients that only understand the boolean form coerce the object payload to\n * \"disabled\" (native-only), so serving the object form can never turn the\n * feature on for a client that cannot parse it. Exported so the flag registry\n * and every consumer stay in sync on the exact key string.\n */\nexport const MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY =\n  'moneyHeadlessAllProviders';\n\n/**\n * Contract version of the object payload. An enabled payload whose\n * `featureVersion` differs (or is absent) fails closed, so the payload's\n * meaning can change in a future client without old clients misreading it.\n * Mirrors the platform pattern used by `assetsUnifyState`.\n */\nexport const HEADLESS_ALL_PROVIDERS_FEATURE_VERSION = '1';\n\n/**\n * The subset of `RemoteFeatureFlagController` state that\n * {@link isHeadlessAllProvidersEnabled} reads. Structural so consumers can\n * pass the whole controller state (or `undefined` before initialization)\n * without depending on a specific controller version.\n */\nexport type HeadlessFeatureFlagsLookup = {\n  remoteFeatureFlags?: FeatureFlags;\n  localOverrides?: FeatureFlags;\n};\n\n/**\n * Resolves the flag value with `localOverrides` (written by dev-only override\n * screens) merged over `remoteFeatureFlags`, because not every published\n * `RemoteFeatureFlagController` version folds overrides into\n * `remoteFeatureFlags` state; when a version already does, the merge is a\n * no-op.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it).\n * @returns The merged flag value, or `undefined` when absent.\n */\nfunction resolveFlagValue(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): Json | undefined {\n  const flags: FeatureFlags = {\n    ...(remoteFeatureFlagState?.remoteFeatureFlags ?? {}),\n    ...(remoteFeatureFlagState?.localOverrides ?? {}),\n  };\n  return flags[MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY];\n}\n\n/**\n * Whether a flag value is the object payload form: a plain object (not an\n * array) whose `enabled` is the literal boolean `true`. Anything else,\n * including `{ enabled: false }` and objects without `enabled`, is not an\n * enabled payload, so the flag fails closed.\n *\n * @param value - The merged flag value.\n * @returns Whether the value is an enabled object payload.\n */\nfunction isEnabledPayload(value: Json | undefined): value is {\n  [key: string]: Json;\n} {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    !Array.isArray(value) &&\n    value.enabled === true &&\n    value.featureVersion === HEADLESS_ALL_PROVIDERS_FEATURE_VERSION\n  );\n}\n\n/**\n * The `minimumVersion` carried by an enabled payload, or `undefined` for the\n * boolean form, a disabled payload, or a malformed field. This package cannot\n * compare app versions itself; mobile validates the value through its shared\n * `validatedVersionGatedFeatureFlag` util, and the LaunchDarkly `versions`\n * wrapper provides the server-side gate.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it).\n * @returns The minimum app version the payload declares, or `undefined`.\n */\nexport function getHeadlessAllProvidersMinimumVersion(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): string | undefined {\n  const value = resolveFlagValue(remoteFeatureFlagState);\n  if (!isEnabledPayload(value)) {\n    return undefined;\n  }\n  const { minimumVersion } = value;\n  return typeof minimumVersion === 'string' && minimumVersion.trim() !== ''\n    ? minimumVersion\n    : undefined;\n}\n\n/**\n * Coerces a payload field into a provider-id list: keeps only string entries,\n * trims them, and drops empties. An empty or malformed level is treated as\n * \"not provided\" so resolution falls through to the next level rather than\n * restricting to nothing; to force \"nothing eligible\" list a nonexistent id.\n *\n * @param value - The candidate `providerIds` / surface entry value.\n * @returns The non-empty coerced list, or `undefined`.\n */\nfunction coerceProviderIdList(value: Json | undefined): string[] | undefined {\n  if (!Array.isArray(value)) {\n    return undefined;\n  }\n  const ids = value\n    .filter((entry): entry is string => typeof entry === 'string')\n    .map((entry) => entry.trim())\n    .filter((entry) => entry !== '');\n  return ids.length > 0 ? ids : undefined;\n}\n\n/**\n * Whether the Headless Buy all-providers feature flag is enabled.\n *\n * Owns the key lookup and coercion for {@link MONEY_HEADLESS_ALL_PROVIDERS_FLAG_KEY}\n * so the controller's quote widening and UI availability gates resolve the\n * flag identically. `localOverrides` are merged over `remoteFeatureFlags`\n * (see {@link resolveFlagValue}). Coerces defensively: only the literal\n * boolean `true` or an object payload whose `enabled` is the literal `true`\n * enables; any other value (missing, string, number, array, `{ enabled:\n * false }`) resolves to `false`.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it). May be `null`/`undefined` before the controller is\n * initialized.\n * @returns Whether all provider classes are enabled for the headless fiat\n * quote path.\n */\nexport function isHeadlessAllProvidersEnabled(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): boolean {\n  const value = resolveFlagValue(remoteFeatureFlagState);\n  return value === true || isEnabledPayload(value);\n}\n\n/**\n * The provider-id allowlist carried by the flag's object payload, or\n * `undefined` when the widened pick should not be restricted.\n *\n * Returns the payload's top-level `providerIds` when non-empty and valid, or\n * `undefined` (no restriction). The boolean `true` form, a disabled or\n * malformed payload, and empty or all-invalid lists all resolve to\n * `undefined`; unknown keys and non-string entries are ignored.\n *\n * @param remoteFeatureFlagState - `RemoteFeatureFlagController` state (or the\n * relevant subset of it). May be `null`/`undefined` before the controller is\n * initialized.\n * @returns The provider ids the widened pick is restricted to, or `undefined`\n * for no restriction.\n */\nexport function getHeadlessProviderAllowlist(\n  remoteFeatureFlagState: HeadlessFeatureFlagsLookup | null | undefined,\n): string[] | undefined {\n  const value = resolveFlagValue(remoteFeatureFlagState);\n  if (!isEnabledPayload(value)) {\n    return undefined;\n  }\n  return coerceProviderIdList(value.providerIds);\n}\n\n/**\n * Normalizes a provider id for allowlist matching only: trims, strips the\n * canonical `/providers/` path prefix, and lowercases, so `/providers/moonpay`\n * and `moonpay` match each other. Quote and catalog provider ids are matched\n * as-is everywhere else; this exists solely so LaunchDarkly payload authors\n * can use either id form. Not exported from the package index.\n *\n * @param id - A provider id in either the prefixed or bare form.\n * @returns The normalized id used for allowlist comparison.\n */\nexport function normalizeHeadlessProviderId(id: string): string {\n  return id\n    .trim()\n    .replace(/^\\/providers\\//u, '')\n    .toLowerCase();\n}\n"]}