@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/platform-ad-conversions.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @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.
+ */
+/**
+ * Google Ads conversions for Aglyn's own funnel — account created, and tier
+ * subscribed.
+ *
+ * ## Why these are their own tag and not a GA4 import
+ *
+ * An imported GA4 key event lands in Google Ads as a conversion ACTION but
+ * does not create a conversion GOAL, and only a goal can be selected for
+ * bidding or reporting. `Sign-ups` sat with a live action and no goal for a
+ * week: measured, and unusable. A conversion created against the Google tag
+ * makes the goal, which is why these labels exist at all.
+ *
+ * ## Configuration, and why nothing is hardcoded
+ *
+ * ⛔ No default id. `analyticsMayEmit()` is true for ANY production build,
+ * self-hosted ones included — so a hardcoded conversion id would have every
+ * operator's console reporting signups into Aglyn's ad account. Unset means
+ * unset: {@link platformAdConversionTarget} returns null and nothing fires,
+ * which is the only correct behaviour for a deployment that has no ad account.
+ *
+ * The console reads its GA measurement id from `NEXT_PUBLIC_FIREBASE_...` for
+ * the same reason; these follow that precedent.
+ *
+ * ⚠️ `process.env.NAME` is inlined at BUILD time by Next and never the bracket
+ * form, so these are fixed when the image is built rather than when it starts.
+ * An operator changing ad accounts rebuilds.
+ */
+/** The advertiser account, `AW-` and digits. */
+export declare const PLATFORM_ADS_CONVERSION_ID: string;
+/** The per-action labels, minted with each conversion action in Google Ads. */
+export declare const PLATFORM_ADS_SIGNUP_LABEL: string;
+export declare const PLATFORM_ADS_SUBSCRIBE_LABEL: string;
+export type PlatformAdConversion = 'signup' | 'subscribe';
+/**
+ * The `send_to` for a conversion, or `null` when this build has none.
+ *
+ * Both halves are required. A `send_to` of `AW-123/` — an id with an empty
+ * label — is not a no-op: gtag accepts it and reports against the account's
+ * default, so a half-configured deployment would file its signups under
+ * whatever conversion Google picks. Null is the honest answer.
+ */
+export declare function platformAdConversionTarget(kind: PlatformAdConversion): string | null;
+/**
+ * Report one conversion, if this build has one and this visitor allows it.
+ *
+ * `allowed` is PASSED IN rather than read here, deliberately. The consent
+ * verdict lives in the surface that resolved it — reaching back into that
+ * module from here would make an analytics helper import a consent engine, and
+ * would give this two reasons to fail. It is also how the caller stays
+ * testable without a stubbed consent record.
+ *
+ * ⚠️ There is no queueing and no retry. `gtag` is defined by the Analytics
+ * tag, so a conversion fired before the tag boots — or on a visitor who
+ * refused, where the tag never boots at all — is simply not sent. Retrying
+ * would mean holding a conversion for a visitor who has not consented to
+ * being measured, which is the wrong end of the trade.
+ *
+ * Returns whether anything was sent, so a caller can assert on it rather than
+ * on a spy for a global.
+ *
+ * `userData.email` is the enhanced-conversions half (AGL-2683). Set through
+ * `gtag('set', 'user_data', …)` immediately before the event, the tag
+ * normalizes and SHA-256-hashes the address in the browser and sends only the
+ * hash with the conversion ping, which lets Google Ads match the conversion to
+ * a signed-in user when the click cookie is gone — a sign-up finished from the
+ * verification email on another device, or on Safari after its seven-day cap.
+ * It rides the SAME three doors as the event: not allowed, no ad account, or
+ * no tag means nothing is set, and an absent or blank email sets nothing
+ * either. Nothing here reads identity on its own; the caller passes what it
+ * already holds, exactly as it passes the consent verdict.
+ */
+export declare function reportPlatformAdConversion(kind: PlatformAdConversion, allowed: boolean, options?: {
+    transactionId?: string;
+    userData?: {
+        email?: string | null;
+    };
+}): boolean;
+/**
+ * Where a checkout that has STARTED but not yet been reported is remembered.
+ *
+ * The subscribe conversion can only be reported from the browser — an Ads
+ * website conversion is matched to the ad click through the GCLID the tag
+ * holds, and no webhook has one. That put the only reporting moment on
+ * Stripe's `onComplete`, which a visitor can close the tab on: the money was
+ * spent, the customer subscribed, and the campaign shows nothing. A missed
+ * conversion is invisible, which is what makes it worth repairing.
+ *
+ * So the checkout marks itself pending when it opens, and the billing page
+ * reports on the next visit if it finds the mark and a live subscription. The
+ * customer always comes back — they are a customer now.
+ *
+ * ⚠️ Scoped to the org so a mark left by one workspace cannot report a
+ * conversion for another, and paired with a stable `transaction_id` so the
+ * belt and the braces cannot double count.
+ *
+ * `localStorage`, not `sessionStorage`: closing the tab is the case being
+ * repaired, and a session store is exactly what closing the tab clears.
+ */
+export declare const PLATFORM_SUBSCRIBE_PENDING_KEY = "aglyn:ads:subscribe-pending";
+/** Remember that this org opened checkout, so a lost tab is recoverable. */
+export declare function markSubscribeCheckoutPending(orgId: string): void;
+/** Whether this org has a checkout waiting to be reported. */
+export declare function subscribeCheckoutPending(orgId: string): boolean;
+/** Forget it, once reported — or once the org is no longer subscribing. */
+export declare function clearSubscribeCheckoutPending(): void;
+export default reportPlatformAdConversion;

package/src/lib/app-utils/platform-ad-conversions.js

@@ -0,0 +1,174 @@
+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.
+ */ /**
+ * Google Ads conversions for Aglyn's own funnel — account created, and tier
+ * subscribed.
+ *
+ * ## Why these are their own tag and not a GA4 import
+ *
+ * An imported GA4 key event lands in Google Ads as a conversion ACTION but
+ * does not create a conversion GOAL, and only a goal can be selected for
+ * bidding or reporting. `Sign-ups` sat with a live action and no goal for a
+ * week: measured, and unusable. A conversion created against the Google tag
+ * makes the goal, which is why these labels exist at all.
+ *
+ * ## Configuration, and why nothing is hardcoded
+ *
+ * ⛔ No default id. `analyticsMayEmit()` is true for ANY production build,
+ * self-hosted ones included — so a hardcoded conversion id would have every
+ * operator's console reporting signups into Aglyn's ad account. Unset means
+ * unset: {@link platformAdConversionTarget} returns null and nothing fires,
+ * which is the only correct behaviour for a deployment that has no ad account.
+ *
+ * The console reads its GA measurement id from `NEXT_PUBLIC_FIREBASE_...` for
+ * the same reason; these follow that precedent.
+ *
+ * ⚠️ `process.env.NAME` is inlined at BUILD time by Next and never the bracket
+ * form, so these are fixed when the image is built rather than when it starts.
+ * An operator changing ad accounts rebuilds.
+ */ /** The advertiser account, `AW-` and digits. */ export const PLATFORM_ADS_CONVERSION_ID = process.env.NEXT_PUBLIC_ADS_CONVERSION_ID || '';
+/** The per-action labels, minted with each conversion action in Google Ads. */ export const PLATFORM_ADS_SIGNUP_LABEL = process.env.NEXT_PUBLIC_ADS_SIGNUP_LABEL || '';
+export const PLATFORM_ADS_SUBSCRIBE_LABEL = process.env.NEXT_PUBLIC_ADS_SUBSCRIBE_LABEL || '';
+const LABELS = {
+    signup: PLATFORM_ADS_SIGNUP_LABEL,
+    subscribe: PLATFORM_ADS_SUBSCRIBE_LABEL
+};
+/**
+ * The `send_to` for a conversion, or `null` when this build has none.
+ *
+ * Both halves are required. A `send_to` of `AW-123/` — an id with an empty
+ * label — is not a no-op: gtag accepts it and reports against the account's
+ * default, so a half-configured deployment would file its signups under
+ * whatever conversion Google picks. Null is the honest answer.
+ */ export function platformAdConversionTarget(kind) {
+    const label = LABELS[kind];
+    if (!PLATFORM_ADS_CONVERSION_ID || !label) return null;
+    return `${PLATFORM_ADS_CONVERSION_ID}/${label}`;
+}
+/**
+ * Report one conversion, if this build has one and this visitor allows it.
+ *
+ * `allowed` is PASSED IN rather than read here, deliberately. The consent
+ * verdict lives in the surface that resolved it — reaching back into that
+ * module from here would make an analytics helper import a consent engine, and
+ * would give this two reasons to fail. It is also how the caller stays
+ * testable without a stubbed consent record.
+ *
+ * ⚠️ There is no queueing and no retry. `gtag` is defined by the Analytics
+ * tag, so a conversion fired before the tag boots — or on a visitor who
+ * refused, where the tag never boots at all — is simply not sent. Retrying
+ * would mean holding a conversion for a visitor who has not consented to
+ * being measured, which is the wrong end of the trade.
+ *
+ * Returns whether anything was sent, so a caller can assert on it rather than
+ * on a spy for a global.
+ *
+ * `userData.email` is the enhanced-conversions half (AGL-2683). Set through
+ * `gtag('set', 'user_data', …)` immediately before the event, the tag
+ * normalizes and SHA-256-hashes the address in the browser and sends only the
+ * hash with the conversion ping, which lets Google Ads match the conversion to
+ * a signed-in user when the click cookie is gone — a sign-up finished from the
+ * verification email on another device, or on Safari after its seven-day cap.
+ * It rides the SAME three doors as the event: not allowed, no ad account, or
+ * no tag means nothing is set, and an absent or blank email sets nothing
+ * either. Nothing here reads identity on its own; the caller passes what it
+ * already holds, exactly as it passes the consent verdict.
+ */ export function reportPlatformAdConversion(kind, allowed, options = {}) {
+    var _ref;
+    var _options_userData;
+    if (!allowed) return false;
+    const target = platformAdConversionTarget(kind);
+    if (!target) return false;
+    const scope = globalThis;
+    if (typeof scope.gtag !== 'function') return false;
+    // Enhanced conversions (AGL-2683): the address reaches the tag lower-cased
+    // and trimmed — gtag hashes it before anything leaves the browser. Set right
+    // before the event so it attaches to THIS conversion and cannot linger on a
+    // later, unrelated one.
+    const email = String((_ref = (_options_userData = options.userData) == null ? void 0 : _options_userData.email) != null ? _ref : '').trim().toLowerCase();
+    if (email) scope.gtag('set', 'user_data', {
+        email
+    });
+    /*
+   * `transaction_id` is what makes a conversion SAFE TO REPORT TWICE.
+   *
+   * Google Ads de-duplicates on it, so a caller no longer has to guarantee
+   * exactly-once delivery from the browser — which is a guarantee a browser
+   * cannot give. Without it, the only safe moment to report is the one the
+   * visitor might close the tab on, and a missed conversion is invisible: the
+   * money was spent, the customer converted, and the campaign shows nothing.
+   *
+   * ⚠️ It must be STABLE for the thing being counted, not per attempt. A fresh
+   * id on every call de-duplicates nothing and quietly restores the double
+   * count it exists to prevent.
+   */ scope.gtag('event', 'conversion', _extends({
+        send_to: target
+    }, options.transactionId ? {
+        transaction_id: options.transactionId
+    } : {}));
+    return true;
+}
+/**
+ * Where a checkout that has STARTED but not yet been reported is remembered.
+ *
+ * The subscribe conversion can only be reported from the browser — an Ads
+ * website conversion is matched to the ad click through the GCLID the tag
+ * holds, and no webhook has one. That put the only reporting moment on
+ * Stripe's `onComplete`, which a visitor can close the tab on: the money was
+ * spent, the customer subscribed, and the campaign shows nothing. A missed
+ * conversion is invisible, which is what makes it worth repairing.
+ *
+ * So the checkout marks itself pending when it opens, and the billing page
+ * reports on the next visit if it finds the mark and a live subscription. The
+ * customer always comes back — they are a customer now.
+ *
+ * ⚠️ Scoped to the org so a mark left by one workspace cannot report a
+ * conversion for another, and paired with a stable `transaction_id` so the
+ * belt and the braces cannot double count.
+ *
+ * `localStorage`, not `sessionStorage`: closing the tab is the case being
+ * repaired, and a session store is exactly what closing the tab clears.
+ */ export const PLATFORM_SUBSCRIBE_PENDING_KEY = 'aglyn:ads:subscribe-pending';
+/** Remember that this org opened checkout, so a lost tab is recoverable. */ export function markSubscribeCheckoutPending(orgId) {
+    if (!orgId || typeof window === 'undefined') return;
+    try {
+        window.localStorage.setItem(PLATFORM_SUBSCRIBE_PENDING_KEY, orgId);
+    } catch (unused) {
+    // Storage refused. The `onComplete` path still reports; only the repair
+    // for a closed tab is lost, which is where this started.
+    }
+}
+/** Whether this org has a checkout waiting to be reported. */ export function subscribeCheckoutPending(orgId) {
+    if (!orgId || typeof window === 'undefined') return false;
+    try {
+        return window.localStorage.getItem(PLATFORM_SUBSCRIBE_PENDING_KEY) === orgId;
+    } catch (unused) {
+        return false;
+    }
+}
+/** Forget it, once reported — or once the org is no longer subscribing. */ export function clearSubscribeCheckoutPending() {
+    if (typeof window === 'undefined') return;
+    try {
+        window.localStorage.removeItem(PLATFORM_SUBSCRIBE_PENDING_KEY);
+    } catch (unused) {
+    // A mark that cannot be cleared is re-reported, and `transaction_id`
+    // makes that harmless. This is the reason it is not optional.
+    }
+}
+export default reportPlatformAdConversion;
+
+//# sourceMappingURL=platform-ad-conversions.js.map

package/src/lib/app-utils/platform-ad-conversions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-ad-conversions.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 * Google Ads conversions for Aglyn's own funnel — account created, and tier\n * subscribed.\n *\n * ## Why these are their own tag and not a GA4 import\n *\n * An imported GA4 key event lands in Google Ads as a conversion ACTION but\n * does not create a conversion GOAL, and only a goal can be selected for\n * bidding or reporting. `Sign-ups` sat with a live action and no goal for a\n * week: measured, and unusable. A conversion created against the Google tag\n * makes the goal, which is why these labels exist at all.\n *\n * ## Configuration, and why nothing is hardcoded\n *\n * ⛔ No default id. `analyticsMayEmit()` is true for ANY production build,\n * self-hosted ones included — so a hardcoded conversion id would have every\n * operator's console reporting signups into Aglyn's ad account. Unset means\n * unset: {@link platformAdConversionTarget} returns null and nothing fires,\n * which is the only correct behaviour for a deployment that has no ad account.\n *\n * The console reads its GA measurement id from `NEXT_PUBLIC_FIREBASE_...` for\n * the same reason; these follow that precedent.\n *\n * ⚠️ `process.env.NAME` is inlined at BUILD time by Next and never the bracket\n * form, so these are fixed when the image is built rather than when it starts.\n * An operator changing ad accounts rebuilds.\n */\n\n/** The advertiser account, `AW-` and digits. */\nexport const PLATFORM_ADS_CONVERSION_ID =\n  process.env.NEXT_PUBLIC_ADS_CONVERSION_ID || ''\n\n/** The per-action labels, minted with each conversion action in Google Ads. */\nexport const PLATFORM_ADS_SIGNUP_LABEL =\n  process.env.NEXT_PUBLIC_ADS_SIGNUP_LABEL || ''\nexport const PLATFORM_ADS_SUBSCRIBE_LABEL =\n  process.env.NEXT_PUBLIC_ADS_SUBSCRIBE_LABEL || ''\n\nexport type PlatformAdConversion = 'signup' | 'subscribe'\n\nconst LABELS: Readonly<Record<PlatformAdConversion, string>> = {\n  signup: PLATFORM_ADS_SIGNUP_LABEL,\n  subscribe: PLATFORM_ADS_SUBSCRIBE_LABEL,\n}\n\n/**\n * The `send_to` for a conversion, or `null` when this build has none.\n *\n * Both halves are required. A `send_to` of `AW-123/` — an id with an empty\n * label — is not a no-op: gtag accepts it and reports against the account's\n * default, so a half-configured deployment would file its signups under\n * whatever conversion Google picks. Null is the honest answer.\n */\nexport function platformAdConversionTarget(\n  kind: PlatformAdConversion,\n): string | null {\n  const label = LABELS[kind]\n  if (!PLATFORM_ADS_CONVERSION_ID || !label) return null\n  return `${PLATFORM_ADS_CONVERSION_ID}/${label}`\n}\n\ninterface ConversionWindow {\n  gtag?: (...args: unknown[]) => void\n}\n\n/**\n * Report one conversion, if this build has one and this visitor allows it.\n *\n * `allowed` is PASSED IN rather than read here, deliberately. The consent\n * verdict lives in the surface that resolved it — reaching back into that\n * module from here would make an analytics helper import a consent engine, and\n * would give this two reasons to fail. It is also how the caller stays\n * testable without a stubbed consent record.\n *\n * ⚠️ There is no queueing and no retry. `gtag` is defined by the Analytics\n * tag, so a conversion fired before the tag boots — or on a visitor who\n * refused, where the tag never boots at all — is simply not sent. Retrying\n * would mean holding a conversion for a visitor who has not consented to\n * being measured, which is the wrong end of the trade.\n *\n * Returns whether anything was sent, so a caller can assert on it rather than\n * on a spy for a global.\n *\n * `userData.email` is the enhanced-conversions half (AGL-2683). Set through\n * `gtag('set', 'user_data', …)` immediately before the event, the tag\n * normalizes and SHA-256-hashes the address in the browser and sends only the\n * hash with the conversion ping, which lets Google Ads match the conversion to\n * a signed-in user when the click cookie is gone — a sign-up finished from the\n * verification email on another device, or on Safari after its seven-day cap.\n * It rides the SAME three doors as the event: not allowed, no ad account, or\n * no tag means nothing is set, and an absent or blank email sets nothing\n * either. Nothing here reads identity on its own; the caller passes what it\n * already holds, exactly as it passes the consent verdict.\n */\nexport function reportPlatformAdConversion(\n  kind: PlatformAdConversion,\n  allowed: boolean,\n  options: {\n    transactionId?: string\n    userData?: { email?: string | null }\n  } = {},\n): boolean {\n  if (!allowed) return false\n  const target = platformAdConversionTarget(kind)\n  if (!target) return false\n  const scope = globalThis as ConversionWindow\n  if (typeof scope.gtag !== 'function') return false\n  // Enhanced conversions (AGL-2683): the address reaches the tag lower-cased\n  // and trimmed — gtag hashes it before anything leaves the browser. Set right\n  // before the event so it attaches to THIS conversion and cannot linger on a\n  // later, unrelated one.\n  const email = String(options.userData?.email ?? '').trim().toLowerCase()\n  if (email) scope.gtag('set', 'user_data', { email })\n  /*\n   * `transaction_id` is what makes a conversion SAFE TO REPORT TWICE.\n   *\n   * Google Ads de-duplicates on it, so a caller no longer has to guarantee\n   * exactly-once delivery from the browser — which is a guarantee a browser\n   * cannot give. Without it, the only safe moment to report is the one the\n   * visitor might close the tab on, and a missed conversion is invisible: the\n   * money was spent, the customer converted, and the campaign shows nothing.\n   *\n   * ⚠️ It must be STABLE for the thing being counted, not per attempt. A fresh\n   * id on every call de-duplicates nothing and quietly restores the double\n   * count it exists to prevent.\n   */\n  scope.gtag('event', 'conversion', {\n    send_to: target,\n    ...(options.transactionId\n      ? { transaction_id: options.transactionId }\n      : {}),\n  })\n  return true\n}\n\n/**\n * Where a checkout that has STARTED but not yet been reported is remembered.\n *\n * The subscribe conversion can only be reported from the browser — an Ads\n * website conversion is matched to the ad click through the GCLID the tag\n * holds, and no webhook has one. That put the only reporting moment on\n * Stripe's `onComplete`, which a visitor can close the tab on: the money was\n * spent, the customer subscribed, and the campaign shows nothing. A missed\n * conversion is invisible, which is what makes it worth repairing.\n *\n * So the checkout marks itself pending when it opens, and the billing page\n * reports on the next visit if it finds the mark and a live subscription. The\n * customer always comes back — they are a customer now.\n *\n * ⚠️ Scoped to the org so a mark left by one workspace cannot report a\n * conversion for another, and paired with a stable `transaction_id` so the\n * belt and the braces cannot double count.\n *\n * `localStorage`, not `sessionStorage`: closing the tab is the case being\n * repaired, and a session store is exactly what closing the tab clears.\n */\nexport const PLATFORM_SUBSCRIBE_PENDING_KEY = 'aglyn:ads:subscribe-pending'\n\n/** Remember that this org opened checkout, so a lost tab is recoverable. */\nexport function markSubscribeCheckoutPending(orgId: string): void {\n  if (!orgId || typeof window === 'undefined') return\n  try {\n    window.localStorage.setItem(PLATFORM_SUBSCRIBE_PENDING_KEY, orgId)\n  } catch {\n    // Storage refused. The `onComplete` path still reports; only the repair\n    // for a closed tab is lost, which is where this started.\n  }\n}\n\n/** Whether this org has a checkout waiting to be reported. */\nexport function subscribeCheckoutPending(orgId: string): boolean {\n  if (!orgId || typeof window === 'undefined') return false\n  try {\n    return window.localStorage.getItem(PLATFORM_SUBSCRIBE_PENDING_KEY) === orgId\n  } catch {\n    return false\n  }\n}\n\n/** Forget it, once reported — or once the org is no longer subscribing. */\nexport function clearSubscribeCheckoutPending(): void {\n  if (typeof window === 'undefined') return\n  try {\n    window.localStorage.removeItem(PLATFORM_SUBSCRIBE_PENDING_KEY)\n  } catch {\n    // A mark that cannot be cleared is re-reported, and `transaction_id`\n    // makes that harmless. This is the reason it is not optional.\n  }\n}\n\nexport default reportPlatformAdConversion\n"],"names":["PLATFORM_ADS_CONVERSION_ID","process","env","NEXT_PUBLIC_ADS_CONVERSION_ID","PLATFORM_ADS_SIGNUP_LABEL","NEXT_PUBLIC_ADS_SIGNUP_LABEL","PLATFORM_ADS_SUBSCRIBE_LABEL","NEXT_PUBLIC_ADS_SUBSCRIBE_LABEL","LABELS","signup","subscribe","platformAdConversionTarget","kind","label","reportPlatformAdConversion","allowed","options","target","scope","globalThis","gtag","email","String","userData","trim","toLowerCase","send_to","transactionId","transaction_id","PLATFORM_SUBSCRIBE_PENDING_KEY","markSubscribeCheckoutPending","orgId","window","localStorage","setItem","subscribeCheckoutPending","getItem","clearSubscribeCheckoutPending","removeItem"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GAED,8CAA8C,GAC9C,OAAO,MAAMA,6BACXC,QAAQC,GAAG,CAACC,6BAA6B,IAAI,GAAE;AAEjD,6EAA6E,GAC7E,OAAO,MAAMC,4BACXH,QAAQC,GAAG,CAACG,4BAA4B,IAAI,GAAE;AAChD,OAAO,MAAMC,+BACXL,QAAQC,GAAG,CAACK,+BAA+B,IAAI,GAAE;AAInD,MAAMC,SAAyD;IAC7DC,QAAQL;IACRM,WAAWJ;AACb;AAEA;;;;;;;CAOC,GACD,OAAO,SAASK,2BACdC,IAA0B;IAE1B,MAAMC,QAAQL,MAAM,CAACI,KAAK;IAC1B,IAAI,CAACZ,8BAA8B,CAACa,OAAO,OAAO;IAClD,OAAO,GAAGb,2BAA2B,CAAC,EAAEa,OAAO;AACjD;AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,SAASC,2BACdF,IAA0B,EAC1BG,OAAgB,EAChBC,UAGI,CAAC,CAAC;;QAWeA;IATrB,IAAI,CAACD,SAAS,OAAO;IACrB,MAAME,SAASN,2BAA2BC;IAC1C,IAAI,CAACK,QAAQ,OAAO;IACpB,MAAMC,QAAQC;IACd,IAAI,OAAOD,MAAME,IAAI,KAAK,YAAY,OAAO;IAC7C,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,wBAAwB;IACxB,MAAMC,QAAQC,gBAAON,oBAAAA,QAAQO,QAAQ,qBAAhBP,kBAAkBK,KAAK,mBAAI,IAAIG,IAAI,GAAGC,WAAW;IACtE,IAAIJ,OAAOH,MAAME,IAAI,CAAC,OAAO,aAAa;QAAEC;IAAM;IAClD;;;;;;;;;;;;GAYC,GACDH,MAAME,IAAI,CAAC,SAAS,cAAc;QAChCM,SAAST;OACLD,QAAQW,aAAa,GACrB;QAAEC,gBAAgBZ,QAAQW,aAAa;IAAC,IACxC,CAAC;IAEP,OAAO;AACT;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAME,iCAAiC,8BAA6B;AAE3E,0EAA0E,GAC1E,OAAO,SAASC,6BAA6BC,KAAa;IACxD,IAAI,CAACA,SAAS,OAAOC,WAAW,aAAa;IAC7C,IAAI;QACFA,OAAOC,YAAY,CAACC,OAAO,CAACL,gCAAgCE;IAC9D,EAAE,eAAM;IACN,wEAAwE;IACxE,yDAAyD;IAC3D;AACF;AAEA,4DAA4D,GAC5D,OAAO,SAASI,yBAAyBJ,KAAa;IACpD,IAAI,CAACA,SAAS,OAAOC,WAAW,aAAa,OAAO;IACpD,IAAI;QACF,OAAOA,OAAOC,YAAY,CAACG,OAAO,CAACP,oCAAoCE;IACzE,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,yEAAyE,GACzE,OAAO,SAASM;IACd,IAAI,OAAOL,WAAW,aAAa;IACnC,IAAI;QACFA,OAAOC,YAAY,CAACK,UAAU,CAACT;IACjC,EAAE,eAAM;IACN,qEAAqE;IACrE,8DAA8D;IAChE;AACF;AAEA,eAAef,2BAA0B"}

package/src/lib/app-utils/platform-advertising-tags.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @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.
+ */
+/**
+ * Which advertising tags may load on AGLYN'S OWN NON-TENANT SURFACES — the
+ * console (`app.aglyn.com`, `auth.aglyn.com`) and the docs site
+ * (`docs.aglyn.com`).
+ *
+ * ## Why this exists beside `advertising-tags.ts` rather than inside it
+ *
+ * {@link resolveAdvertisingTags} answers the same question for a TENANT page,
+ * and every one of its inputs is a host document: the surface discriminator is
+ * `isPlatformMarketingHost`, the configuration is `analytics.adTags`, and the
+ * consent record is keyed per host id. None of those exist here. The console
+ * and the docs are not sites anybody published; they are Aglyn's own
+ * properties, so their ids come from build configuration and their consent
+ * comes from the platform record.
+ *
+ * What is deliberately NOT duplicated is the vendor registry. Both resolvers
+ * read {@link ADVERTISING_VENDORS}, so a vendor is described — loaded, torn
+ * down, and its cookies named — exactly once. A second registry is how a
+ * vendor comes to be revocable on one surface and resident forever on
+ * another.
+ *
+ * ## Configuration, and why nothing is hardcoded
+ *
+ * ⛔ No default id, for any vendor. `analyticsMayEmit()` is true for ANY
+ * production build, self-hosted ones included, so a hardcoded pixel id would
+ * have every operator's console building retargeting audiences in Aglyn's ad
+ * accounts out of their users. Unset means unset and nothing loads — the same
+ * rule `platform-ad-conversions.ts` and the docs site's `DOCS_*` values are
+ * built on, and the one this file follows rather than reinvents.
+ *
+ * A self-host operator's own advertising tags are their business: setting
+ * these variables to their own ids is how they run them, and leaving them
+ * unset is how they run none.
+ *
+ * ⚠️ `process.env.NAME` is inlined at BUILD time by Next and never the bracket
+ * form, so every read below is written out literally. They are fixed when the
+ * image is built rather than when it starts; changing ad accounts is a
+ * rebuild.
+ */
+import { type ResolvedAdvertisingTag } from './advertising-tags';
+import { type AnalyticsEnvironment } from './analytics-environment';
+/**
+ * The build-configured account id for each vendor this surface can mount,
+ * keyed by {@link AdvertisingVendor.id}.
+ *
+ * Read at CALL time rather than captured in a module constant, so a spec can
+ * drive every branch — the alternative is a constant that can only ever be
+ * observed in one state, which is the shape of a check that cannot fail.
+ * `readAnalyticsEnvironment` is written the same way and for the same reason.
+ */
+export declare function readPlatformAdTagIds(): Record<string, string>;
+/** The build-configured Google Tag Manager container, or an empty string. */
+export declare function readPlatformGtmContainerId(): string;
+/**
+ * Which advertising tags may exist on this surface, for this visitor, right
+ * now.
+ *
+ * Pure, and empty is the answer to every question it cannot answer — a build
+ * that may not emit, a visitor who has not granted, an unconfigured vendor, a
+ * malformed id.
+ *
+ * `advertisingGranted` is PASSED IN rather than read here, and that is the
+ * whole of the arrangement this module is for. Each surface resolves consent
+ * through the machinery it already has — the console through
+ * `platformAdvertisingAllowed()` over its own posture-resolved record, the
+ * docs site through the registrable-domain mirror of that same record — and
+ * neither gets a second reading of a cookie from inside an analytics helper.
+ * One resolver per surface, asked by the mount rather than re-implemented in
+ * it.
+ *
+ * `analyticsMayEmit` is checked HERE and not left to the caller, because it is
+ * the one condition that is a property of the BUILD rather than of the
+ * visitor: `next dev` and any Vercel preview build resolve these ids exactly
+ * as production does, and without this a preview deploy would build real
+ * retargeting audiences out of our own engineers (AGL-2067).
+ */
+export declare function resolvePlatformAdvertisingTags(advertisingGranted: boolean, ids?: Record<string, string>, env?: AnalyticsEnvironment, internal?: boolean): ResolvedAdvertisingTag[];
+/**
+ * The Google Tag Manager container this surface may load, or null.
+ *
+ * ## Why the gate here is ANALYTICS and never advertising
+ *
+ * A container is not a tag — it is a LOADER, and what it loads is decided in
+ * Google's UI by whoever owns it, not here. The tenant runtime already settled
+ * the rule this follows: a container cannot have a WEAKER gate than GA,
+ * because it is the likeliest thing on a page to carry an advertising tag, and
+ * it cannot have a stronger one either or a container-only surface would never
+ * load at all. So it rides the analytics grant, and the advertising signals
+ * the visitor did or did not give reach its tags through Consent Mode v2 —
+ * which is why `PLATFORM_CONSENT_DEFAULT_COMMANDS` has to be declared before
+ * `gtm.js` is requested and not after.
+ *
+ * ⚠️ A container's CONTENTS are not visible from this repository, and what is
+ * in one is a disclosure obligation as much as a technical one: a tag added in
+ * Google's UI appears in no inventory here and no spec can see it. That is a
+ * reason to know what a container holds before configuring one on a surface,
+ * not a reason for this function to be looser.
+ *
+ * ⛔ NO `<noscript>` iframe accompanies this anywhere, deliberately, and it is
+ * the one piece of Google's standard snippet always omitted. That iframe fires
+ * the container with no JavaScript — so no consent defaults, no gate, nothing
+ * to suppress it. It is a consent bypass with a fallback's reputation. A
+ * visitor with JavaScript off gets no container, which is the correct answer.
+ */
+export declare function resolvePlatformGtmContainerId(analyticsGranted: boolean, containerId?: string, env?: AnalyticsEnvironment, internal?: boolean): string | null;
+/**
+ * The inline boot for a Google Tag Manager container.
+ *
+ * The consent-mode declaration is NOT part of this string. Every surface that
+ * calls it declares `PLATFORM_CONSENT_DEFAULT_COMMANDS` earlier and by its own
+ * route — the console pushes them onto `dataLayer` before the Firebase SDK
+ * boots gtag, the docs site emits them from its `ssrTemplate` ahead of every
+ * plugin tag — and re-declaring a default mid-page re-DENIES what the first
+ * one granted until an update lands. One declaration per document, made by
+ * whoever is first.
+ *
+ * The `gtag` shim is defined anyway, because it is cheap and because
+ * `dataLayer.push` of a plain array is the classic silent no-op if anything
+ * downstream reaches for the function form.
+ */
+export declare function platformGtmBootSnippet(): string;
+/** The container library URL for `containerId`. */
+export declare function platformGtmScriptSrc(containerId: string): string;