@aglyn/tenant-data-admin 1.0.0-beta.250 → 1.0.0-beta.252

package/src/lib/server/ad-audience-sync.js

@@ -0,0 +1,446 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createHash } from "node:crypto";
+/**
+ * THE ACCOUNT-HOLDER AD AUDIENCE (AGL-3780) — the pure half.
+ *
+ * Once a night the operator's own account holders are kept in step with a
+ * customer-list audience on each of the operator's OWN ad accounts — Meta
+ * Custom Audiences, Google Customer Match and LinkedIn DMP segments — so
+ * signed-up people can be retargeted and left out of prospecting. This is
+ * the platform's marketing, not a merchant feature: a merchant's own pixels
+ * and conversion APIs are the ad-conversions plugin, which this shares
+ * nothing with.
+ *
+ * Everything here is pure — normalization, hashing, who is eligible, the
+ * add/remove diff and each provider's request — so the spec walks every rule
+ * without a network. `ad-audience-sync-run.ts` reads the accounts, sends and
+ * records.
+ *
+ * No address ever leaves in the clear: each provider receives the SHA-256 hex
+ * digest of the address normalized the way that provider documents, and
+ * nothing here logs either one.
+ */ export const AD_AUDIENCE_PROVIDERS = [
+    'meta',
+    'google',
+    'linkedin'
+];
+export const AD_AUDIENCE_PROVIDER_LABELS = {
+    meta: 'Meta',
+    google: 'Google',
+    linkedin: 'LinkedIn'
+};
+/*==========================================
+ * NORMALIZATION AND HASHING
+ *=========================================*/ const GOOGLE_CONSUMER_DOMAINS = new Set([
+    'gmail.com',
+    'googlemail.com'
+]);
+/**
+ * The address the way one provider says to normalize it before hashing, or
+ * null when it is not an address at all.
+ *
+ * - **Meta** (Custom Audiences, `EMAIL`): trim leading and trailing white
+ *   space, lowercase.
+ * - **LinkedIn** (DMP segment users, `SHA256_EMAIL`): lowercase, remove any
+ *   white space.
+ * - **Google** (Data Manager API, Customer Match): lowercase, remove leading,
+ *   trailing and inner white space, and for `gmail.com` and `googlemail.com`
+ *   only, remove the dots from the local part and drop a `+` and everything
+ *   after it. Other domains keep both.
+ *
+ * Inner white space is never part of a deliverable address, so removing it
+ * for Meta as well would change nothing real; it is left exactly as Meta
+ * documents it.
+ */ export function normalizeAudienceEmail(provider, raw) {
+    if (typeof raw !== 'string') return null;
+    let email = provider === 'meta' ? raw.trim().toLowerCase() : raw.replace(/\s+/g, '').toLowerCase();
+    const at = email.lastIndexOf('@');
+    if (at <= 0 || at === email.length - 1 || email.indexOf('@') !== at) return null;
+    if (provider === 'google') {
+        let local = email.slice(0, at);
+        const domain = email.slice(at + 1);
+        if (GOOGLE_CONSUMER_DOMAINS.has(domain)) {
+            const plus = local.indexOf('+');
+            if (plus >= 0) local = local.slice(0, plus);
+            local = local.replace(/\./g, '');
+            if (!local) return null;
+            email = `${local}@${domain}`;
+        }
+    }
+    return email;
+}
+/** Lowercase SHA-256 hex of a UTF-8 string: what all three providers take. */ export function sha256Hex(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+/** The hash one provider receives for an address, or null for no address. */ export function hashAudienceEmail(provider, raw) {
+    const normalized = normalizeAudienceEmail(provider, raw);
+    return normalized ? sha256Hex(normalized) : null;
+}
+export const AD_AUDIENCE_EXCLUSIONS = [
+    'no-email',
+    'disabled',
+    'staff',
+    'internal',
+    'locked',
+    'banned',
+    'opted-out',
+    'unverified',
+    'no-country',
+    'not-us'
+];
+/** The one country the audience is built for. */ export const AD_AUDIENCE_COUNTRY = 'US';
+const ALPHA2 = /^[A-Z]{2}$/;
+/**
+ * The account's country, and which signal said so.
+ *
+ * 1. **The billing address** of a workspace the account owns. It is the
+ *    address the account holder typed or gave Stripe, it is the address tax
+ *    is computed on, and it is the strongest country fact the platform holds.
+ *    When the account owns workspaces billed in different countries, the
+ *    answer is US only when EVERY one of them is US: an account that bills
+ *    from abroad is not counted as a US account holder on the strength of
+ *    one US workspace.
+ * 2. Otherwise **the sign-up geography**: the country the edge reported for
+ *    the request that created the account (AGL-3289). It says where the
+ *    person was when they signed up, which is a weaker fact, and it is the
+ *    one most accounts have.
+ * 3. Otherwise nothing, and an account with no country is left out. A phone
+ *    number's `+1` is deliberately not a signal: it is shared with Canada and
+ *    the Caribbean.
+ */ export function resolveAccountCountry(account) {
+    var _account_signupCountry;
+    const billing = [
+        ...new Set(account.billingCountries.map((country)=>String(country != null ? country : '').trim().toUpperCase()).filter((country)=>ALPHA2.test(country)))
+    ];
+    if (billing.length) {
+        const foreign = billing.find((country)=>country !== AD_AUDIENCE_COUNTRY);
+        return {
+            country: foreign != null ? foreign : AD_AUDIENCE_COUNTRY,
+            source: 'billing'
+        };
+    }
+    const signup = String((_account_signupCountry = account.signupCountry) != null ? _account_signupCountry : '').trim().toUpperCase();
+    if (ALPHA2.test(signup)) return {
+        country: signup,
+        source: 'signup'
+    };
+    return {
+        country: null,
+        source: null
+    };
+}
+/** The domain part of an operator address, lowercased, or null. */ export function emailDomain(address) {
+    const value = String(address != null ? address : '').trim().toLowerCase();
+    const at = value.lastIndexOf('@');
+    return at > 0 && at < value.length - 1 ? value.slice(at + 1) : null;
+}
+/**
+ * Why this account is left out, or null when it belongs in the audience.
+ *
+ * Every condition must hold: an address, not disabled, not staff, not on the
+ * operator's own domain, no account lock (an `abuse` lock is a permanent ban),
+ * not on the ban list, not opted out, a verified address, and a United
+ * States country. Account deletion needs no rule: an erased account has no
+ * Auth record, so it is never read at all, and the diff removes it.
+ *
+ * The address must be VERIFIED because anyone can sign up with an address
+ * that is not theirs, and uploading it would put a person who never signed up
+ * into the audience. A Google or SSO sign-in arrives verified.
+ */ export function adAudienceExclusion(account, options = {}) {
+    var _options_internalDomains;
+    const domain = emailDomain(account.email);
+    if (!domain) return 'no-email';
+    if (account.disabled) return 'disabled';
+    if (account.staff) return 'staff';
+    if (((_options_internalDomains = options.internalDomains) != null ? _options_internalDomains : []).some((internal)=>internal.toLowerCase() === domain)) {
+        return 'internal';
+    }
+    if (account.locked) return 'locked';
+    if (account.banned) return 'banned';
+    if (account.optedOut) return 'opted-out';
+    if (!account.emailVerified) return 'unverified';
+    const { country } = resolveAccountCountry(account);
+    if (!country) return 'no-country';
+    if (country !== AD_AUDIENCE_COUNTRY) return 'not-us';
+    return null;
+}
+/*==========================================
+ * THE DIFF
+ *=========================================*/ /** What has to change for a provider to hold `next` when it holds `previous`. */ export function diffAudience(previous, next) {
+    const before = new Set(previous);
+    const after = new Set(next);
+    return {
+        toAdd: [
+            ...after
+        ].filter((hash)=>!before.has(hash)).sort(),
+        toRemove: [
+            ...before
+        ].filter((hash)=>!after.has(hash)).sort()
+    };
+}
+/**
+ * Whether a night's set shrank so far it is more likely a failed read than
+ * real churn. Below twenty there is no telling the two apart, so it is never
+ * refused; above it, losing more than half the audience in one night is held
+ * until a person passes `force`.
+ */ export function isSuspiciousShrink(previousSize, nextSize) {
+    return previousSize >= 20 && nextSize < previousSize / 2;
+}
+/** `items` in runs of at most `size`. */ export function chunk(items, size) {
+    const runs = [];
+    for(let index = 0; index < items.length; index += size){
+        runs.push(items.slice(index, index + size));
+    }
+    return runs;
+}
+/**
+ * The variables, read here by their literal names so the self-host
+ * environment reference can see every one of them.
+ */ export function adAudienceEnv() {
+    return {
+        META_AUDIENCE_SYNC_ACCESS_TOKEN: process.env.META_AUDIENCE_SYNC_ACCESS_TOKEN,
+        META_AUDIENCE_SYNC_AUDIENCE_ID: process.env.META_AUDIENCE_SYNC_AUDIENCE_ID,
+        GOOGLE_AUDIENCE_SYNC_CLIENT_ID: process.env.GOOGLE_AUDIENCE_SYNC_CLIENT_ID,
+        GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET: process.env.GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET,
+        GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN: process.env.GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN,
+        GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID: process.env.GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID,
+        GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID: process.env.GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID,
+        GOOGLE_AUDIENCE_SYNC_USER_LIST_ID: process.env.GOOGLE_AUDIENCE_SYNC_USER_LIST_ID,
+        LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN: process.env.LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN,
+        LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID: process.env.LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID
+    };
+}
+const REQUIRED = {
+    meta: [
+        'META_AUDIENCE_SYNC_ACCESS_TOKEN',
+        'META_AUDIENCE_SYNC_AUDIENCE_ID'
+    ],
+    google: [
+        'GOOGLE_AUDIENCE_SYNC_CLIENT_ID',
+        'GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET',
+        'GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN',
+        'GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID',
+        'GOOGLE_AUDIENCE_SYNC_USER_LIST_ID'
+    ],
+    linkedin: [
+        'LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN',
+        'LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID'
+    ]
+};
+const digits = (value)=>value.replace(/\D/g, '');
+/**
+ * Each provider's settings, or null with the names it lacks. A provider is
+ * configured only when every required variable is set; a half-configured one
+ * is skipped, never half-sent.
+ *
+ * The Meta audience is never created here. Creating one when the id is unset
+ * would mint a fresh, empty audience on every run whose variable was lost, and
+ * the ads targeting the real one would go on pointing at it, so the id is
+ * required and the audience is made once, by hand.
+ */ export function readAdAudienceConfig(env = adAudienceEnv()) {
+    const value = (name)=>{
+        var _env_name;
+        return String((_env_name = env[name]) != null ? _env_name : '').trim();
+    };
+    const missing = Object.fromEntries(AD_AUDIENCE_PROVIDERS.map((provider)=>[
+            provider,
+            REQUIRED[provider].filter((name)=>!value(name))
+        ]));
+    const loginCustomerId = digits(value('GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID'));
+    return {
+        meta: missing.meta.length ? null : {
+            accessToken: value('META_AUDIENCE_SYNC_ACCESS_TOKEN'),
+            // `act_` belongs to the ad account, never to an audience id.
+            audienceId: value('META_AUDIENCE_SYNC_AUDIENCE_ID')
+        },
+        google: missing.google.length ? null : {
+            clientId: value('GOOGLE_AUDIENCE_SYNC_CLIENT_ID'),
+            clientSecret: value('GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET'),
+            refreshToken: value('GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN'),
+            // Google Ads shows `841-500-9958`; the API takes the digits.
+            customerId: digits(value('GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID')),
+            loginCustomerId: loginCustomerId || null,
+            userListId: digits(value('GOOGLE_AUDIENCE_SYNC_USER_LIST_ID'))
+        },
+        linkedin: missing.linkedin.length ? null : {
+            accessToken: value('LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN'),
+            // The segment URN's id, whichever form was pasted.
+            segmentId: value('LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID').replace(/^urn:li:dmpSegment:/, '')
+        },
+        missing
+    };
+}
+/**
+ * META — the replace session.
+ *
+ * `POST /{audience}/usersreplace` swaps the audience's whole membership for
+ * the batches of one session: `batch_seq` 1 opens it and `last_batch_flag`
+ * closes it, so a removal needs no separate call and nothing has to be
+ * remembered about who was there before. Each batch carries at most 10,000
+ * hashes, and the session must finish inside 90 minutes. A replace does not
+ * reset an ad set's learning phase, which an add and a delete would.
+ */ export const META_GRAPH_VERSION = 'v25.0';
+export const META_REPLACE_BATCH = 10000;
+export function buildMetaReplaceRequests(config, hashes, sessionId) {
+    const batches = chunk(hashes, META_REPLACE_BATCH);
+    return batches.map((batch, index)=>({
+            method: 'POST',
+            url: `https://graph.facebook.com/${META_GRAPH_VERSION}/${encodeURIComponent(config.audienceId)}/usersreplace`,
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: {
+                payload: {
+                    schema: 'EMAIL_SHA256',
+                    data: batch
+                },
+                session: {
+                    session_id: sessionId,
+                    batch_seq: index + 1,
+                    last_batch_flag: index === batches.length - 1,
+                    estimated_num_total: hashes.length
+                },
+                access_token: config.accessToken
+            }
+        }));
+}
+/**
+ * GOOGLE — the Data Manager API, not the Google Ads API.
+ *
+ * Since 2026-04-01 the Google Ads API's `OfflineUserDataJobService` refuses
+ * Customer Match uploads for a developer token with no Customer Match
+ * activity in the six months before, and Google points every such project at
+ * the Data Manager API instead. It needs an OAuth token with the
+ * `datamanager` scope and no developer token.
+ *
+ * Adds go to `audienceMembers:ingest` and removals to `audienceMembers:remove`,
+ * 10,000 members a request. The Data Manager API has no replace, so the
+ * removals come from the set this sync last sent.
+ *
+ * No `consent` is sent. The audience is United States account holders only,
+ * for whom Google requires no consent signal, and stating `CONSENT_GRANTED`
+ * would assert a consent this platform does not collect.
+ * `customerMatchTermsOfServiceStatus: ACCEPTED` is the operator's own
+ * acceptance of the Customer Match terms, which Google requires on an
+ * ingest; they are accepted in the Google Ads account before this is
+ * configured.
+ */ export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+export const GOOGLE_DATA_MANAGER_BASE = 'https://datamanager.googleapis.com/v1';
+export const GOOGLE_MEMBERS_BATCH = 10000;
+export function buildGoogleTokenRequest(config) {
+    return {
+        method: 'POST',
+        url: GOOGLE_TOKEN_URL,
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+            refresh_token: config.refreshToken
+        }).toString()
+    };
+}
+export function buildGoogleMemberRequests(config, accessToken, action, hashes) {
+    const destination = _extends({
+        operatingAccount: {
+            accountType: 'GOOGLE_ADS',
+            accountId: config.customerId
+        }
+    }, config.loginCustomerId ? {
+        loginAccount: {
+            accountType: 'GOOGLE_ADS',
+            accountId: config.loginCustomerId
+        }
+    } : {}, {
+        productDestinationId: config.userListId
+    });
+    return chunk(hashes, GOOGLE_MEMBERS_BATCH).map((batch)=>({
+            method: 'POST',
+            url: `${GOOGLE_DATA_MANAGER_BASE}/audienceMembers:${action}`,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${accessToken}`
+            },
+            body: _extends({
+                destinations: [
+                    destination
+                ],
+                audienceMembers: batch.map((hash)=>({
+                        userData: {
+                            userIdentifiers: [
+                                {
+                                    emailAddress: hash
+                                }
+                            ]
+                        }
+                    })),
+                encoding: 'HEX'
+            }, action === 'ingest' ? {
+                termsOfService: {
+                    customerMatchTermsOfServiceStatus: 'ACCEPTED'
+                }
+            } : {})
+        }));
+}
+/**
+ * LINKEDIN — DMP segment users, streamed.
+ *
+ * `POST /rest/dmpSegments/{id}/users` with `X-RestLi-Method: BATCH_CREATE`
+ * takes up to 5,000 `ADD` or `REMOVE` elements a request. There is no
+ * replace, so the removals come from the set this sync last sent. Adding an
+ * id twice or removing one already gone both answer 201, so a retry is safe.
+ * The API is open only to developers LinkedIn has approved for Matched
+ * Audiences, with the `rw_dmp_segments` permission.
+ */ export const LINKEDIN_VERSION = '202609';
+export const LINKEDIN_USERS_BATCH = 5000;
+export function buildLinkedInUserRequests(config, action, hashes) {
+    return chunk(hashes, LINKEDIN_USERS_BATCH).map((batch)=>({
+            method: 'POST',
+            url: `https://api.linkedin.com/rest/dmpSegments/${encodeURIComponent(config.segmentId)}/users`,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${config.accessToken}`,
+                'LinkedIn-Version': LINKEDIN_VERSION,
+                'X-Restli-Protocol-Version': '2.0.0',
+                'X-RestLi-Method': 'BATCH_CREATE'
+            },
+            body: {
+                elements: batch.map((hash)=>({
+                        action,
+                        userIds: [
+                            {
+                                idType: 'SHA256_EMAIL',
+                                idValue: hash
+                            }
+                        ]
+                    }))
+            }
+        }));
+}
+/** How many elements of a LinkedIn batch response were refused. */ export function linkedInRefusedCount(answer) {
+    const elements = answer == null ? void 0 : answer.elements;
+    if (!Array.isArray(elements)) return 0;
+    return elements.filter((element)=>{
+        const status = Number(element == null ? void 0 : element.status);
+        return !(status >= 200 && status < 300);
+    }).length;
+}
+
+//# sourceMappingURL=ad-audience-sync.js.map

package/src/lib/server/ad-audience-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/ad-audience-sync.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createHash } from 'node:crypto'\n\n/**\n * THE ACCOUNT-HOLDER AD AUDIENCE (AGL-3780) — the pure half.\n *\n * Once a night the operator's own account holders are kept in step with a\n * customer-list audience on each of the operator's OWN ad accounts — Meta\n * Custom Audiences, Google Customer Match and LinkedIn DMP segments — so\n * signed-up people can be retargeted and left out of prospecting. This is\n * the platform's marketing, not a merchant feature: a merchant's own pixels\n * and conversion APIs are the ad-conversions plugin, which this shares\n * nothing with.\n *\n * Everything here is pure — normalization, hashing, who is eligible, the\n * add/remove diff and each provider's request — so the spec walks every rule\n * without a network. `ad-audience-sync-run.ts` reads the accounts, sends and\n * records.\n *\n * No address ever leaves in the clear: each provider receives the SHA-256 hex\n * digest of the address normalized the way that provider documents, and\n * nothing here logs either one.\n */\n\nexport const AD_AUDIENCE_PROVIDERS = ['meta', 'google', 'linkedin'] as const\nexport type AdAudienceProvider = (typeof AD_AUDIENCE_PROVIDERS)[number]\n\nexport const AD_AUDIENCE_PROVIDER_LABELS: Record<AdAudienceProvider, string> = {\n  meta: 'Meta',\n  google: 'Google',\n  linkedin: 'LinkedIn',\n}\n\n/*==========================================\n * NORMALIZATION AND HASHING\n *=========================================*/\n\nconst GOOGLE_CONSUMER_DOMAINS = new Set(['gmail.com', 'googlemail.com'])\n\n/**\n * The address the way one provider says to normalize it before hashing, or\n * null when it is not an address at all.\n *\n * - **Meta** (Custom Audiences, `EMAIL`): trim leading and trailing white\n *   space, lowercase.\n * - **LinkedIn** (DMP segment users, `SHA256_EMAIL`): lowercase, remove any\n *   white space.\n * - **Google** (Data Manager API, Customer Match): lowercase, remove leading,\n *   trailing and inner white space, and for `gmail.com` and `googlemail.com`\n *   only, remove the dots from the local part and drop a `+` and everything\n *   after it. Other domains keep both.\n *\n * Inner white space is never part of a deliverable address, so removing it\n * for Meta as well would change nothing real; it is left exactly as Meta\n * documents it.\n */\nexport function normalizeAudienceEmail(\n  provider: AdAudienceProvider,\n  raw: unknown,\n): string | null {\n  if (typeof raw !== 'string') return null\n  let email =\n    provider === 'meta' ? raw.trim().toLowerCase() : raw.replace(/\\s+/g, '').toLowerCase()\n  const at = email.lastIndexOf('@')\n  if (at <= 0 || at === email.length - 1 || email.indexOf('@') !== at) return null\n  if (provider === 'google') {\n    let local = email.slice(0, at)\n    const domain = email.slice(at + 1)\n    if (GOOGLE_CONSUMER_DOMAINS.has(domain)) {\n      const plus = local.indexOf('+')\n      if (plus >= 0) local = local.slice(0, plus)\n      local = local.replace(/\\./g, '')\n      if (!local) return null\n      email = `${local}@${domain}`\n    }\n  }\n  return email\n}\n\n/** Lowercase SHA-256 hex of a UTF-8 string: what all three providers take. */\nexport function sha256Hex(value: string): string {\n  return createHash('sha256').update(value, 'utf8').digest('hex')\n}\n\n/** The hash one provider receives for an address, or null for no address. */\nexport function hashAudienceEmail(provider: AdAudienceProvider, raw: unknown): string | null {\n  const normalized = normalizeAudienceEmail(provider, raw)\n  return normalized ? sha256Hex(normalized) : null\n}\n\n/*==========================================\n * ELIGIBILITY\n *=========================================*/\n\n/** What the sync knows about one account, read from Auth and Firestore. */\nexport interface AdAudienceAccount {\n  uid: string\n  email: string | null\n  emailVerified: boolean\n  disabled: boolean\n  /** The `staff` custom claim. */\n  staff: boolean\n  /** `users/{uid}.adAudienceOptOut` is set. */\n  optedOut: boolean\n  /** An account lockdown is in force (`lockdowns/user--{uid}`). */\n  locked: boolean\n  /** The address is on the account-ban suppression list (an `abuse` ban). */\n  banned: boolean\n  /**\n   * The billing-address countries (`orgs/{id}.contact.address.country`) of\n   * the workspaces the account OWNS.\n   */\n  billingCountries: readonly string[]\n  /** `users/{uid}.acquisition.geo.country`: where the sign-up request came from. */\n  signupCountry: string | null\n}\n\n/** Why an account is left out. Counted in every report; never per person. */\nexport type AdAudienceExclusion =\n  | 'no-email'\n  | 'disabled'\n  | 'staff'\n  | 'internal'\n  | 'locked'\n  | 'banned'\n  | 'opted-out'\n  | 'unverified'\n  | 'no-country'\n  | 'not-us'\n\nexport const AD_AUDIENCE_EXCLUSIONS: readonly AdAudienceExclusion[] = [\n  'no-email',\n  'disabled',\n  'staff',\n  'internal',\n  'locked',\n  'banned',\n  'opted-out',\n  'unverified',\n  'no-country',\n  'not-us',\n]\n\n/** The one country the audience is built for. */\nexport const AD_AUDIENCE_COUNTRY = 'US'\n\nexport type AdAudienceCountrySource = 'billing' | 'signup'\n\nconst ALPHA2 = /^[A-Z]{2}$/\n\n/**\n * The account's country, and which signal said so.\n *\n * 1. **The billing address** of a workspace the account owns. It is the\n *    address the account holder typed or gave Stripe, it is the address tax\n *    is computed on, and it is the strongest country fact the platform holds.\n *    When the account owns workspaces billed in different countries, the\n *    answer is US only when EVERY one of them is US: an account that bills\n *    from abroad is not counted as a US account holder on the strength of\n *    one US workspace.\n * 2. Otherwise **the sign-up geography**: the country the edge reported for\n *    the request that created the account (AGL-3289). It says where the\n *    person was when they signed up, which is a weaker fact, and it is the\n *    one most accounts have.\n * 3. Otherwise nothing, and an account with no country is left out. A phone\n *    number's `+1` is deliberately not a signal: it is shared with Canada and\n *    the Caribbean.\n */\nexport function resolveAccountCountry(account: {\n  billingCountries: readonly string[]\n  signupCountry: string | null\n}): { country: string | null; source: AdAudienceCountrySource | null } {\n  const billing = [\n    ...new Set(\n      account.billingCountries\n        .map((country) => String(country ?? '').trim().toUpperCase())\n        .filter((country) => ALPHA2.test(country)),\n    ),\n  ]\n  if (billing.length) {\n    const foreign = billing.find((country) => country !== AD_AUDIENCE_COUNTRY)\n    return { country: foreign ?? AD_AUDIENCE_COUNTRY, source: 'billing' }\n  }\n  const signup = String(account.signupCountry ?? '').trim().toUpperCase()\n  if (ALPHA2.test(signup)) return { country: signup, source: 'signup' }\n  return { country: null, source: null }\n}\n\n/** The domain part of an operator address, lowercased, or null. */\nexport function emailDomain(address: string | null | undefined): string | null {\n  const value = String(address ?? '').trim().toLowerCase()\n  const at = value.lastIndexOf('@')\n  return at > 0 && at < value.length - 1 ? value.slice(at + 1) : null\n}\n\n/**\n * Why this account is left out, or null when it belongs in the audience.\n *\n * Every condition must hold: an address, not disabled, not staff, not on the\n * operator's own domain, no account lock (an `abuse` lock is a permanent ban),\n * not on the ban list, not opted out, a verified address, and a United\n * States country. Account deletion needs no rule: an erased account has no\n * Auth record, so it is never read at all, and the diff removes it.\n *\n * The address must be VERIFIED because anyone can sign up with an address\n * that is not theirs, and uploading it would put a person who never signed up\n * into the audience. A Google or SSO sign-in arrives verified.\n */\nexport function adAudienceExclusion(\n  account: AdAudienceAccount,\n  options: { internalDomains?: readonly string[] } = {},\n): AdAudienceExclusion | null {\n  const domain = emailDomain(account.email)\n  if (!domain) return 'no-email'\n  if (account.disabled) return 'disabled'\n  if (account.staff) return 'staff'\n  if ((options.internalDomains ?? []).some((internal) => internal.toLowerCase() === domain)) {\n    return 'internal'\n  }\n  if (account.locked) return 'locked'\n  if (account.banned) return 'banned'\n  if (account.optedOut) return 'opted-out'\n  if (!account.emailVerified) return 'unverified'\n  const { country } = resolveAccountCountry(account)\n  if (!country) return 'no-country'\n  if (country !== AD_AUDIENCE_COUNTRY) return 'not-us'\n  return null\n}\n\n/*==========================================\n * THE DIFF\n *=========================================*/\n\n/** What has to change for a provider to hold `next` when it holds `previous`. */\nexport function diffAudience(\n  previous: Iterable<string>,\n  next: Iterable<string>,\n): { toAdd: string[]; toRemove: string[] } {\n  const before = new Set(previous)\n  const after = new Set(next)\n  return {\n    toAdd: [...after].filter((hash) => !before.has(hash)).sort(),\n    toRemove: [...before].filter((hash) => !after.has(hash)).sort(),\n  }\n}\n\n/**\n * Whether a night's set shrank so far it is more likely a failed read than\n * real churn. Below twenty there is no telling the two apart, so it is never\n * refused; above it, losing more than half the audience in one night is held\n * until a person passes `force`.\n */\nexport function isSuspiciousShrink(previousSize: number, nextSize: number): boolean {\n  return previousSize >= 20 && nextSize < previousSize / 2\n}\n\n/** `items` in runs of at most `size`. */\nexport function chunk<T>(items: readonly T[], size: number): T[][] {\n  const runs: T[][] = []\n  for (let index = 0; index < items.length; index += size) {\n    runs.push(items.slice(index, index + size))\n  }\n  return runs\n}\n\n/*==========================================\n * CONFIGURATION\n *=========================================*/\n\nexport interface MetaAudienceConfig {\n  accessToken: string\n  audienceId: string\n}\n\nexport interface GoogleAudienceConfig {\n  clientId: string\n  clientSecret: string\n  refreshToken: string\n  /** The Google Ads customer that owns the list, digits only. */\n  customerId: string\n  /** A manager account the credentials reach the customer through, digits only. */\n  loginCustomerId: string | null\n  /** The Customer Match user list id. */\n  userListId: string\n}\n\nexport interface LinkedInAudienceConfig {\n  accessToken: string\n  segmentId: string\n}\n\nexport interface AdAudienceConfig {\n  meta: MetaAudienceConfig | null\n  google: GoogleAudienceConfig | null\n  linkedin: LinkedInAudienceConfig | null\n  /** For each provider left unconfigured, the variables it is missing. */\n  missing: Record<AdAudienceProvider, string[]>\n}\n\n/**\n * The variables, read here by their literal names so the self-host\n * environment reference can see every one of them.\n */\nexport function adAudienceEnv(): Record<string, string | undefined> {\n  return {\n    META_AUDIENCE_SYNC_ACCESS_TOKEN: process.env.META_AUDIENCE_SYNC_ACCESS_TOKEN,\n    META_AUDIENCE_SYNC_AUDIENCE_ID: process.env.META_AUDIENCE_SYNC_AUDIENCE_ID,\n    GOOGLE_AUDIENCE_SYNC_CLIENT_ID: process.env.GOOGLE_AUDIENCE_SYNC_CLIENT_ID,\n    GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET: process.env.GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET,\n    GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN: process.env.GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN,\n    GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID: process.env.GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID,\n    GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID: process.env.GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID,\n    GOOGLE_AUDIENCE_SYNC_USER_LIST_ID: process.env.GOOGLE_AUDIENCE_SYNC_USER_LIST_ID,\n    LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN: process.env.LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN,\n    LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID: process.env.LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID,\n  }\n}\n\nconst REQUIRED: Record<AdAudienceProvider, readonly string[]> = {\n  meta: ['META_AUDIENCE_SYNC_ACCESS_TOKEN', 'META_AUDIENCE_SYNC_AUDIENCE_ID'],\n  google: [\n    'GOOGLE_AUDIENCE_SYNC_CLIENT_ID',\n    'GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET',\n    'GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN',\n    'GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID',\n    'GOOGLE_AUDIENCE_SYNC_USER_LIST_ID',\n  ],\n  linkedin: ['LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN', 'LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID'],\n}\n\nconst digits = (value: string) => value.replace(/\\D/g, '')\n\n/**\n * Each provider's settings, or null with the names it lacks. A provider is\n * configured only when every required variable is set; a half-configured one\n * is skipped, never half-sent.\n *\n * The Meta audience is never created here. Creating one when the id is unset\n * would mint a fresh, empty audience on every run whose variable was lost, and\n * the ads targeting the real one would go on pointing at it, so the id is\n * required and the audience is made once, by hand.\n */\nexport function readAdAudienceConfig(\n  env: Record<string, string | undefined> = adAudienceEnv(),\n): AdAudienceConfig {\n  const value = (name: string) => String(env[name] ?? '').trim()\n  const missing = Object.fromEntries(\n    AD_AUDIENCE_PROVIDERS.map((provider) => [\n      provider,\n      REQUIRED[provider].filter((name) => !value(name)),\n    ]),\n  ) as Record<AdAudienceProvider, string[]>\n  const loginCustomerId = digits(value('GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID'))\n  return {\n    meta: missing.meta.length\n      ? null\n      : {\n          accessToken: value('META_AUDIENCE_SYNC_ACCESS_TOKEN'),\n          // `act_` belongs to the ad account, never to an audience id.\n          audienceId: value('META_AUDIENCE_SYNC_AUDIENCE_ID'),\n        },\n    google: missing.google.length\n      ? null\n      : {\n          clientId: value('GOOGLE_AUDIENCE_SYNC_CLIENT_ID'),\n          clientSecret: value('GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET'),\n          refreshToken: value('GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN'),\n          // Google Ads shows `841-500-9958`; the API takes the digits.\n          customerId: digits(value('GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID')),\n          loginCustomerId: loginCustomerId || null,\n          userListId: digits(value('GOOGLE_AUDIENCE_SYNC_USER_LIST_ID')),\n        },\n    linkedin: missing.linkedin.length\n      ? null\n      : {\n          accessToken: value('LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN'),\n          // The segment URN's id, whichever form was pasted.\n          segmentId: value('LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID').replace(/^urn:li:dmpSegment:/, ''),\n        },\n    missing,\n  }\n}\n\n/*==========================================\n * PROVIDER REQUESTS\n *=========================================*/\n\n/** One HTTP request, built without sending it. */\nexport interface AudienceRequest {\n  method: 'POST'\n  url: string\n  headers: Record<string, string>\n  /** A JSON body, or a form body when `headers` says so. */\n  body: Record<string, unknown> | string\n}\n\n/**\n * META — the replace session.\n *\n * `POST /{audience}/usersreplace` swaps the audience's whole membership for\n * the batches of one session: `batch_seq` 1 opens it and `last_batch_flag`\n * closes it, so a removal needs no separate call and nothing has to be\n * remembered about who was there before. Each batch carries at most 10,000\n * hashes, and the session must finish inside 90 minutes. A replace does not\n * reset an ad set's learning phase, which an add and a delete would.\n */\nexport const META_GRAPH_VERSION = 'v25.0'\nexport const META_REPLACE_BATCH = 10_000\n\nexport function buildMetaReplaceRequests(\n  config: MetaAudienceConfig,\n  hashes: readonly string[],\n  sessionId: number,\n): AudienceRequest[] {\n  const batches = chunk(hashes, META_REPLACE_BATCH)\n  return batches.map((batch, index) => ({\n    method: 'POST',\n    url: `https://graph.facebook.com/${META_GRAPH_VERSION}/${encodeURIComponent(config.audienceId)}/usersreplace`,\n    headers: { 'Content-Type': 'application/json' },\n    body: {\n      payload: { schema: 'EMAIL_SHA256', data: batch },\n      session: {\n        session_id: sessionId,\n        batch_seq: index + 1,\n        last_batch_flag: index === batches.length - 1,\n        estimated_num_total: hashes.length,\n      },\n      access_token: config.accessToken,\n    },\n  }))\n}\n\n/**\n * GOOGLE — the Data Manager API, not the Google Ads API.\n *\n * Since 2026-04-01 the Google Ads API's `OfflineUserDataJobService` refuses\n * Customer Match uploads for a developer token with no Customer Match\n * activity in the six months before, and Google points every such project at\n * the Data Manager API instead. It needs an OAuth token with the\n * `datamanager` scope and no developer token.\n *\n * Adds go to `audienceMembers:ingest` and removals to `audienceMembers:remove`,\n * 10,000 members a request. The Data Manager API has no replace, so the\n * removals come from the set this sync last sent.\n *\n * No `consent` is sent. The audience is United States account holders only,\n * for whom Google requires no consent signal, and stating `CONSENT_GRANTED`\n * would assert a consent this platform does not collect.\n * `customerMatchTermsOfServiceStatus: ACCEPTED` is the operator's own\n * acceptance of the Customer Match terms, which Google requires on an\n * ingest; they are accepted in the Google Ads account before this is\n * configured.\n */\nexport const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token'\nexport const GOOGLE_DATA_MANAGER_BASE = 'https://datamanager.googleapis.com/v1'\nexport const GOOGLE_MEMBERS_BATCH = 10_000\n\nexport function buildGoogleTokenRequest(config: GoogleAudienceConfig): AudienceRequest {\n  return {\n    method: 'POST',\n    url: GOOGLE_TOKEN_URL,\n    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n    body: new URLSearchParams({\n      grant_type: 'refresh_token',\n      client_id: config.clientId,\n      client_secret: config.clientSecret,\n      refresh_token: config.refreshToken,\n    }).toString(),\n  }\n}\n\nexport function buildGoogleMemberRequests(\n  config: GoogleAudienceConfig,\n  accessToken: string,\n  action: 'ingest' | 'remove',\n  hashes: readonly string[],\n): AudienceRequest[] {\n  const destination = {\n    operatingAccount: { accountType: 'GOOGLE_ADS', accountId: config.customerId },\n    ...(config.loginCustomerId\n      ? { loginAccount: { accountType: 'GOOGLE_ADS', accountId: config.loginCustomerId } }\n      : {}),\n    productDestinationId: config.userListId,\n  }\n  return chunk(hashes, GOOGLE_MEMBERS_BATCH).map((batch) => ({\n    method: 'POST',\n    url: `${GOOGLE_DATA_MANAGER_BASE}/audienceMembers:${action}`,\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${accessToken}`,\n    },\n    body: {\n      destinations: [destination],\n      audienceMembers: batch.map((hash) => ({\n        userData: { userIdentifiers: [{ emailAddress: hash }] },\n      })),\n      encoding: 'HEX',\n      ...(action === 'ingest'\n        ? { termsOfService: { customerMatchTermsOfServiceStatus: 'ACCEPTED' } }\n        : {}),\n    },\n  }))\n}\n\n/**\n * LINKEDIN — DMP segment users, streamed.\n *\n * `POST /rest/dmpSegments/{id}/users` with `X-RestLi-Method: BATCH_CREATE`\n * takes up to 5,000 `ADD` or `REMOVE` elements a request. There is no\n * replace, so the removals come from the set this sync last sent. Adding an\n * id twice or removing one already gone both answer 201, so a retry is safe.\n * The API is open only to developers LinkedIn has approved for Matched\n * Audiences, with the `rw_dmp_segments` permission.\n */\nexport const LINKEDIN_VERSION = '202609'\nexport const LINKEDIN_USERS_BATCH = 5_000\n\nexport function buildLinkedInUserRequests(\n  config: LinkedInAudienceConfig,\n  action: 'ADD' | 'REMOVE',\n  hashes: readonly string[],\n): AudienceRequest[] {\n  return chunk(hashes, LINKEDIN_USERS_BATCH).map((batch) => ({\n    method: 'POST',\n    url: `https://api.linkedin.com/rest/dmpSegments/${encodeURIComponent(config.segmentId)}/users`,\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: `Bearer ${config.accessToken}`,\n      'LinkedIn-Version': LINKEDIN_VERSION,\n      'X-Restli-Protocol-Version': '2.0.0',\n      'X-RestLi-Method': 'BATCH_CREATE',\n    },\n    body: {\n      elements: batch.map((hash) => ({\n        action,\n        userIds: [{ idType: 'SHA256_EMAIL', idValue: hash }],\n      })),\n    },\n  }))\n}\n\n/** How many elements of a LinkedIn batch response were refused. */\nexport function linkedInRefusedCount(answer: unknown): number {\n  const elements = (answer as { elements?: unknown } | null)?.elements\n  if (!Array.isArray(elements)) return 0\n  return elements.filter((element) => {\n    const status = Number((element as { status?: unknown } | null)?.status)\n    return !(status >= 200 && status < 300)\n  }).length\n}\n"],"names":["createHash","AD_AUDIENCE_PROVIDERS","AD_AUDIENCE_PROVIDER_LABELS","meta","google","linkedin","GOOGLE_CONSUMER_DOMAINS","Set","normalizeAudienceEmail","provider","raw","email","trim","toLowerCase","replace","at","lastIndexOf","length","indexOf","local","slice","domain","has","plus","sha256Hex","value","update","digest","hashAudienceEmail","normalized","AD_AUDIENCE_EXCLUSIONS","AD_AUDIENCE_COUNTRY","ALPHA2","resolveAccountCountry","account","billing","billingCountries","map","country","String","toUpperCase","filter","test","foreign","find","source","signup","signupCountry","emailDomain","address","adAudienceExclusion","options","disabled","staff","internalDomains","some","internal","locked","banned","optedOut","emailVerified","diffAudience","previous","next","before","after","toAdd","hash","sort","toRemove","isSuspiciousShrink","previousSize","nextSize","chunk","items","size","runs","index","push","adAudienceEnv","META_AUDIENCE_SYNC_ACCESS_TOKEN","process","env","META_AUDIENCE_SYNC_AUDIENCE_ID","GOOGLE_AUDIENCE_SYNC_CLIENT_ID","GOOGLE_AUDIENCE_SYNC_CLIENT_SECRET","GOOGLE_AUDIENCE_SYNC_REFRESH_TOKEN","GOOGLE_AUDIENCE_SYNC_CUSTOMER_ID","GOOGLE_AUDIENCE_SYNC_LOGIN_CUSTOMER_ID","GOOGLE_AUDIENCE_SYNC_USER_LIST_ID","LINKEDIN_AUDIENCE_SYNC_ACCESS_TOKEN","LINKEDIN_AUDIENCE_SYNC_SEGMENT_ID","REQUIRED","digits","readAdAudienceConfig","name","missing","Object","fromEntries","loginCustomerId","accessToken","audienceId","clientId","clientSecret","refreshToken","customerId","userListId","segmentId","META_GRAPH_VERSION","META_REPLACE_BATCH","buildMetaReplaceRequests","config","hashes","sessionId","batches","batch","method","url","encodeURIComponent","headers","body","payload","schema","data","session","session_id","batch_seq","last_batch_flag","estimated_num_total","access_token","GOOGLE_TOKEN_URL","GOOGLE_DATA_MANAGER_BASE","GOOGLE_MEMBERS_BATCH","buildGoogleTokenRequest","URLSearchParams","grant_type","client_id","client_secret","refresh_token","toString","buildGoogleMemberRequests","action","destination","operatingAccount","accountType","accountId","loginAccount","productDestinationId","Authorization","destinations","audienceMembers","userData","userIdentifiers","emailAddress","encoding","termsOfService","customerMatchTermsOfServiceStatus","LINKEDIN_VERSION","LINKEDIN_USERS_BATCH","buildLinkedInUserRequests","elements","userIds","idType","idValue","linkedInRefusedCount","answer","Array","isArray","element","status","Number"],"mappings":"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"}

package/src/lib/server/consent-by-address.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A person's consent as their CONTACT records it, read by address.
+ *
+ * Three surfaces ask this, and they must get one answer:
+ *
+ *  - the list gate (`email/list-members-preview` and `-add`), deciding
+ *    whether an address can be enrolled and on what basis;
+ *  - `performCampaignSend`, for a list member a rule enrolled — the
+ *    materializer writes no basis onto those rows, because matching a rule is
+ *    not an opt-in, so the person's real basis is the one on their contact;
+ *  - the list's Consent column, which shows what the send will act on.
+ *
+ * A copy per surface agrees only until the shape moves, which is how the
+ * Consent column once reported every member as having no basis while the
+ * sender mailed them.
+ */
+import type { ConsentGroup } from '@aglyn/aglyn/app-utils/consent-groups';
+import { type MarketingConsentRecord } from '@aglyn/aglyn/app-utils/marketing-consent';
+/** Addresses per `in` query — Firestore's disjunction limit. */
+export declare const CONTACT_LOOKUP_CHUNK = 30;
+/**
+ * The stored consent facts for these addresses, off the org's contacts.
+ *
+ * Read UNSCOPED, deliberately, exactly as the Inbox route reads it:
+ * `scopedToHost` narrows an org collection to what one site may see, and a
+ * refusal filtered out by that narrowing is a refusal the caller would then
+ * step over — the failure mode is mailing or enrolling somebody who said no.
+ * A grant cannot leak across sites through this read either: the record is
+ * read for `group`, so another site's opt-in answers `otherGrant`, never
+ * `granted`. Callers serving a browser must still prove the requester is an
+ * org-wide member, which is the tier the rules grant the whole org's
+ * contacts to.
+ *
+ * ## A refusal wins over an opt-in when the CRM holds both
+ *
+ * Nothing guarantees one contact per address — the collection is keyed by
+ * resource id, not by email — so two records for one person can disagree.
+ * Taking whichever the query happened to answer first would make the outcome
+ * depend on document order. A recorded refusal is the answer whenever one
+ * exists, which is the same precedence `assignmentBasis` applies within a
+ * single record.
+ *
+ * ## A refusal outlives the contact it was written on (AGL-3338)
+ *
+ * Deleting a contact keeps every refusal it held in the org's retained store,
+ * so the address is read with what was retained laid over whatever record is
+ * left — `withRetainedRefusals` — and an address with no contact at all still
+ * reads `declined` when its person said no. A grant given after the refusal,
+ * on a contact the person signed up again through, is the person changing
+ * their mind and reads `granted`. The grants carried onto a membership come
+ * off the same merged record.
+ *
+ * A failed read falls to `declined` for the whole batch: a read that throws
+ * can neither say the person consented nor that they refused, and the
+ * direction that costs a retry is the one that does not reach somebody whose
+ * stored refusal we simply failed to see. The retained store is read the
+ * same way, and fails the same way.
+ *
+ * @param contacts the org's contacts collection
+ *                 (`orgDataCollectionForHost(hostId, 'contacts')`), passed
+ *                 as the pending lookup so a failure to resolve it reads as
+ *                 the same `declined` as a failed query.
+ * @param addresses normalized addresses (`normalizeContactEmail`).
+ */
+export declare function readContactConsent(contacts: FirebaseFirestore.CollectionReference | Promise<FirebaseFirestore.CollectionReference>, group: ConsentGroup, addresses: readonly string[]): Promise<{
+    stored: Map<string, MarketingConsentRecord>;
+    grants: Map<string, Record<string, Record<string, unknown>>>;
+}>;
+/**
+ * Lays each rule-enrolled member's contact basis over the basis its row
+ * carries, where the row carries none.
+ *
+ * A row the dynamic-list materializer wrote (`via: 'rule'`) never holds a
+ * basis of its own — see the ⛔ in `dynamic-list-materialize.ts` — so for
+ * those rows the person's contact is the record. Only an `unrecorded` row
+ * is filled: a basis stored on the membership (an attestation, an opt-in an
+ * automation carried, a refusal) is a fact about that membership and stays
+ * the answer. Rows enrolled any other way are untouched.
+ *
+ * @param contacts as for {@link readContactConsent}.
+ * @param records the members' own records, keyed by normalized address;
+ *                updated in place.
+ * @param ruleMembers the normalized addresses of the `via: 'rule'` rows.
+ */
+export declare function withContactConsentForRuleMembers(contacts: FirebaseFirestore.CollectionReference | Promise<FirebaseFirestore.CollectionReference>, group: ConsentGroup, records: Map<string, MarketingConsentRecord>, ruleMembers: ReadonlySet<string>): Promise<Map<string, MarketingConsentRecord>>;