@aglyn/shared-ui-email-campaigns 1.0.0-beta.143

package/src/lib/model/campaign-revenue.js

@@ -0,0 +1,332 @@
+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.
+ */ /*
+ * The window and the model name come from `@aglyn/shared-util-email`, not
+ * from here. The writer is in `tenant-data-admin`, which may not import a
+ * feature plugin, and a window defined on both sides of the join would drift
+ * into a number credited under one rule and printed under another.
+ */ import { EMAIL_ATTRIBUTION_MODEL, EMAIL_ATTRIBUTION_WINDOW_DAYS } from "@aglyn/shared-util-email";
+import { campaignRate } from "./campaign-report.js";
+/**
+ * WHAT A CAMPAIGN EARNED — the read half of the commerce↔email join.
+ *
+ * ## Why this is a join and not an attribution model
+ *
+ * Every compared ESP reconstructs campaign revenue probabilistically, because
+ * none of them owns the order. Klaviyo and Mailchimp watch someone else's
+ * store through an integration and a browser snippet, so their figure is a
+ * reconciliation against a foreign system and their window is the fudge
+ * factor that makes the reconciliation close. Commerce here is first-party:
+ * the click and the order are rows in one database, keyed the same way, so
+ * the "attribution" is a lookup.
+ *
+ * That does not make the MODEL choice go away — two campaigns can both have
+ * touched a buyer and only one can be credited — but it does mean the model
+ * is the only judgement in the number. There is no sampling, no identity
+ * resolution and no cookie.
+ *
+ * ## The model: LAST CLICK, inside a fixed 7-day window
+ *
+ * Stated in one sentence, which is the whole requirement: **an order is
+ * credited to the last campaign whose link the buyer clicked, if they clicked
+ * it within the {@link EMAIL_ATTRIBUTION_WINDOW_DAYS} days before they
+ * ordered.**
+ *
+ * Three decisions are inside that sentence.
+ *
+ * **Last touch, not multi-touch.** Multi-touch is the more honest description
+ * of how buying works and it is unpresentable: it splits one order across
+ * several campaigns by a rule the merchant did not choose, so no campaign's
+ * revenue is a number they can check against their own bank, and two
+ * campaigns' figures cannot be added or compared without knowing the split
+ * rule. HubSpot ships multi-touch and puts it behind an Enterprise plan and a
+ * consultant. A figure a merchant cannot explain to themselves is worse than
+ * no figure, and it is worse in the specific way that matters here: they will
+ * still make decisions with it.
+ *
+ * **A CLICK is the touch. An open is not.** An open is evidence about the
+ * recipient's mail client, not about the recipient — Apple's Mail Privacy
+ * Protection prefetches images, which inflated network-wide open rates by
+ * roughly 15% and means a large share of recorded opens had no human behind
+ * them. Crediting revenue to an open would therefore credit campaigns for
+ * orders from people who never saw them, and the error is not random: it
+ * concentrates on whichever campaign most recently reached an Apple Mail
+ * user. `email-delivery-log.ts` records the same preference for the same
+ * reason, and the audience rules already segment on clicks over opens.
+ *
+ * **Seven days, and not configurable.** Klaviyo's window is 1–30 days per
+ * channel; ActiveCampaign's is a fixed, unadjustable 7. Fixed is the better
+ * default here because a configurable window is a setting whose change
+ * silently rewrites history: yesterday's report and today's would disagree
+ * about a campaign that has not been touched since, with nothing on screen to
+ * say why. The stored record carries `windowDays` per order for exactly that
+ * reason — a future setting can be added without making the orders already
+ * attributed unreadable, because each one says which window it was judged
+ * under.
+ *
+ * ## GROSS and REFUNDED, never a decrement
+ *
+ * A refunded order must stop counting as revenue a campaign earned, and there
+ * are two ways to make it stop. Decrementing the gross figure makes a stored
+ * number mean one thing before a refund and another after, with nothing to
+ * distinguish them; recording the reversal beside it keeps both facts. This
+ * is the shape `contact-refund.ts` chose for `ltvCents`/`refundedCents` on the
+ * contact and the orders CSV chose for `amountUsd`/`refundedUsd`, and it is
+ * chosen again here so all three answer "what did this earn, net" the same
+ * way.
+ *
+ * So {@link campaignRevenueReport} reports gross, refunded and net, and NET
+ * is the figure the screen leads with. Net is clamped at zero for display
+ * only: a refund larger than the sale it reverses is arithmetically possible
+ * on an order attributed before a partial refund settled, and a negative
+ * campaign revenue is a sentence nobody can act on.
+ *
+ * ## Currencies are never summed
+ *
+ * Money is stored in minor units and no currency travels with it — every
+ * checkout door in this repo sets `currency: 'usd'` on the Stripe line items,
+ * so the amounts really are all USD, but that is a fact about the code rather
+ * than a field on the order. The rollup therefore buckets BY currency and
+ * this module never adds two buckets together. A campaign with two currencies
+ * renders two blocks and no total, and says so.
+ *
+ * The rule survives the merge across a container's emails.
+ * {@link campaignRevenueAcrossSends} keys its accumulator on the currency, so
+ * two rollups can only ever meet inside a bucket they already share — there
+ * is no code path in which a USD amount and a EUR amount reach the same
+ * addition, and no combined figure exists for a screen to print by accident.
+ */ /**
+ * Re-exported so a reader of the report has the window and the model name
+ * without reaching past this module for them — the screen prints both, and a
+ * window nobody can see is a window nobody can check.
+ */ export { EMAIL_ATTRIBUTION_MODEL, EMAIL_ATTRIBUTION_WINDOW_DAYS, EMAIL_ATTRIBUTION_WINDOW_MS } from "@aglyn/shared-util-email";
+/**
+ * Why there is no total, in the words both reports use.
+ *
+ * One sentence, one definition. A send's report and its campaign's report
+ * make the same refusal for the same reason, and two copies of the sentence
+ * is how one of them comes to be softened into a promise of a total.
+ */ export const REVENUE_MULTI_CURRENCY_MESSAGE = 'This campaign earned in more than one currency. Each is reported on its ' + 'own — nothing here converts between them, so there is deliberately no ' + 'combined total.';
+/** A stored count as a non-negative integer. */ function count(raw) {
+    const value = Math.floor(Number(raw != null ? raw : 0));
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Money per message, or `null` when the division cannot honestly be taken.
+ *
+ * The three refusals are {@link campaignRate}'s, and this defers to it rather
+ * than restating them: a zero denominator, an unrecorded denominator, and a
+ * non-finite input all answer `null` there, so a second implementation of
+ * "when may we divide" cannot drift from the first.
+ */ export function campaignMoneyPerMessage(numeratorCents, denominator, denominatorLabel, currency) {
+    const divisible = campaignRate(numeratorCents, denominator, denominatorLabel);
+    if (!divisible) return null;
+    return {
+        cents: divisible.value,
+        numeratorCents: divisible.numerator,
+        denominator: divisible.denominator,
+        denominatorLabel,
+        currency
+    };
+}
+/**
+ * Turns the stored rollup into the revenue section.
+ *
+ * `delivered` comes from the campaign's own `stats` and is passed in rather
+ * than re-read, so the numerator and the denominator on screen are taken from
+ * the same instant. It is `null` when no delivery event has ever been
+ * recorded — the campaign predates the delivery webhook, or the events are
+ * still in flight — and every figure over it is then withheld with a caveat,
+ * never substituted for `sent`.
+ */ export function campaignRevenueReport(options) {
+    var _ref, _ref1;
+    const { rollup, delivered, midFlight } = options;
+    const stored = (_ref = rollup == null ? void 0 : rollup.byCurrency) != null ? _ref : {};
+    const caveats = [];
+    const currencies = Object.entries(stored).map(([currency, totals])=>{
+        const grossCents = count(totals == null ? void 0 : totals.grossCents);
+        const refundedCents = count(totals == null ? void 0 : totals.refundedCents);
+        /*
+       * CLAMPED, and only here at the point of display.
+       *
+       * Both stored figures are monotonic counters of money that really
+       * moved in one direction, so neither can be negative; their DIFFERENCE
+       * can be, for one reason — an order credited to a campaign and then
+       * refunded by more than the amount that was credited, which happens
+       * when a partial refund settles against an order whose attributed
+       * amount was the charge at the time. Clamping at write time would
+       * erase the evidence; clamping at read time keeps the stored pair
+       * intact and stops the screen printing a campaign with negative
+       * earnings, which is not a sentence anybody can act on.
+       */ const netCents = Math.max(0, grossCents - refundedCents);
+        return {
+            currency,
+            grossCents,
+            refundedCents,
+            netCents,
+            orders: count(totals == null ? void 0 : totals.orders),
+            refundedOrders: count(totals == null ? void 0 : totals.refundedOrders),
+            netPerDelivered: campaignMoneyPerMessage(netCents, delivered != null ? delivered : undefined, 'delivered', currency)
+        };
+    }).filter((entry)=>entry.orders > 0 || entry.grossCents > 0).sort((a, b)=>b.netCents - a.netCents || a.currency.localeCompare(b.currency));
+    const attributedOrders = currencies.reduce((total, entry)=>total + entry.orders, 0);
+    const multiCurrency = currencies.length > 1;
+    if (delivered === null && currencies.length) {
+        caveats.push({
+            id: 'revenue-denominator-unrecorded',
+            message: 'No delivery events have been recorded for this campaign, so revenue ' + 'per delivered message cannot be computed. The amounts below are ' + 'still real.'
+        });
+    }
+    if (multiCurrency) {
+        caveats.push({
+            id: 'revenue-multi-currency',
+            message: REVENUE_MULTI_CURRENCY_MESSAGE
+        });
+    }
+    if (midFlight && currencies.length) {
+        caveats.push({
+            id: 'revenue-mid-flight',
+            message: 'This campaign is still going out. Revenue and delivered messages ' + 'are both still rising, so every figure below is a running total ' + 'rather than a final one.'
+        });
+    }
+    return {
+        currencies,
+        attributedOrders,
+        recorded: rollup !== undefined,
+        multiCurrency,
+        model: String((_ref1 = rollup == null ? void 0 : rollup.model) != null ? _ref1 : EMAIL_ATTRIBUTION_MODEL),
+        windowDays: count(rollup == null ? void 0 : rollup.windowDays) || EMAIL_ATTRIBUTION_WINDOW_DAYS,
+        caveats
+    };
+}
+/**
+ * MERGES A CAMPAIGN'S EMAILS INTO ONE REVENUE SECTION, per currency.
+ *
+ * `reports/revenue` is written per SEND, so a container's figure is one
+ * document per email and a merge. The merge is the whole risk: two emails of
+ * one campaign can have earned in different currencies, and adding their
+ * amounts produces a number that is wrong with nothing on screen to show it.
+ *
+ * ## The currency is the accumulator's KEY, not a field beside the amount
+ *
+ * That is the structural half of the guarantee. Amounts are added into a map
+ * keyed by currency, so two amounts can only reach the same addition when
+ * they already carry the same code — a USD figure and a EUR figure have no
+ * path to each other, whatever a later caller asks for. There is no combined
+ * field on the result, so a screen cannot print a cross-currency total by
+ * reading the wrong property, and
+ * {@link CampaignRevenueAcrossSends.multiCurrency} is what tells the screen
+ * to label the blocks.
+ *
+ * ## Clamped ONCE, over the campaign
+ *
+ * The single-send report clamps its net at zero because a partial refund can
+ * settle against an order credited at the full charge. Doing that per email
+ * and then summing would let one over-refunded email keep money a sibling
+ * email handed back — an email at -$50 clamped to $0 beside one at $200 would
+ * report $200 for a campaign holding $150. So gross and refunded are summed
+ * as they stand and the difference is clamped once, at the end.
+ *
+ * ## No per-message average, deliberately
+ *
+ * The send report divides net revenue by that send's own `delivered`, taken
+ * from the same document at the same instant. A container has no such pair.
+ * Its delivery total is summed over the emails that RECORDED a delivery count
+ * and its revenue over the emails that have a revenue record, and those are
+ * different subsets of the campaign — so the quotient would be an average
+ * over a population nobody named, which is the defect the whole reporting
+ * surface is built to refuse. The amounts are reported without one.
+ *
+ * @param rollups - one entry per email read, `undefined` where no record
+ * exists.
+ */ export function campaignRevenueAcrossSends(rollups) {
+    const byCurrency = new Map();
+    const models = new Set();
+    const windows = new Set();
+    let recorded = 0;
+    for (const rollup of rollups){
+        var _rollup_model, _rollup_byCurrency;
+        if (!rollup) continue;
+        recorded += 1;
+        models.add(String((_rollup_model = rollup.model) != null ? _rollup_model : EMAIL_ATTRIBUTION_MODEL));
+        windows.add(count(rollup.windowDays) || EMAIL_ATTRIBUTION_WINDOW_DAYS);
+        for (const [code, stored] of Object.entries((_rollup_byCurrency = rollup.byCurrency) != null ? _rollup_byCurrency : {})){
+            var _byCurrency_get;
+            const currency = String(code).trim().toLowerCase();
+            if (!currency) continue;
+            const entry = (_byCurrency_get = byCurrency.get(currency)) != null ? _byCurrency_get : {
+                currency,
+                grossCents: 0,
+                refundedCents: 0,
+                netCents: 0,
+                orders: 0,
+                refundedOrders: 0,
+                emails: 0
+            };
+            entry.grossCents += count(stored == null ? void 0 : stored.grossCents);
+            entry.refundedCents += count(stored == null ? void 0 : stored.refundedCents);
+            entry.orders += count(stored == null ? void 0 : stored.orders);
+            entry.refundedOrders += count(stored == null ? void 0 : stored.refundedOrders);
+            // One rollup holds at most one bucket per currency, so this counts
+            // EMAILS that earned in it rather than orders.
+            entry.emails += 1;
+            byCurrency.set(currency, entry);
+        }
+    }
+    const currencies = [
+        ...byCurrency.values()
+    ].map((entry)=>_extends({}, entry, {
+            netCents: Math.max(0, entry.grossCents - entry.refundedCents)
+        })).filter((entry)=>entry.orders > 0 || entry.grossCents > 0).sort((a, b)=>b.netCents - a.netCents || a.currency.localeCompare(b.currency));
+    const multiCurrency = currencies.length > 1;
+    const caveats = [];
+    if (multiCurrency) {
+        caveats.push({
+            id: 'revenue-multi-currency',
+            message: REVENUE_MULTI_CURRENCY_MESSAGE
+        });
+    }
+    /*
+   * Two rules met in one figure, which is the currency problem in another
+   * dimension: a campaign whose older emails were credited under a different
+   * model or a different window holds amounts that were judged by different
+   * tests. They are still money in one unit, so unlike two currencies they
+   * add — the total stands, and the reader is told the rule behind it is not
+   * single.
+   */ if (models.size > 1 || windows.size > 1) {
+        caveats.push({
+            id: 'revenue-mixed-model',
+            message: 'This campaign’s emails were not all credited under the same rule. ' + 'The amounts are real, but they were judged by different attribution ' + 'models or windows, so they are not strictly comparable with each ' + 'other.'
+        });
+    }
+    return {
+        currencies,
+        attributedOrders: currencies.reduce((total, entry)=>total + entry.orders, 0),
+        read: rollups.length,
+        recorded,
+        multiCurrency,
+        models: [
+            ...models
+        ].sort(),
+        windowDays: [
+            ...windows
+        ].sort((a, b)=>a - b),
+        caveats
+    };
+}
+
+//# sourceMappingURL=campaign-revenue.js.map

package/src/lib/model/campaign-revenue.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/email-campaigns/src/lib/model/campaign-revenue.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 window and the model name come from `@aglyn/shared-util-email`, not\n * from here. The writer is in `tenant-data-admin`, which may not import a\n * feature plugin, and a window defined on both sides of the join would drift\n * into a number credited under one rule and printed under another.\n */\nimport {\n  EMAIL_ATTRIBUTION_MODEL,\n  EMAIL_ATTRIBUTION_WINDOW_DAYS,\n} from '@aglyn/shared-util-email'\nimport { campaignRate, type CampaignCaveat } from './campaign-report'\n\n/**\n * WHAT A CAMPAIGN EARNED — the read half of the commerce↔email join.\n *\n * ## Why this is a join and not an attribution model\n *\n * Every compared ESP reconstructs campaign revenue probabilistically, because\n * none of them owns the order. Klaviyo and Mailchimp watch someone else's\n * store through an integration and a browser snippet, so their figure is a\n * reconciliation against a foreign system and their window is the fudge\n * factor that makes the reconciliation close. Commerce here is first-party:\n * the click and the order are rows in one database, keyed the same way, so\n * the \"attribution\" is a lookup.\n *\n * That does not make the MODEL choice go away — two campaigns can both have\n * touched a buyer and only one can be credited — but it does mean the model\n * is the only judgement in the number. There is no sampling, no identity\n * resolution and no cookie.\n *\n * ## The model: LAST CLICK, inside a fixed 7-day window\n *\n * Stated in one sentence, which is the whole requirement: **an order is\n * credited to the last campaign whose link the buyer clicked, if they clicked\n * it within the {@link EMAIL_ATTRIBUTION_WINDOW_DAYS} days before they\n * ordered.**\n *\n * Three decisions are inside that sentence.\n *\n * **Last touch, not multi-touch.** Multi-touch is the more honest description\n * of how buying works and it is unpresentable: it splits one order across\n * several campaigns by a rule the merchant did not choose, so no campaign's\n * revenue is a number they can check against their own bank, and two\n * campaigns' figures cannot be added or compared without knowing the split\n * rule. HubSpot ships multi-touch and puts it behind an Enterprise plan and a\n * consultant. A figure a merchant cannot explain to themselves is worse than\n * no figure, and it is worse in the specific way that matters here: they will\n * still make decisions with it.\n *\n * **A CLICK is the touch. An open is not.** An open is evidence about the\n * recipient's mail client, not about the recipient — Apple's Mail Privacy\n * Protection prefetches images, which inflated network-wide open rates by\n * roughly 15% and means a large share of recorded opens had no human behind\n * them. Crediting revenue to an open would therefore credit campaigns for\n * orders from people who never saw them, and the error is not random: it\n * concentrates on whichever campaign most recently reached an Apple Mail\n * user. `email-delivery-log.ts` records the same preference for the same\n * reason, and the audience rules already segment on clicks over opens.\n *\n * **Seven days, and not configurable.** Klaviyo's window is 1–30 days per\n * channel; ActiveCampaign's is a fixed, unadjustable 7. Fixed is the better\n * default here because a configurable window is a setting whose change\n * silently rewrites history: yesterday's report and today's would disagree\n * about a campaign that has not been touched since, with nothing on screen to\n * say why. The stored record carries `windowDays` per order for exactly that\n * reason — a future setting can be added without making the orders already\n * attributed unreadable, because each one says which window it was judged\n * under.\n *\n * ## GROSS and REFUNDED, never a decrement\n *\n * A refunded order must stop counting as revenue a campaign earned, and there\n * are two ways to make it stop. Decrementing the gross figure makes a stored\n * number mean one thing before a refund and another after, with nothing to\n * distinguish them; recording the reversal beside it keeps both facts. This\n * is the shape `contact-refund.ts` chose for `ltvCents`/`refundedCents` on the\n * contact and the orders CSV chose for `amountUsd`/`refundedUsd`, and it is\n * chosen again here so all three answer \"what did this earn, net\" the same\n * way.\n *\n * So {@link campaignRevenueReport} reports gross, refunded and net, and NET\n * is the figure the screen leads with. Net is clamped at zero for display\n * only: a refund larger than the sale it reverses is arithmetically possible\n * on an order attributed before a partial refund settled, and a negative\n * campaign revenue is a sentence nobody can act on.\n *\n * ## Currencies are never summed\n *\n * Money is stored in minor units and no currency travels with it — every\n * checkout door in this repo sets `currency: 'usd'` on the Stripe line items,\n * so the amounts really are all USD, but that is a fact about the code rather\n * than a field on the order. The rollup therefore buckets BY currency and\n * this module never adds two buckets together. A campaign with two currencies\n * renders two blocks and no total, and says so.\n *\n * The rule survives the merge across a container's emails.\n * {@link campaignRevenueAcrossSends} keys its accumulator on the currency, so\n * two rollups can only ever meet inside a bucket they already share — there\n * is no code path in which a USD amount and a EUR amount reach the same\n * addition, and no combined figure exists for a screen to print by accident.\n */\n\n/**\n * Re-exported so a reader of the report has the window and the model name\n * without reaching past this module for them — the screen prints both, and a\n * window nobody can see is a window nobody can check.\n */\nexport {\n  EMAIL_ATTRIBUTION_MODEL,\n  EMAIL_ATTRIBUTION_WINDOW_DAYS,\n  EMAIL_ATTRIBUTION_WINDOW_MS,\n} from '@aglyn/shared-util-email'\n\n/** One currency's totals as the rollup stores them. */\nexport interface CampaignRevenueCurrencyStored {\n  /** Minor units credited to this campaign, gross of refunds. */\n  grossCents?: number\n  /** Minor units handed back on orders that had been credited. */\n  refundedCents?: number\n  /** Orders credited to this campaign. */\n  orders?: number\n  /** Of those, how many ended fully reversed. */\n  refundedOrders?: number\n}\n\n/**\n * The stored shape of `campaigns/{campaignId}/reports/revenue`.\n *\n * Its own document, for the reason the link rollup is its own document: the\n * campaign document is read by the history list, the glance widget and the\n * send path, and a map that grows with the campaign's sales would make every\n * one of those reads larger. Split, it is read by the one screen that draws\n * it.\n */\nexport interface CampaignRevenueRollup {\n  byCurrency?: Record<string, CampaignRevenueCurrencyStored>\n  /** The model the orders in this rollup were credited under. */\n  model?: string\n  /** The window, in days, they were credited inside. */\n  windowDays?: number\n}\n\n/**\n * Money over a population, with the population named — {@link CampaignRate}'s\n * rule applied to an average instead of a share.\n *\n * A percentage and an average go wrong the same way, so they carry the same\n * guarantee: the denominator travels as data and the screen has to print it.\n * \"$0.42 per recipient\" over an audience nobody named is the figure this\n * whole reporting surface exists to refuse.\n */\nexport interface CampaignMoneyPerMessage {\n  /** Minor units per message of the denominator. Fractional by nature. */\n  cents: number\n  numeratorCents: number\n  denominator: number\n  denominatorLabel: string\n  currency: string\n}\n\n/** One currency's block on screen. */\nexport interface CampaignRevenueCurrencyReport {\n  /** Lowercase ISO code as the sale recorded it, e.g. `'usd'`. */\n  currency: string\n  grossCents: number\n  refundedCents: number\n  /** `gross - refunded`, clamped at zero. */\n  netCents: number\n  orders: number\n  refundedOrders: number\n  /**\n   * Net revenue per DELIVERED message, or `null` when it cannot be taken.\n   *\n   * Delivered is the denominator for the same reason every engagement rate on\n   * this report is taken over it: mail that bounced was never in front of a\n   * human, so counting it depresses a figure describing the audience with a\n   * fact about the address list.\n   *\n   * It is deliberately NOT taken over `audienceSize`. That figure is written\n   * by the FIRST batch only and is a floor when audience resolution hit its\n   * read ceiling, so a campaign delivered over six runs would divide six\n   * runs' revenue by one run's measure of the audience — the stale-population\n   * division this surface is built to make impossible.\n   */\n  netPerDelivered: CampaignMoneyPerMessage | null\n}\n\n/** Everything the revenue section renders. */\nexport interface CampaignRevenueReport {\n  /** One block per currency, largest net first. Never summed together. */\n  currencies: CampaignRevenueCurrencyReport[]\n  /** Orders credited to this campaign, across every currency. */\n  attributedOrders: number\n  /**\n   * Whether any attribution has ever been recorded for this campaign.\n   *\n   * `false` means the rollup document does not exist, which is NOT the same\n   * as \"this campaign earned nothing\" — it is also every campaign sent before\n   * the join existed, and every campaign on a site with no store. The screen\n   * renders the difference rather than printing a zero for both.\n   */\n  recorded: boolean\n  /** More than one currency is present, so no total may be shown. */\n  multiCurrency: boolean\n  /** The model these figures were credited under, as stored. */\n  model: string\n  /** The window they were credited inside, as stored. */\n  windowDays: number\n  caveats: CampaignCaveat[]\n}\n\n/**\n * Why there is no total, in the words both reports use.\n *\n * One sentence, one definition. A send's report and its campaign's report\n * make the same refusal for the same reason, and two copies of the sentence\n * is how one of them comes to be softened into a promise of a total.\n */\nexport const REVENUE_MULTI_CURRENCY_MESSAGE =\n  'This campaign earned in more than one currency. Each is reported on its ' +\n  'own — nothing here converts between them, so there is deliberately no ' +\n  'combined total.'\n\n/** A stored count as a non-negative integer. */\nfunction count(raw: unknown): number {\n  const value = Math.floor(Number(raw ?? 0))\n  return Number.isFinite(value) && value > 0 ? value : 0\n}\n\n/**\n * Money per message, or `null` when the division cannot honestly be taken.\n *\n * The three refusals are {@link campaignRate}'s, and this defers to it rather\n * than restating them: a zero denominator, an unrecorded denominator, and a\n * non-finite input all answer `null` there, so a second implementation of\n * \"when may we divide\" cannot drift from the first.\n */\nexport function campaignMoneyPerMessage(\n  numeratorCents: number,\n  denominator: number | undefined,\n  denominatorLabel: string,\n  currency: string,\n): CampaignMoneyPerMessage | null {\n  const divisible = campaignRate(numeratorCents, denominator, denominatorLabel)\n  if (!divisible) return null\n  return {\n    cents: divisible.value,\n    numeratorCents: divisible.numerator,\n    denominator: divisible.denominator,\n    denominatorLabel,\n    currency,\n  }\n}\n\n/**\n * Turns the stored rollup into the revenue section.\n *\n * `delivered` comes from the campaign's own `stats` and is passed in rather\n * than re-read, so the numerator and the denominator on screen are taken from\n * the same instant. It is `null` when no delivery event has ever been\n * recorded — the campaign predates the delivery webhook, or the events are\n * still in flight — and every figure over it is then withheld with a caveat,\n * never substituted for `sent`.\n */\nexport function campaignRevenueReport(options: {\n  rollup: CampaignRevenueRollup | undefined\n  /** `stats.delivered`, or `null` when it was never recorded. */\n  delivered: number | null\n  /** True while the send is still working through its audience. */\n  midFlight?: boolean\n}): CampaignRevenueReport {\n  const { rollup, delivered, midFlight } = options\n  const stored = rollup?.byCurrency ?? {}\n  const caveats: CampaignCaveat[] = []\n\n  const currencies: CampaignRevenueCurrencyReport[] = Object.entries(stored)\n    .map(([currency, totals]) => {\n      const grossCents = count(totals?.grossCents)\n      const refundedCents = count(totals?.refundedCents)\n      /*\n       * CLAMPED, and only here at the point of display.\n       *\n       * Both stored figures are monotonic counters of money that really\n       * moved in one direction, so neither can be negative; their DIFFERENCE\n       * can be, for one reason — an order credited to a campaign and then\n       * refunded by more than the amount that was credited, which happens\n       * when a partial refund settles against an order whose attributed\n       * amount was the charge at the time. Clamping at write time would\n       * erase the evidence; clamping at read time keeps the stored pair\n       * intact and stops the screen printing a campaign with negative\n       * earnings, which is not a sentence anybody can act on.\n       */\n      const netCents = Math.max(0, grossCents - refundedCents)\n      return {\n        currency,\n        grossCents,\n        refundedCents,\n        netCents,\n        orders: count(totals?.orders),\n        refundedOrders: count(totals?.refundedOrders),\n        netPerDelivered: campaignMoneyPerMessage(\n          netCents,\n          delivered ?? undefined,\n          'delivered',\n          currency,\n        ),\n      }\n    })\n    .filter((entry) => entry.orders > 0 || entry.grossCents > 0)\n    .sort(\n      (a, b) => b.netCents - a.netCents || a.currency.localeCompare(b.currency),\n    )\n\n  const attributedOrders = currencies.reduce(\n    (total, entry) => total + entry.orders,\n    0,\n  )\n  const multiCurrency = currencies.length > 1\n\n  if (delivered === null && currencies.length) {\n    caveats.push({\n      id: 'revenue-denominator-unrecorded',\n      message:\n        'No delivery events have been recorded for this campaign, so revenue ' +\n        'per delivered message cannot be computed. The amounts below are ' +\n        'still real.',\n    })\n  }\n  if (multiCurrency) {\n    caveats.push({\n      id: 'revenue-multi-currency',\n      message: REVENUE_MULTI_CURRENCY_MESSAGE,\n    })\n  }\n  if (midFlight && currencies.length) {\n    caveats.push({\n      id: 'revenue-mid-flight',\n      message:\n        'This campaign is still going out. Revenue and delivered messages ' +\n        'are both still rising, so every figure below is a running total ' +\n        'rather than a final one.',\n    })\n  }\n\n  return {\n    currencies,\n    attributedOrders,\n    recorded: rollup !== undefined,\n    multiCurrency,\n    model: String(rollup?.model ?? EMAIL_ATTRIBUTION_MODEL),\n    windowDays: count(rollup?.windowDays) || EMAIL_ATTRIBUTION_WINDOW_DAYS,\n    caveats,\n  }\n}\n\n/** One currency's totals, merged across a campaign's emails. */\nexport interface CampaignRevenueCurrencyAcrossSends {\n  /** Lowercase ISO code as the sales recorded it, e.g. `'usd'`. */\n  currency: string\n  grossCents: number\n  refundedCents: number\n  /** `gross - refunded` over the whole campaign, clamped once at zero. */\n  netCents: number\n  orders: number\n  refundedOrders: number\n  /** Emails of the campaign whose revenue record holds this currency. */\n  emails: number\n}\n\n/** Everything a campaign container's revenue section renders. */\nexport interface CampaignRevenueAcrossSends {\n  /** One block per currency, largest net first. Never summed together. */\n  currencies: CampaignRevenueCurrencyAcrossSends[]\n  /**\n   * Orders credited across every currency.\n   *\n   * A COUNT, which is why it may cross currencies when the money may not: an\n   * order is one order whatever it was paid in, and counting two of them\n   * loses nothing. Adding their amounts loses the unit.\n   */\n  attributedOrders: number\n  /** Emails whose revenue record was looked for. */\n  read: number\n  /**\n   * Of those, how many have a revenue record at all.\n   *\n   * The rollup is created by the attribution writer on the first order it\n   * credits, so an email with no record has never been credited with one.\n   * Zero across the whole campaign is therefore the container's version of\n   * {@link CampaignRevenueReport.recorded} being `false`: it is not \"this\n   * campaign earned nothing\", it is also every campaign sent before the join\n   * existed and every campaign on a site with no store.\n   */\n  recorded: number\n  /** More than one currency is present, so no total may be shown. */\n  multiCurrency: boolean\n  /** The models these emails were credited under, distinct and sorted. */\n  models: string[]\n  /** The windows, in days, they were credited inside, distinct and sorted. */\n  windowDays: number[]\n  caveats: CampaignCaveat[]\n}\n\n/**\n * MERGES A CAMPAIGN'S EMAILS INTO ONE REVENUE SECTION, per currency.\n *\n * `reports/revenue` is written per SEND, so a container's figure is one\n * document per email and a merge. The merge is the whole risk: two emails of\n * one campaign can have earned in different currencies, and adding their\n * amounts produces a number that is wrong with nothing on screen to show it.\n *\n * ## The currency is the accumulator's KEY, not a field beside the amount\n *\n * That is the structural half of the guarantee. Amounts are added into a map\n * keyed by currency, so two amounts can only reach the same addition when\n * they already carry the same code — a USD figure and a EUR figure have no\n * path to each other, whatever a later caller asks for. There is no combined\n * field on the result, so a screen cannot print a cross-currency total by\n * reading the wrong property, and\n * {@link CampaignRevenueAcrossSends.multiCurrency} is what tells the screen\n * to label the blocks.\n *\n * ## Clamped ONCE, over the campaign\n *\n * The single-send report clamps its net at zero because a partial refund can\n * settle against an order credited at the full charge. Doing that per email\n * and then summing would let one over-refunded email keep money a sibling\n * email handed back — an email at -$50 clamped to $0 beside one at $200 would\n * report $200 for a campaign holding $150. So gross and refunded are summed\n * as they stand and the difference is clamped once, at the end.\n *\n * ## No per-message average, deliberately\n *\n * The send report divides net revenue by that send's own `delivered`, taken\n * from the same document at the same instant. A container has no such pair.\n * Its delivery total is summed over the emails that RECORDED a delivery count\n * and its revenue over the emails that have a revenue record, and those are\n * different subsets of the campaign — so the quotient would be an average\n * over a population nobody named, which is the defect the whole reporting\n * surface is built to refuse. The amounts are reported without one.\n *\n * @param rollups - one entry per email read, `undefined` where no record\n * exists.\n */\nexport function campaignRevenueAcrossSends(\n  rollups: readonly (CampaignRevenueRollup | undefined)[],\n): CampaignRevenueAcrossSends {\n  const byCurrency = new Map<string, CampaignRevenueCurrencyAcrossSends>()\n  const models = new Set<string>()\n  const windows = new Set<number>()\n  let recorded = 0\n\n  for (const rollup of rollups) {\n    if (!rollup) continue\n    recorded += 1\n    models.add(String(rollup.model ?? EMAIL_ATTRIBUTION_MODEL))\n    windows.add(count(rollup.windowDays) || EMAIL_ATTRIBUTION_WINDOW_DAYS)\n    for (const [code, stored] of Object.entries(rollup.byCurrency ?? {})) {\n      const currency = String(code).trim().toLowerCase()\n      if (!currency) continue\n      const entry = byCurrency.get(currency) ?? {\n        currency,\n        grossCents: 0,\n        refundedCents: 0,\n        netCents: 0,\n        orders: 0,\n        refundedOrders: 0,\n        emails: 0,\n      }\n      entry.grossCents += count(stored?.grossCents)\n      entry.refundedCents += count(stored?.refundedCents)\n      entry.orders += count(stored?.orders)\n      entry.refundedOrders += count(stored?.refundedOrders)\n      // One rollup holds at most one bucket per currency, so this counts\n      // EMAILS that earned in it rather than orders.\n      entry.emails += 1\n      byCurrency.set(currency, entry)\n    }\n  }\n\n  const currencies = [...byCurrency.values()]\n    .map((entry) => ({\n      ...entry,\n      netCents: Math.max(0, entry.grossCents - entry.refundedCents),\n    }))\n    .filter((entry) => entry.orders > 0 || entry.grossCents > 0)\n    .sort(\n      (a, b) => b.netCents - a.netCents || a.currency.localeCompare(b.currency),\n    )\n\n  const multiCurrency = currencies.length > 1\n  const caveats: CampaignCaveat[] = []\n  if (multiCurrency) {\n    caveats.push({\n      id: 'revenue-multi-currency',\n      message: REVENUE_MULTI_CURRENCY_MESSAGE,\n    })\n  }\n  /*\n   * Two rules met in one figure, which is the currency problem in another\n   * dimension: a campaign whose older emails were credited under a different\n   * model or a different window holds amounts that were judged by different\n   * tests. They are still money in one unit, so unlike two currencies they\n   * add — the total stands, and the reader is told the rule behind it is not\n   * single.\n   */\n  if (models.size > 1 || windows.size > 1) {\n    caveats.push({\n      id: 'revenue-mixed-model',\n      message:\n        'This campaign’s emails were not all credited under the same rule. ' +\n        'The amounts are real, but they were judged by different attribution ' +\n        'models or windows, so they are not strictly comparable with each ' +\n        'other.',\n    })\n  }\n\n  return {\n    currencies,\n    attributedOrders: currencies.reduce(\n      (total, entry) => total + entry.orders,\n      0,\n    ),\n    read: rollups.length,\n    recorded,\n    multiCurrency,\n    models: [...models].sort(),\n    windowDays: [...windows].sort((a, b) => a - b),\n    caveats,\n  }\n}\n"],"names":["EMAIL_ATTRIBUTION_MODEL","EMAIL_ATTRIBUTION_WINDOW_DAYS","campaignRate","EMAIL_ATTRIBUTION_WINDOW_MS","REVENUE_MULTI_CURRENCY_MESSAGE","count","raw","value","Math","floor","Number","isFinite","campaignMoneyPerMessage","numeratorCents","denominator","denominatorLabel","currency","divisible","cents","numerator","campaignRevenueReport","options","rollup","delivered","midFlight","stored","byCurrency","caveats","currencies","Object","entries","map","totals","grossCents","refundedCents","netCents","max","orders","refundedOrders","netPerDelivered","undefined","filter","entry","sort","a","b","localeCompare","attributedOrders","reduce","total","multiCurrency","length","push","id","message","recorded","model","String","windowDays","campaignRevenueAcrossSends","rollups","Map","models","Set","windows","add","code","trim","toLowerCase","get","emails","set","values","size","read"],"mappings":"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"}

package/src/lib/model/campaign-send-time.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */
+/**
+ * WHEN A LIST READS ITS MAIL: a suggested send time, taken from the sends that
+ * already went to it.
+ *
+ * A rule and not a guess. Each past send is put in the slot it went out in —
+ * its weekday and hour, in one named time zone — and the slot whose sends were
+ * opened by the largest share of the people they reached is the suggestion.
+ * The share is POOLED across a slot's sends (every unique open over every
+ * delivered message) rather than averaged, so one small send that happened to
+ * be opened by all nine of its recipients does not outrank a slot that reached
+ * thousands.
+ *
+ * Only sends that can be measured are counted: a send with no delivered count
+ * large enough to say anything is left out, and so is one whose opens exceed
+ * its deliveries, which is a record that disagrees with itself. With fewer
+ * measured sends than the minimum there is no suggestion at all — "not enough
+ * history" is an answer a composer can say, and a slot picked from one send is
+ * not.
+ *
+ * Pure, with the reads left to the caller that holds the credentials.
+ */
+/** One past send to the list, as the suggestion needs it. */
+export interface CampaignSendTimeSample {
+    /** When the send went out. */
+    sentAtMs: number;
+    /** Messages the provider delivered. */
+    delivered: number;
+    /** Distinct recipients who opened it. */
+    uniqueOpens: number;
+}
+export interface CampaignSendTimeSuggestion {
+    /** 0 for Sunday through 6 for Saturday, in `timeZone`. */
+    weekday: number;
+    /** 0 to 23, in `timeZone`. */
+    hour: number;
+    /** The IANA zone the slot is stated in. */
+    timeZone: string;
+    /** The pooled unique-open rate of the sends in the slot, 0 to 1. */
+    openRate: number;
+    /** Measured sends that went out in the slot. */
+    sends: number;
+    /** Measured sends the slot was chosen among. */
+    measured: number;
+}
+/** The fewest measured sends a suggestion is taken from. */
+export declare const CAMPAIGN_SEND_TIME_MIN_SENDS = 3;
+/** The fewest delivered messages that make a send measurable. */
+export declare const CAMPAIGN_SEND_TIME_MIN_DELIVERED = 20;
+/**
+ * The slot the list's past sends were opened most in, or `null` when too few
+ * sends can be measured. An unknown time zone is read as UTC, and the answer
+ * says so.
+ */
+export declare function suggestCampaignSendTime(samples: ReadonlyArray<CampaignSendTimeSample>, options?: {
+    timeZone?: string;
+}): CampaignSendTimeSuggestion | null;
+/** The slot as a person reads it: "Tuesdays around 9 AM (UTC)". */
+export declare function campaignSendTimeLabel(suggestion: Pick<CampaignSendTimeSuggestion, 'weekday' | 'hour' | 'timeZone'>): string;

package/src/lib/model/campaign-send-time.js

@@ -0,0 +1,120 @@
+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.
+ */ import { campaignRate } from "./campaign-report.js";
+/** The fewest measured sends a suggestion is taken from. */ export const CAMPAIGN_SEND_TIME_MIN_SENDS = 3;
+/** The fewest delivered messages that make a send measurable. */ export const CAMPAIGN_SEND_TIME_MIN_DELIVERED = 20;
+const WEEKDAYS = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6
+};
+const WEEKDAY_NAMES = [
+    'Sunday',
+    'Monday',
+    'Tuesday',
+    'Wednesday',
+    'Thursday',
+    'Friday',
+    'Saturday'
+];
+function slotFormatter(timeZone) {
+    try {
+        return new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            weekday: 'short',
+            hour: 'numeric',
+            hourCycle: 'h23'
+        });
+    } catch (unused) {
+        return null;
+    }
+}
+/** The weekday and hour an instant falls in, in a zone. */ function slotOf(formatter, atMs) {
+    let weekday;
+    let hour;
+    for (const part of formatter.formatToParts(new Date(atMs))){
+        if (part.type === 'weekday') weekday = WEEKDAYS[part.value];
+        if (part.type === 'hour') hour = Number(part.value) % 24;
+    }
+    return weekday === undefined || hour === undefined || !Number.isFinite(hour) ? null : {
+        weekday,
+        hour
+    };
+}
+/**
+ * The slot the list's past sends were opened most in, or `null` when too few
+ * sends can be measured. An unknown time zone is read as UTC, and the answer
+ * says so.
+ */ export function suggestCampaignSendTime(samples, options = {}) {
+    var _slotFormatter;
+    var _options_timeZone;
+    const requested = ((_options_timeZone = options.timeZone) == null ? void 0 : _options_timeZone.trim()) || 'UTC';
+    const formatter = (_slotFormatter = slotFormatter(requested)) != null ? _slotFormatter : slotFormatter('UTC');
+    const timeZone = slotFormatter(requested) ? requested : 'UTC';
+    if (!formatter) return null;
+    const slots = new Map();
+    let measured = 0;
+    for (const sample of samples){
+        var _slots_get;
+        const delivered = Number(sample.delivered);
+        const opens = Number(sample.uniqueOpens);
+        if (!Number.isFinite(sample.sentAtMs) || sample.sentAtMs <= 0) continue;
+        if (!Number.isFinite(delivered) || delivered < CAMPAIGN_SEND_TIME_MIN_DELIVERED) continue;
+        if (!Number.isFinite(opens) || opens < 0 || opens > delivered) continue;
+        const slot = slotOf(formatter, sample.sentAtMs);
+        if (!slot) continue;
+        measured += 1;
+        const key = `${slot.weekday}:${slot.hour}`;
+        const held = (_slots_get = slots.get(key)) != null ? _slots_get : _extends({}, slot, {
+            delivered: 0,
+            opens: 0,
+            sends: 0
+        });
+        held.delivered += delivered;
+        held.opens += opens;
+        held.sends += 1;
+        slots.set(key, held);
+    }
+    if (measured < CAMPAIGN_SEND_TIME_MIN_SENDS) return null;
+    let best = null;
+    for (const slot of slots.values()){
+        const rate = campaignRate(slot.opens, slot.delivered, 'delivered');
+        if (!rate) continue;
+        const candidate = {
+            weekday: slot.weekday,
+            hour: slot.hour,
+            timeZone,
+            openRate: rate.value,
+            sends: slot.sends,
+            measured
+        };
+        const better = !best || candidate.openRate > best.openRate || candidate.openRate === best.openRate && (candidate.sends > best.sends || candidate.sends === best.sends && candidate.weekday * 24 + candidate.hour < best.weekday * 24 + best.hour);
+        if (better) best = candidate;
+    }
+    return best;
+}
+/** The slot as a person reads it: "Tuesdays around 9 AM (UTC)". */ export function campaignSendTimeLabel(suggestion) {
+    const hour12 = suggestion.hour % 12 === 0 ? 12 : suggestion.hour % 12;
+    const meridiem = suggestion.hour < 12 ? 'AM' : 'PM';
+    return `${WEEKDAY_NAMES[suggestion.weekday]}s around ${hour12} ${meridiem} (${suggestion.timeZone})`;
+}
+
+//# sourceMappingURL=campaign-send-time.js.map

package/src/lib/model/campaign-send-time.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/email-campaigns/src/lib/model/campaign-send-time.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\nimport { campaignRate } from './campaign-report'\n\n/**\n * WHEN A LIST READS ITS MAIL: a suggested send time, taken from the sends that\n * already went to it.\n *\n * A rule and not a guess. Each past send is put in the slot it went out in —\n * its weekday and hour, in one named time zone — and the slot whose sends were\n * opened by the largest share of the people they reached is the suggestion.\n * The share is POOLED across a slot's sends (every unique open over every\n * delivered message) rather than averaged, so one small send that happened to\n * be opened by all nine of its recipients does not outrank a slot that reached\n * thousands.\n *\n * Only sends that can be measured are counted: a send with no delivered count\n * large enough to say anything is left out, and so is one whose opens exceed\n * its deliveries, which is a record that disagrees with itself. With fewer\n * measured sends than the minimum there is no suggestion at all — \"not enough\n * history\" is an answer a composer can say, and a slot picked from one send is\n * not.\n *\n * Pure, with the reads left to the caller that holds the credentials.\n */\n\n/** One past send to the list, as the suggestion needs it. */\nexport interface CampaignSendTimeSample {\n  /** When the send went out. */\n  sentAtMs: number\n  /** Messages the provider delivered. */\n  delivered: number\n  /** Distinct recipients who opened it. */\n  uniqueOpens: number\n}\n\nexport interface CampaignSendTimeSuggestion {\n  /** 0 for Sunday through 6 for Saturday, in `timeZone`. */\n  weekday: number\n  /** 0 to 23, in `timeZone`. */\n  hour: number\n  /** The IANA zone the slot is stated in. */\n  timeZone: string\n  /** The pooled unique-open rate of the sends in the slot, 0 to 1. */\n  openRate: number\n  /** Measured sends that went out in the slot. */\n  sends: number\n  /** Measured sends the slot was chosen among. */\n  measured: number\n}\n\n/** The fewest measured sends a suggestion is taken from. */\nexport const CAMPAIGN_SEND_TIME_MIN_SENDS = 3\n\n/** The fewest delivered messages that make a send measurable. */\nexport const CAMPAIGN_SEND_TIME_MIN_DELIVERED = 20\n\nconst WEEKDAYS: Record<string, number> = {\n  Sun: 0,\n  Mon: 1,\n  Tue: 2,\n  Wed: 3,\n  Thu: 4,\n  Fri: 5,\n  Sat: 6,\n}\n\nconst WEEKDAY_NAMES = [\n  'Sunday',\n  'Monday',\n  'Tuesday',\n  'Wednesday',\n  'Thursday',\n  'Friday',\n  'Saturday',\n]\n\nfunction slotFormatter(timeZone: string): Intl.DateTimeFormat | null {\n  try {\n    return new Intl.DateTimeFormat('en-US', {\n      timeZone,\n      weekday: 'short',\n      hour: 'numeric',\n      hourCycle: 'h23',\n    })\n  } catch {\n    return null\n  }\n}\n\n/** The weekday and hour an instant falls in, in a zone. */\nfunction slotOf(\n  formatter: Intl.DateTimeFormat,\n  atMs: number,\n): { weekday: number; hour: number } | null {\n  let weekday: number | undefined\n  let hour: number | undefined\n  for (const part of formatter.formatToParts(new Date(atMs))) {\n    if (part.type === 'weekday') weekday = WEEKDAYS[part.value]\n    if (part.type === 'hour') hour = Number(part.value) % 24\n  }\n  return weekday === undefined || hour === undefined || !Number.isFinite(hour)\n    ? null\n    : { weekday, hour }\n}\n\n/**\n * The slot the list's past sends were opened most in, or `null` when too few\n * sends can be measured. An unknown time zone is read as UTC, and the answer\n * says so.\n */\nexport function suggestCampaignSendTime(\n  samples: ReadonlyArray<CampaignSendTimeSample>,\n  options: { timeZone?: string } = {},\n): CampaignSendTimeSuggestion | null {\n  const requested = options.timeZone?.trim() || 'UTC'\n  const formatter = slotFormatter(requested) ?? slotFormatter('UTC')\n  const timeZone = slotFormatter(requested) ? requested : 'UTC'\n  if (!formatter) return null\n  const slots = new Map<string, { weekday: number; hour: number; delivered: number; opens: number; sends: number }>()\n  let measured = 0\n  for (const sample of samples) {\n    const delivered = Number(sample.delivered)\n    const opens = Number(sample.uniqueOpens)\n    if (!Number.isFinite(sample.sentAtMs) || sample.sentAtMs <= 0) continue\n    if (!Number.isFinite(delivered) || delivered < CAMPAIGN_SEND_TIME_MIN_DELIVERED) continue\n    if (!Number.isFinite(opens) || opens < 0 || opens > delivered) continue\n    const slot = slotOf(formatter, sample.sentAtMs)\n    if (!slot) continue\n    measured += 1\n    const key = `${slot.weekday}:${slot.hour}`\n    const held = slots.get(key) ?? { ...slot, delivered: 0, opens: 0, sends: 0 }\n    held.delivered += delivered\n    held.opens += opens\n    held.sends += 1\n    slots.set(key, held)\n  }\n  if (measured < CAMPAIGN_SEND_TIME_MIN_SENDS) return null\n  let best: CampaignSendTimeSuggestion | null = null\n  for (const slot of slots.values()) {\n    const rate = campaignRate(slot.opens, slot.delivered, 'delivered')\n    if (!rate) continue\n    const candidate: CampaignSendTimeSuggestion = {\n      weekday: slot.weekday,\n      hour: slot.hour,\n      timeZone,\n      openRate: rate.value,\n      sends: slot.sends,\n      measured,\n    }\n    const better =\n      !best ||\n      candidate.openRate > best.openRate ||\n      (candidate.openRate === best.openRate &&\n        (candidate.sends > best.sends ||\n          (candidate.sends === best.sends &&\n            candidate.weekday * 24 + candidate.hour < best.weekday * 24 + best.hour)))\n    if (better) best = candidate\n  }\n  return best\n}\n\n/** The slot as a person reads it: \"Tuesdays around 9 AM (UTC)\". */\nexport function campaignSendTimeLabel(\n  suggestion: Pick<CampaignSendTimeSuggestion, 'weekday' | 'hour' | 'timeZone'>,\n): string {\n  const hour12 = suggestion.hour % 12 === 0 ? 12 : suggestion.hour % 12\n  const meridiem = suggestion.hour < 12 ? 'AM' : 'PM'\n  return `${WEEKDAY_NAMES[suggestion.weekday]}s around ${hour12} ${meridiem} (${suggestion.timeZone})`\n}\n"],"names":["campaignRate","CAMPAIGN_SEND_TIME_MIN_SENDS","CAMPAIGN_SEND_TIME_MIN_DELIVERED","WEEKDAYS","Sun","Mon","Tue","Wed","Thu","Fri","Sat","WEEKDAY_NAMES","slotFormatter","timeZone","Intl","DateTimeFormat","weekday","hour","hourCycle","slotOf","formatter","atMs","part","formatToParts","Date","type","value","Number","undefined","isFinite","suggestCampaignSendTime","samples","options","requested","trim","slots","Map","measured","sample","delivered","opens","uniqueOpens","sentAtMs","slot","key","held","get","sends","set","best","values","rate","candidate","openRate","better","campaignSendTimeLabel","suggestion","hour12","meridiem"],"mappings":"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"}