@aglyn/plugins-marketing 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/model/email-record.js

@@ -0,0 +1,206 @@
+/**
+ * @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.
+ */ /**
+ * READING ONE MESSAGE RECORD.
+ *
+ * A message — an email that was or will be sent — is a document under
+ * `hosts/{hostId}/campaigns`. Two facts about that document are awkward
+ * enough that every surface reading it gets them wrong the same way, so they
+ * are decided here once.
+ */ /**
+ * When a message went out, or is due to.
+ *
+ * **There is no one SEND date field.** The send path writes `{status:'sent',
+ * sentAt}` from one branch and `{status:'scheduled', sendAtMs}` from another.
+ * So a list ordered on either field in Firestore does not mis-sort —
+ * `orderBy` DROPS every document missing the ordered field — and half the
+ * messages simply vanish. Sorting on this instead keeps both kinds in one
+ * ordered list.
+ *
+ * `sentAt` is a Firestore `Timestamp`, which the client SDK gives as an
+ * object with `seconds` and `toMillis()`; a document read from cache while a
+ * write is pending can carry a sentinel with neither, which reads as 0 and
+ * sorts last rather than throwing.
+ *
+ * A DRAFT correctly answers 0 here: it has no send time, and inventing one
+ * from its creation would put an unsent message on the timeline of mail that
+ * went out. Ordering a list is {@link emailListTimeMs}'s job.
+ *
+ * @returns epoch ms, or 0 when the message has no time at all.
+ */ export function emailSendTimeMs(record) {
+    var _ref, _ref1;
+    var _record_staffReview;
+    // A send held for staff review is parked at a time no run reaches
+    // (AGL-3356). That is a mechanism, not a send time, and printed it reads as
+    // the year 9999 — so a held send answers "no time", like a draft, and the
+    // lists order it by when it was created.
+    if ((record == null ? void 0 : (_record_staffReview = record['staffReview']) == null ? void 0 : _record_staffReview['state']) === 'held' && String((_ref = record == null ? void 0 : record['status']) != null ? _ref : '') === 'scheduled') {
+        return 0;
+    }
+    const sentAt = record == null ? void 0 : record['sentAt'];
+    if (typeof (sentAt == null ? void 0 : sentAt.toMillis) === 'function') return sentAt.toMillis();
+    if (typeof (sentAt == null ? void 0 : sentAt.seconds) === 'number') return sentAt.seconds * 1000;
+    const scheduled = Number((_ref1 = record == null ? void 0 : record['sendAtMs']) != null ? _ref1 : 0);
+    return Number.isFinite(scheduled) ? scheduled : 0;
+}
+/**
+ * The field every writer of a message stamps when it MINTS the document.
+ *
+ * The one date on every message, which is what neither `sentAt` nor
+ * `sendAtMs` is — each is written by one branch of the send path and neither
+ * is on both kinds. A field carried by every record is the precondition for
+ * ordering this collection in Firestore rather than in the browser, because
+ * `orderBy` drops documents that lack the ordered field instead of
+ * mis-sorting them.
+ *
+ * Epoch milliseconds rather than a `Timestamp`, matching `sendAtMs` beside
+ * it: the two are compared against each other on every list that draws
+ * drafts and sends together, and a comparison that has to unwrap one side
+ * first is a comparison somebody writes wrong.
+ */ export const EMAIL_CREATED_AT_FIELD = 'createdAtMs';
+/**
+ * When a message was created, for the records that carry it.
+ *
+ * `null` — not 0 — for a record carrying no {@link EMAIL_CREATED_AT_FIELD},
+ * because 0 is a real instant at the far end of the sort and "we do not know"
+ * is not "1970". A null orders by the record's send time instead, so the list
+ * is correct for a record from any era.
+ */ export function emailCreatedAtMs(record) {
+    var _ref;
+    const created = Number((_ref = record == null ? void 0 : record[EMAIL_CREATED_AT_FIELD]) != null ? _ref : Number.NaN);
+    return Number.isFinite(created) && created > 0 ? created : null;
+}
+/**
+ * WHERE A MESSAGE SITS IN A LIST OF MESSAGES.
+ *
+ * Its send time where it has one, and its creation time where it does not.
+ *
+ * A draft has neither `sentAt` nor `sendAtMs`, so ordering a list on the send
+ * time alone gives every draft the key 0 and files it below mail sent years
+ * ago — the newest thing a merchant did, at the bottom of the page, behind
+ * whatever paging the list has. Falling back to creation puts it where the
+ * merchant left it.
+ *
+ * The fallback is deliberately not the other way round. A SENT message orders
+ * by when it went out, never by when it was drafted: the list is a record of
+ * what happened, and a message drafted in March and sent in June belongs in
+ * June.
+ *
+ * @returns epoch ms, or 0 for a record with no time of any kind — a draft
+ *   written before the created stamp existed, which sorts last exactly as it
+ *   did before.
+ */ export function emailListTimeMs(record) {
+    return emailSendTimeMs(record) || emailCreatedAtMs(record) || 0;
+}
+/**
+ * Reader-facing text for a message's state.
+ *
+ * The KEYS are persisted values written by the send path and read by the
+ * scheduled-campaign processor — nothing here may change them, including
+ * `canceled`, which is already the American spelling and is a stored enum in
+ * either case. Only the right-hand side is display text, and an unrecognized
+ * state falls through as itself rather than being flattened into one of
+ * these: a state this list cannot name is worth seeing.
+ *
+ * `draft` is an email that has been created and not sent. `sending` is the
+ * claim the scheduled processor and the send-now route both take before they
+ * mail, and it is named here because a merchant who reloads mid-send would
+ * otherwise be shown the raw token.
+ *
+ * ⚠️ **Not what a console row should draw.** This names the STORED value, and
+ * an email delivering an audience larger than one batch is stored as
+ * `scheduled` between runs — so a row rendering this says "Scheduled" about a
+ * send that has already put five hundred messages in five hundred inboxes.
+ * `campaignSendDisplay` in `campaign-container.ts` reads the counters beside
+ * the status and is what every surface here draws. This remains the honest
+ * answer to the narrower question of what one stored token means.
+ */ export function emailStateLabel(status) {
+    const value = String(status != null ? status : '');
+    if (value === 'sent') return 'Sent';
+    if (value === 'scheduled') return 'Scheduled';
+    if (value === 'canceled') return 'Canceled';
+    if (value === 'draft') return 'Draft';
+    if (value === 'sending') return 'Sending';
+    return value || 'Unknown';
+}
+/**
+ * Whether an email has yet been mailed to anybody.
+ *
+ * The surfaces that report on a send need this because an unsent email has no
+ * `stats` at all, and a report that divides into an absent denominator
+ * presents "not sent yet" as a delivery rate of 0% — the same class of fault
+ * as a rate rendered over a denominator it does not name.
+ */ export function emailIsUnsent(record) {
+    var _ref;
+    const value = String((_ref = record == null ? void 0 : record['status']) != null ? _ref : '');
+    return value === 'draft' || value === 'scheduled' || value === 'sending';
+}
+/**
+ * Reader-facing names for the built-in audience kinds.
+ *
+ * The KEYS are the persisted `audience` values written on every message since
+ * the composer shipped; only the values on the right are display text. A
+ * `list` audience is deliberately absent — it is not a kind of audience, it
+ * is a NAMED one, and naming it is {@link emailAudienceLabel}'s job.
+ */ export const EMAIL_AUDIENCE_LABELS = {
+    leads: 'All leads',
+    members: 'All site members',
+    segment: 'A contact segment',
+    manual: 'Addresses typed into the composer'
+};
+/**
+ * Which audience a message went to, named for a reader.
+ *
+ * A list send is named by the name the SEND recorded, never by the name the
+ * list carries today: resolving it now would let a rename rewrite the history
+ * of a message that went out months ago, and a deletion erase it. A send that
+ * recorded no name says so instead of printing a document id, which is not
+ * something a merchant recognises as a list.
+ */ export function emailAudienceLabel(record) {
+    var _ref, _ref1;
+    const audience = String((_ref = record == null ? void 0 : record['audience']) != null ? _ref : '');
+    if (audience !== 'list') {
+        var _ref2, _EMAIL_AUDIENCE_LABELS_audience;
+        return (_ref2 = (_EMAIL_AUDIENCE_LABELS_audience = EMAIL_AUDIENCE_LABELS[audience]) != null ? _EMAIL_AUDIENCE_LABELS_audience : audience) != null ? _ref2 : 'Not recorded';
+    }
+    const name = String((_ref1 = record == null ? void 0 : record['listName']) != null ? _ref1 : '');
+    if (name) return name;
+    return (record == null ? void 0 : record['listId']) ? 'A list this send did not name' : 'A list this send did not record';
+}
+export function emailSentAs(record) {
+    var _ref, _ref1, _ref2;
+    const stamp = record == null ? void 0 : record['sentAs'];
+    const from = String((_ref = stamp == null ? void 0 : stamp['from']) != null ? _ref : '').trim();
+    // The ADDRESS is what makes the stamp a record of a send. A `sentAs` map
+    // carrying only a display name is a partial write, and reporting it as
+    // recorded would put a name on screen beside an address nothing supplied.
+    if (!from) {
+        return {
+            recorded: false,
+            from: null,
+            fromName: null,
+            replyTo: null
+        };
+    }
+    return {
+        recorded: true,
+        from,
+        fromName: String((_ref1 = stamp == null ? void 0 : stamp['fromName']) != null ? _ref1 : '').trim() || null,
+        replyTo: String((_ref2 = stamp == null ? void 0 : stamp['replyTo']) != null ? _ref2 : '').trim() || null
+    };
+}
+
+//# sourceMappingURL=email-record.js.map

package/src/lib/model/email-record.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/email-record.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 * READING ONE MESSAGE RECORD.\n *\n * A message — an email that was or will be sent — is a document under\n * `hosts/{hostId}/campaigns`. Two facts about that document are awkward\n * enough that every surface reading it gets them wrong the same way, so they\n * are decided here once.\n */\n\n/**\n * When a message went out, or is due to.\n *\n * **There is no one SEND date field.** The send path writes `{status:'sent',\n * sentAt}` from one branch and `{status:'scheduled', sendAtMs}` from another.\n * So a list ordered on either field in Firestore does not mis-sort —\n * `orderBy` DROPS every document missing the ordered field — and half the\n * messages simply vanish. Sorting on this instead keeps both kinds in one\n * ordered list.\n *\n * `sentAt` is a Firestore `Timestamp`, which the client SDK gives as an\n * object with `seconds` and `toMillis()`; a document read from cache while a\n * write is pending can carry a sentinel with neither, which reads as 0 and\n * sorts last rather than throwing.\n *\n * A DRAFT correctly answers 0 here: it has no send time, and inventing one\n * from its creation would put an unsent message on the timeline of mail that\n * went out. Ordering a list is {@link emailListTimeMs}'s job.\n *\n * @returns epoch ms, or 0 when the message has no time at all.\n */\nexport function emailSendTimeMs(\n  record: Record<string, any> | null | undefined,\n): number {\n  // A send held for staff review is parked at a time no run reaches\n  // (AGL-3356). That is a mechanism, not a send time, and printed it reads as\n  // the year 9999 — so a held send answers \"no time\", like a draft, and the\n  // lists order it by when it was created.\n  if (\n    record?.['staffReview']?.['state'] === 'held' &&\n    String(record?.['status'] ?? '') === 'scheduled'\n  ) {\n    return 0\n  }\n  const sentAt = record?.['sentAt'] as\n    | { toMillis?: () => number; seconds?: number }\n    | undefined\n  if (typeof sentAt?.toMillis === 'function') return sentAt.toMillis()\n  if (typeof sentAt?.seconds === 'number') return sentAt.seconds * 1000\n  const scheduled = Number(record?.['sendAtMs'] ?? 0)\n  return Number.isFinite(scheduled) ? scheduled : 0\n}\n\n/**\n * The field every writer of a message stamps when it MINTS the document.\n *\n * The one date on every message, which is what neither `sentAt` nor\n * `sendAtMs` is — each is written by one branch of the send path and neither\n * is on both kinds. A field carried by every record is the precondition for\n * ordering this collection in Firestore rather than in the browser, because\n * `orderBy` drops documents that lack the ordered field instead of\n * mis-sorting them.\n *\n * Epoch milliseconds rather than a `Timestamp`, matching `sendAtMs` beside\n * it: the two are compared against each other on every list that draws\n * drafts and sends together, and a comparison that has to unwrap one side\n * first is a comparison somebody writes wrong.\n */\nexport const EMAIL_CREATED_AT_FIELD = 'createdAtMs'\n\n/**\n * When a message was created, for the records that carry it.\n *\n * `null` — not 0 — for a record carrying no {@link EMAIL_CREATED_AT_FIELD},\n * because 0 is a real instant at the far end of the sort and \"we do not know\"\n * is not \"1970\". A null orders by the record's send time instead, so the list\n * is correct for a record from any era.\n */\nexport function emailCreatedAtMs(\n  record: Record<string, any> | null | undefined,\n): number | null {\n  const created = Number(record?.[EMAIL_CREATED_AT_FIELD] ?? Number.NaN)\n  return Number.isFinite(created) && created > 0 ? created : null\n}\n\n/**\n * WHERE A MESSAGE SITS IN A LIST OF MESSAGES.\n *\n * Its send time where it has one, and its creation time where it does not.\n *\n * A draft has neither `sentAt` nor `sendAtMs`, so ordering a list on the send\n * time alone gives every draft the key 0 and files it below mail sent years\n * ago — the newest thing a merchant did, at the bottom of the page, behind\n * whatever paging the list has. Falling back to creation puts it where the\n * merchant left it.\n *\n * The fallback is deliberately not the other way round. A SENT message orders\n * by when it went out, never by when it was drafted: the list is a record of\n * what happened, and a message drafted in March and sent in June belongs in\n * June.\n *\n * @returns epoch ms, or 0 for a record with no time of any kind — a draft\n *   written before the created stamp existed, which sorts last exactly as it\n *   did before.\n */\nexport function emailListTimeMs(\n  record: Record<string, any> | null | undefined,\n): number {\n  return emailSendTimeMs(record) || emailCreatedAtMs(record) || 0\n}\n\n/**\n * Reader-facing text for a message's state.\n *\n * The KEYS are persisted values written by the send path and read by the\n * scheduled-campaign processor — nothing here may change them, including\n * `canceled`, which is already the American spelling and is a stored enum in\n * either case. Only the right-hand side is display text, and an unrecognized\n * state falls through as itself rather than being flattened into one of\n * these: a state this list cannot name is worth seeing.\n *\n * `draft` is an email that has been created and not sent. `sending` is the\n * claim the scheduled processor and the send-now route both take before they\n * mail, and it is named here because a merchant who reloads mid-send would\n * otherwise be shown the raw token.\n *\n * ⚠️ **Not what a console row should draw.** This names the STORED value, and\n * an email delivering an audience larger than one batch is stored as\n * `scheduled` between runs — so a row rendering this says \"Scheduled\" about a\n * send that has already put five hundred messages in five hundred inboxes.\n * `campaignSendDisplay` in `campaign-container.ts` reads the counters beside\n * the status and is what every surface here draws. This remains the honest\n * answer to the narrower question of what one stored token means.\n */\nexport function emailStateLabel(status: unknown): string {\n  const value = String(status ?? '')\n  if (value === 'sent') return 'Sent'\n  if (value === 'scheduled') return 'Scheduled'\n  if (value === 'canceled') return 'Canceled'\n  if (value === 'draft') return 'Draft'\n  if (value === 'sending') return 'Sending'\n  return value || 'Unknown'\n}\n\n/**\n * Whether an email has yet been mailed to anybody.\n *\n * The surfaces that report on a send need this because an unsent email has no\n * `stats` at all, and a report that divides into an absent denominator\n * presents \"not sent yet\" as a delivery rate of 0% — the same class of fault\n * as a rate rendered over a denominator it does not name.\n */\nexport function emailIsUnsent(\n  record: Record<string, any> | null | undefined,\n): boolean {\n  const value = String(record?.['status'] ?? '')\n  return value === 'draft' || value === 'scheduled' || value === 'sending'\n}\n\n/**\n * Reader-facing names for the built-in audience kinds.\n *\n * The KEYS are the persisted `audience` values written on every message since\n * the composer shipped; only the values on the right are display text. A\n * `list` audience is deliberately absent — it is not a kind of audience, it\n * is a NAMED one, and naming it is {@link emailAudienceLabel}'s job.\n */\nexport const EMAIL_AUDIENCE_LABELS: Record<string, string> = {\n  leads: 'All leads',\n  members: 'All site members',\n  segment: 'A contact segment',\n  manual: 'Addresses typed into the composer',\n}\n\n/**\n * Which audience a message went to, named for a reader.\n *\n * A list send is named by the name the SEND recorded, never by the name the\n * list carries today: resolving it now would let a rename rewrite the history\n * of a message that went out months ago, and a deletion erase it. A send that\n * recorded no name says so instead of printing a document id, which is not\n * something a merchant recognises as a list.\n */\nexport function emailAudienceLabel(\n  record: Record<string, any> | null | undefined,\n): string {\n  const audience = String(record?.['audience'] ?? '')\n  if (audience !== 'list') {\n    return EMAIL_AUDIENCE_LABELS[audience] ?? audience ?? 'Not recorded'\n  }\n  const name = String(record?.['listName'] ?? '')\n  if (name) return name\n  return record?.['listId']\n    ? 'A list this send did not name'\n    : 'A list this send did not record'\n}\n\n/**\n * The sender a message actually left with, as this record has it.\n *\n * `recorded` is the whole point of the shape. The address a send goes out on\n * is stamped by the send — see `sentAsStamp` — and every message sent before\n * that stamp existed carries nothing, so a surface has to be able to tell an\n * unrecorded sender apart from one it could compose. Composing it is the\n * thing that must not happen: a site's sending identity is a setting, and\n * resolving it now would answer \"what would this send as today\" on a report\n * whose subject is a message that went out months ago, under whatever address\n * the site held then.\n *\n * The same rule {@link emailAudienceLabel} follows for a list name, and for\n * the same reason: the report says what happened, not what would happen now.\n *\n * `replyTo` is null on a message that set none, which is not missing\n * information — a message with no `Reply-To:` takes replies at its `from`,\n * and that is a fact the record states by omission rather than one it lost.\n * The difference only reads correctly when `recorded` is true, which is why\n * a caller must consult that first.\n */\nexport interface EmailSentAs {\n  /** False on a message sent before the send began stamping its sender. */\n  recorded: boolean\n  from: string | null\n  /** The display name recipients saw, or null when the address stood alone. */\n  fromName: string | null\n  /** Where replies were pointed, or null when they go to `from`. */\n  replyTo: string | null\n}\n\nexport function emailSentAs(\n  record: Record<string, any> | null | undefined,\n): EmailSentAs {\n  const stamp = record?.['sentAs'] as Record<string, any> | null | undefined\n  const from = String(stamp?.['from'] ?? '').trim()\n  // The ADDRESS is what makes the stamp a record of a send. A `sentAs` map\n  // carrying only a display name is a partial write, and reporting it as\n  // recorded would put a name on screen beside an address nothing supplied.\n  if (!from) {\n    return { recorded: false, from: null, fromName: null, replyTo: null }\n  }\n  return {\n    recorded: true,\n    from,\n    fromName: String(stamp?.['fromName'] ?? '').trim() || null,\n    replyTo: String(stamp?.['replyTo'] ?? '').trim() || null,\n  }\n}\n"],"names":["emailSendTimeMs","record","String","sentAt","toMillis","seconds","scheduled","Number","isFinite","EMAIL_CREATED_AT_FIELD","emailCreatedAtMs","created","NaN","emailListTimeMs","emailStateLabel","status","value","emailIsUnsent","EMAIL_AUDIENCE_LABELS","leads","members","segment","manual","emailAudienceLabel","audience","name","emailSentAs","stamp","from","trim","recorded","fromName","replyTo"],"mappings":"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"}

package/src/lib/model/site-contract.d.ts

@@ -20,7 +20,7 @@
  * reads back. Pure types — shared by the /server graph and the client
  * runtime without pulling either's dependencies.
  */
-import type { HostActionStep, SiteEventType } from '@aglyn/aglyn';
+import type { ClientInteractionStep, SiteEventType } from '@aglyn/aglyn';
 import type { ExperimentStatus } from './experiments';
 export interface ClientAutomation {
     id: string;
@@ -35,7 +35,7 @@ export interface ClientAutomation {
     cooldownMinutes?: number;
     /** Fire on every occurrence, not once per pageview (AGL-562). */
     everyTime?: boolean;
-    steps: HostActionStep[];
+    steps: ClientInteractionStep[];
     hasServerSteps: boolean;
 }
 export interface ScreenExperiment {

package/src/lib/model/site-contract.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/site-contract.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 marketing plugin's site wire contract (AGL-419): shapes its server\n * page-enricher writes into the page props and its client site-runtime\n * reads back. Pure types — shared by the /server graph and the client\n * runtime without pulling either's dependencies.\n */\n\nimport type { HostActionStep, SiteEventType } from '@aglyn/aglyn'\nimport type { ExperimentStatus } from './experiments'\n\nexport interface ClientAutomation {\n  id: string\n  event: SiteEventType\n  selector?: string\n  threshold?: number\n  /** Fire at most once per visitor (AGL-266). */\n  oncePerVisitor?: boolean\n  /** Fire at most once per browser session (AGL-274). */\n  oncePerSession?: boolean\n  /** Minimum minutes between fires for the same visitor (AGL-274). */\n  cooldownMinutes?: number\n  /** Fire on every occurrence, not once per pageview (AGL-562). */\n  everyTime?: boolean\n  steps: HostActionStep[]\n  hasServerSteps: boolean\n}\n\nexport interface ScreenExperiment {\n  id: string\n  target: 'screen' | 'section'\n  status: ExperimentStatus\n  nodeId?: string\n  winnerVariantId?: string\n  /** Past this the client runner serves the default (AGL-273). */\n  endAtMs?: number\n  goal?: { event: string; filter?: string }\n  variants: Array<{ id: string; weight?: number; versionId?: string }>\n  payloads: Record<string, Record<string, any> | null>\n}\n\nexport interface AnnouncementBarData {\n  text: string\n  href?: string\n  backgroundColor?: string\n  textColor?: string\n  dismissible: boolean\n  contentHash: string\n  overlayId?: string\n}\n\nexport interface PopupData {\n  headline?: string\n  body: string\n  imageUrl?: string\n  /**\n   * Alt text for {@link imageUrl} (AGL-1896).\n   *\n   * The popup image used to render with a hardcoded `alt=\"\"` and there was\n   * no field anywhere that could have changed it — an author-chosen banner,\n   * on a paying customer's published site, invisible to a screen reader by\n   * construction. Defaults from the DAM asset's own alt when the author\n   * picks one through \"Browse media\"; an empty value still renders `alt=\"\"`,\n   * which is the right markup for a genuinely decorative banner.\n   */\n  imageAlt?: string\n  ctaLabel?: string\n  ctaHref?: string\n  trigger: string\n  triggerValue: number\n  frequencyDays: number\n  /**\n   * Cap the popup to one showing per browser session (AGL-2174). When\n   * set, `frequencyDays` is not consulted — the two are alternative\n   * answers to the same question.\n   */\n  oncePerSession?: boolean\n  collectEmail?: boolean\n  startAtMs?: number\n  endAtMs?: number\n  contentHash: string\n  overlayId?: string\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;CAKC,GA6CD,WA+BC"}
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/site-contract.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 marketing plugin's site wire contract (AGL-419): shapes its server\n * page-enricher writes into the page props and its client site-runtime\n * reads back. Pure types — shared by the /server graph and the client\n * runtime without pulling either's dependencies.\n */\n\nimport type { ClientInteractionStep, SiteEventType } from '@aglyn/aglyn'\nimport type { ExperimentStatus } from './experiments'\n\nexport interface ClientAutomation {\n  id: string\n  event: SiteEventType\n  selector?: string\n  threshold?: number\n  /** Fire at most once per visitor (AGL-266). */\n  oncePerVisitor?: boolean\n  /** Fire at most once per browser session (AGL-274). */\n  oncePerSession?: boolean\n  /** Minimum minutes between fires for the same visitor (AGL-274). */\n  cooldownMinutes?: number\n  /** Fire on every occurrence, not once per pageview (AGL-562). */\n  everyTime?: boolean\n  steps: ClientInteractionStep[]\n  hasServerSteps: boolean\n}\n\nexport interface ScreenExperiment {\n  id: string\n  target: 'screen' | 'section'\n  status: ExperimentStatus\n  nodeId?: string\n  winnerVariantId?: string\n  /** Past this the client runner serves the default (AGL-273). */\n  endAtMs?: number\n  goal?: { event: string; filter?: string }\n  variants: Array<{ id: string; weight?: number; versionId?: string }>\n  payloads: Record<string, Record<string, any> | null>\n}\n\nexport interface AnnouncementBarData {\n  text: string\n  href?: string\n  backgroundColor?: string\n  textColor?: string\n  dismissible: boolean\n  contentHash: string\n  overlayId?: string\n}\n\nexport interface PopupData {\n  headline?: string\n  body: string\n  imageUrl?: string\n  /**\n   * Alt text for {@link imageUrl} (AGL-1896).\n   *\n   * The popup image used to render with a hardcoded `alt=\"\"` and there was\n   * no field anywhere that could have changed it — an author-chosen banner,\n   * on a paying customer's published site, invisible to a screen reader by\n   * construction. Defaults from the DAM asset's own alt when the author\n   * picks one through \"Browse media\"; an empty value still renders `alt=\"\"`,\n   * which is the right markup for a genuinely decorative banner.\n   */\n  imageAlt?: string\n  ctaLabel?: string\n  ctaHref?: string\n  trigger: string\n  triggerValue: number\n  frequencyDays: number\n  /**\n   * Cap the popup to one showing per browser session (AGL-2174). When\n   * set, `frequencyDays` is not consulted — the two are alternative\n   * answers to the same question.\n   */\n  oncePerSession?: boolean\n  collectEmail?: boolean\n  startAtMs?: number\n  endAtMs?: number\n  contentHash: string\n  overlayId?: string\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;CAKC,GA6CD,WA+BC"}

package/src/lib/model/template-report.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @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.
+ */
+/**
+ * ONE DESIGN, MEASURED ACROSS EVERY CAMPAIGN THAT USED IT.
+ *
+ * ## What this adds to `campaign-report.ts`
+ *
+ * A campaign report divides two numbers that were recorded by the same send.
+ * A design report divides two SUMS, and a sum has a membership: which
+ * campaigns went into it. That is the whole difficulty, and it is a new way
+ * for the repo's rule — every rate names its denominator — to be broken.
+ *
+ * ## The rule, restated for a sum
+ *
+ * **A rate's numerator and its denominator are summed over the SAME set of
+ * campaigns, and the screen is told how large that set is.**
+ *
+ * `delivered` is written only by the delivery webhook, so a design used by
+ * five campaigns may have three that recorded it and two that never did.
+ * Summing `uniqueOpens` over all five and dividing by `delivered` summed over
+ * three produces an open rate that can exceed 100% and is, in every case,
+ * the flattering substitution `campaign-report.ts` exists to refuse — carried
+ * out by addition instead of by picking the wrong field.
+ *
+ * So each rate here is built from a FILTERED subset, and
+ * {@link TemplateRate.denominatorLabel} names the subset as well as the
+ * quantity: `delivered across 3 of 5 campaigns`. A reader comparing this
+ * design's open rate with another's can see the two were taken over different
+ * populations without being told separately.
+ *
+ * ## Counts are over everything; rates are over what can be divided
+ *
+ * The COUNTS — opens, clicks, unsubscribes — are summed over every campaign,
+ * because a count is true whatever else was recorded. Only the rates narrow.
+ * The two are labelled differently on screen for that reason, and the caveats
+ * say how many campaigns each rate left out.
+ *
+ * ## Why this is a pure module
+ *
+ * Same reason as `campaign-report.ts`: a division written in JSX is a
+ * denominator chosen by whoever writes the next card. Here it is worse — the
+ * subset is invisible in the output unless something carries it — so the
+ * subset is data, computed once, and the screen renders it.
+ */
+import { type SendRate, type SendStats } from '@aglyn/shared-ui-email-campaigns/model/send-report';
+/** A rate over a sum, carrying how many campaigns the sum covers. */
+export type TemplateRate = SendRate;
+/**
+ * One campaign that used the design, as the report reads it.
+ *
+ * `sentAtMs` is nullable because a campaign document can exist without ever
+ * having been sent — a scheduled campaign holds `sendAtMs` and no `sentAt`.
+ * Those carry no engagement and the reader is shown their status rather than
+ * a row of zeroes.
+ */
+export interface TemplateCampaign {
+    campaignId: string;
+    subject: string;
+    /** Epoch ms, or null for a campaign that has not been sent. */
+    sentAtMs: number | null;
+    /** `'sent'`, `'scheduled'`, `'canceled'`. A persisted value; not relabeled. */
+    status: string;
+    /** The audience KIND — `'leads'`, `'members'`, `'segment'`, `'list'`. */
+    audience: string;
+    /** Set when `audience` is `'list'`. */
+    listId?: string;
+    /** The list's name AS IT WAS at send time, when the send recorded one. */
+    listName?: string;
+    stats: SendStats | undefined;
+}
+/**
+ * One audience the design was sent to.
+ *
+ * A LIST is named by the name the send recorded, not by the name the list
+ * carries today: a renamed or deleted list would otherwise rewrite the
+ * history of a campaign that went out months ago, and a deleted one would
+ * erase it. The same reasoning as the campaign report's populations.
+ */
+export interface TemplateAudience {
+    /** Stable key — the list id, or the audience kind for the built-ins. */
+    id: string;
+    label: string;
+    /** How many campaigns using this design went to this audience. */
+    campaigns: number;
+    /** Addresses those campaigns ADDRESSED, summed. */
+    addressed: number;
+    /**
+     * The named list has since been deleted or renamed out of reach.
+     *
+     * Only ever true for a `list` audience, and only when the send recorded no
+     * name — an older send, before the name was stored. The screen says "list
+     * no longer named" rather than printing a raw document id as if it were
+     * something a merchant would recognise.
+     */
+    unnamed?: boolean;
+}
+/** Why a number the design report would otherwise show is being withheld. */
+export interface TemplateCaveat {
+    id: 'no-campaigns' | 'delivery-partial' | 'click-tracking-partial' | 'campaigns-truncated' | 'audience-truncated';
+    message: string;
+}
+/** Everything the design report screen renders. */
+export interface TemplateReport {
+    /** Campaigns that used this design AND were sent. */
+    sentCampaigns: number;
+    /** Campaigns that used this design, sent or not. */
+    totalCampaigns: number;
+    /** Epoch ms of the most recent send, or null. */
+    lastSentAtMs: number | null;
+    recipients: number;
+    sent: number;
+    /** Summed over the campaigns that recorded it; null when none did. */
+    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: {
+        delivery: TemplateRate | null;
+        open: TemplateRate | null;
+        click: TemplateRate | null;
+        clickToOpen: TemplateRate | null;
+        bounce: TemplateRate | null;
+        complaint: TemplateRate | null;
+        unsubscribe: TemplateRate | null;
+    };
+    audiences: TemplateAudience[];
+    caveats: TemplateCaveat[];
+}
+/**
+ * Aggregates every campaign that used one design.
+ *
+ * @param campaigns every campaign document naming this design, sent or not.
+ * @param truncated the query that produced `campaigns` stopped at its read
+ *        ceiling, so every total here is a FLOOR. Reported as a caveat rather
+ *        than hidden, on the same reasoning as `audienceSizeTruncated`: a
+ *        figure that is at least this large is useful, and a figure presented
+ *        as complete when it is not is worse than none.
+ */
+export declare function templateReport(campaigns: readonly TemplateCampaign[], truncated?: boolean): TemplateReport;