@aglyn/plugins-marketing 1.0.0-beta.143

package/src/lib/components/campaign-reach-sections.d.ts

@@ -0,0 +1,137 @@
+export interface CampaignReachProps {
+    hostId: string;
+    /**
+     * The campaign's emails, by send id — the handle both collections join on.
+     *
+     * A stable array is not required: both sections key their reads on the
+     * joined string, so a caller rebuilding the array every render pays for one
+     * set of reads rather than one per render.
+     */
+    sendIds: readonly string[];
+    /** The campaign holds more emails than `sendIds` names. */
+    truncated: boolean;
+}
+/**
+ * WHAT THE CAMPAIGN CAUSED, counted rather than listed.
+ *
+ * Four aggregation counts over `campaignAttributions`, one per kind, each
+ * narrowed to this campaign's own sends. An aggregation is billed per
+ * thousand index entries rather than per document, so the honest figure costs
+ * about as much as a single row — which is what lets this run on mount
+ * instead of behind a button. Listing the records would not: that is the
+ * per-record read every figure on this page is arranged to avoid, and the
+ * site-wide Conversions section already lists them.
+ *
+ * The composite index the query needs — `kind` then `campaignId` — is already
+ * declared for the conversions list's own campaign-scoped view, and an `in`
+ * runs as a disjunction of equalities against that same index.
+ *
+ * ## The kinds are never added together
+ *
+ * One form submission by a new person writes a submission, a contact AND a
+ * lead: three true statements about one visit. A total would count that visit
+ * three times and would look exactly like a bigger number, so there is no
+ * total here and the note under the figures says why.
+ */
+export declare function CampaignConversionsSection(props: CampaignReachProps & {
+    /** The marketing hub URL, for the site-wide conversions list. */
+    basePath: string;
+}): import("react").JSX.Element;
+export declare namespace CampaignConversionsSection {
+    var displayName: string;
+}
+/**
+ * WHAT THE CAMPAIGN EARNED — per currency, and never across them.
+ *
+ * The same question a campaign of one email answers, answered the same way by
+ * a campaign of several: how many messages a container happens to hold is not
+ * a fact about whether its revenue is knowable. So this is the same section
+ * the single-send report carries — `Revenue`, in the same place in the page's
+ * order, drawn by the same money components — over a merge rather than over
+ * one document.
+ *
+ * ## Why it takes a merge, and what the merge may not do
+ *
+ * `reports/revenue` is written per SEND. There is no container-level rollup
+ * and there should not be one: it would have to be kept true against every
+ * order and every refund of every email in the campaign, duplicating figures
+ * that are already correct one level down. So the campaign's figure is one
+ * document per email and an addition — and the addition is the danger.
+ *
+ * **Currency is to money what kind is to a conversion.** The section above
+ * refuses to total form submissions with leads because one visit writes both;
+ * this refuses to total USD with EUR because the sum has no unit. Both
+ * refusals are structural rather than remembered:
+ * {@link campaignRevenueAcrossSends} keys its accumulator on the currency, so
+ * amounts in different currencies never reach the same addition, and the
+ * result carries no combined field for a screen to print.
+ *
+ * ## One currency reads as one figure; several read as several
+ *
+ * The common case is one currency, and it is drawn exactly as a single
+ * email's report draws it — net, gross, refunded, orders — with no currency
+ * heading, because a label saying `USD` over a page that only ever shows
+ * dollars is noise. The moment a second currency appears every block gets its
+ * code as a heading and its own email count, and a caveat says in words what
+ * the headings say in layout: these do not add up, and nothing here converts
+ * between them. The rare case pays for itself; the common one does not pay
+ * for the rare one.
+ *
+ * ## Behind a button, and the button says the price
+ *
+ * One document per email — the per-record read the conversions section above
+ * is shaped to avoid. That section can run on mount because an aggregation is
+ * billed per thousand index entries, so its four honest figures cost about as
+ * much as a single row however large the campaign is. This cannot: fifty
+ * emails is fifty document reads, every time the page opens, for a section
+ * most readers of a campaign are not opening the page for. So it is asked
+ * for, at the same control and in the same words as the destinations section
+ * below, which buys its rows the same way.
+ *
+ * ## Nothing, and nothing readable, are different sentences
+ *
+ * The rollup is created by the writer on the first order it credits, so an
+ * email with no record has never earned. A campaign where NO email has one
+ * has not been shown to have earned nothing — it is also every campaign sent
+ * before the join existed and every campaign on a site with no store, which
+ * is the distinction the single-send report draws in the same two sentences.
+ * A read that is REFUSED shows neither: the figures are withheld behind a
+ * warning, and any figures already on screen are dropped rather than left
+ * standing beside it, because a stale total under a fresh error is the one
+ * arrangement that looks authoritative and is not.
+ */
+export declare function CampaignRevenueSection(props: CampaignReachProps): import("react").JSX.Element;
+export declare namespace CampaignRevenueSection {
+    var displayName: string;
+}
+/**
+ * WHERE THE CAMPAIGN SENT PEOPLE — the pages its mail pointed at.
+ *
+ * The union of `campaigns/{sendId}/reports/links` across the campaign's
+ * emails, which is the closest the stored data comes to "the surfaces this
+ * campaign runs across". It is observed rather than declared: a page is on
+ * this list because a link in this campaign's mail was followed to it.
+ *
+ * ## Behind a button, and the button says the price
+ *
+ * One document per email, up to the ceiling the page holds — which is the
+ * per-record read the figures above are shaped to avoid, so it is asked for
+ * rather than paid on mount. The same bargain the conversions list makes for
+ * its landing-page grouping.
+ *
+ * ## What a row is, and what it is not
+ *
+ * A destination is the link's address with its query string dropped, because
+ * a campaign body is merged per recipient and a personalised query would mint
+ * one row per person — and could carry that person's address into an
+ * aggregate the whole team reads. The cost is that two links to one page
+ * distinguished only by their tracking parameters are one row, which the note
+ * under the table states rather than leaving the reader to discover.
+ *
+ * Clicks are EVENTS. One reader clicking twice counts twice, so a destination
+ * total is not a count of people.
+ */
+export declare function CampaignDestinationsSection(props: CampaignReachProps): import("react").JSX.Element;
+export declare namespace CampaignDestinationsSection {
+    var displayName: string;
+}