@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/billing-addons.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @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 { resolveOrgEntitlements, type OrgPlan, type OrgSeatAddons } from '@aglyn/aglyn/server';
+/**
+ * Self-serve add-on price map (AGL-525): the bridge between
+ * `STRIPE_PRICE_*` env price ids, `org.seatAddons` keys, and
+ * `PLAN_PRICING` USD amounts. Add-ons bill as extra items on the org's
+ * one subscription, so every kind has a monthly and a yearly price
+ * (Stripe allows a single interval per subscription; annual orgs attach
+ * the `_YEARLY` variants). Seat/member/dataset/host prices and the Aglyn AI
+ * add-on (AGL-2896) are per-plan; POS registers and the Event Calendar are
+ * flat. Prices are minted by `tools/scripts/setup-stripe.mjs` — keep the
+ * three in sync.
+ */
+export type AddonKind = keyof Required<OrgSeatAddons>;
+export declare const ADDON_KINDS: readonly AddonKind[];
+export type BillingInterval = 'month' | 'year';
+/**
+ * Every plan that is sold with a Stripe price — DERIVED, never hand-listed
+ * (AGL-1340).
+ *
+ * The literal that used to sit here listed starter, pro, business and
+ * advanced only — it predated the Scale and Agency tiers, so
+ * `addonKindFromPriceId()` could not recognise a single Scale/Agency add-on
+ * price coming back from Stripe. `addonPriceId()` still SOLD them (it only
+ * uppercases the plan), so the money moved and the read-back returned
+ * nothing: the webhook wrote `seatAddons: {all zeros}` for the
+ * highest-paying orgs on the next subscription event, and `seatAddons` is an
+ * ENTITLEMENT INPUT (`plan-entitlements.ts` — it raises `hostLimit` and
+ * `posRegisters`, and flips the `eventCalendar` feature).
+ *
+ * Deriving from `SELF_SERVE_PLANS` is what stops the next tier from
+ * reintroducing it: `free` has nothing to sell and `enterprise` is quoted
+ * per deal (no `STRIPE_PRICE_ENTERPRISE_*` exists), so everything else is
+ * by definition a paid, priced plan.
+ */
+export declare const PAID_PLANS: readonly OrgPlan[];
+/**
+ * The Stripe price id for an add-on kind on a plan at a billing interval;
+ * null when the plan doesn't sell it (free) or the env isn't configured.
+ */
+export declare function addonPriceId(kind: AddonKind, plan: OrgPlan, interval: BillingInterval): string | null;
+/**
+ * Reverse map: which add-on kind a subscription item's price id sells.
+ * Null for non-add-on prices (the base plan item, unknown prices).
+ */
+export declare function addonKindFromPriceId(priceId: string | null | undefined): AddonKind | null;
+/**
+ * The BASE plan's Stripe price id at an interval
+ * (`STRIPE_PRICE_{PLAN}[_YEARLY]`); null for `free`, for the custom-priced
+ * `enterprise`, and for an env that isn't configured. Read at call time, so
+ * it never freezes a stale value at module load the way the routes'
+ * `PRICE_ENV` maps do.
+ */
+export declare function planPriceId(plan: OrgPlan, interval: BillingInterval): string | null;
+/**
+ * Which plan a subscription item's price sells AND on which interval; null for
+ * an add-on price, the metered price, an ad-hoc enterprise price, and anything
+ * unknown.
+ *
+ * The interval half exists because a schedule phase read back from Stripe
+ * carries price IDS and nothing else (AGL-2150): rebuilding that phase's item
+ * list needs to know which interval it is priced on, and guessing it from the
+ * live subscription is wrong exactly when the pending change is also an
+ * interval change.
+ */
+export declare function planAndIntervalFromPriceId(priceId: string | null | undefined): {
+    plan: OrgPlan;
+    interval: BillingInterval;
+} | null;
+/**
+ * Which plan a subscription item's price sells; null for an add-on price,
+ * the metered price, an ad-hoc enterprise price, and anything unknown.
+ */
+export declare function planFromPriceId(priceId: string | null | undefined): OrgPlan | null;
+/**
+ * The shared metered-usage price (AGL-635) that makes reported usage
+ * billable, for a given billing interval.
+ *
+ * Stripe rejects a subscription whose items mix `recurring.interval`, so the
+ * metered item has to recur the same way the plan does. There are two prices
+ * — `aglyn_metered_usage` (monthly) and `aglyn_metered_usage_yearly` — and
+ * both bill $0.01 per aggregated unit against the SAME meter, because the
+ * rollup posts an already-computed value in CENTS. The interval is therefore
+ * the only thing that differs, and it is the only thing a caller must get
+ * right.
+ *
+ * `interval` is REQUIRED on purpose (AGL-1280). It used to be monthly-only
+ * with no argument, so the failure mode of forgetting it was attaching a
+ * monthly price to a yearly subscription — the exact mixed-interval crash
+ * this signature now makes unrepresentable. A default would hand that
+ * footgun straight back.
+ */
+export declare function meteredPriceId(interval: 'month' | 'year'): string | null;
+/**
+ * Whether a price id is EITHER shared metered-usage price.
+ *
+ * Interval-agnostic by design: callers ask this to exclude the metered item
+ * from plan/add-on reasoning, and an annual subscription's metered item must
+ * be excluded just as thoroughly as a monthly one.
+ */
+export declare function isMeteredPriceId(priceId: string | null | undefined): boolean;
+/**
+ * The subscription's BASE PLAN item, identified POSITIVELY (AGL-1340).
+ *
+ * This used to be "whatever no add-on price claims" — identification by
+ * elimination, which quietly returns the wrong item the moment a
+ * subscription carries anything the add-on map doesn't recognise: the
+ * metered item, a grandfathered v1 price, a coupon-era SKU, an item added
+ * by hand in the Stripe dashboard. Picking an add-on item as the plan item
+ * means a plan switch re-prices the ADD-ON, and reads the billing interval
+ * off it.
+ *
+ * So: match a known `STRIPE_PRICE_{PLAN}[_YEARLY]` first. Only when nothing
+ * matches — an enterprise deal bills on an ad-hoc price, and grandfathered
+ * subscriptions predate the current SKUs — fall back to the old rule,
+ * minus the metered item, and finally to `items[0]` so behaviour for those
+ * subscriptions is unchanged.
+ */
+export declare function findPlanItem<T extends {
+    price?: {
+        id?: string;
+    } | null;
+}>(items: readonly T[] | null | undefined): T | null;
+/**
+ * Monthly USD per unit for an add-on on a plan (yearly prices are ×12 of
+ * this); null when the plan doesn't sell the kind. Single pricing source
+ * of truth: `PLAN_PRICING` + the two flat add-on constants.
+ */
+export declare function addonUnitUsd(kind: AddonKind, plan: OrgPlan): number | null;
+/**
+ * Full add-on quantity map (explicit zeros for absent kinds) from a
+ * subscription's items — the shape written to `org.seatAddons` so
+ * removals and dashboard edits converge on sync (AGL-527).
+ */
+export declare function addonQuantitiesFromItems(items: Array<{
+    price?: {
+        id?: string;
+    } | null;
+    quantity?: number | null;
+}> | null | undefined): Record<AddonKind, number>;
+/**
+ * Max purchasable quantity per kind, from a purchases-free entitlement
+ * resolution (plan defaults + staff overrides only) so the ceiling does not
+ * drift as the org buys: seat/dataset kinds stop at the plan's hard max,
+ * hosts/registers use flat ceilings, the Event Calendar and Aglyn AI are 0/1
+ * toggles. POS registers additionally require the `pos` feature.
+ *
+ * Lives here rather than inside `/api/billing/addons` because a PLAN CHANGE
+ * needs the same ceiling for a different plan. The addons route asks "how many
+ * may this org buy on the plan it is on"; `buildTargetItems` asks "how many of
+ * what it already bought can the plan it is moving to actually deliver". Two
+ * readers, one definition — a second copy is how they answer differently.
+ */
+export declare function addonMaxForBaseline(kind: AddonKind, baseline: ReturnType<typeof resolveOrgEntitlements>): number;
+/** The ceiling a PLAN would impose on an add-on kind, purchases excluded. */
+export declare function addonMaxForPlan(kind: AddonKind, plan: OrgPlan): number;

package/src/lib/server/billing-addons.js

@@ -0,0 +1,277 @@
+/**
+ * @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 { EVENT_CALENDAR_ADDON_MONTHLY_USD, EXTRA_HOSTS_ADDON_MAX, PLAN_PRICING, POS_REGISTER_ADDON_MONTHLY_USD, POS_REGISTERS_ADDON_MAX, resolveOrgEntitlements, SELF_SERVE_PLANS, UNLIMITED } from "@aglyn/aglyn/server";
+export const ADDON_KINDS = [
+    'managers',
+    'members',
+    'datasets',
+    'hosts',
+    'posRegisters',
+    'eventCalendar',
+    'aiAddon'
+];
+/** Kinds priced per plan (env `STRIPE_PRICE_{PLAN}_{SUFFIX}[_YEARLY]`). */ const PER_PLAN_ENV_SUFFIX = {
+    managers: 'EXTRA_SEAT',
+    members: 'EXTRA_MEMBER',
+    datasets: 'EXTRA_DATASET',
+    hosts: 'EXTRA_HOST',
+    aiAddon: 'AI_ADDON'
+};
+/** Kinds priced flat across plans (env `STRIPE_PRICE_{SUFFIX}[_YEARLY]`). */ const FLAT_ENV_NAME = {
+    posRegisters: 'POS_REGISTER',
+    eventCalendar: 'EVENT_CALENDAR'
+};
+/**
+ * Every plan that is sold with a Stripe price — DERIVED, never hand-listed
+ * (AGL-1340).
+ *
+ * The literal that used to sit here listed starter, pro, business and
+ * advanced only — it predated the Scale and Agency tiers, so
+ * `addonKindFromPriceId()` could not recognise a single Scale/Agency add-on
+ * price coming back from Stripe. `addonPriceId()` still SOLD them (it only
+ * uppercases the plan), so the money moved and the read-back returned
+ * nothing: the webhook wrote `seatAddons: {all zeros}` for the
+ * highest-paying orgs on the next subscription event, and `seatAddons` is an
+ * ENTITLEMENT INPUT (`plan-entitlements.ts` — it raises `hostLimit` and
+ * `posRegisters`, and flips the `eventCalendar` feature).
+ *
+ * Deriving from `SELF_SERVE_PLANS` is what stops the next tier from
+ * reintroducing it: `free` has nothing to sell and `enterprise` is quoted
+ * per deal (no `STRIPE_PRICE_ENTERPRISE_*` exists), so everything else is
+ * by definition a paid, priced plan.
+ */ export const PAID_PLANS = SELF_SERVE_PLANS.filter((plan)=>plan !== 'free');
+function env(name) {
+    const value = process.env[name];
+    return value ? value : null;
+}
+/**
+ * The Stripe price id for an add-on kind on a plan at a billing interval;
+ * null when the plan doesn't sell it (free) or the env isn't configured.
+ */ export function addonPriceId(kind, plan, interval) {
+    const yearly = interval === 'year' ? '_YEARLY' : '';
+    const flat = FLAT_ENV_NAME[kind];
+    if (flat) return env(`STRIPE_PRICE_${flat}${yearly}`);
+    const suffix = PER_PLAN_ENV_SUFFIX[kind];
+    if (!suffix || plan === 'free') return null;
+    return env(`STRIPE_PRICE_${plan.toUpperCase()}_${suffix}${yearly}`);
+}
+/**
+ * Reverse map: which add-on kind a subscription item's price id sells.
+ * Null for non-add-on prices (the base plan item, unknown prices).
+ */ export function addonKindFromPriceId(priceId) {
+    if (!priceId) return null;
+    for (const kind of ADDON_KINDS){
+        for (const interval of [
+            'month',
+            'year'
+        ]){
+            if (FLAT_ENV_NAME[kind]) {
+                if (addonPriceId(kind, 'starter', interval) === priceId) return kind;
+                continue;
+            }
+            for (const plan of PAID_PLANS){
+                if (addonPriceId(kind, plan, interval) === priceId) return kind;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The BASE plan's Stripe price id at an interval
+ * (`STRIPE_PRICE_{PLAN}[_YEARLY]`); null for `free`, for the custom-priced
+ * `enterprise`, and for an env that isn't configured. Read at call time, so
+ * it never freezes a stale value at module load the way the routes'
+ * `PRICE_ENV` maps do.
+ */ export function planPriceId(plan, interval) {
+    if (!PAID_PLANS.includes(plan)) return null;
+    const yearly = interval === 'year' ? '_YEARLY' : '';
+    return env(`STRIPE_PRICE_${plan.toUpperCase()}${yearly}`);
+}
+/**
+ * Which plan a subscription item's price sells AND on which interval; null for
+ * an add-on price, the metered price, an ad-hoc enterprise price, and anything
+ * unknown.
+ *
+ * The interval half exists because a schedule phase read back from Stripe
+ * carries price IDS and nothing else (AGL-2150): rebuilding that phase's item
+ * list needs to know which interval it is priced on, and guessing it from the
+ * live subscription is wrong exactly when the pending change is also an
+ * interval change.
+ */ export function planAndIntervalFromPriceId(priceId) {
+    if (!priceId) return null;
+    for (const plan of PAID_PLANS){
+        for (const interval of [
+            'month',
+            'year'
+        ]){
+            if (planPriceId(plan, interval) === priceId) return {
+                plan,
+                interval
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Which plan a subscription item's price sells; null for an add-on price,
+ * the metered price, an ad-hoc enterprise price, and anything unknown.
+ */ export function planFromPriceId(priceId) {
+    var _ref;
+    var _planAndIntervalFromPriceId;
+    return (_ref = (_planAndIntervalFromPriceId = planAndIntervalFromPriceId(priceId)) == null ? void 0 : _planAndIntervalFromPriceId.plan) != null ? _ref : null;
+}
+/**
+ * The shared metered-usage price (AGL-635) that makes reported usage
+ * billable, for a given billing interval.
+ *
+ * Stripe rejects a subscription whose items mix `recurring.interval`, so the
+ * metered item has to recur the same way the plan does. There are two prices
+ * — `aglyn_metered_usage` (monthly) and `aglyn_metered_usage_yearly` — and
+ * both bill $0.01 per aggregated unit against the SAME meter, because the
+ * rollup posts an already-computed value in CENTS. The interval is therefore
+ * the only thing that differs, and it is the only thing a caller must get
+ * right.
+ *
+ * `interval` is REQUIRED on purpose (AGL-1280). It used to be monthly-only
+ * with no argument, so the failure mode of forgetting it was attaching a
+ * monthly price to a yearly subscription — the exact mixed-interval crash
+ * this signature now makes unrepresentable. A default would hand that
+ * footgun straight back.
+ */ export function meteredPriceId(interval) {
+    return env(interval === 'year' ? 'STRIPE_PRICE_METERED_YEARLY' : 'STRIPE_PRICE_METERED');
+}
+/**
+ * Whether a price id is EITHER shared metered-usage price.
+ *
+ * Interval-agnostic by design: callers ask this to exclude the metered item
+ * from plan/add-on reasoning, and an annual subscription's metered item must
+ * be excluded just as thoroughly as a monthly one.
+ */ export function isMeteredPriceId(priceId) {
+    if (!priceId) return false;
+    return priceId === meteredPriceId('month') || priceId === meteredPriceId('year');
+}
+/**
+ * The subscription's BASE PLAN item, identified POSITIVELY (AGL-1340).
+ *
+ * This used to be "whatever no add-on price claims" — identification by
+ * elimination, which quietly returns the wrong item the moment a
+ * subscription carries anything the add-on map doesn't recognise: the
+ * metered item, a grandfathered v1 price, a coupon-era SKU, an item added
+ * by hand in the Stripe dashboard. Picking an add-on item as the plan item
+ * means a plan switch re-prices the ADD-ON, and reads the billing interval
+ * off it.
+ *
+ * So: match a known `STRIPE_PRICE_{PLAN}[_YEARLY]` first. Only when nothing
+ * matches — an enterprise deal bills on an ad-hoc price, and grandfathered
+ * subscriptions predate the current SKUs — fall back to the old rule,
+ * minus the metered item, and finally to `items[0]` so behaviour for those
+ * subscriptions is unchanged.
+ */ export function findPlanItem(items) {
+    var _ref;
+    const list = items != null ? items : [];
+    const byPlanPrice = list.find((item)=>{
+        var _item_price;
+        return planFromPriceId(item == null ? void 0 : (_item_price = item.price) == null ? void 0 : _item_price.id);
+    });
+    if (byPlanPrice) return byPlanPrice;
+    const notAnAddon = list.find((item)=>{
+        var _item_price, _item_price1;
+        return !addonKindFromPriceId(item == null ? void 0 : (_item_price = item.price) == null ? void 0 : _item_price.id) && !isMeteredPriceId(item == null ? void 0 : (_item_price1 = item.price) == null ? void 0 : _item_price1.id);
+    });
+    return (_ref = notAnAddon != null ? notAnAddon : list[0]) != null ? _ref : null;
+}
+/**
+ * Monthly USD per unit for an add-on on a plan (yearly prices are ×12 of
+ * this); null when the plan doesn't sell the kind. Single pricing source
+ * of truth: `PLAN_PRICING` + the two flat add-on constants.
+ */ export function addonUnitUsd(kind, plan) {
+    const pricing = PLAN_PRICING[plan];
+    switch(kind){
+        case 'managers':
+            return pricing.extraSeatMonthlyUsd;
+        case 'members':
+            return pricing.extraCollaboratorMonthlyUsd;
+        case 'datasets':
+            return pricing.extraDatasetMonthlyUsd;
+        case 'hosts':
+            return pricing.extraHostMonthlyUsd;
+        case 'posRegisters':
+            return POS_REGISTER_ADDON_MONTHLY_USD;
+        case 'eventCalendar':
+            return EVENT_CALENDAR_ADDON_MONTHLY_USD;
+        case 'aiAddon':
+            return pricing.aiAddonMonthlyUsd;
+    }
+}
+/**
+ * Full add-on quantity map (explicit zeros for absent kinds) from a
+ * subscription's items — the shape written to `org.seatAddons` so
+ * removals and dashboard edits converge on sync (AGL-527).
+ */ export function addonQuantitiesFromItems(items) {
+    const quantities = Object.fromEntries(ADDON_KINDS.map((kind)=>[
+            kind,
+            0
+        ]));
+    for (const item of items != null ? items : []){
+        var _item_price;
+        const kind = addonKindFromPriceId(item == null ? void 0 : (_item_price = item.price) == null ? void 0 : _item_price.id);
+        if (kind) {
+            var _ref;
+            quantities[kind] += Math.max(0, Math.floor(Number((_ref = item == null ? void 0 : item.quantity) != null ? _ref : 0)));
+        }
+    }
+    return quantities;
+}
+/**
+ * Max purchasable quantity per kind, from a purchases-free entitlement
+ * resolution (plan defaults + staff overrides only) so the ceiling does not
+ * drift as the org buys: seat/dataset kinds stop at the plan's hard max,
+ * hosts/registers use flat ceilings, the Event Calendar and Aglyn AI are 0/1
+ * toggles. POS registers additionally require the `pos` feature.
+ *
+ * Lives here rather than inside `/api/billing/addons` because a PLAN CHANGE
+ * needs the same ceiling for a different plan. The addons route asks "how many
+ * may this org buy on the plan it is on"; `buildTargetItems` asks "how many of
+ * what it already bought can the plan it is moving to actually deliver". Two
+ * readers, one definition — a second copy is how they answer differently.
+ */ export function addonMaxForBaseline(kind, baseline) {
+    const bounded = (included, max)=>Number.isFinite(max) ? Math.max(0, max - included) : EXTRA_HOSTS_ADDON_MAX;
+    switch(kind){
+        case 'managers':
+            return bounded(baseline.managersPerOrg, baseline.maxManagersPerOrg);
+        case 'members':
+            return bounded(baseline.membersPerHost, baseline.maxMembersPerHost);
+        case 'datasets':
+            return bounded(baseline.datasetsPerOrg, baseline.maxDatasetsPerOrg);
+        case 'hosts':
+            return baseline.hostLimit === UNLIMITED ? 0 : EXTRA_HOSTS_ADDON_MAX;
+        case 'posRegisters':
+            return baseline.features.pos ? POS_REGISTERS_ADDON_MAX : 0;
+        case 'eventCalendar':
+            return 1;
+        case 'aiAddon':
+            // Org-wide like the Event Calendar: one purchase, and the price map
+            // (null on Free and Enterprise) says whether the plan sells it at all.
+            return 1;
+    }
+}
+/** The ceiling a PLAN would impose on an add-on kind, purchases excluded. */ export function addonMaxForPlan(kind, plan) {
+    return addonMaxForBaseline(kind, resolveOrgEntitlements({
+        plan
+    }));
+}
+
+//# sourceMappingURL=billing-addons.js.map

package/src/lib/server/billing-addons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/billing-addons.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 {\n  EVENT_CALENDAR_ADDON_MONTHLY_USD,\n  EXTRA_HOSTS_ADDON_MAX,\n  PLAN_PRICING,\n  POS_REGISTER_ADDON_MONTHLY_USD,\n  POS_REGISTERS_ADDON_MAX,\n  resolveOrgEntitlements,\n  SELF_SERVE_PLANS,\n  UNLIMITED,\n  type OrgPlan,\n  type OrgSeatAddons,\n} from '@aglyn/aglyn/server'\n\n/**\n * Self-serve add-on price map (AGL-525): the bridge between\n * `STRIPE_PRICE_*` env price ids, `org.seatAddons` keys, and\n * `PLAN_PRICING` USD amounts. Add-ons bill as extra items on the org's\n * one subscription, so every kind has a monthly and a yearly price\n * (Stripe allows a single interval per subscription; annual orgs attach\n * the `_YEARLY` variants). Seat/member/dataset/host prices and the Aglyn AI\n * add-on (AGL-2896) are per-plan; POS registers and the Event Calendar are\n * flat. Prices are minted by `tools/scripts/setup-stripe.mjs` — keep the\n * three in sync.\n */\nexport type AddonKind = keyof Required<OrgSeatAddons>\n\nexport const ADDON_KINDS: readonly AddonKind[] = [\n  'managers',\n  'members',\n  'datasets',\n  'hosts',\n  'posRegisters',\n  'eventCalendar',\n  'aiAddon',\n]\n\nexport type BillingInterval = 'month' | 'year'\n\n/** Kinds priced per plan (env `STRIPE_PRICE_{PLAN}_{SUFFIX}[_YEARLY]`). */\nconst PER_PLAN_ENV_SUFFIX: Partial<Record<AddonKind, string>> = {\n  managers: 'EXTRA_SEAT',\n  members: 'EXTRA_MEMBER',\n  datasets: 'EXTRA_DATASET',\n  hosts: 'EXTRA_HOST',\n  aiAddon: 'AI_ADDON',\n}\n\n/** Kinds priced flat across plans (env `STRIPE_PRICE_{SUFFIX}[_YEARLY]`). */\nconst FLAT_ENV_NAME: Partial<Record<AddonKind, string>> = {\n  posRegisters: 'POS_REGISTER',\n  eventCalendar: 'EVENT_CALENDAR',\n}\n\n/**\n * Every plan that is sold with a Stripe price — DERIVED, never hand-listed\n * (AGL-1340).\n *\n * The literal that used to sit here listed starter, pro, business and\n * advanced only — it predated the Scale and Agency tiers, so\n * `addonKindFromPriceId()` could not recognise a single Scale/Agency add-on\n * price coming back from Stripe. `addonPriceId()` still SOLD them (it only\n * uppercases the plan), so the money moved and the read-back returned\n * nothing: the webhook wrote `seatAddons: {all zeros}` for the\n * highest-paying orgs on the next subscription event, and `seatAddons` is an\n * ENTITLEMENT INPUT (`plan-entitlements.ts` — it raises `hostLimit` and\n * `posRegisters`, and flips the `eventCalendar` feature).\n *\n * Deriving from `SELF_SERVE_PLANS` is what stops the next tier from\n * reintroducing it: `free` has nothing to sell and `enterprise` is quoted\n * per deal (no `STRIPE_PRICE_ENTERPRISE_*` exists), so everything else is\n * by definition a paid, priced plan.\n */\nexport const PAID_PLANS: readonly OrgPlan[] = SELF_SERVE_PLANS.filter(\n  (plan) => plan !== 'free',\n)\n\nfunction env(name: string): string | null {\n  const value = process.env[name]\n  return value ? value : null\n}\n\n/**\n * The Stripe price id for an add-on kind on a plan at a billing interval;\n * null when the plan doesn't sell it (free) or the env isn't configured.\n */\nexport function addonPriceId(\n  kind: AddonKind,\n  plan: OrgPlan,\n  interval: BillingInterval,\n): string | null {\n  const yearly = interval === 'year' ? '_YEARLY' : ''\n  const flat = FLAT_ENV_NAME[kind]\n  if (flat) return env(`STRIPE_PRICE_${flat}${yearly}`)\n  const suffix = PER_PLAN_ENV_SUFFIX[kind]\n  if (!suffix || plan === 'free') return null\n  return env(`STRIPE_PRICE_${plan.toUpperCase()}_${suffix}${yearly}`)\n}\n\n/**\n * Reverse map: which add-on kind a subscription item's price id sells.\n * Null for non-add-on prices (the base plan item, unknown prices).\n */\nexport function addonKindFromPriceId(\n  priceId: string | null | undefined,\n): AddonKind | null {\n  if (!priceId) return null\n  for (const kind of ADDON_KINDS) {\n    for (const interval of ['month', 'year'] as const) {\n      if (FLAT_ENV_NAME[kind]) {\n        if (addonPriceId(kind, 'starter', interval) === priceId) return kind\n        continue\n      }\n      for (const plan of PAID_PLANS) {\n        if (addonPriceId(kind, plan, interval) === priceId) return kind\n      }\n    }\n  }\n  return null\n}\n\n/**\n * The BASE plan's Stripe price id at an interval\n * (`STRIPE_PRICE_{PLAN}[_YEARLY]`); null for `free`, for the custom-priced\n * `enterprise`, and for an env that isn't configured. Read at call time, so\n * it never freezes a stale value at module load the way the routes'\n * `PRICE_ENV` maps do.\n */\nexport function planPriceId(\n  plan: OrgPlan,\n  interval: BillingInterval,\n): string | null {\n  if (!PAID_PLANS.includes(plan)) return null\n  const yearly = interval === 'year' ? '_YEARLY' : ''\n  return env(`STRIPE_PRICE_${plan.toUpperCase()}${yearly}`)\n}\n\n/**\n * Which plan a subscription item's price sells AND on which interval; null for\n * an add-on price, the metered price, an ad-hoc enterprise price, and anything\n * unknown.\n *\n * The interval half exists because a schedule phase read back from Stripe\n * carries price IDS and nothing else (AGL-2150): rebuilding that phase's item\n * list needs to know which interval it is priced on, and guessing it from the\n * live subscription is wrong exactly when the pending change is also an\n * interval change.\n */\nexport function planAndIntervalFromPriceId(\n  priceId: string | null | undefined,\n): { plan: OrgPlan; interval: BillingInterval } | null {\n  if (!priceId) return null\n  for (const plan of PAID_PLANS) {\n    for (const interval of ['month', 'year'] as const) {\n      if (planPriceId(plan, interval) === priceId) return { plan, interval }\n    }\n  }\n  return null\n}\n\n/**\n * Which plan a subscription item's price sells; null for an add-on price,\n * the metered price, an ad-hoc enterprise price, and anything unknown.\n */\nexport function planFromPriceId(\n  priceId: string | null | undefined,\n): OrgPlan | null {\n  return planAndIntervalFromPriceId(priceId)?.plan ?? null\n}\n\n/**\n * The shared metered-usage price (AGL-635) that makes reported usage\n * billable, for a given billing interval.\n *\n * Stripe rejects a subscription whose items mix `recurring.interval`, so the\n * metered item has to recur the same way the plan does. There are two prices\n * — `aglyn_metered_usage` (monthly) and `aglyn_metered_usage_yearly` — and\n * both bill $0.01 per aggregated unit against the SAME meter, because the\n * rollup posts an already-computed value in CENTS. The interval is therefore\n * the only thing that differs, and it is the only thing a caller must get\n * right.\n *\n * `interval` is REQUIRED on purpose (AGL-1280). It used to be monthly-only\n * with no argument, so the failure mode of forgetting it was attaching a\n * monthly price to a yearly subscription — the exact mixed-interval crash\n * this signature now makes unrepresentable. A default would hand that\n * footgun straight back.\n */\nexport function meteredPriceId(interval: 'month' | 'year'): string | null {\n  return env(\n    interval === 'year' ? 'STRIPE_PRICE_METERED_YEARLY' : 'STRIPE_PRICE_METERED',\n  )\n}\n\n/**\n * Whether a price id is EITHER shared metered-usage price.\n *\n * Interval-agnostic by design: callers ask this to exclude the metered item\n * from plan/add-on reasoning, and an annual subscription's metered item must\n * be excluded just as thoroughly as a monthly one.\n */\nexport function isMeteredPriceId(priceId: string | null | undefined): boolean {\n  if (!priceId) return false\n  return (\n    priceId === meteredPriceId('month') || priceId === meteredPriceId('year')\n  )\n}\n\n/**\n * The subscription's BASE PLAN item, identified POSITIVELY (AGL-1340).\n *\n * This used to be \"whatever no add-on price claims\" — identification by\n * elimination, which quietly returns the wrong item the moment a\n * subscription carries anything the add-on map doesn't recognise: the\n * metered item, a grandfathered v1 price, a coupon-era SKU, an item added\n * by hand in the Stripe dashboard. Picking an add-on item as the plan item\n * means a plan switch re-prices the ADD-ON, and reads the billing interval\n * off it.\n *\n * So: match a known `STRIPE_PRICE_{PLAN}[_YEARLY]` first. Only when nothing\n * matches — an enterprise deal bills on an ad-hoc price, and grandfathered\n * subscriptions predate the current SKUs — fall back to the old rule,\n * minus the metered item, and finally to `items[0]` so behaviour for those\n * subscriptions is unchanged.\n */\nexport function findPlanItem<T extends { price?: { id?: string } | null }>(\n  items: readonly T[] | null | undefined,\n): T | null {\n  const list = items ?? []\n  const byPlanPrice = list.find((item) => planFromPriceId(item?.price?.id))\n  if (byPlanPrice) return byPlanPrice\n  const notAnAddon = list.find(\n    (item) =>\n      !addonKindFromPriceId(item?.price?.id) &&\n      !isMeteredPriceId(item?.price?.id),\n  )\n  return notAnAddon ?? list[0] ?? null\n}\n\n/**\n * Monthly USD per unit for an add-on on a plan (yearly prices are ×12 of\n * this); null when the plan doesn't sell the kind. Single pricing source\n * of truth: `PLAN_PRICING` + the two flat add-on constants.\n */\nexport function addonUnitUsd(kind: AddonKind, plan: OrgPlan): number | null {\n  const pricing = PLAN_PRICING[plan]\n  switch (kind) {\n    case 'managers':\n      return pricing.extraSeatMonthlyUsd\n    case 'members':\n      return pricing.extraCollaboratorMonthlyUsd\n    case 'datasets':\n      return pricing.extraDatasetMonthlyUsd\n    case 'hosts':\n      return pricing.extraHostMonthlyUsd\n    case 'posRegisters':\n      return POS_REGISTER_ADDON_MONTHLY_USD\n    case 'eventCalendar':\n      return EVENT_CALENDAR_ADDON_MONTHLY_USD\n    case 'aiAddon':\n      return pricing.aiAddonMonthlyUsd\n  }\n}\n\n/**\n * Full add-on quantity map (explicit zeros for absent kinds) from a\n * subscription's items — the shape written to `org.seatAddons` so\n * removals and dashboard edits converge on sync (AGL-527).\n */\nexport function addonQuantitiesFromItems(\n  items:\n    | Array<{ price?: { id?: string } | null; quantity?: number | null }>\n    | null\n    | undefined,\n): Record<AddonKind, number> {\n  const quantities = Object.fromEntries(\n    ADDON_KINDS.map((kind) => [kind, 0]),\n  ) as Record<AddonKind, number>\n  for (const item of items ?? []) {\n    const kind = addonKindFromPriceId(item?.price?.id)\n    if (kind) {\n      quantities[kind] += Math.max(0, Math.floor(Number(item?.quantity ?? 0)))\n    }\n  }\n  return quantities\n}\n\n/**\n * Max purchasable quantity per kind, from a purchases-free entitlement\n * resolution (plan defaults + staff overrides only) so the ceiling does not\n * drift as the org buys: seat/dataset kinds stop at the plan's hard max,\n * hosts/registers use flat ceilings, the Event Calendar and Aglyn AI are 0/1\n * toggles. POS registers additionally require the `pos` feature.\n *\n * Lives here rather than inside `/api/billing/addons` because a PLAN CHANGE\n * needs the same ceiling for a different plan. The addons route asks \"how many\n * may this org buy on the plan it is on\"; `buildTargetItems` asks \"how many of\n * what it already bought can the plan it is moving to actually deliver\". Two\n * readers, one definition — a second copy is how they answer differently.\n */\nexport function addonMaxForBaseline(\n  kind: AddonKind,\n  baseline: ReturnType<typeof resolveOrgEntitlements>,\n): number {\n  const bounded = (included: number, max: number) =>\n    Number.isFinite(max) ? Math.max(0, max - included) : EXTRA_HOSTS_ADDON_MAX\n  switch (kind) {\n    case 'managers':\n      return bounded(baseline.managersPerOrg, baseline.maxManagersPerOrg)\n    case 'members':\n      return bounded(baseline.membersPerHost, baseline.maxMembersPerHost)\n    case 'datasets':\n      return bounded(baseline.datasetsPerOrg, baseline.maxDatasetsPerOrg)\n    case 'hosts':\n      return baseline.hostLimit === UNLIMITED ? 0 : EXTRA_HOSTS_ADDON_MAX\n    case 'posRegisters':\n      return baseline.features.pos ? POS_REGISTERS_ADDON_MAX : 0\n    case 'eventCalendar':\n      return 1\n    case 'aiAddon':\n      // Org-wide like the Event Calendar: one purchase, and the price map\n      // (null on Free and Enterprise) says whether the plan sells it at all.\n      return 1\n  }\n}\n\n/** The ceiling a PLAN would impose on an add-on kind, purchases excluded. */\nexport function addonMaxForPlan(kind: AddonKind, plan: OrgPlan): number {\n  return addonMaxForBaseline(kind, resolveOrgEntitlements({ plan } as never))\n}\n"],"names":["EVENT_CALENDAR_ADDON_MONTHLY_USD","EXTRA_HOSTS_ADDON_MAX","PLAN_PRICING","POS_REGISTER_ADDON_MONTHLY_USD","POS_REGISTERS_ADDON_MAX","resolveOrgEntitlements","SELF_SERVE_PLANS","UNLIMITED","ADDON_KINDS","PER_PLAN_ENV_SUFFIX","managers","members","datasets","hosts","aiAddon","FLAT_ENV_NAME","posRegisters","eventCalendar","PAID_PLANS","filter","plan","env","name","value","process","addonPriceId","kind","interval","yearly","flat","suffix","toUpperCase","addonKindFromPriceId","priceId","planPriceId","includes","planAndIntervalFromPriceId","planFromPriceId","meteredPriceId","isMeteredPriceId","findPlanItem","items","notAnAddon","list","byPlanPrice","find","item","price","id","addonUnitUsd","pricing","extraSeatMonthlyUsd","extraCollaboratorMonthlyUsd","extraDatasetMonthlyUsd","extraHostMonthlyUsd","aiAddonMonthlyUsd","addonQuantitiesFromItems","quantities","Object","fromEntries","map","Math","max","floor","Number","quantity","addonMaxForBaseline","baseline","bounded","included","isFinite","managersPerOrg","maxManagersPerOrg","membersPerHost","maxMembersPerHost","datasetsPerOrg","maxDatasetsPerOrg","hostLimit","features","pos","addonMaxForPlan"],"mappings":"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"}

package/src/lib/server/campaign-attribution-store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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.
+ */
+/** The per-host collection of conversion attribution records. */
+export declare const CAMPAIGN_ATTRIBUTIONS_COLLECTION = "campaignAttributions";
+/**
+ * Removes every conversion attributed to one person, across every site.
+ *
+ * ## Why an erasure reaches these at all
+ *
+ * An attribution is a claim about a person: "this human came from that
+ * campaign and then did this". It is the same personal fact as the click
+ * stamp it was derived from, and the erasure path already deletes those —
+ * `eraseEmailDeliveriesForAddresses` drops `campaignTouches` alongside the
+ * engagement stamps and says why. A summary that outlived its source would
+ * leave an erasure that removed the evidence and kept the conclusion.
+ *
+ * ## Why a collection-group query
+ *
+ * The record is per HOST, because that is where a site's own reporting reads
+ * it. An erasure arrives as an ADDRESS and knows nothing about which sites
+ * that person ever visited. The collection group is the join between the two,
+ * and `personKey` is on the record precisely so one exists — declared in
+ * `cloud/firebase-firestore.indexes.json` with `COLLECTION_GROUP` scope,
+ * because a collection-group query gets no automatic single-field index and
+ * would otherwise fail with FAILED_PRECONDITION at the moment somebody asked
+ * to be forgotten.
+ *
+ * ## The order's own record is NOT touched
+ *
+ * `emailAttributions` holds a commercial fact about a sale, keyed by the
+ * order's id and carrying no address — the revenue join says so where it
+ * writes it. This holds a record of a person's behavior under a key derived
+ * from their address. Different facts, different answers, and the split is
+ * why both are defensible.
+ *
+ * Never throws: an erasure that fails on one leg must still complete the
+ * others, and the caller reports what it removed.
+ *
+ * @returns how many records were removed.
+ */
+export declare function eraseCampaignAttributionsForPersonKey(key: string | null | undefined, firestore?: any): Promise<number>;

package/src/lib/server/campaign-attribution-store.js

@@ -0,0 +1,95 @@
+/**
+ * @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.
+ */ /**
+ * Where conversion attributions are kept, and how an erasure reaches them.
+ *
+ * ## Why this is a leaf module and not part of the join
+ *
+ * The erasure runs from `email-delivery-log.ts`, in the same function that
+ * drops a person's campaign touches — which is the point, because an
+ * attribution is a conclusion drawn from those touches and a conclusion that
+ * outlives its evidence is an erasure that did not happen. But the join
+ * itself READS that module (`readEmailCampaignTouch` is one half of the
+ * last-touch comparison), so putting the erasure beside the join would make
+ * the two modules import each other. Under jest that cycle resolves to
+ * `undefined` at import time rather than failing loudly, which is how an
+ * erasure comes to silently do nothing while its test passes.
+ *
+ * So the collection name and the sweep live here, importing nothing but
+ * Firestore, and both sides import this.
+ */ import firebaseAdmin from "./firebase-admin.js";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+/** The per-host collection of conversion attribution records. */ export const CAMPAIGN_ATTRIBUTIONS_COLLECTION = 'campaignAttributions';
+/** How many records one erasure pass removes per batch. */ const ERASURE_BATCH = 400;
+/**
+ * Removes every conversion attributed to one person, across every site.
+ *
+ * ## Why an erasure reaches these at all
+ *
+ * An attribution is a claim about a person: "this human came from that
+ * campaign and then did this". It is the same personal fact as the click
+ * stamp it was derived from, and the erasure path already deletes those —
+ * `eraseEmailDeliveriesForAddresses` drops `campaignTouches` alongside the
+ * engagement stamps and says why. A summary that outlived its source would
+ * leave an erasure that removed the evidence and kept the conclusion.
+ *
+ * ## Why a collection-group query
+ *
+ * The record is per HOST, because that is where a site's own reporting reads
+ * it. An erasure arrives as an ADDRESS and knows nothing about which sites
+ * that person ever visited. The collection group is the join between the two,
+ * and `personKey` is on the record precisely so one exists — declared in
+ * `cloud/firebase-firestore.indexes.json` with `COLLECTION_GROUP` scope,
+ * because a collection-group query gets no automatic single-field index and
+ * would otherwise fail with FAILED_PRECONDITION at the moment somebody asked
+ * to be forgotten.
+ *
+ * ## The order's own record is NOT touched
+ *
+ * `emailAttributions` holds a commercial fact about a sale, keyed by the
+ * order's id and carrying no address — the revenue join says so where it
+ * writes it. This holds a record of a person's behavior under a key derived
+ * from their address. Different facts, different answers, and the split is
+ * why both are defensible.
+ *
+ * Never throws: an erasure that fails on one leg must still complete the
+ * others, and the caller reports what it removed.
+ *
+ * @returns how many records were removed.
+ */ export async function eraseCampaignAttributionsForPersonKey(key, firestore) {
+    if (!key || typeof key !== 'string') return 0;
+    const db = firestore != null ? firestore : defaultFirestore();
+    let removed = 0;
+    try {
+        // Bounded rather than `while (true)`: a pathological volume must not be
+        // able to hold an erasure request open indefinitely, and the pass that
+        // runs next picks up whatever a bounded one left.
+        for(let pass = 0; pass < 20; pass += 1){
+            const snapshot = await db.collectionGroup(CAMPAIGN_ATTRIBUTIONS_COLLECTION).where('personKey', '==', key).limit(ERASURE_BATCH).get();
+            if (snapshot.empty) break;
+            const batch = db.batch();
+            snapshot.docs.forEach((doc)=>batch.delete(doc.ref));
+            await batch.commit();
+            removed += snapshot.size;
+            if (snapshot.size < ERASURE_BATCH) break;
+        }
+    } catch (error) {
+        console.error('eraseCampaignAttributionsForPersonKey failed', error);
+    }
+    return removed;
+}
+
+//# sourceMappingURL=campaign-attribution-store.js.map

package/src/lib/server/campaign-attribution-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/campaign-attribution-store.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\n/**\n * Where conversion attributions are kept, and how an erasure reaches them.\n *\n * ## Why this is a leaf module and not part of the join\n *\n * The erasure runs from `email-delivery-log.ts`, in the same function that\n * drops a person's campaign touches — which is the point, because an\n * attribution is a conclusion drawn from those touches and a conclusion that\n * outlives its evidence is an erasure that did not happen. But the join\n * itself READS that module (`readEmailCampaignTouch` is one half of the\n * last-touch comparison), so putting the erasure beside the join would make\n * the two modules import each other. Under jest that cycle resolves to\n * `undefined` at import time rather than failing loudly, which is how an\n * erasure comes to silently do nothing while its test passes.\n *\n * So the collection name and the sweep live here, importing nothing but\n * Firestore, and both sides import this.\n */\n\nimport firebaseAdmin from './firebase-admin'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/** The per-host collection of conversion attribution records. */\nexport const CAMPAIGN_ATTRIBUTIONS_COLLECTION = 'campaignAttributions'\n\n/** How many records one erasure pass removes per batch. */\nconst ERASURE_BATCH = 400\n\n/**\n * Removes every conversion attributed to one person, across every site.\n *\n * ## Why an erasure reaches these at all\n *\n * An attribution is a claim about a person: \"this human came from that\n * campaign and then did this\". It is the same personal fact as the click\n * stamp it was derived from, and the erasure path already deletes those —\n * `eraseEmailDeliveriesForAddresses` drops `campaignTouches` alongside the\n * engagement stamps and says why. A summary that outlived its source would\n * leave an erasure that removed the evidence and kept the conclusion.\n *\n * ## Why a collection-group query\n *\n * The record is per HOST, because that is where a site's own reporting reads\n * it. An erasure arrives as an ADDRESS and knows nothing about which sites\n * that person ever visited. The collection group is the join between the two,\n * and `personKey` is on the record precisely so one exists — declared in\n * `cloud/firebase-firestore.indexes.json` with `COLLECTION_GROUP` scope,\n * because a collection-group query gets no automatic single-field index and\n * would otherwise fail with FAILED_PRECONDITION at the moment somebody asked\n * to be forgotten.\n *\n * ## The order's own record is NOT touched\n *\n * `emailAttributions` holds a commercial fact about a sale, keyed by the\n * order's id and carrying no address — the revenue join says so where it\n * writes it. This holds a record of a person's behavior under a key derived\n * from their address. Different facts, different answers, and the split is\n * why both are defensible.\n *\n * Never throws: an erasure that fails on one leg must still complete the\n * others, and the caller reports what it removed.\n *\n * @returns how many records were removed.\n */\nexport async function eraseCampaignAttributionsForPersonKey(\n  key: string | null | undefined,\n  firestore?: any,\n): Promise<number> {\n  if (!key || typeof key !== 'string') return 0\n  const db = firestore ?? defaultFirestore()\n  let removed = 0\n  try {\n    // Bounded rather than `while (true)`: a pathological volume must not be\n    // able to hold an erasure request open indefinitely, and the pass that\n    // runs next picks up whatever a bounded one left.\n    for (let pass = 0; pass < 20; pass += 1) {\n      const snapshot = await db\n        .collectionGroup(CAMPAIGN_ATTRIBUTIONS_COLLECTION)\n        .where('personKey', '==', key)\n        .limit(ERASURE_BATCH)\n        .get()\n      if (snapshot.empty) break\n      const batch = db.batch()\n      snapshot.docs.forEach((doc: any) => batch.delete(doc.ref))\n      await batch.commit()\n      removed += snapshot.size\n      if (snapshot.size < ERASURE_BATCH) break\n    }\n  } catch (error) {\n    console.error('eraseCampaignAttributionsForPersonKey failed', error)\n  }\n  return removed\n}\n"],"names":["firebaseAdmin","defaultFirestore","app","firestore","CAMPAIGN_ATTRIBUTIONS_COLLECTION","ERASURE_BATCH","eraseCampaignAttributionsForPersonKey","key","db","removed","pass","snapshot","collectionGroup","where","limit","get","empty","batch","docs","forEach","doc","delete","ref","commit","size","error","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;CAiBC,GAED,OAAOA,mBAAmB,sBAAkB;AAE5C,MAAMC,mBAAmB,IAAMD,cAAcE,GAAG,GAAGC,SAAS;AAE5D,+DAA+D,GAC/D,OAAO,MAAMC,mCAAmC,uBAAsB;AAEtE,yDAAyD,GACzD,MAAMC,gBAAgB;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCC,GACD,OAAO,eAAeC,sCACpBC,GAA8B,EAC9BJ,SAAe;IAEf,IAAI,CAACI,OAAO,OAAOA,QAAQ,UAAU,OAAO;IAC5C,MAAMC,KAAKL,oBAAAA,YAAaF;IACxB,IAAIQ,UAAU;IACd,IAAI;QACF,wEAAwE;QACxE,uEAAuE;QACvE,kDAAkD;QAClD,IAAK,IAAIC,OAAO,GAAGA,OAAO,IAAIA,QAAQ,EAAG;YACvC,MAAMC,WAAW,MAAMH,GACpBI,eAAe,CAACR,kCAChBS,KAAK,CAAC,aAAa,MAAMN,KACzBO,KAAK,CAACT,eACNU,GAAG;YACN,IAAIJ,SAASK,KAAK,EAAE;YACpB,MAAMC,QAAQT,GAAGS,KAAK;YACtBN,SAASO,IAAI,CAACC,OAAO,CAAC,CAACC,MAAaH,MAAMI,MAAM,CAACD,IAAIE,GAAG;YACxD,MAAML,MAAMM,MAAM;YAClBd,WAAWE,SAASa,IAAI;YACxB,IAAIb,SAASa,IAAI,GAAGnB,eAAe;QACrC;IACF,EAAE,OAAOoB,OAAO;QACdC,QAAQD,KAAK,CAAC,gDAAgDA;IAChE;IACA,OAAOhB;AACT"}