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

package/src/lib/server/free-workspace-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/free-workspace-cap.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 * THE FREE-WORKSPACE CEILING (AGL-2265).\n *\n * Every free cap in the product is enforced PER ORG, and nothing bounded how\n * many orgs one account could hold — so the free allowance multiplied by\n * workspaces: N orgs = N sites, N × 250 MB media, N × 5 GB bandwidth, N × 10\n * Assist messages a day. `/api/orgs/create` is rate limited per uid and per IP\n * (AGL-1534), which bounds the RATE and not the TOTAL.\n *\n * the decision, 2026-08-19: **three, with a control in the staff console.**\n * Three is the number; the number living in a Firestore document rather than a\n * constant is the other half of the decision, because the population this\n * refuses (a script minting workspaces) and the population it must not refuse\n * (an agency, a consultant, a customer support raises) are told apart by a\n * human, and a human must not need a deploy to say yes.\n *\n * ## What counts\n *\n * A FREE workspace ATTRIBUTED to the account. Three properties, each of which\n * is a bug if it is wrong:\n *\n *  - **Paid workspaces do not count.** An agency's workspaces are paid, and\n *    the abuse this closes is free-allowance multiplication. `plan` is read\n *    through `resolveEffectivePlan`, so a workspace whose subscription died\n *    counts again — correctly: it is free again.\n *  - **Being INVITED to someone else's workspace never counts.** The count\n *    comes off `orgs`, keyed by ownership and creation. It never reads\n *    `users/{uid}/orgs`, which is a membership index — a contractor added to\n *    ten client workspaces owns none of them.\n *  - **Handing a workspace away does not free a slot.** See below; this is\n *    the whole difficulty.\n *\n * ## Why the count is not launderable\n *\n * A create-time quota computed from a number the applicant can lower is not a\n * quota. The cheap laundering sequence here is not deletion — deleting a\n * workspace really does give up the workspace — it is **ownership transfer**,\n * which is free, instant and reversible:\n *\n *     hold 3 → transfer #3 to an alt account → count reads 2 → create a 4th\n *     → transfer #3 back → hold 4, having never been refused.\n *\n * So the count is the UNION of two sets: workspaces the account owns NOW\n * (`ownerUid`) and workspaces the account CREATED (`createdByUid`).\n * `createdByUid` is stamped once, inside the creating transaction, and no code\n * path anywhere mutates it — `transferOrgOwnership` moves `ownerUid` and does\n * not touch it. Transferring away therefore changes nothing about the count,\n * and the sequence above is refused at the fourth workspace exactly as it\n * would have been without the detour. Erasing a workspace removes the org\n * document from both sets, which is the one decrement that is honest: the\n * allowance it was multiplying went with it.\n *\n * (Orgs created before this shipped carry no `createdByUid`. They are counted\n * by `ownerUid` like always, so the union is never smaller than the old\n * behaviour; it only stops shrinking under a transfer.)\n *\n * ## Why the decision is atomic\n *\n * The count is read INSIDE the org-creation transaction, and the transaction\n * also reads-and-writes a per-owner marker document. Without that marker, two\n * `/api/orgs/create` requests in flight together would both observe three,\n * both find headroom and both commit a fourth and a fifth: the new org\n * documents are not in either transaction's read set, so nothing would make\n * them contend. The marker is a document they DO both read and both write, so\n * the second commit aborts, the callback re-runs, its queries re-read at the\n * new read time, they now see the org the first request committed, and it is\n * refused. That is the AGL-2267 lesson — a read-then-write quota must contend\n * on something.\n *\n * ## Storage, and why it needs no rules or index deploy\n *\n * The ceiling lives at `rateLimits/freeWorkspaceCapConfig` and the per-owner\n * marker at `rateLimits/freeWorkspaces_{uid}`, the same collection AGL-794's\n * counters and AGL-2409's send-rate ramp already use, and for the same\n * reason: it inherits the deny-all security rule and the `expiresAt` TTL\n * policy that already exist. Deny-all matters here — no client, staff\n * included, may write the ceiling; the audited console route is the only\n * writer.\n *\n * The config document **must never carry `expiresAt`**, or the TTL policy that\n * serves the counters would delete the ceiling and the platform would silently\n * revert to the compiled-in default. The marker document carries one on\n * purpose: it is disposable, its only job is contention, and a swept marker\n * costs nothing because the queries are the authority for the number.\n *\n * ## Failure posture: the DEFAULT, which is neither open nor closed\n *\n * An unreadable configuration resolves to the compiled-in 3 and reports\n * `ready: false`. Not zero — a Firestore blip must not refuse every signup on\n * the platform. Not unlimited — a Firestore blip must not be the way through\n * the control. `checkQuota(undefined)` resolving to the free tier is a bug\n * this codebase has already had; `freeWorkspaceCapVerdict` therefore takes\n * `ready` as an explicit input and a not-yet-loaded limit is never read as a\n * number.\n */\n\nimport { resolveEffectivePlan } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from './firebase-admin'\nimport { RATE_LIMIT_COLLECTION } from './rate-limit-store'\n\n/** the number, 2026-08-19. The floor the console can move off. */\nexport const DEFAULT_FREE_WORKSPACE_CAP = 3\n\n/** Document id of the live ceiling. NEVER written with `expiresAt`. */\nexport const FREE_WORKSPACE_CAP_CONFIG_DOC = 'freeWorkspaceCapConfig'\n\n/** Id prefix for the per-owner contention markers. */\nexport const FREE_WORKSPACE_MARKER_PREFIX = 'freeWorkspaces_'\n\n/** Bounds the console will accept. One is a real answer; zero is not. */\nexport const FREE_WORKSPACE_CAP_MIN = 1\nexport const FREE_WORKSPACE_CAP_MAX = 500\n\n/** Longest audited note the console may attach to a change. */\nexport const FREE_WORKSPACE_CAP_NOTE_MAX = 280\n\n/**\n * How many of an owner's org documents the count will read.\n *\n * The count filters by plan in memory (`plan` is not a queryable predicate\n * that survives `resolveEffectivePlan`'s subscription check), so the query\n * cannot be bounded at the ceiling. An account holding more orgs than this is\n * far past any ceiling staff would set and is a support conversation, not a\n * create-time decision.\n */\nexport const FREE_WORKSPACE_SCAN_LIMIT = 250\n\n/** How long a contention marker survives. Disposable — see the notes above. */\nexport const FREE_WORKSPACE_MARKER_TTL_MS = 24 * 60 * 60 * 1000\n\nexport interface FreeWorkspaceCapConfig {\n  /** Free workspaces one account may hold. */\n  limit: number\n  /** False turns the ceiling OFF entirely (staff kill switch). */\n  enabled: boolean\n  /** Why it is where it is — shown on the card, written to the audit row. */\n  note: string\n  updatedAtMs: number | null\n  updatedByEmail: string | null\n  /**\n   * Whether this is a value that was actually READ, or the compiled-in\n   * default standing in for one that could not be.\n   *\n   * Exposed rather than swallowed because a loading default answering a\n   * question as though it were a real value is a bug shape this codebase has\n   * shipped before. Callers that must not act on a guess check this; the\n   * verdict function below treats it as the difference between \"the operator\n   * chose unlimited\" and \"we do not know yet\", and the second is never\n   * unlimited.\n   */\n  ready: boolean\n}\n\n/** The marker document id for one owner. */\nexport function freeWorkspaceMarkerDocId(uid: string): string {\n  return `${FREE_WORKSPACE_MARKER_PREFIX}${uid}`\n}\n\n/**\n * Coerces whatever is stored (or nothing) into a usable ceiling.\n *\n * A missing, non-numeric, zero, negative or absurd `limit` becomes the\n * compiled-in default rather than zero. Storing a broken number must not be a\n * way to refuse every signup, and it must not be a way to admit everyone\n * either — both are the same mistake with opposite signs.\n */\nexport function normalizeFreeWorkspaceCapConfig(\n  data: Partial<FreeWorkspaceCapConfig> | null | undefined,\n  options?: { ready?: boolean },\n): FreeWorkspaceCapConfig {\n  const rawLimit = Number(data?.limit)\n  const limit =\n    Number.isFinite(rawLimit) && rawLimit >= FREE_WORKSPACE_CAP_MIN\n      ? Math.min(FREE_WORKSPACE_CAP_MAX, Math.floor(rawLimit))\n      : DEFAULT_FREE_WORKSPACE_CAP\n  const updatedAtMs = Number(data?.updatedAtMs)\n  return {\n    limit,\n    // Only an explicit `false` turns it off — an absent field is ON, so a\n    // half-written document cannot silently disable the ceiling.\n    enabled: data?.enabled !== false,\n    note: typeof data?.note === 'string' ? data.note.slice(0, FREE_WORKSPACE_CAP_NOTE_MAX) : '',\n    updatedAtMs: Number.isFinite(updatedAtMs) && updatedAtMs > 0 ? updatedAtMs : null,\n    updatedByEmail:\n      typeof data?.updatedByEmail === 'string' && data.updatedByEmail\n        ? data.updatedByEmail\n        : null,\n    ready: options?.ready !== false,\n  }\n}\n\nexport interface FreeWorkspaceCapVerdict {\n  allowed: boolean\n  /** The ceiling the decision was actually made against. */\n  limit: number\n  held: number\n  remaining: number\n  /** False when the ceiling was a stand-in rather than a value we read. */\n  ready: boolean\n  /** True when the ceiling is switched off and this granted for that reason. */\n  disabled: boolean\n}\n\n/**\n * The whole decision, pure.\n *\n * The `ready` input is the point of the signature. A config that has not\n * loaded arrives here as `{ ready: false }` and is answered against the\n * compiled-in default — never as `limit: 0` (which would refuse every signup\n * on the platform during a blip) and never as \"no limit known, therefore no\n * limit\" (which would make an outage the way through the control).\n */\nexport function freeWorkspaceCapVerdict(input: {\n  held: number\n  limit?: number | null\n  enabled?: boolean\n  ready?: boolean\n}): FreeWorkspaceCapVerdict {\n  const ready = input.ready !== false\n  const rawHeld = Number(input.held)\n  const held = Number.isFinite(rawHeld) && rawHeld > 0 ? Math.floor(rawHeld) : 0\n  const rawLimit = Number(input.limit)\n  // An unready config does not get to contribute a number at all, even if one\n  // happens to be sitting in the field.\n  const limit =\n    ready && Number.isFinite(rawLimit) && rawLimit >= FREE_WORKSPACE_CAP_MIN\n      ? Math.min(FREE_WORKSPACE_CAP_MAX, Math.floor(rawLimit))\n      : DEFAULT_FREE_WORKSPACE_CAP\n  const disabled = input.enabled === false\n  return {\n    allowed: disabled || held < limit,\n    limit,\n    held,\n    remaining: Math.max(0, limit - held),\n    ready,\n    disabled,\n  }\n}\n\n/**\n * Whether an org document is on the free plan for the purposes of this count.\n *\n * `resolveEffectivePlan` and not `data.plan`: a workspace whose subscription\n * is canceled or unpaid resolves back to free, which is right — it is\n * consuming the free allowance again, so it counts again.\n */\nexport function isFreeOrgDoc(data: unknown): boolean {\n  return resolveEffectivePlan((data ?? {}) as never) === 'free'\n}\n\n/**\n * The two queries whose UNION is the attributed set. Exported so the spec can\n * assert the second one exists — the union IS the anti-laundering property,\n * and a future edit that drops `createdByUid` for being redundant would put\n * the transfer sequence back without changing any behaviour a happy-path test\n * observes.\n */\nexport function freeWorkspaceOwnerQueries(firestore: any, uid: string): any[] {\n  const orgs = firestore.collection('orgs')\n  return [\n    orgs.where('ownerUid', '==', uid).limit(FREE_WORKSPACE_SCAN_LIMIT),\n    orgs.where('createdByUid', '==', uid).limit(FREE_WORKSPACE_SCAN_LIMIT),\n  ]\n}\n\nexport interface FreeWorkspaceCount {\n  held: number\n  orgIds: string[]\n}\n\n/**\n * How many free workspaces are attributed to `uid`.\n *\n * `readQuery` is how the caller runs each query, and it is the whole\n * difference between the two callers: outside a transaction a query runs\n * itself (`query.get()`), inside one it must run through the transaction\n * (`tx.get(query)`) or the count is not in the read set and the retry that\n * makes this atomic never happens. Passing a Firestore instance and calling\n * `firestore.get(query)` would silently be neither — that method does not\n * exist, and the count would come back as zero, admitting everyone.\n */\nasync function countAttributedFreeWorkspaces(\n  readQuery: (query: any) => Promise<any>,\n  firestore: any,\n  uid: string,\n): Promise<FreeWorkspaceCount> {\n  const seen = new Map<string, unknown>()\n  for (const query of freeWorkspaceOwnerQueries(firestore, uid)) {\n    const snapshot = await readQuery(query)\n    for (const doc of snapshot?.docs ?? []) {\n      // Deduplicated by id: the common case is one org in BOTH sets.\n      if (!seen.has(doc.id)) seen.set(doc.id, doc.data())\n    }\n  }\n  const orgIds = [...seen.entries()]\n    .filter(([, data]) => isFreeOrgDoc(data))\n    .map(([id]) => id)\n  return { held: orgIds.length, orgIds }\n}\n\n/**\n * Read-only count, for the console and for anything that wants to explain a\n * refusal after the fact. The creation path does NOT use this — it counts\n * inside its own transaction.\n */\nexport async function countFreeWorkspacesForOwner(options: {\n  uid: string\n  firestore?: any\n}): Promise<FreeWorkspaceCount> {\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  try {\n    return await countAttributedFreeWorkspaces(\n      (query) => query.get(),\n      firestore,\n      options.uid,\n    )\n  } catch (error) {\n    console.error('[free-workspace-cap] count unavailable', error)\n    return { held: 0, orgIds: [] }\n  }\n}\n\n/**\n * Config cache TTL. 15s, the same number and reasoning as the lockdown doc\n * and the send-rate ramp: staff move this rarely and a warm process converges\n * within a quarter of a minute.\n */\nconst CONFIG_TTL_MS = 15_000\n\nlet configCache: { at: number; config: FreeWorkspaceCapConfig } | undefined\nlet configPending: Promise<FreeWorkspaceCapConfig> | undefined\n\n/** Drop the in-process config cache — called by the console after a write. */\nexport function invalidateFreeWorkspaceCapConfigCache(): void {\n  configCache = undefined\n  configPending = undefined\n}\n\n/**\n * The live ceiling.\n *\n * An unreachable document returns the compiled-in default with\n * `ready: false`, which every caller must carry rather than flatten — see the\n * failure-posture note at the top of the file.\n */\nexport async function readFreeWorkspaceCapConfig(options?: {\n  firestore?: any\n  now?: number\n}): Promise<FreeWorkspaceCapConfig> {\n  const now = options?.now ?? Date.now()\n  if (!options?.firestore && configCache && now - configCache.at < CONFIG_TTL_MS) {\n    return configCache.config\n  }\n  const load = async (): Promise<FreeWorkspaceCapConfig> => {\n    try {\n      const firestore = options?.firestore ?? firebaseAdmin.app().firestore()\n      const snapshot = await firestore\n        .collection(RATE_LIMIT_COLLECTION)\n        .doc(FREE_WORKSPACE_CAP_CONFIG_DOC)\n        .get()\n      // A document that does not exist is READY: nobody has changed the\n      // number, and the compiled-in 3 is the answer, not a guess.\n      return normalizeFreeWorkspaceCapConfig(\n        snapshot?.exists\n          ? (snapshot.data() as Partial<FreeWorkspaceCapConfig>)\n          : null,\n        { ready: true },\n      )\n    } catch {\n      return normalizeFreeWorkspaceCapConfig(null, { ready: false })\n    }\n  }\n  // An injected firestore is a test or a one-off read; never cached, so a\n  // spec cannot poison the process cache for the next one.\n  if (options?.firestore) return load()\n  if (!configPending) {\n    configPending = load()\n      .then((config) => {\n        // A degraded read is never cached — the next create should try again\n        // rather than serve a stand-in for fifteen seconds.\n        if (config.ready) configCache = { at: now, config }\n        return config\n      })\n      .finally(() => {\n        configPending = undefined\n      })\n  }\n  return configPending\n}\n\n/**\n * The document the console writes when staff move the ceiling.\n *\n * Returned rather than written so the route owns the write (and the audit row\n * beside it), and so a spec can assert the SHAPE without a Firestore. The one\n * thing it must never contain is `expiresAt`.\n */\nexport function freeWorkspaceCapConfigWrite(input: {\n  limit: number\n  enabled: boolean\n  actorEmail?: string | null\n  note?: string\n  now?: number\n}): Partial<FreeWorkspaceCapConfig> {\n  const normalized = normalizeFreeWorkspaceCapConfig({\n    limit: input.limit,\n    enabled: input.enabled,\n    note: input.note,\n    updatedAtMs: input.now ?? Date.now(),\n    updatedByEmail: input.actorEmail ?? null,\n  })\n  return {\n    limit: normalized.limit,\n    enabled: normalized.enabled,\n    note: normalized.note,\n    updatedAtMs: normalized.updatedAtMs,\n    updatedByEmail: normalized.updatedByEmail,\n  }\n}\n\n/**\n * Thrown by `createOrganization` when the ceiling refuses. Carries the numbers\n * so the API route can say which ceiling and how many, rather than \"no\".\n */\nexport class FreeWorkspaceCapError extends Error {\n  readonly limit: number\n  readonly held: number\n  constructor(verdict: { limit: number; held: number }) {\n    super(\n      `Free workspace ceiling reached: ${verdict.held} of ${verdict.limit}`,\n    )\n    this.name = 'FreeWorkspaceCapError'\n    this.limit = verdict.limit\n    this.held = verdict.held\n  }\n}\n\n/**\n * The create-time gate, run INSIDE the creating transaction.\n *\n * Reads the attributed count through `tx` (so it is part of the read set and\n * re-runs against fresh data on a retry) and reads-then-writes the per-owner\n * marker (so two concurrent creates by one account contend, and the loser\n * re-runs and sees the winner's org).\n *\n * Throws `FreeWorkspaceCapError` when it refuses. Firestore does not retry a\n * callback that threw, which is what we want: a refusal is a decision, not\n * contention.\n *\n * Call it AFTER the caller's other reads and BEFORE the caller's writes — it\n * both reads and writes, and Firestore requires all reads first.\n */\nexport async function enforceFreeWorkspaceCapInTransaction(options: {\n  tx: any\n  firestore: any\n  uid: string\n  config: FreeWorkspaceCapConfig\n  now?: number\n}): Promise<FreeWorkspaceCapVerdict> {\n  const { tx, firestore, uid, config } = options\n  const now = options.now ?? Date.now()\n  const markerRef = firestore\n    .collection(RATE_LIMIT_COLLECTION)\n    .doc(freeWorkspaceMarkerDocId(uid))\n\n  const [count, marker] = await Promise.all([\n    countAttributedFreeWorkspaces((query) => tx.get(query), firestore, uid),\n    tx.get(markerRef),\n  ])\n\n  const verdict = freeWorkspaceCapVerdict({\n    held: count.held,\n    limit: config.limit,\n    enabled: config.enabled,\n    ready: config.ready,\n  })\n  if (!verdict.allowed) throw new FreeWorkspaceCapError(verdict)\n\n  const priorCreates = Number(\n    (marker?.exists ? marker.get('creates') : 0) ?? 0,\n  )\n  // An ABSOLUTE value derived from the read, not `FieldValue.increment`: the\n  // read is what has to contend, and an increment is atomic on the number and\n  // useless for the decision (AGL-2267).\n  tx.set(\n    markerRef,\n    {\n      creates: (Number.isFinite(priorCreates) ? priorCreates : 0) + 1,\n      heldAtLastCreate: count.held,\n      lastCreateAtMs: now,\n      // Disposable. NOT on the config document — see the storage note.\n      expiresAt: new Date(now + FREE_WORKSPACE_MARKER_TTL_MS),\n    },\n    { merge: true },\n  )\n  return verdict\n}\n\n/**\n * Turn a ceiling refusal into the 403 the creating routes return, or null when\n * the error is something else and must keep propagating to the 500.\n *\n * Lives here beside the policy, and mirrors `collaboratorSeatRefusalResponse`,\n * so a route's catch block is one line and cannot accidentally mask a real\n * fault. The copy names the number and the way out, because the person reading\n * it is far more often a consultant with three real workspaces than the script\n * this exists to stop.\n */\nexport function freeWorkspaceCapRefusalResponse(error: unknown): Response | null {\n  if (!(error instanceof FreeWorkspaceCapError)) return null\n  return Response.json(\n    {\n      error:\n        `You already have ${error.held} free workspaces, which is the limit ` +\n        `of ${error.limit}. Upgrade one of them, delete one you no longer ` +\n        'need, or contact support and we can raise the limit for your account.',\n      code: 'free_workspace_limit',\n      limit: error.limit,\n      held: error.held,\n    },\n    { status: 403 },\n  )\n}\n"],"names":["resolveEffectivePlan","firebaseAdmin","RATE_LIMIT_COLLECTION","DEFAULT_FREE_WORKSPACE_CAP","FREE_WORKSPACE_CAP_CONFIG_DOC","FREE_WORKSPACE_MARKER_PREFIX","FREE_WORKSPACE_CAP_MIN","FREE_WORKSPACE_CAP_MAX","FREE_WORKSPACE_CAP_NOTE_MAX","FREE_WORKSPACE_SCAN_LIMIT","FREE_WORKSPACE_MARKER_TTL_MS","freeWorkspaceMarkerDocId","uid","normalizeFreeWorkspaceCapConfig","data","options","rawLimit","Number","limit","isFinite","Math","min","floor","updatedAtMs","enabled","note","slice","updatedByEmail","ready","freeWorkspaceCapVerdict","input","rawHeld","held","disabled","allowed","remaining","max","isFreeOrgDoc","freeWorkspaceOwnerQueries","firestore","orgs","collection","where","countAttributedFreeWorkspaces","readQuery","seen","Map","query","snapshot","doc","docs","has","id","set","orgIds","entries","filter","map","length","countFreeWorkspacesForOwner","app","get","error","console","CONFIG_TTL_MS","configCache","configPending","invalidateFreeWorkspaceCapConfigCache","undefined","readFreeWorkspaceCapConfig","now","Date","at","config","load","exists","then","finally","freeWorkspaceCapConfigWrite","normalized","actorEmail","FreeWorkspaceCapError","Error","verdict","name","enforceFreeWorkspaceCapInTransaction","marker","tx","markerRef","count","Promise","all","priorCreates","creates","heldAtLastCreate","lastCreateAtMs","expiresAt","merge","freeWorkspaceCapRefusalResponse","Response","json","code","status"],"mappings":"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"}

package/src/lib/server/ga4-measurement-protocol.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @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.
+ */
+export interface Ga4PurchaseItem {
+    item_id: string;
+    item_name: string;
+    item_category?: string;
+    price?: number;
+    quantity?: number;
+}
+export interface Ga4PurchaseInput {
+    /** Stripe object id — invoice or checkout session. GA de-duplicates on it. */
+    transactionId: string;
+    /** Whole currency units, NOT cents. */
+    value: number;
+    /** ISO 4217, upper-cased by the caller or here. */
+    currency: string;
+    items: Ga4PurchaseItem[];
+    billingInterval?: 'monthly' | 'annual';
+    /**
+     * The browser's GA `client_id`, captured at checkout start and carried on
+     * Stripe metadata. Absent for renewals and for customers whose gtag never
+     * ran; see the module comment.
+     */
+    clientId?: string | null;
+    /** Opaque Firebase uid. The one identifier GA is allowed to hold. */
+    userId?: string | null;
+    /** Stripe customer id — used ONLY to synthesize a fallback client id. */
+    stripeCustomerId?: string | null;
+    /**
+     * Whether this transaction is OURS — a staff or rehearsal purchase — rather
+     * than a customer's (AGL-1582). Carried from the browser that started
+     * checkout on Stripe metadata, the same way `clientId` is.
+     *
+     * Opt-in only, never inferred: wrongly flagging a real customer erases their
+     * revenue from every report, and a GA4 data filter is not retroactive.
+     */
+    internal?: boolean;
+}
+export interface Ga4SendResult {
+    sent: boolean;
+    /** True when no real browser client id was available. */
+    synthesizedClientId: boolean;
+    reason?: string;
+}
+/**
+ * A stable, opaque stand-in for a browser client id.
+ *
+ * GA expects the `<random>.<timestamp>` shape. Determinism matters more than
+ * realism: the same `seed` must map to the same synthetic user every time, or
+ * one paying customer becomes a crowd of one-purchase strangers and ARPA is
+ * nonsense. Derived by a cheap non-cryptographic hash — this is a bucketing
+ * key, not a secret, and the seed it comes from never leaves this function.
+ *
+ * The seed is whatever identifies the actor the events belong to on the
+ * surface doing the sending: the Stripe customer for revenue, the host id for
+ * a scheduled publish (AGL-1589). Both are opaque to GA — only the hash is
+ * ever transmitted.
+ */
+export declare function synthesizeClientId(seed: string): string;
+/**
+ * Send one `purchase` to GA4. Never throws.
+ *
+ * Returns a result rather than void so the caller can log the fallback rate;
+ * nothing about the return value should change billing behaviour.
+ */
+export declare function sendGa4Purchase(input: Ga4PurchaseInput): Promise<Ga4SendResult>;
+/**
+ * Send one GA4 `refund` — revenue that came back (AGL-1850). Never throws.
+ *
+ * Both `purchase` senders were one-directional, so GA revenue could only
+ * ever go UP: a refunded invoice or marketplace sale stayed on the books
+ * forever, drifting GA away from Stripe by exactly the refund volume. GA4's
+ * native `refund` event is built for this — sent with the ORIGINAL
+ * purchase's `transaction_id`, GA nets the two against each other in every
+ * revenue report.
+ *
+ * `transaction_id` is therefore the one field that carries the whole
+ * mechanism: the invoice id for a subscription refund, the checkout session
+ * id for a marketplace one — whatever the matching `purchase` reported,
+ * never the refund's own charge or event id.
+ *
+ * `value` is what actually came back, in the SAME accounting the purchase
+ * used. For a subscription that is `amount_refunded` (the purchase reported
+ * `amount_paid`, all ours); for a marketplace sale it is the platform-net
+ * share (the purchase reported our net per AGL-1639, so refunding the gross
+ * would net MORE than the sale ever reported). The caller owns that
+ * arithmetic because the caller holds the ledger; this sender ships whatever
+ * number it is handed.
+ *
+ * Same claiming rules as `purchase` (the caller discriminates, this module
+ * transmits), same client-id capture-or-synthesize fallback, same
+ * fire-and-forget posture — a throw would un-claim the Stripe event.
+ */
+export declare function sendGa4Refund(input: Ga4PurchaseInput): Promise<Ga4SendResult>;
+/**
+ * Send one `subscription_cancelled` — the churn half of the funnel
+ * (AGL-1851). Never throws.
+ *
+ * Every event instruments the way INTO revenue and nothing the way out, so
+ * GA could not answer churn rate, plan-tier churn mix or tenure at
+ * cancellation. Sent server-side for the same reason `purchase` is: a
+ * subscription ends with no browser present — portal cancellations at
+ * period end, dunning exhaustion, staff action — so a client event is not a
+ * weaker option, it is no option.
+ *
+ * A CUSTOM name, deliberately. GA4's only subscription-cancel vocabulary
+ * (`app_store_subscription_cancel`) is reserved for app-store data sources
+ * and a web hit wearing it is dropped, which is silence, not pollution —
+ * the worse failure. The params need dimension registration to report on
+ * (AGL-1637): `plan` — the plan being LEFT, never the `free` the org mirror
+ * writes; `billing_interval` — the churn half of the AGL-1640 annual-mix
+ * metric; `tenure_days` — whole days from the subscription's `created` to
+ * when it actually ended, the "how long do they stay" number.
+ */
+export declare function sendGa4SubscriptionCancelled(input: {
+    /** The plan tier the org is LEAVING (metadata/price-derived, not `free`). */
+    plan: string;
+    /** `monthly` | `annual`, when the subscription's price interval said. */
+    billingInterval?: 'monthly' | 'annual';
+    /** Whole days the subscription lived; omitted when timestamps are absent. */
+    tenureDays?: number;
+    /** Same capture-or-synthesize contract as `purchase`. */
+    clientId?: string | null;
+    userId?: string | null;
+    stripeCustomerId?: string | null;
+    /** Ours rather than a customer's (AGL-1582) — see `Ga4PurchaseInput`. */
+    internal?: boolean;
+}): Promise<Ga4SendResult>;
+/**
+ * Send one `site_published` for a route that went live with no browser
+ * involved (AGL-1589). Never throws.
+ *
+ * ## Why this is allowed to be a synthetic user
+ *
+ * The client id is derived from the HOST — the site whose route went live —
+ * and not from the author, because the author is not present: a scheduled
+ * publish is applied by the cron beat minutes or hours after anybody clicked
+ * anything, and the browser that wrote the schedule is long gone. There is no
+ * session to join and nothing to attribute.
+ *
+ * Deriving it from the host rather than randomly is what keeps the metric
+ * honest in the one direction it can be dishonest. "% who publish a site"
+ * counts USERS, so a random id per publish would let one site scheduling ten
+ * publishes look like ten activated customers — the same inflation
+ * `publishScreenRoute` avoids by firing only when a route goes live. One host
+ * is one synthetic user, forever, however many of its screens go live on a
+ * timer.
+ *
+ * ## One param, deliberately
+ *
+ * `first_publish` and nothing else, matching the browser event (AGL-1588).
+ * The host id is a resource identifier bought for nothing, and the rest of the
+ * metric is answered by the event alone; the id is used only as the hash seed
+ * and never transmitted.
+ *
+ * The caller decides `first_publish` from the routing map it read before
+ * registering the entry, through the same `isFirstPublishedRoute` the console
+ * uses — a dimension is only worth registering if every sender means the same
+ * thing by it, and this sender is the one nobody can watch happen.
+ */
+export declare function sendGa4SitePublished(input: {
+    /** Host uid the route went live on — hashed into a client id, never sent. */
+    hostId: string;
+    /**
+     * Whether the host had no live route at all before this one. Omit when it
+     * genuinely cannot be determined — the param is optional and an absent
+     * breakdown value beats an invented one.
+     */
+    firstPublish?: boolean;
+    /**
+     * Ours rather than a customer's (AGL-1582). A scheduled publish of our own
+     * marketing site or a demo host is an activation event for nobody, and
+     * `site_published` is the headline activation metric.
+     */
+    internal?: boolean;
+}): Promise<Ga4SendResult>;
+/**
+ * Send one `stripe_connected` for an account that became able to take
+ * payments with no browser present (AGL-1580). Never throws.
+ *
+ * ## Why this needs a server sender at all
+ *
+ * There are two client-side emitters for this event — the commerce payments
+ * card and the marketplace seller panel — and both are gated the same way:
+ *
+ *     if (!chargesEnabled) trackEvent('stripe_connected')
+ *
+ * where `chargesEnabled` is the state read from the merchant's profile BEFORE
+ * the connect request. The gate is right in intent: the connect handler is a
+ * re-entrant create-or-resume that answers `chargesEnabled: true` on every
+ * later visit, so a bare event there would count one merchant once per click
+ * forever.
+ *
+ * What defeats it is AGL-1997. Stripe emits `account.updated` the moment
+ * hosted onboarding completes — while the merchant is still on Stripe's
+ * domain, before the `return_url` bounces them back — and
+ * {@link syncConnectAccountStatus} mirrors `charges_enabled` onto the profile
+ * from that webhook. So by the time the merchant lands back in the console
+ * the flag they are supposed to transition FROM already reads `true`, the
+ * client guard is false, and the event never fires. It is not a race that
+ * usually goes the wrong way; the webhook wins by an entire page load.
+ *
+ * ## The two senders cannot double-count
+ *
+ * Both key off the SAME stored flag, from opposite sides of it:
+ *
+ * - merchant clicks first → the connect route writes `true` → the later
+ *   `account.updated` sees no transition → only the CLIENT event fires;
+ * - webhook lands first → the transition is here → the merchant's later click
+ *   reads a pre-state of `true` → only the SERVER event fires.
+ *
+ * Exactly one of the two guards can be open for a given account, which is why
+ * this is added alongside the client emitters rather than replacing them —
+ * a deployment with no Connect webhook destination (the self-host default)
+ * still reports through the browser.
+ *
+ * ## One synthetic user per connected account
+ *
+ * The client id is hashed from the Stripe account id for the reason
+ * {@link sendGa4SitePublished} hashes the host: "% who connect Stripe" counts
+ * MERCHANTS, and a random id per hit would let one account that reconnects
+ * look like several activated customers. The account id is the hash seed and
+ * is never transmitted.
+ *
+ * ## No parameters, deliberately
+ *
+ * `stripe_connected` is declared as `Record<string, never>` in the client
+ * event contract, and a server sender that invented a param would create a
+ * dimension only half the hits carry.
+ */
+export declare function sendGa4StripeConnected(input: {
+    /** Stripe account id — hashed into a client id, never sent. */
+    accountId: string;
+    /**
+     * Ours rather than a customer's (AGL-1582). Omitted by the webhook caller
+     * for the same reason the publish executor omits it: no server-side signal
+     * distinguishes our own connected account from a customer's, and guessing
+     * would stamp real merchants as internal — which a data filter then
+     * permanently discards.
+     */
+    internal?: boolean;
+}): Promise<Ga4SendResult>;