@mindful-web/marko-web-omeda-identity-x 1.89.2 → 1.90.1

package/README.md

@@ -99,6 +99,81 @@ A related trap when reading site configs: some repos' `onAuthenticationSuccess.p
 `product.deploymentTypeId` and emits `deploymentTypes`. Check which formatter consumes a list before
 assuming its ids are products.
 
+### Per-source overrides (`source`)
+
+A hook's appends are otherwise unconditional — every login source gets the same products, opt-ins
+and demographics. Add a `source` map to vary them by where the conversion came from:
+
+```js
+// sites/<site>/config/identity-x-opt-in-hooks.js
+module.exports = {
+  onLoginLinkSent: {
+    productIds: [15375],
+    deploymentTypeIds: [332],
+    source: {
+      contentGating: { productIds: [] },   // no product for either content gate…
+      contentGate: { productIds: [42] },   // …except this one specifically
+    },
+  },
+};
+```
+
+Resolve it in a formatter with
+[`resolveOptInHookConfig`](./utils/resolve-opt-in-hook-config.js), which returns `undefined` when
+the hook isn't configured, so the usual early bail is unchanged:
+
+```js
+const resolveOptInHookConfig = require('@mindful-web/marko-web-omeda-identity-x/utils/resolve-opt-in-hook-config');
+
+const { demographics, deploymentTypeIds, productIds } = resolveOptInHookConfig({
+  optInHooks: identityXOptInHooks,
+  hook: 'onLoginLinkSent',
+  source: loginSource,
+}) || {};
+```
+
+**Layering** is `base → bucket → exact source`, each a shallow **per-key replace**: only the keys
+an override names are replaced, the rest inherit. That is what lets `productIds: []` mean "no
+products for this source" while leaving `deploymentTypeIds` alone. An empty array is truthy, so the
+existing `(productIds || []).reduce(...)` in every formatter produces no appends unchanged. An
+exact-source key always beats the bucket containing it.
+
+**Keys** may be a bucket or an exact login source, in any casing (`contentGate`,
+`content_meter_login` and `CONTENT_GATE` are equivalent). The buckets are the four areas of the
+Insights → Audience → Audience Conversion report:
+
+| Bucket key | Login sources |
+|---|---|
+| `contentGating` | `contentGate`, `content_meter_login` |
+| `newsletter` (or `newsletterSignups`) | `newsletterSignup`, `recommendedSignup` |
+| `featureGating` | `comments`, `contentAccess`, `contentDownload`, `equipmentCalculator`, `loadAnalyzer`, `top250`, `pib_login`, `contactCompany`, `ingredientIssues` |
+| `other` | `default`, `subscribe`, `google-one-tap`, `idxApi` |
+
+Two groupings surprise people, and both are deliberate upstream: **`comments` is feature gating**,
+not other; and **`contentAccess` / `contentDownload` are feature gating**, not content gating (they
+gate an asset rather than an article, and have no Views signal). Sources in no bucket —
+`change-email`, `progressiveProfile`, `truckHistoryReport`, `poultryTrendsLiveChartPage` — are
+reachable only by an exact-source key.
+
+The bucket definitions are mirrored from `mindful-reporting`'s
+`packages/audience/repo/src/repos/member-events/conversion-sources.ts`; there is no package shared
+between the two repos, so [`conversion-source-buckets.js`](./utils/conversion-source-buckets.js)
+duplicates them. **Edit both together** — a source missing here silently falls back to the base
+config rather than erroring.
+
+Two caveats:
+
+- **Each hook names the value differently.** `onLoginLinkSent` receives `source`,
+  `onAuthenticationSuccess` receives `loginSource`, `onUserProfileUpdate` receives `actionSource`.
+  Pass whichever local holds it.
+- **`onUserProfileUpdate` has no reliable source.** Neither `routes/profile.js` nor
+  `routes/progressive-profile.js` passes one; `actionSource` only arrives if a client put it in
+  `additionalEventData`, and is usually `undefined`. Overrides on that hook are inert whenever it
+  is — the value resolves to the base config.
+
+An unrecognized, empty or missing source is never an error: the set of login sources is open (any
+site template can introduce a new `source="…"`), so it resolves to the base config.
+
 ### Customer re-sync interval
 
 `userResyncIntervalMs` is read from the **IdentityX** config (`idxConfig`), not from the properties

package/components/identify.marko.js

@@ -2,7 +2,7 @@
 "use strict";
 
 var marko_template = module.exports = require("marko/dist/html").t(__filename),
-    marko_componentType = "/@mindful-web/marko-web-omeda-identity-x$1.89.2/components/identify.marko",
+    marko_componentType = "/@mindful-web/marko-web-omeda-identity-x$1.90.1/components/identify.marko",
     marko_component = require("./identify.marko"),
     marko_renderer = require("marko/dist/runtime/components/renderer"),
     module_getCookieId = require("@mindful-web/marko-web-omeda-identity-x/utils/get-cookie-id"),
@@ -51,7 +51,7 @@ marko_template._ = marko_renderer(render, {
   }, marko_component);
 
 marko_template.meta = {
-    id: "/@mindful-web/marko-web-omeda-identity-x$1.89.2/components/identify.marko",
+    id: "/@mindful-web/marko-web-omeda-identity-x$1.90.1/components/identify.marko",
     component: "./identify.marko",
     tags: [
       "@mindful-web/marko-web-identity-x/components/identify.marko",

package/index.js

@@ -296,11 +296,24 @@ module.exports = (app, params = {}) => {
  *   "onUserProfileUpdate"
  * )} IDXHookTypeEnum
  *
+ * The login sources shipped by this monorepo's packages. **Not exhaustive** — the set is open:
+ * a site template may pass any `source="…"` string of its own (fusable alone adds `loadAnalyzer`,
+ * `top250`, `pib_login`, `equipmentCalculator`), so treat an unlisted value as valid data rather
+ * than a bug. Grouping into report buckets lives in `utils/conversion-source-buckets.js`.
+ *
  * @typedef {(
  *   "default"|
  *   "newsletterSignup"|
+ *   "recommendedSignup"|
  *   "comments"|
- *   "contentGate"
+ *   "contentGate"|
+ *   "content_meter_login"|
+ *   "contentAccess"|
+ *   "contentDownload"|
+ *   "progressiveProfile"|
+ *   "google-one-tap"|
+ *   "change-email"|
+ *   "subscribe"
  * )} OIDXLoginSource
  *
  * @typedef {(

package/omeda-data/get-promo-code-for.js

@@ -15,6 +15,7 @@ const { get } = require('@mindful-web/object-path');
  * @param {string} [params.comments='Comments']
  * @param {object} [params.contentMeterLogin]
  * @param {string} [params.contentGate='HardGate']
+ * @param {string} [params.googleOneTap='GoogleOneTap']
  * @param {object} [params.req]
  * @returns {string}
  */
@@ -36,6 +37,10 @@ module.exports = ({
     overlay: 'MeterGate',
   },
   contentGate = 'HardGate',
+  // Google Sign-In. `routes/google.js` uses one `loginSource` for both of its
+  // surfaces (the One-Tap prompt and the rendered button), so this single code
+  // covers both.
+  googleOneTap = 'GoogleOneTap',
   req,
 }) => {
   if (get(req, 'cookies.omeda_promo_code')) return get(req, 'cookies.omeda_promo_code');
@@ -53,6 +58,8 @@ module.exports = ({
       return `${promoCodePrefix}${contentMeterLogin.default}`;
     case 'contentGate':
       return `${promoCodePrefix}${contentGate}`;
+    case 'google-one-tap':
+      return `${promoCodePrefix}${googleOneTap}`;
     default:
       return `${promoCodePrefix}${defaultPromoCode}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindful-web/marko-web-omeda-identity-x",
-  "version": "1.89.2",
+  "version": "1.90.1",
   "description": "Marko Omeda+IdentityX integration tools",
   "repository": "https://github.com/parameter1/mindful-web/tree/main/packages/marko-web-omeda-identity-x",
   "author": "Josh Worden <josh@parameter1.com>",
@@ -33,5 +33,5 @@
     "chai": "^4.3.7",
     "mocha": "^6.2.3"
   },
-  "gitHead": "a813aca477e54e14bc61e5bbb5c77fd7d870ea01"
+  "gitHead": "e0185d370d34b4d465ceedae9e453b1925e5e6f5"
 }

package/test/opt-in-hook-config.spec.js

@@ -0,0 +1,256 @@
+const { describe, it } = require('mocha');
+const { expect } = require('chai');
+const {
+  BUCKETS,
+  getBucketForKey,
+  getBucketForSource,
+  normalizeSource,
+} = require('../utils/conversion-source-buckets');
+const resolveOptInHookConfig = require('../utils/resolve-opt-in-hook-config');
+
+const HOOK = 'onLoginLinkSent';
+
+describe('utils/conversion-source-buckets', () => {
+  describe('normalizeSource', () => {
+    // Expected values are `constantCase(...)` from the `change-case` package, which is what
+    // mindful-reporting applies when it writes the member event. Every real login-source literal
+    // in the fleet is listed so a regression in the regexes shows up as a named failure.
+    const cases = [
+      ['contentGate', 'CONTENT_GATE'],
+      ['content_meter_login', 'CONTENT_METER_LOGIN'],
+      ['newsletterSignup', 'NEWSLETTER_SIGNUP'],
+      ['recommendedSignup', 'RECOMMENDED_SIGNUP'],
+      ['comments', 'COMMENTS'],
+      ['contentAccess', 'CONTENT_ACCESS'],
+      ['contentDownload', 'CONTENT_DOWNLOAD'],
+      ['equipmentCalculator', 'EQUIPMENT_CALCULATOR'],
+      ['loadAnalyzer', 'LOAD_ANALYZER'],
+      ['pib_login', 'PIB_LOGIN'],
+      ['google-one-tap', 'GOOGLE_ONE_TAP'],
+      ['change-email', 'CHANGE_EMAIL'],
+      ['progressiveProfile', 'PROGRESSIVE_PROFILE'],
+      ['truckHistoryReport', 'TRUCK_HISTORY_REPORT'],
+      ['poultryTrendsLiveChartPage', 'POULTRY_TRENDS_LIVE_CHART_PAGE'],
+      ['default', 'DEFAULT'],
+      ['subscribe', 'SUBSCRIBE'],
+    ];
+
+    cases.forEach(([input, expected]) => {
+      it(`normalizes ${input} to ${expected}`, () => {
+        expect(normalizeSource(input)).to.equal(expected);
+      });
+    });
+
+    // The one case a naive implementation gets wrong. Reporting's key is `TOP250`; splitting on a
+    // letter→digit boundary would yield `TOP_250` and silently stop matching.
+    it('does not insert a separator between a letter and a digit', () => {
+      expect(normalizeSource('top250')).to.equal('TOP250');
+    });
+
+    it('is a no-op for already-normalized input', () => {
+      ['TOP250', 'CONTENT_GATE', 'GOOGLE_ONE_TAP'].forEach((v) => {
+        expect(normalizeSource(v)).to.equal(v);
+      });
+    });
+
+    it('handles null and undefined without throwing', () => {
+      expect(normalizeSource(undefined)).to.equal('');
+      expect(normalizeSource(null)).to.equal('');
+    });
+  });
+
+  describe('getBucketForSource', () => {
+    it('buckets content-gating sources', () => {
+      expect(getBucketForSource('contentGate')).to.equal(BUCKETS.contentGating);
+      expect(getBucketForSource('content_meter_login')).to.equal(BUCKETS.contentGating);
+    });
+
+    it('buckets newsletter sources', () => {
+      expect(getBucketForSource('newsletterSignup')).to.equal(BUCKETS.newsletter);
+      expect(getBucketForSource('recommendedSignup')).to.equal(BUCKETS.newsletter);
+    });
+
+    // The two counterintuitive groupings, asserted so nobody "corrects" the map.
+    it('buckets comments as feature gating, not other', () => {
+      expect(getBucketForSource('comments')).to.equal(BUCKETS.featureGating);
+    });
+
+    it('buckets content access/download as feature gating, not content gating', () => {
+      expect(getBucketForSource('contentAccess')).to.equal(BUCKETS.featureGating);
+      expect(getBucketForSource('contentDownload')).to.equal(BUCKETS.featureGating);
+    });
+
+    it('buckets google one tap as other', () => {
+      expect(getBucketForSource('google-one-tap')).to.equal(BUCKETS.other);
+    });
+
+    it('returns undefined for deliberately unbucketed sources', () => {
+      ['change-email', 'progressiveProfile', 'truckHistoryReport'].forEach((v) => {
+        expect(getBucketForSource(v)).to.equal(undefined);
+      });
+    });
+
+    it('returns undefined for unknown and empty sources', () => {
+      expect(getBucketForSource('somethingBrandNew')).to.equal(undefined);
+      expect(getBucketForSource(undefined)).to.equal(undefined);
+      expect(getBucketForSource('')).to.equal(undefined);
+    });
+  });
+
+  describe('getBucketForKey', () => {
+    it('accepts the report area names', () => {
+      expect(getBucketForKey('contentGating')).to.equal(BUCKETS.contentGating);
+      expect(getBucketForKey('featureGating')).to.equal(BUCKETS.featureGating);
+      expect(getBucketForKey('newsletter')).to.equal(BUCKETS.newsletter);
+      expect(getBucketForKey('other')).to.equal(BUCKETS.other);
+    });
+
+    it('accepts the plural newsletter heading shown in the UI', () => {
+      expect(getBucketForKey('newsletterSignups')).to.equal(BUCKETS.newsletter);
+    });
+
+    it('returns undefined for an exact-source key', () => {
+      expect(getBucketForKey('contentGate')).to.equal(undefined);
+      expect(getBucketForKey('google-one-tap')).to.equal(undefined);
+    });
+  });
+});
+
+describe('utils/resolve-opt-in-hook-config', () => {
+  const base = { demographics: [], deploymentTypeIds: [332], productIds: [366] };
+
+  it('returns undefined when the hook is not configured', () => {
+    expect(resolveOptInHookConfig({ optInHooks: {}, hook: HOOK, source: 'contentGate' })).to.equal(undefined);
+    expect(resolveOptInHookConfig({ hook: HOOK, source: 'contentGate' })).to.equal(undefined);
+    expect(resolveOptInHookConfig()).to.equal(undefined);
+  });
+
+  it('returns the base config when no overrides are declared', () => {
+    const resolved = resolveOptInHookConfig({
+      optInHooks: { [HOOK]: base },
+      hook: HOOK,
+      source: 'contentGate',
+    });
+    expect(resolved).to.deep.equal(base);
+  });
+
+  it('never returns the source map as payload data', () => {
+    const resolved = resolveOptInHookConfig({
+      optInHooks: { [HOOK]: { ...base, source: { contentGating: { productIds: [] } } } },
+      hook: HOOK,
+      source: 'contentGate',
+    });
+    expect(resolved).to.not.have.property('source');
+  });
+
+  it('applies a bucket override, per key', () => {
+    const resolved = resolveOptInHookConfig({
+      optInHooks: { [HOOK]: { ...base, source: { contentGating: { productIds: [] } } } },
+      hook: HOOK,
+      source: 'contentGate',
+    });
+    // productIds suppressed; everything else inherited.
+    expect(resolved).to.deep.equal({ demographics: [], deploymentTypeIds: [332], productIds: [] });
+  });
+
+  it('applies a bucket override to every source in that bucket', () => {
+    const optInHooks = { [HOOK]: { ...base, source: { contentGating: { productIds: [] } } } };
+    ['contentGate', 'content_meter_login'].forEach((source) => {
+      const resolved = resolveOptInHookConfig({ optInHooks, hook: HOOK, source });
+      expect(resolved.productIds, `source ${source}`).to.deep.equal([]);
+    });
+  });
+
+  it('leaves sources outside the overridden bucket on the base config', () => {
+    const resolved = resolveOptInHookConfig({
+      optInHooks: { [HOOK]: { ...base, source: { contentGating: { productIds: [] } } } },
+      hook: HOOK,
+      source: 'newsletterSignup',
+    });
+    expect(resolved).to.deep.equal(base);
+  });
+
+  it('lets an exact-source override beat its own bucket', () => {
+    const optInHooks = {
+      [HOOK]: {
+        ...base,
+        source: {
+          contentGating: { productIds: [] },
+          contentGate: { productIds: [42] },
+        },
+      },
+    };
+    // The carve-out wins for the named source...
+    expect(resolveOptInHookConfig({ optInHooks, hook: HOOK, source: 'contentGate' }).productIds).to.deep.equal([42]);
+    // ...while its bucket sibling still gets the bucket rule.
+    expect(resolveOptInHookConfig({ optInHooks, hook: HOOK, source: 'content_meter_login' }).productIds).to.deep.equal([]);
+  });
+
+  it('applies an exact-source override for an unbucketed source', () => {
+    const resolved = resolveOptInHookConfig({
+      optInHooks: { [HOOK]: { ...base, source: { progressiveProfile: { productIds: [7] } } } },
+      hook: HOOK,
+      source: 'progressiveProfile',
+    });
+    expect(resolved.productIds).to.deep.equal([7]);
+  });
+
+  it('matches override keys regardless of casing', () => {
+    ['contentGate', 'CONTENT_GATE', 'content-gate'].forEach((key) => {
+      const resolved = resolveOptInHookConfig({
+        optInHooks: { [HOOK]: { ...base, source: { [key]: { productIds: [9] } } } },
+        hook: HOOK,
+        source: 'contentGate',
+      });
+      expect(resolved.productIds, `key ${key}`).to.deep.equal([9]);
+    });
+  });
+
+  it('can override several keys at once', () => {
+    const resolved = resolveOptInHookConfig({
+      optInHooks: {
+        [HOOK]: { ...base, source: { contentGating: { productIds: [], deploymentTypeIds: [] } } },
+      },
+      hook: HOOK,
+      source: 'contentGate',
+    });
+    expect(resolved).to.deep.equal({ demographics: [], deploymentTypeIds: [], productIds: [] });
+  });
+
+  it('does not mutate the supplied config', () => {
+    const optInHooks = { [HOOK]: { ...base, source: { contentGating: { productIds: [] } } } };
+    resolveOptInHookConfig({ optInHooks, hook: HOOK, source: 'contentGate' });
+    expect(optInHooks[HOOK].productIds).to.deep.equal([366]);
+    expect(optInHooks[HOOK].source.contentGating.productIds).to.deep.equal([]);
+  });
+
+  it('falls back to base for an unknown, empty or missing source', () => {
+    const optInHooks = { [HOOK]: { ...base, source: { contentGating: { productIds: [] } } } };
+    [undefined, '', 'somethingBrandNew'].forEach((source) => {
+      expect(resolveOptInHookConfig({ optInHooks, hook: HOOK, source }), `source ${source}`).to.deep.equal(base);
+    });
+  });
+
+  it('ignores a non-object source map or override value', () => {
+    expect(resolveOptInHookConfig({
+      optInHooks: { [HOOK]: { ...base, source: 'nope' } },
+      hook: HOOK,
+      source: 'contentGate',
+    })).to.deep.equal(base);
+
+    expect(resolveOptInHookConfig({
+      optInHooks: { [HOOK]: { ...base, source: { contentGating: 'nope' } } },
+      hook: HOOK,
+      source: 'contentGate',
+    })).to.deep.equal(base);
+  });
+
+  it('resolves each hook independently', () => {
+    const optInHooks = {
+      onLoginLinkSent: { productIds: [1], source: { contentGating: { productIds: [] } } },
+      onAuthenticationSuccess: { productIds: [2] },
+    };
+    expect(resolveOptInHookConfig({ optInHooks, hook: 'onLoginLinkSent', source: 'contentGate' }).productIds).to.deep.equal([]);
+    expect(resolveOptInHookConfig({ optInHooks, hook: 'onAuthenticationSuccess', source: 'contentGate' }).productIds).to.deep.equal([2]);
+  });
+});

package/utils/conversion-source-buckets.js

@@ -0,0 +1,139 @@
+/**
+ * Groups IdentityX login sources into the same four "source buckets" the Insights → Audience →
+ * Audience Conversion report uses, so a site's `identityXOptInHooks` can override its Omeda
+ * appends per bucket rather than per individual source.
+ *
+ * ## Where these names come from
+ *
+ * The buckets are defined in the **reporting** repo, not here:
+ * `mindful-reporting/packages/audience/repo/src/repos/member-events/conversion-sources.ts`
+ * (consumed by `classifyConversionRow` in
+ * `packages/repo/src/insights/audience-captures/conversion-query.ts`). `SOURCE_TO_BUCKET` below is
+ * a deliberate mirror of that file's four maps — there is no package shared between mindful-web
+ * and mindful-reporting, so the duplication cannot be avoided.
+ *
+ * **Keep the two in sync.** If reporting adds a source to a bucket and this map isn't updated,
+ * that source silently falls back to a site's base hook config rather than erroring — a quiet
+ * wrong answer. When editing either file, edit both.
+ *
+ * ## The two vocabularies
+ *
+ * The website emits mixed casing (`contentGate`, `content_meter_login`, `google-one-tap`), while
+ * reporting keys on UPPER_SNAKE (`CONTENT_GATE`, `CONTENT_METER_LOGIN`, `GOOGLE_ONE_TAP`). The
+ * bridge is `constantCase(source)`, applied when the member event is written
+ * (`mindful-reporting/graphql/idx-compat/src/resolvers/app-user.ts`). `normalizeSource` reproduces
+ * that transform so this map can use the exact strings reporting uses.
+ */
+
+/**
+ * Normalizes a login source to the UPPER_SNAKE form reporting stores, matching `constantCase`
+ * from the `change-case` package (which is not a dependency here — this is three replacements,
+ * not worth one).
+ *
+ * Only a lower→upper boundary introduces a separator. A letter→digit boundary must NOT:
+ * `constantCase('top250')` is `TOP250`, and reporting's key is `TOP250`, so a `([a-z])(\d)` rule
+ * would produce `TOP_250` and silently stop matching. Already-normalized input is a no-op, so
+ * config may be written in either vocabulary.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+const normalizeSource = (value) => String(value == null ? '' : value)
+  .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+  .replace(/[-\s]+/g, '_')
+  .toUpperCase();
+
+/** The bucket a source belongs to, mirroring reporting's `ConversionRowArea`. */
+const BUCKETS = {
+  contentGating: 'contentGating',
+  featureGating: 'featureGating',
+  newsletter: 'newsletter',
+  other: 'other',
+};
+
+/**
+ * Normalized login source → bucket. Mirrors, in order, `CONTENT_GATING_SOURCE_TO_NAME`,
+ * `NEWSLETTER_SOURCES`, `FEATURE_GATING_SOURCE_TO_NAME` and `OTHER_SOURCE_TO_NAME` from
+ * reporting's `conversion-sources.ts`.
+ *
+ * Two groupings routinely surprise people, and both are deliberate upstream:
+ * - `COMMENTS` is **feature** gating, not `other`.
+ * - `CONTENT_ACCESS` / `CONTENT_DOWNLOAD` are **feature** gating, not `contentGating` — they gate
+ *   an asset rather than an article, and carry no p1-events Views signal.
+ *
+ * Sources deliberately absent (no bucket in the report, so reachable only by an exact-source
+ * override key): `CHANGE_EMAIL`, `PROGRESSIVE_PROFILE`, `TRUCK_HISTORY_REPORT`,
+ * `POULTRY_TRENDS_LIVE_CHART_PAGE`.
+ */
+const SOURCE_TO_BUCKET = {
+  // Content gating — the only areas with a Views signal, hence a real conversion rate.
+  CONTENT_GATE: BUCKETS.contentGating,
+  CONTENT_METER_LOGIN: BUCKETS.contentGating,
+
+  // Newsletter widgets. "Recommended" uses its own source rather than NEWSLETTER_SIGNUP.
+  NEWSLETTER_SIGNUP: BUCKETS.newsletter,
+  RECOMMENDED_SIGNUP: BUCKETS.newsletter,
+
+  // Feature gating — page/tool gates.
+  COMMENTS: BUCKETS.featureGating,
+  CONTACT_COMPANY: BUCKETS.featureGating,
+  CONTENT_ACCESS: BUCKETS.featureGating,
+  CONTENT_DOWNLOAD: BUCKETS.featureGating,
+  EQUIPMENT_CALCULATOR: BUCKETS.featureGating,
+  INGREDIENT_ISSUES: BUCKETS.featureGating,
+  LOAD_ANALYZER: BUCKETS.featureGating,
+  PIB_LOGIN: BUCKETS.featureGating,
+  TOP250: BUCKETS.featureGating,
+
+  // Other / catch-all.
+  DEFAULT: BUCKETS.other,
+  GOOGLE_ONE_TAP: BUCKETS.other,
+  IDX_API: BUCKETS.other,
+  SUBSCRIBE: BUCKETS.other,
+};
+
+/**
+ * Normalized override key → bucket. Accepts the report's internal area name and, for the
+ * newsletter bucket, the plural heading the UI actually displays ("Newsletter Signups"), since
+ * that is what a config author reading the report is most likely to type.
+ */
+const BUCKET_KEY_TO_BUCKET = {
+  CONTENT_GATING: BUCKETS.contentGating,
+  FEATURE_GATING: BUCKETS.featureGating,
+  NEWSLETTER: BUCKETS.newsletter,
+  NEWSLETTER_SIGNUPS: BUCKETS.newsletter,
+  OTHER: BUCKETS.other,
+};
+
+/**
+ * Returns the bucket for a login source, or `undefined` when the source has no bucket (unknown,
+ * empty, or one of the deliberately unbucketed values above).
+ *
+ * @param {string} [source]
+ * @returns {string|undefined}
+ */
+const getBucketForSource = (source) => {
+  if (!source) return undefined;
+  return SOURCE_TO_BUCKET[normalizeSource(source)];
+};
+
+/**
+ * Returns the bucket an override key refers to, or `undefined` when the key is not a bucket name
+ * (i.e. it should be treated as an exact source key).
+ *
+ * @param {string} [key]
+ * @returns {string|undefined}
+ */
+const getBucketForKey = (key) => {
+  if (!key) return undefined;
+  return BUCKET_KEY_TO_BUCKET[normalizeSource(key)];
+};
+
+module.exports = {
+  BUCKETS,
+  BUCKET_KEY_TO_BUCKET,
+  SOURCE_TO_BUCKET,
+  getBucketForKey,
+  getBucketForSource,
+  normalizeSource,
+};

package/utils/resolve-opt-in-hook-config.js

@@ -0,0 +1,85 @@
+const { getBucketForKey, getBucketForSource, normalizeSource } = require('./conversion-source-buckets');
+
+const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Resolves a site's `identityXOptInHooks[hook]` config for one login source, applying any
+ * per-source overrides declared under that hook's `source` key.
+ *
+ * ## Config shape
+ *
+ * ```js
+ * // sites/<site>/config/identity-x-opt-in-hooks.js
+ * onAuthenticationSuccess: {
+ *   productIds: [83, 88, 84],
+ *   deploymentTypeIds: [332],
+ *   source: {
+ *     contentGating: { productIds: [] },   // both content gates: no products, keep deployments
+ *     contentGate:   { productIds: [42] }, // ...except this one specifically
+ *   },
+ * }
+ * ```
+ *
+ * Override keys may be either a **bucket** (`contentGating`, `featureGating`, `newsletter` /
+ * `newsletterSignups`, `other`) or an **exact login source** (`contentGate`,
+ * `content_meter_login`, `google-one-tap`, …), in any casing — keys are normalized before
+ * comparison, so `contentGate`, `content_meter_login` and `CONTENT_GATE` all work. See
+ * `./conversion-source-buckets` for which sources belong to which bucket (`COMMENTS` is feature
+ * gating, not other; `CONTENT_ACCESS`/`CONTENT_DOWNLOAD` are feature gating, not content gating).
+ *
+ * ## Layering
+ *
+ * `base → bucket override → exact-source override`, each a shallow **per-key replace**: only the
+ * keys present in an override replace the base, and unspecified keys inherit. That is what makes
+ * `productIds: []` express "no products for this source" while leaving `deploymentTypeIds` and
+ * `demographics` alone. An empty array is truthy, so the consuming formatters' existing
+ * `(productIds || []).reduce(...)` produces no appends without any change on their side.
+ *
+ * An exact-source key always wins over the bucket that contains it, so a bucket-wide rule can be
+ * carved out for one source. Bucket names and source names do not currently collide.
+ *
+ * ## Degradation
+ *
+ * The set of login sources is **open** — any site template can introduce a new `source="..."` —
+ * so an unrecognized, empty or `undefined` source is not an error: it resolves to the base config.
+ * A non-object `source` value is ignored the same way.
+ *
+ * Note the three hooks name this value differently in their formatter args: `onLoginLinkSent`
+ * receives `source`, `onAuthenticationSuccess` receives `loginSource`, and `onUserProfileUpdate`
+ * receives `actionSource` (which is client-supplied and frequently `undefined` — overrides on that
+ * hook are inert whenever it is). Pass whichever local holds the value.
+ *
+ * @param {object} params
+ * @param {object} [params.optInHooks] The site's `identityXOptInHooks` config.
+ * @param {string} params.hook One of `onLoginLinkSent`, `onAuthenticationSuccess`,
+ *   `onUserProfileUpdate`.
+ * @param {string} [params.source] The login source for this request.
+ * @returns {object|undefined} The resolved config (without its `source` map), or `undefined` when
+ *   the hook is not configured — so callers can keep their existing early bail.
+ */
+module.exports = ({ optInHooks, hook, source } = {}) => {
+  const hookConfig = isPlainObject(optInHooks) ? optInHooks[hook] : undefined;
+  if (!isPlainObject(hookConfig)) return undefined;
+
+  const { source: overrides, ...base } = hookConfig;
+  if (!isPlainObject(overrides) || !source) return base;
+
+  const bucket = getBucketForSource(source);
+  const normalizedSource = normalizeSource(source);
+
+  // A single pass over the override keys, so one key cannot be applied twice and the two layers
+  // stay independent of the order the config happens to declare them in.
+  const layers = Object.keys(overrides).reduce((acc, key) => {
+    const value = overrides[key];
+    if (!isPlainObject(value)) return acc;
+    const keyBucket = getBucketForKey(key);
+    if (keyBucket) {
+      if (keyBucket === bucket) acc.bucket.push(value);
+      return acc;
+    }
+    if (normalizeSource(key) === normalizedSource) acc.exact.push(value);
+    return acc;
+  }, { bucket: [], exact: [] });
+
+  return [...layers.bucket, ...layers.exact].reduce((acc, layer) => ({ ...acc, ...layer }), base);
+};