@aglyn/shared-ui-email-campaigns 1.0.0-beta.221 → 1.0.0-beta.223

package/README.md

@@ -1,6 +1,6 @@
 # @aglyn/shared-ui-email-campaigns
 
-The email-campaign document model, owned by none of the plugins that read it.
+The bulk-send reporting math, owned by none of the plugins that send in bulk.
 
 > Beta. Published from the Aglyn monorepo under the `beta` dist-tag; APIs can change between beta releases.
 
@@ -12,59 +12,38 @@ npm install @aglyn/shared-ui-email-campaigns@beta
 
 ## Why it is not in a plugin
 
-An email campaign is written by one plugin and reported by another. The
-Marketing plugin owns the `campaigns` console section; the Email plugin owns
-the message, template and list surfaces. Both are independently toggleable —
-`release_marketing` and `release_email` are separate flags in
-`libs/aglyn/src/lib/plugin-manager/enabled-plugins.ts` — so an organization
-can have either one without the other.
-
-A shape that lives inside one of them is therefore a shape the other reaches
-past a switch to get. Because every plugin compiles into the same console
-bundle, such an import resolves at runtime whether or not the owning plugin is
-enabled, and the plugin switchboard is bypassed silently rather than failing.
-Putting the shared half here makes both plugins peers of it: each depends on
-this library, neither depends on the other for a rate, a field name or a
-`<Figure>`.
-
-The boundary is enforced in
-`libs/plugins/marketing/src/lib/plugin-email-boundary.spec.ts`, which fails if
-Marketing re-acquires an import of anything this library owns from
-`@aglyn/plugins-email`.
+Two plugins mail in bulk and report what their mail did: the Marketing plugin
+sends campaigns, and the Outreach plugin runs one-to-one sequences. Each send
+records the same counters — sent, delivered, opens, clicks, bounces — and each
+report divides them. A rate taken in two places is a rate that drifts: one
+reader divides opens by `sent`, the other by `delivered`, and the same mail
+reads two ways. So the division lives here, once, and both plugins are its
+peers; neither imports the other.
 
 ## The model only
 
 ```typescript
 // Pure. No React, no MUI — safe in a /server handler.
-import {
-  campaignReport,
-  CAMPAIGN_SEND_CONTAINER_FIELD,
-} from '@aglyn/shared-ui-email-campaigns/model'
+import { sendRate, sendLinkReport, type SendStats } from '@aglyn/shared-ui-email-campaigns/model'
 ```
 
 The library renders nothing. The figure renderers live in
-`@aglyn/shared-ui-jsx`, and the control that files a record under a campaign
-is the core's generic `ContainerPicker` (`@aglyn/tenant-feature-instance`),
-handed the `campaign` kind the Marketing plugin declares.
+`@aglyn/shared-ui-jsx`.
 
 ## What is here
 
-| Module                      | Answers                                                                           |
-| --------------------------- | --------------------------------------------------------------------------------- |
-| `model/campaign-container`  | The campaign's window, its lists, its sends, and the rollup across them           |
-| `model/campaign-report`     | The rate math, the population each rate describes, and the link rollup            |
-| `model/email-record`        | One message: its state, its audience, and when it went out                        |
+| Module              | Answers                                                                                   |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `model/send-report` | A send's stored counters, a rate with its denominator named, and the per-link click rollup |
 
 ## What is not here
 
-What a campaign caused and earned — the conversions it is credited with and
-its revenue per currency. Only the Marketing plugin reads them, so they are
-its model (`libs/plugins/marketing/src/lib/model/`), not a shape two plugins
-share.
-
-Sending. The send loop, the composer, the topic subscriptions and the
-send-time API all stay in `@aglyn/plugins-email`: they are behavior that the
-Email plugin's switch is supposed to govern, not shapes that two plugins share.
+A campaign's own model (AGL-3080): its container and window, a send's report
+and the populations it measured, a message's record, what a design's sends
+did, and what a campaign caused and earned. Only the Marketing plugin reads
+them, so they are its model (`libs/plugins/marketing/src/lib/model/`), not a
+shape two plugins share. The Email plugin's template page shows what a
+design's sends did through a zone the Marketing plugin fills.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-ui-email-campaigns",
-  "version": "1.0.0-beta.221",
+  "version": "1.0.0-beta.223",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -29,8 +29,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.221",
-    "@aglyn/shared-util-email": "1.0.0-beta.221",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.223",
+    "@aglyn/shared-util-email": "1.0.0-beta.223",
     "@swc/helpers": "0.5.23"
   },
   "peerDependencies": {

package/src/lib/model/index.d.ts

@@ -15,24 +15,14 @@
  * limitations under the License.
  */
 /**
- * The email-campaign document model: the stored shapes and the pure
- * arithmetic over them.
+ * The bulk-send reporting math: a send's stored counters, the rate a figure
+ * is taken as (always with its denominator named), and the link rollup.
  *
- * Nothing here imports React or MUI, so a server handler that needs a field
- * name or a rate can take this barrel without dragging a component graph
- * into its bundle. The renderers live one directory over, behind
+ * Generic to every plugin that mails in bulk — the campaign sender, the
+ * sequence runner — and owned by none of them (AGL-3080). Nothing here
+ * imports React or MUI, so a server handler that needs a rate can take this
+ * barrel without dragging a component graph into its bundle. The renderers
+ * live one directory over, behind
  * `@aglyn/shared-ui-jsx/components/measured-figures.component`.
  */
-/**
- * Campaign reporting: the rate math, the populations the send recorded, and
- * the link rollup — pure, so every denominator is named once and provable
- * rather than chosen in JSX.
- */
-export * from './campaign-report';
-/** Reading one message record — its state, and when it went out. */
-export * from './email-record';
-/**
- * The campaign CONTAINER — its window, its lists, and the arithmetic that
- * rolls its sends into one set of figures.
- */
-export * from './campaign-container';
+export * from './send-report';

package/src/lib/model/index.js

@@ -14,22 +14,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ /**
- * The email-campaign document model: the stored shapes and the pure
- * arithmetic over them.
+ * The bulk-send reporting math: a send's stored counters, the rate a figure
+ * is taken as (always with its denominator named), and the link rollup.
  *
- * Nothing here imports React or MUI, so a server handler that needs a field
- * name or a rate can take this barrel without dragging a component graph
- * into its bundle. The renderers live one directory over, behind
+ * Generic to every plugin that mails in bulk — the campaign sender, the
+ * sequence runner — and owned by none of them (AGL-3080). Nothing here
+ * imports React or MUI, so a server handler that needs a rate can take this
+ * barrel without dragging a component graph into its bundle. The renderers
+ * live one directory over, behind
  * `@aglyn/shared-ui-jsx/components/measured-figures.component`.
- */ /**
- * Campaign reporting: the rate math, the populations the send recorded, and
- * the link rollup — pure, so every denominator is named once and provable
- * rather than chosen in JSX.
- */ export * from "./campaign-report.js";
-/** Reading one message record — its state, and when it went out. */ export * from "./email-record.js";
-/**
- * The campaign CONTAINER — its window, its lists, and the arithmetic that
- * rolls its sends into one set of figures.
- */ export * from "./campaign-container.js";
+ */ export * from "./send-report.js";
 
 //# sourceMappingURL=index.js.map

package/src/lib/model/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../libs/shared/ui/email-campaigns/src/lib/model/index.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 email-campaign document model: the stored shapes and the pure\n * arithmetic over them.\n *\n * Nothing here imports React or MUI, so a server handler that needs a field\n * name or a rate can take this barrel without dragging a component graph\n * into its bundle. The renderers live one directory over, behind\n * `@aglyn/shared-ui-jsx/components/measured-figures.component`.\n */\n\n/**\n * Campaign reporting: the rate math, the populations the send recorded, and\n * the link rollup — pure, so every denominator is named once and provable\n * rather than chosen in JSX.\n */\nexport * from './campaign-report'\n\n/** Reading one message record — its state, and when it went out. */\nexport * from './email-record'\n\n/**\n * The campaign CONTAINER — its window, its lists, and the arithmetic that\n * rolls its sends into one set of figures.\n */\nexport * from './campaign-container'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,GAED;;;;CAIC,GACD,cAAc,uBAAmB;AAEjC,kEAAkE,GAClE,cAAc,oBAAgB;AAE9B;;;CAGC,GACD,cAAc,0BAAsB"}
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/email-campaigns/src/lib/model/index.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 bulk-send reporting math: a send's stored counters, the rate a figure\n * is taken as (always with its denominator named), and the link rollup.\n *\n * Generic to every plugin that mails in bulk — the campaign sender, the\n * sequence runner — and owned by none of them (AGL-3080). Nothing here\n * imports React or MUI, so a server handler that needs a rate can take this\n * barrel without dragging a component graph into its bundle. The renderers\n * live one directory over, behind\n * `@aglyn/shared-ui-jsx/components/measured-figures.component`.\n */\nexport * from './send-report'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;CAUC,GACD,cAAc,mBAAe"}

package/src/lib/model/{campaign-report.d.ts → send-report.d.ts}

@@ -15,11 +15,17 @@
  * limitations under the License.
  */
 /**
- * CAMPAIGN REPORTING MATH — the only place a rate is computed.
+ * BULK SEND REPORTING MATH — the only place a rate is computed.
+ *
+ * Owned by none of the plugins that read it: the plugin that sends a
+ * campaign, the one that keeps the email templates a send is built from and
+ * the one that runs one-to-one sequences all report what their mail did, and
+ * each divides the same counters a send records. Putting the division here
+ * makes them peers of one rule rather than three copies of it.
  *
  * ## Why a pure module and not a component
  *
- * Every number on the report screen is a division, and a division is where
+ * Every number on a report screen is a division, and a division is where
  * email reporting goes wrong. Putting the arithmetic in JSX means the
  * denominator is chosen by whoever writes the next card, in a file nobody
  * tests for arithmetic; putting it here means each rate is named once,
@@ -32,47 +38,47 @@
  * rate over `delivered` are different numbers with the same label, and the
  * gap between them is exactly the mail that bounced. The industry convention
  * is over `delivered`, and a report that quietly used `sent` would read
- * higher than the same campaign measured anywhere else.
+ * higher than the same send measured anywhere else.
  *
- * So {@link CampaignRate} carries `denominatorLabel`, and the screen is
- * required to render it. There is no overload that omits it.
+ * So {@link SendRate} carries `denominatorLabel`, and the screen is required
+ * to render it. There is no overload that omits it.
  *
  * ## Why some rates are deliberately absent
  *
- * {@link campaignRate} answers `null`, not zero, when it cannot divide:
+ * {@link sendRate} answers `null`, not zero, when it cannot divide:
  *
  *  - **A zero denominator.** 0 opens out of 0 delivered is not a 0% open
  *    rate, it is no open rate. Rendering 0% invites the reader to compare it
- *    with a campaign that really did fail.
+ *    with a send that really did fail.
  *  - **An UNKNOWN denominator.** `delivered` is counted by the delivery
- *    webhook, which was connected after some campaigns were sent. A campaign
- *    with 400 sends and no delivery events has an unknown denominator, not a
+ *    webhook, which was connected after some sends went out. A send with 400
+ *    messages and no delivery events has an unknown denominator, not a
  *    denominator of zero — and dividing by `sent` instead is precisely the
  *    flattering substitution above.
  *
  * ## The structural-zero window
  *
  * Click tracking rewrites links in the HTML part. Sends that carried no HTML
- * part were therefore untrackable, and every one of those campaigns reports 0
- * clicks whatever the recipients actually did — a real 0 and a structural 0
+ * part were therefore untrackable, and every one of them reports 0 clicks
+ * whatever the recipients actually did — a real 0 and a structural 0
  * rendered identically. `send-email.ts` now synthesises an HTML part for a
- * text-only send, so every send after that carries one, and
- * `campaign-send.ts` records {@link CampaignStats.clickTracked} to say so.
- *
- * A campaign with no such marker predates the record. Its click COUNT is
- * still shown — it is a real count of real events — but no click RATE is
- * computed from it, because a rate presents the number as a measurement of
- * the audience and for those campaigns it is a measurement of the sender.
+ * text-only send, so every send after that carries one, and the sender
+ * records {@link SendStats.clickTracked} to say so. A send with no such
+ * marker predates the record: its click COUNT is still shown — it is a real
+ * count of real events — but no click RATE is computed from it, because a
+ * rate presents the number as a measurement of the audience and for those
+ * sends it is a measurement of the sender.
  */
 /**
- * The `stats` map on `hosts/{hostId}/campaigns/{campaignId}`.
+ * The `stats` map one bulk send keeps — a campaign send's on
+ * `orgs/{orgId}/campaigns/{sendId}`.
  *
  * Every field is optional and every reader defaults it, because these are
  * written by three different writers at three different times — the send, the
  * delivery webhook, the unsubscribe handler — and a campaign is a legitimate,
  * readable document from the instant the first of them lands.
  */
-export interface CampaignStats {
+export interface SendStats {
     /** The whole audience the send was taken from, before the per-send cap. */
     audienceSize?: number;
     /** `audienceSize` is a FLOOR: audience resolution hit its read ceiling. */
@@ -139,7 +145,7 @@ export interface CampaignStats {
  * numbers called "open rate" distinguishable, and the screen renders it
  * beside the percentage for that reason.
  */
-export interface CampaignRate {
+export interface SendRate {
     /** 0–1. Multiply for display; the model never formats. */
     value: number;
     numerator: number;
@@ -153,98 +159,16 @@ export interface CampaignRate {
  * `null` on a zero or unknown denominator — see the module header for why
  * that is not the same as 0%.
  */
-export declare function campaignRate(numerator: number | undefined, denominator: number | undefined, denominatorLabel: string): CampaignRate | null;
-/** Why a number the report would otherwise show is being withheld. */
-export interface CampaignCaveat {
-    /** Stable id, so a spec can assert on the caveat rather than its prose. */
-    id: 'delivery-unrecorded' | 'click-tracking-unrecorded' | 'audience-truncated' | 'send-deferred' | 'revenue-denominator-unrecorded' | 'revenue-multi-currency' | 'revenue-mid-flight' | 'revenue-mixed-model' | 'conversions-kinds-overlap' | 'conversions-web-not-rolled-up' | 'conversions-unattributed-is-a-ceiling' | 'conversions-total-crosses-hosts' | 'sequences-funnel-not-summed';
-    message: string;
-}
-/** One population the send measured, for the audience breakdown. */
-export interface CampaignPopulation {
-    id: string;
-    label: string;
-    count: number;
-    /** What this count is a part OF, named. */
-    ofLabel: string;
-    of: number;
-}
-/** Everything the report screen renders, decided here rather than in JSX. */
-export interface CampaignReport {
-    sent: number;
-    recipients: number;
-    delivered: number | null;
-    opens: number;
-    clicks: number;
-    uniqueOpens: number | null;
-    uniqueClicks: number | null;
-    bounced: number;
-    complained: number;
-    unsubscribes: number;
-    /** Rates, each `null` when its denominator is zero or unrecorded. */
-    rates: {
-        /** Accepted by the receiving server, over what the provider accepted. */
-        delivery: CampaignRate | null;
-        /** Distinct readers who opened, over delivered. */
-        open: CampaignRate | null;
-        /** Distinct readers who clicked, over delivered. */
-        click: CampaignRate | null;
-        /**
-         * Distinct clickers over distinct OPENERS — a different question from
-         * `click`, and the one the two get confused for. It answers "of the
-         * people who read it, how many acted", not "of the people who received
-         * it". Reported separately and labelled separately, never as "click
-         * rate".
-         */
-        clickToOpen: CampaignRate | null;
-        /** Bounced over what the provider accepted. */
-        bounce: CampaignRate | null;
-        /** Complaints over delivered — the number mailbox providers judge on. */
-        complaint: CampaignRate | null;
-        /** Unsubscribes through this campaign's link, over delivered. */
-        unsubscribe: CampaignRate | null;
-    };
-    populations: CampaignPopulation[];
-    caveats: CampaignCaveat[];
-}
-/**
- * Turns a stored `stats` map into the report.
- *
- * ## The denominator decisions, in one place
- *
- * - **`delivered`** carries the engagement rates — open, click, complaint,
- *   unsubscribe. Mail that bounced was never in front of a human, so
- *   including it in the denominator of an open rate depresses a number that
- *   describes the audience with a fact about the address list. This is also
- *   the convention every other tool reports, which matters: a merchant
- *   comparing our figure with their previous ESP's must be comparing the same
- *   quantity.
- * - **`sent`** carries the delivery and bounce rates, because those describe
- *   what happened to what we handed the provider, and `delivered` is the
- *   numerator of one of them — a rate cannot be over itself.
- * - **`uniqueOpens`** is the open-rate numerator, not `opens`. Open EVENTS
- *   over recipients can exceed 100% the moment one person opens twice, and a
- *   percentage above 100 is how a reader learns the number means something
- *   other than what it says. Both are shown; only the distinct count is
- *   divided.
- *
- * ## `delivered` unknown vs. zero
- *
- * A campaign predating the delivery webhook records no `delivered` at all.
- * That is reported as `null` and every rate over it is withheld, with a
- * caveat naming the reason — rather than substituting `sent`, which would
- * silently publish the flattered number this module exists to refuse.
- */
-export declare function campaignReport(stats: CampaignStats | undefined): CampaignReport;
+export declare function sendRate(numerator: number | undefined, denominator: number | undefined, denominatorLabel: string): SendRate | null;
 /**
  * How many distinct destinations one campaign's rollup keeps.
  *
  * A CAP rather than a page size, and it exists because the map lives in a
  * single document with a 1 MiB ceiling. Clicks past the cap are counted in
- * {@link CampaignLinkRollup.overflowClicks} rather than dropped, so the
+ * {@link SendLinkRollup.overflowClicks} rather than dropped, so the
  * table's total still reconciles with `stats.clicks`.
  */
-export declare const CAMPAIGN_LINK_ROLLUP_MAX = 50;
+export declare const SEND_LINK_ROLLUP_MAX = 50;
 /**
  * Reduces a clicked URL to the key the rollup counts under.
  *
@@ -269,29 +193,29 @@ export declare const CAMPAIGN_LINK_ROLLUP_MAX = 50;
  * @returns the normalized URL, or `null` for anything unparseable or not
  *          http(s). A rollup key must be a URL a merchant recognises.
  */
-export declare function campaignLinkKey(link: string | null | undefined): string | null;
+export declare function sendLinkKey(link: string | null | undefined): string | null;
 /** One destination in the rollup. */
-export interface CampaignLinkRow {
+export interface SendLinkRow {
     url: string;
     /** Click EVENTS on this destination. One reader clicking twice counts two. */
     clicks: number;
     /** Share of the campaign's counted link clicks. */
-    share: CampaignRate | null;
+    share: SendRate | null;
 }
 /** The stored shape of `campaigns/{campaignId}/reports/links`. */
-export interface CampaignLinkRollup {
+export interface SendLinkRollup {
     links?: Record<string, {
         url?: string;
         clicks?: number;
     }>;
-    /** Clicks on destinations past {@link CAMPAIGN_LINK_ROLLUP_MAX}. */
+    /** Clicks on destinations past {@link SEND_LINK_ROLLUP_MAX}. */
     overflowClicks?: number;
     /** Click events that arrived carrying no destination at all. */
     unattributedClicks?: number;
 }
 /** What the link table renders. */
-export interface CampaignLinkReport {
-    rows: CampaignLinkRow[];
+export interface SendLinkReport {
+    rows: SendLinkRow[];
     /** Clicks counted against a named destination — the table's total. */
     attributedClicks: number;
     overflowClicks: number;
@@ -308,53 +232,4 @@ export interface CampaignLinkReport {
  * that are not on screen is the kind of arithmetic a reader cannot check.
  * Both excluded figures are returned so the screen can state them.
  */
-export declare function campaignLinkReport(rollup: CampaignLinkRollup | undefined): CampaignLinkReport;
-/**
- * The outcomes the runtime credits, in funnel order. An array first, because
- * the ORDER is the reading order and a second list is a second chance to
- * leave one out; the union is derived from it.
- */
-export declare const CAMPAIGN_SEQUENCE_OUTCOMES: readonly ["enrolled", "sent", "replied", "meetings", "converted"];
-export type CampaignSequenceOutcome = (typeof CAMPAIGN_SEQUENCE_OUTCOMES)[number];
-/**
- * The org collection holding one document per campaign container,
- * `orgs/{orgId}/campaignSequenceReports/{campaignId}`.
- */
-export declare const CAMPAIGN_SEQUENCE_REPORTS_COLLECTION = "campaignSequenceReports";
-/** What a reader calls each outcome, and what the count means. */
-export declare const CAMPAIGN_SEQUENCE_OUTCOME_COPY: Readonly<Record<CampaignSequenceOutcome, {
-    label: string;
-    note: string;
-}>>;
-/**
- * The stored shape of `campaignSequenceReports/{campaignId}`.
- *
- * Read-side only, every field optional: another plugin's runtime wrote it,
- * and a reader that assumed a field was present would throw on the first
- * document written before the field existed.
- */
-export interface CampaignSequencesRollup {
-    byOutcome?: Partial<Record<CampaignSequenceOutcome, number>>;
-    /** When the runtime last credited anything, epoch ms. */
-    updatedAtMs?: number;
-}
-/** One outcome's figure on screen. */
-export interface CampaignSequenceFigure {
-    outcome: CampaignSequenceOutcome;
-    label: string;
-    /** The count, or `null` when the rollup holds no entry for the outcome. */
-    value: number | null;
-    note: string;
-}
-/** Everything the Sequences section renders. */
-export interface CampaignSequencesReport {
-    /** Always all five, always in {@link CAMPAIGN_SEQUENCE_OUTCOMES} order. */
-    figures: CampaignSequenceFigure[];
-    /** Whether the rollup document exists at all — see the block header. */
-    recorded: boolean;
-    /** At least one outcome holds a figure. */
-    any: boolean;
-    caveats: CampaignCaveat[];
-}
-/** Turns the stored rollup into the Sequences section. */
-export declare function campaignSequencesReport(rollup: CampaignSequencesRollup | undefined): CampaignSequencesReport;
+export declare function sendLinkReport(rollup: SendLinkRollup | undefined): SendLinkReport;