@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.222

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

@@ -1,283 +0,0 @@
-/**
- * @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 { type DocumentReference, type Firestore } from 'firebase-admin/firestore';
-import { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey } from './campaign-attribution-store';
-/**
- * THE IDENTIFY-MOMENT JOIN — a form, a lead, a contact or a booking, credited
- * to the campaign that led to it.
- *
- * ## Why there is a second join at all, and why it is not a second SCHEME
- *
- * `email-revenue-attribution.ts` credits an ORDER by looking the buyer's
- * address up in the touch map a click wrote. That works because an order
- * names its buyer. Every other outcome a campaign causes is produced by
- * somebody who was anonymous until the instant they produced it: they arrive
- * from a campaign link, browse, and only become identifiable when they submit
- * a form, sign up, book or check out. There is no address to look up until
- * the very moment being attributed.
- *
- * So the touch is carried on the VISITOR (`utm-touch.ts`) and attached
- * here, at each moment they become somebody. What is NOT rebuilt is the
- * model: the same seven-day window, the same last-click rule, the same
- * `model`/`windowDays` stamped onto every record so a report can say what it
- * counted. The email channel is not re-derived either — it is READ from the
- * touch the delivery webhook already wrote, so a campaign email and a
- * campaign ad are two inputs to one comparison rather than two schemes with
- * two answers.
- *
- * ## Last touch, across both channels
- *
- * At the identify moment there can be two candidate touches:
- *
- *  - the WEB touch the visitor's device carried, from an ad, a partner link
- *    or a social post; and
- *  - the EMAIL touch on `emailDeliveries/{personKey}.campaignTouches[hostId]`,
- *    written server-side when they clicked a campaign's mail.
- *
- * Both are window-checked and the LATER one wins. Splitting the outcome
- * between them is the multi-touch model the revenue work rejected for the
- * reason that applies here unchanged: a rule the merchant did not choose
- * produces a figure nobody can check. One outcome, one campaign, and a rule
- * stated on the record.
- *
- * ## No campaign touch means NO RECORD
- *
- * Direct traffic writes nothing at all, and there is deliberately no fallback
- * — no "most recent campaign on this site", no referrer inference, no
- * `utm_source=direct`. A conversion nobody can be credited with is a
- * conversion nobody is credited with, and the absence of a record is how the
- * report says so. The cost of a miss is one uncounted outcome; the cost of a
- * guess is a campaign that reads as effective because it was the last one to
- * run.
- *
- * ## Three reads at most, and usually one
- *
- * Resolving a touch costs ONE keyed document read, and only when the visitor
- * gave an address — no query, no index, nothing that can be truncated. A door
- * resolves once per request and hands the result to every writer beneath it,
- * so a form submission that creates a submission, a contact and a lead pays
- * for the lookup once rather than three times.
- *
- * ## Never throws
- *
- * The same contract as the revenue join and for the same reason: the visitor
- * has already done the thing being attributed and the record of it is already
- * written. A lost attribution understates a campaign; a thrown one loses a
- * lead.
- */
-/**
- * The collection and the erasure sweep, re-exported so a caller needs one
- * import for the whole join. They are DEFINED in a leaf module because the
- * sweep runs from `email-delivery-log.ts`, which this file reads — see
- * `campaign-attribution-store.ts` for why that cycle is not merely untidy.
- */
-export { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey, };
-/** The single conversion rollup document under an email campaign. */
-export declare const CAMPAIGN_CONVERSIONS_REPORT_DOC = "conversions";
-/**
- * Which identify moment a record credits.
- *
- * Kept apart rather than summed, which is the whole reason the kind is on the
- * record. One form submission by a new person creates a submission, a contact
- * and possibly a lead — three true statements about one visitor action — and
- * a report that added them would treble every campaign's conversions. A
- * reader asks for one kind at a time, exactly as the revenue rollup buckets
- * by currency and never totals across them.
- */
-export type CampaignConversionKind = 'form' | 'lead' | 'contact' | 'booking';
-/**
- * Which channel the credited touch arrived through.
- *
- * `sequence` (AGL-3254) is a click on, or the sending of, a one-to-one
- * email a rep's sequence sent. It is read off the same touch map as the
- * email channel — the Outreach click route stamps it there with the
- * sequence and the enrollment beside the campaign the sequence is in — so
- * a booking made from a sequence link is credited by the door that credits
- * every other booking, and nothing in this join has to know what a
- * sequence is.
- */
-export type CampaignTouchChannel = 'email' | 'web' | 'sequence';
-/** The touch a conversion is credited to, once both channels have been asked. */
-export interface ResolvedCampaignTouch {
-    channel: CampaignTouchChannel;
-    /**
-     * The campaign document, when the touch was a click on our own mail — or
-     * the campaign CONTAINER (`emailCampaigns/{id}`) a sequence is in, for a
-     * sequence touch.
-     */
-    campaignId?: string;
-    /** The sequence the touch came through, for a `sequence` touch. */
-    sequenceId?: string;
-    /** The enrollment the touch came through, for a `sequence` touch. */
-    enrollmentId?: string;
-    /** `utm_source`, when the touch was a link on the web. */
-    source?: string;
-    /** `utm_medium`, when the touch was a link on the web. */
-    medium?: string;
-    /** `utm_campaign`, when the touch was a link on the web. */
-    campaign?: string;
-    /** When the visitor followed the campaign link, epoch ms. */
-    touchedAtMs: number;
-    /**
-     * `sha256` of the normalized address the touch was resolved against, when
-     * the visitor gave one. The handle an erasure erases by — see
-     * {@link eraseCampaignAttributionsForPersonKey}.
-     */
-    personKey?: string;
-}
-/** What one conversion attribution record holds. */
-export interface CampaignConversionRecord extends ResolvedCampaignTouch {
-    kind: CampaignConversionKind;
-    /** The submission, lead, contact or booking this credits. */
-    refId: string;
-    /** When the visitor became identifiable. */
-    convertedAtMs: number;
-    /** The model this credit was decided under. */
-    model: string;
-    /** The window, in days, it was decided inside. */
-    windowDays: number;
-}
-/**
- * The document id for one conversion.
- *
- * `{kind}:{refId}`, so the same submission credited twice is the same
- * document — which is what makes {@link attributeCampaignConversion}'s
- * `create()` idempotent. Scoped by kind because the ids come from different
- * collections and a booking id has no reason to be distinct from a form
- * submission's.
- */
-export declare function campaignConversionId(kind: CampaignConversionKind, refId: string): string;
-/**
- * The campaign touch to credit a conversion happening now, or `null`.
- *
- * Called ONCE per conversion request, at the door, and the result handed to
- * every writer beneath it. See the module docblock for the cost argument.
- *
- * @returns the winning touch, or `null` when neither channel has one inside
- *          the window — which is the ordinary case and writes nothing.
- */
-export declare function resolveCampaignTouch(options: {
-    hostId: string;
-    /**
-     * The wire form the conversion request carried, when the door reports
-     * one. Re-parsed through the allowlist that wrote it rather than trusted:
-     * it arrives from the visitor's browser, so it may claim no more than an
-     * inbound URL could.
-     */
-    wire?: unknown;
-    /** The address the visitor identified with, raw. */
-    email?: unknown;
-    /** When they identified themselves. Defaults to now. */
-    atMs?: number;
-}, firestore?: any): Promise<ResolvedCampaignTouch | null>;
-/**
- * Credits one conversion to the campaign the visitor last came from.
- *
- * ## Why the record is a document and not a field
- *
- * The revenue join's three reasons, and the first is decisive here too.
- * `create()` fails when the document already exists, which is exact
- * idempotency for free: a retried form POST, a redelivered booking webhook
- * and a re-run capture all land here a second time and must all leave the
- * rollup where they found it. Second, the four kinds live in four different
- * collections — a contact is org-scoped and shared across every site in the
- * org — so there is no one document a field could go on. Third, the
- * submission, the lead and the booking are read by the inbox, the export and
- * the fulfilment path, and none of them wants a field about marketing.
- *
- * ## The rollup exists for the EMAIL channel only
- *
- * A campaign document is a real entity with a real id, so its conversions
- * roll up under it beside the revenue the same join already credits it with.
- * A web campaign is a LABEL the marketer typed into a URL, with no document,
- * no id and no bound on how many distinct values exist — the same unbounded
- * key space the analytics collector caps its per-day label map against. A
- * rollup keyed on it would be a map anybody who can vary a query string can
- * grow. So the web channel's records stand on their own and a report reads
- * them; see the module's report seam note.
- *
- * @returns the record written, or `null` when nothing was credited.
- */
-export declare function attributeCampaignConversion(options: {
-    hostId: string;
-    kind: CampaignConversionKind;
-    /** The submission, lead, contact or booking being credited. */
-    refId: string;
-    /** The touch {@link resolveCampaignTouch} picked, or `null` for direct. */
-    touch: ResolvedCampaignTouch | null | undefined;
-    /** When the visitor became identifiable. Defaults to now. */
-    convertedAtMs?: number;
-}, firestore?: any): Promise<CampaignConversionRecord | null>;
-/**
- * The per-org collection of sequence rollups. Restated from the reader
- * (`campaign-report.ts` in the campaigns UI library, which this package may
- * not import) and asserted equal by the reader's spec.
- */
-export declare const CAMPAIGN_SEQUENCE_REPORTS_COLLECTION = "campaignSequenceReports";
-/** The outcomes the runtime credits, in funnel order. */
-export declare const CAMPAIGN_SEQUENCE_OUTCOMES: readonly ["enrolled", "sent", "replied", "meetings", "converted"];
-export type CampaignSequenceOutcome = (typeof CAMPAIGN_SEQUENCE_OUTCOMES)[number];
-/**
- * Credits one outcome, for one enrollment, to every campaign named.
- *
- * Never throws, and never refuses the batch for one bad id: the outcome
- * has already happened, and a campaign that is gone gains an orphaned
- * report rather than blocking the credit to one that is not — the
- * conversions rollup's own argument for a merge-set that creates.
- *
- * @returns how many campaigns were credited.
- */
-export declare function creditCampaignSequenceOutcome(options: {
-    /** The site the enrollment emails for; resolves the org when none is given. */
-    hostId: string;
-    /**
-     * The org whose containers the campaigns are, when the caller holds it —
-     * an enrollment is an org document, so its routes do. Saves the
-     * `hostIndex` read.
-     */
-    orgId?: string | null;
-    /** The campaigns the enrollment carries; unusable ids are skipped. */
-    campaignIds: readonly string[];
-    outcome: CampaignSequenceOutcome;
-    /** When the outcome happened. Defaults to now. */
-    atMs?: number;
-}, firestore?: any): Promise<number>;
-/** `orgs/{orgId}/campaigns/{sendId}`. */
-export declare function orgCampaignSendRef(orgId: string, sendId: string, firestore?: Firestore): DocumentReference;
-/** `orgs/{orgId}/campaignSequenceReports/{campaignId}`. */
-export declare function orgCampaignSequenceReportRef(orgId: string, campaignId: string, firestore?: Firestore): DocumentReference;
-export interface ResolveCampaignSendRefInput {
-    /** The site the link or the message tag names. */
-    hostId: string;
-    /** The send id (`cid` on a link, `campaignId` on a message tag). */
-    sendId: string;
-    /**
-     * The org, when the caller already has it — a message tag minted since
-     * AGL-3273 carries it. Saves the `hostIndex` read.
-     */
-    orgId?: string | null;
-    firestore?: Firestore;
-}
-/**
- * The send's document, wherever it currently is. Null when neither location
- * holds it — a send id from a link whose send was discarded, or a forged one.
- *
- * Costs one read after the migration (the org document), plus the
- * `hostIndex` lookup when the caller has no org id; that lookup is
- * request-cached.
- */
-export declare function resolveCampaignSendRef(input: ResolveCampaignSendRefInput): Promise<DocumentReference | null>;