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

package/src/lib/model/campaign-kind.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @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.
+ */
+/**
+ * A CAMPAIGN, AS A CONTAINER KIND.
+ *
+ * This plugin keeps campaigns and declares the kind in `plugins.config.json`
+ * (`containers`): the containers are `orgs/{orgId}/emailCampaigns`, and a
+ * form, a screen, a lead or a contact is filed under one by carrying its id
+ * in `campaignIds` on its own document. The other plugins that file records
+ * under a campaign name the kind, never this module; the core derives the
+ * field from it (`app-utils/container-membership.ts`).
+ */
+export declare const CAMPAIGN_KIND = "campaign";
+/**
+ * The field a member holds its campaigns in. Persisted on every filed form,
+ * screen and lead, and inside each holder's facet on a contact.
+ */
+export declare const CAMPAIGN_MEMBERSHIP_FIELD: string;
+/**
+ * The host subcollections whose documents may name a campaign and that this
+ * plugin clears when a campaign is deleted: a form's and a screen's, filed
+ * from their own pages.
+ *
+ * The list a campaign's deletion walks, and the list the assignment surfaces
+ * spec reads — so a collection that grows a picker without growing the
+ * detach fails the build rather than shipping a campaign whose removal
+ * leaves that collection pointing at nothing.
+ *
+ * Another plugin's members are NOT here. A lead and a contact are the CRM's
+ * — a lead carries the field at the top of its document, on the org and on
+ * the site rows the lead migration has not reached, and a contact inside a
+ * per-holder facet — and a sequence and its enrollments are Outreach's. Each
+ * of those plugins registers a detacher
+ * (`plugin-manager/plugin-membership-detach.ts`) and the deletion runs it.
+ */
+export declare const CAMPAIGN_MEMBER_HOST_COLLECTIONS: readonly ["forms", "screens"];

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

@@ -0,0 +1,52 @@
+/**
+ * @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 { containerMembershipField } from "@aglyn/aglyn/app-utils/container-membership";
+/**
+ * A CAMPAIGN, AS A CONTAINER KIND.
+ *
+ * This plugin keeps campaigns and declares the kind in `plugins.config.json`
+ * (`containers`): the containers are `orgs/{orgId}/emailCampaigns`, and a
+ * form, a screen, a lead or a contact is filed under one by carrying its id
+ * in `campaignIds` on its own document. The other plugins that file records
+ * under a campaign name the kind, never this module; the core derives the
+ * field from it (`app-utils/container-membership.ts`).
+ */ export const CAMPAIGN_KIND = 'campaign';
+/**
+ * The field a member holds its campaigns in. Persisted on every filed form,
+ * screen and lead, and inside each holder's facet on a contact.
+ */ export const CAMPAIGN_MEMBERSHIP_FIELD = containerMembershipField(CAMPAIGN_KIND);
+/**
+ * The host subcollections whose documents may name a campaign and that this
+ * plugin clears when a campaign is deleted: a form's and a screen's, filed
+ * from their own pages.
+ *
+ * The list a campaign's deletion walks, and the list the assignment surfaces
+ * spec reads — so a collection that grows a picker without growing the
+ * detach fails the build rather than shipping a campaign whose removal
+ * leaves that collection pointing at nothing.
+ *
+ * Another plugin's members are NOT here. A lead and a contact are the CRM's
+ * — a lead carries the field at the top of its document, on the org and on
+ * the site rows the lead migration has not reached, and a contact inside a
+ * per-holder facet — and a sequence and its enrollments are Outreach's. Each
+ * of those plugins registers a detacher
+ * (`plugin-manager/plugin-membership-detach.ts`) and the deletion runs it.
+ */ export const CAMPAIGN_MEMBER_HOST_COLLECTIONS = [
+    'forms',
+    'screens'
+];
+
+//# sourceMappingURL=campaign-kind.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-kind.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 { containerMembershipField } from '@aglyn/aglyn/app-utils/container-membership'\n\n/**\n * A CAMPAIGN, AS A CONTAINER KIND.\n *\n * This plugin keeps campaigns and declares the kind in `plugins.config.json`\n * (`containers`): the containers are `orgs/{orgId}/emailCampaigns`, and a\n * form, a screen, a lead or a contact is filed under one by carrying its id\n * in `campaignIds` on its own document. The other plugins that file records\n * under a campaign name the kind, never this module; the core derives the\n * field from it (`app-utils/container-membership.ts`).\n */\nexport const CAMPAIGN_KIND = 'campaign'\n\n/**\n * The field a member holds its campaigns in. Persisted on every filed form,\n * screen and lead, and inside each holder's facet on a contact.\n */\nexport const CAMPAIGN_MEMBERSHIP_FIELD = containerMembershipField(CAMPAIGN_KIND)\n\n/**\n * The host subcollections whose documents may name a campaign and that this\n * plugin clears when a campaign is deleted: a form's and a screen's, filed\n * from their own pages.\n *\n * The list a campaign's deletion walks, and the list the assignment surfaces\n * spec reads — so a collection that grows a picker without growing the\n * detach fails the build rather than shipping a campaign whose removal\n * leaves that collection pointing at nothing.\n *\n * Another plugin's members are NOT here. A lead and a contact are the CRM's\n * — a lead carries the field at the top of its document, on the org and on\n * the site rows the lead migration has not reached, and a contact inside a\n * per-holder facet — and a sequence and its enrollments are Outreach's. Each\n * of those plugins registers a detacher\n * (`plugin-manager/plugin-membership-detach.ts`) and the deletion runs it.\n */\nexport const CAMPAIGN_MEMBER_HOST_COLLECTIONS = ['forms', 'screens'] as const\n"],"names":["containerMembershipField","CAMPAIGN_KIND","CAMPAIGN_MEMBERSHIP_FIELD","CAMPAIGN_MEMBER_HOST_COLLECTIONS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,wBAAwB,QAAQ,8CAA6C;AAEtF;;;;;;;;;CASC,GACD,OAAO,MAAMC,gBAAgB,WAAU;AAEvC;;;CAGC,GACD,OAAO,MAAMC,4BAA4BF,yBAAyBC,eAAc;AAEhF;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,MAAME,mCAAmC;IAAC;IAAS;CAAU,CAAS"}

package/src/lib/model/campaign-members-query.js

@@ -13,7 +13,7 @@
  * 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 { CAMPAIGN_MEMBERSHIP_FIELD } from "@aglyn/aglyn/app-utils/campaign-membership";
+ */ import { CAMPAIGN_MEMBERSHIP_FIELD } from "./campaign-kind.js";
 import { LIST_QUERY_ID_PATH } from "@aglyn/shared-ui-jsx/const/list-query-plan";
 /*
  * WHAT A CAMPAIGN'S SCREENS AND FORMS LISTS ASK FIRESTORE (AGL-3321).

package/src/lib/model/campaign-members-query.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-members-query.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 { CAMPAIGN_MEMBERSHIP_FIELD } from '@aglyn/aglyn/app-utils/campaign-membership'\nimport type { ListFilterField } from '@aglyn/shared-ui-jsx/const/list-filter'\nimport type { ListFilterClause } from '@aglyn/shared-ui-jsx/const/list-grid-filter'\nimport {\n  LIST_QUERY_ID_PATH,\n  type ListQueryDeclaration,\n  type ListQueryFilter,\n} from '@aglyn/shared-ui-jsx/const/list-query-plan'\n\n/*\n * WHAT A CAMPAIGN'S SCREENS AND FORMS LISTS ASK FIRESTORE (AGL-3321).\n *\n * A campaign's page lists the screens and the forms filed under it, each a\n * table paged by its own query over `hosts/{hostId}/screens` or `/forms`.\n * The search box and the soft delete are predicates on that query, so a\n * member on the fourth page is found and a deleted one is never a row.\n *\n * ## The base: the membership, and (for screens) not deleted\n *\n * `campaignIds array-contains {campaign}` is the join — the member's own\n * field, read from the other end — and it is the query's ONE array clause.\n *\n * A screen is soft-deleted: a delete stamps `deletedAt` and leaves the\n * document, with its campaigns, in place. So the screens query also asks\n * `deletedAt == null`, which matches only a document that HOLDS the field:\n * every screen create stamps `deletedAt: null` (`artifactCreateListKeys`),\n * and `tools/scripts/backfill-artifacts-list-keys.mjs` stamps the screens\n * written before it. A form has no soft delete — it is deleted outright —\n * so its base is the membership alone, and a retired form stays a member.\n *\n * Unsearched, both lists walk the document name, which every record has:\n * the equality and the array clause merge on Firestore's single-field\n * indexes, so the default read needs no composite.\n *\n * ## The search is a PREFIX RANGE on `nameLower`\n *\n * A word search is an `array-contains` on `nameTokens`, and the membership\n * has already spent the query's one array clause. So the search matches the\n * START of the name — `nameLower` from the typed text to the text followed\n * by the highest character — which is a range, orders the page by name while\n * it applies, and is said above the table (`CAMPAIGN_MEMBERS_SEARCH_NOTICE`),\n * as a site's campaigns list says it.\n *\n * ## The composites: two\n *\n * A range beside equalities needs a composite. Under index merging this\n * shape would take one `(predicate, nameLower)` pair per predicate — three\n * across the two collections — so each collection instead carries the ONE\n * composite that serves its whole search shape:\n *\n *   screens  campaignIds CONTAINS, deletedAt ASC, nameLower ASC\n *   forms    campaignIds CONTAINS, nameLower ASC\n *\n * Pinned by `list-query-indexes.spec.ts`. Nothing else is offered: a column\n * filter would be one more predicate beside the range, and so one more\n * composite per collection, for lists that hold a campaign's handful of\n * pages and forms.\n */\n\n/** The name field the search ranges over, as the planner reads it. */\nconst MEMBER_NAME: ListFilterField = {\n  column: 'name',\n  kind: 'text',\n  path: 'displayName',\n  lowerPath: 'nameLower',\n  operators: ['startsWith'],\n}\n\n/** A campaign's screens or forms: the name's start, walked by document name. */\nexport const CAMPAIGN_MEMBERS_QUERY: ListQueryDeclaration = {\n  fields: [MEMBER_NAME],\n  sorts: [{ path: LIST_QUERY_ID_PATH, direction: 'asc' }],\n}\n\n/** The collections a campaign's members are read from. */\nexport type CampaignMemberCollection = 'screens' | 'forms'\n\n/** A screen that has not been deleted: `deletedAt` stored as `null`. */\nexport const SCREEN_NOT_DELETED: ListQueryFilter = {\n  path: 'deletedAt',\n  op: '==',\n  value: null,\n}\n\n/**\n * The predicates every read of a campaign's members carries: the\n * membership, and for screens the soft delete.\n */\nexport function campaignMembersBase(\n  collection: CampaignMemberCollection,\n  campaignId: string,\n): ListQueryFilter[] {\n  return [\n    { path: CAMPAIGN_MEMBERSHIP_FIELD, op: 'array-contains', value: campaignId },\n    ...(collection === 'screens' ? [SCREEN_NOT_DELETED] : []),\n  ]\n}\n\n/** Said above a member table while its search applies. */\nexport const CAMPAIGN_MEMBERS_SEARCH_NOTICE =\n  'Search here matches the start of a name.'\n\n/**\n * The search box's words as the clause the query serves: \"Name starts\n * with\", or null when nothing was typed. The table passes it among its\n * clauses and no search words — see the file header for why.\n */\nexport function campaignMembersSearchClause(\n  words: readonly string[],\n): ListFilterClause | null {\n  const typed = words\n    .map((word) => word.trim())\n    .filter(Boolean)\n    .join(' ')\n  return typed ? { field: 'name', op: 'startsWith', value: typed } : null\n}\n"],"names":["CAMPAIGN_MEMBERSHIP_FIELD","LIST_QUERY_ID_PATH","MEMBER_NAME","column","kind","path","lowerPath","operators","CAMPAIGN_MEMBERS_QUERY","fields","sorts","direction","SCREEN_NOT_DELETED","op","value","campaignMembersBase","collection","campaignId","CAMPAIGN_MEMBERS_SEARCH_NOTICE","campaignMembersSearchClause","words","typed","map","word","trim","filter","Boolean","join","field"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,yBAAyB,QAAQ,6CAA4C;AAGtF,SACEC,kBAAkB,QAGb,6CAA4C;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDC,GAED,oEAAoE,GACpE,MAAMC,cAA+B;IACnCC,QAAQ;IACRC,MAAM;IACNC,MAAM;IACNC,WAAW;IACXC,WAAW;QAAC;KAAa;AAC3B;AAEA,8EAA8E,GAC9E,OAAO,MAAMC,yBAA+C;IAC1DC,QAAQ;QAACP;KAAY;IACrBQ,OAAO;QAAC;YAAEL,MAAMJ;YAAoBU,WAAW;QAAM;KAAE;AACzD,EAAC;AAKD,sEAAsE,GACtE,OAAO,MAAMC,qBAAsC;IACjDP,MAAM;IACNQ,IAAI;IACJC,OAAO;AACT,EAAC;AAED;;;CAGC,GACD,OAAO,SAASC,oBACdC,UAAoC,EACpCC,UAAkB;IAElB,OAAO;QACL;YAAEZ,MAAML;YAA2Ba,IAAI;YAAkBC,OAAOG;QAAW;WACvED,eAAe,YAAY;YAACJ;SAAmB,GAAG,EAAE;KACzD;AACH;AAEA,wDAAwD,GACxD,OAAO,MAAMM,iCACX,2CAA0C;AAE5C;;;;CAIC,GACD,OAAO,SAASC,4BACdC,KAAwB;IAExB,MAAMC,QAAQD,MACXE,GAAG,CAAC,CAACC,OAASA,KAAKC,IAAI,IACvBC,MAAM,CAACC,SACPC,IAAI,CAAC;IACR,OAAON,QAAQ;QAAEO,OAAO;QAAQf,IAAI;QAAcC,OAAOO;IAAM,IAAI;AACrE"}
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-members-query.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 { CAMPAIGN_MEMBERSHIP_FIELD } from './campaign-kind'\nimport type { ListFilterField } from '@aglyn/shared-ui-jsx/const/list-filter'\nimport type { ListFilterClause } from '@aglyn/shared-ui-jsx/const/list-grid-filter'\nimport {\n  LIST_QUERY_ID_PATH,\n  type ListQueryDeclaration,\n  type ListQueryFilter,\n} from '@aglyn/shared-ui-jsx/const/list-query-plan'\n\n/*\n * WHAT A CAMPAIGN'S SCREENS AND FORMS LISTS ASK FIRESTORE (AGL-3321).\n *\n * A campaign's page lists the screens and the forms filed under it, each a\n * table paged by its own query over `hosts/{hostId}/screens` or `/forms`.\n * The search box and the soft delete are predicates on that query, so a\n * member on the fourth page is found and a deleted one is never a row.\n *\n * ## The base: the membership, and (for screens) not deleted\n *\n * `campaignIds array-contains {campaign}` is the join — the member's own\n * field, read from the other end — and it is the query's ONE array clause.\n *\n * A screen is soft-deleted: a delete stamps `deletedAt` and leaves the\n * document, with its campaigns, in place. So the screens query also asks\n * `deletedAt == null`, which matches only a document that HOLDS the field:\n * every screen create stamps `deletedAt: null` (`artifactCreateListKeys`),\n * and `tools/scripts/backfill-artifacts-list-keys.mjs` stamps the screens\n * written before it. A form has no soft delete — it is deleted outright —\n * so its base is the membership alone, and a retired form stays a member.\n *\n * Unsearched, both lists walk the document name, which every record has:\n * the equality and the array clause merge on Firestore's single-field\n * indexes, so the default read needs no composite.\n *\n * ## The search is a PREFIX RANGE on `nameLower`\n *\n * A word search is an `array-contains` on `nameTokens`, and the membership\n * has already spent the query's one array clause. So the search matches the\n * START of the name — `nameLower` from the typed text to the text followed\n * by the highest character — which is a range, orders the page by name while\n * it applies, and is said above the table (`CAMPAIGN_MEMBERS_SEARCH_NOTICE`),\n * as a site's campaigns list says it.\n *\n * ## The composites: two\n *\n * A range beside equalities needs a composite. Under index merging this\n * shape would take one `(predicate, nameLower)` pair per predicate — three\n * across the two collections — so each collection instead carries the ONE\n * composite that serves its whole search shape:\n *\n *   screens  campaignIds CONTAINS, deletedAt ASC, nameLower ASC\n *   forms    campaignIds CONTAINS, nameLower ASC\n *\n * Pinned by `list-query-indexes.spec.ts`. Nothing else is offered: a column\n * filter would be one more predicate beside the range, and so one more\n * composite per collection, for lists that hold a campaign's handful of\n * pages and forms.\n */\n\n/** The name field the search ranges over, as the planner reads it. */\nconst MEMBER_NAME: ListFilterField = {\n  column: 'name',\n  kind: 'text',\n  path: 'displayName',\n  lowerPath: 'nameLower',\n  operators: ['startsWith'],\n}\n\n/** A campaign's screens or forms: the name's start, walked by document name. */\nexport const CAMPAIGN_MEMBERS_QUERY: ListQueryDeclaration = {\n  fields: [MEMBER_NAME],\n  sorts: [{ path: LIST_QUERY_ID_PATH, direction: 'asc' }],\n}\n\n/** The collections a campaign's members are read from. */\nexport type CampaignMemberCollection = 'screens' | 'forms'\n\n/** A screen that has not been deleted: `deletedAt` stored as `null`. */\nexport const SCREEN_NOT_DELETED: ListQueryFilter = {\n  path: 'deletedAt',\n  op: '==',\n  value: null,\n}\n\n/**\n * The predicates every read of a campaign's members carries: the\n * membership, and for screens the soft delete.\n */\nexport function campaignMembersBase(\n  collection: CampaignMemberCollection,\n  campaignId: string,\n): ListQueryFilter[] {\n  return [\n    { path: CAMPAIGN_MEMBERSHIP_FIELD, op: 'array-contains', value: campaignId },\n    ...(collection === 'screens' ? [SCREEN_NOT_DELETED] : []),\n  ]\n}\n\n/** Said above a member table while its search applies. */\nexport const CAMPAIGN_MEMBERS_SEARCH_NOTICE =\n  'Search here matches the start of a name.'\n\n/**\n * The search box's words as the clause the query serves: \"Name starts\n * with\", or null when nothing was typed. The table passes it among its\n * clauses and no search words — see the file header for why.\n */\nexport function campaignMembersSearchClause(\n  words: readonly string[],\n): ListFilterClause | null {\n  const typed = words\n    .map((word) => word.trim())\n    .filter(Boolean)\n    .join(' ')\n  return typed ? { field: 'name', op: 'startsWith', value: typed } : null\n}\n"],"names":["CAMPAIGN_MEMBERSHIP_FIELD","LIST_QUERY_ID_PATH","MEMBER_NAME","column","kind","path","lowerPath","operators","CAMPAIGN_MEMBERS_QUERY","fields","sorts","direction","SCREEN_NOT_DELETED","op","value","campaignMembersBase","collection","campaignId","CAMPAIGN_MEMBERS_SEARCH_NOTICE","campaignMembersSearchClause","words","typed","map","word","trim","filter","Boolean","join","field"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,yBAAyB,QAAQ,qBAAiB;AAG3D,SACEC,kBAAkB,QAGb,6CAA4C;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDC,GAED,oEAAoE,GACpE,MAAMC,cAA+B;IACnCC,QAAQ;IACRC,MAAM;IACNC,MAAM;IACNC,WAAW;IACXC,WAAW;QAAC;KAAa;AAC3B;AAEA,8EAA8E,GAC9E,OAAO,MAAMC,yBAA+C;IAC1DC,QAAQ;QAACP;KAAY;IACrBQ,OAAO;QAAC;YAAEL,MAAMJ;YAAoBU,WAAW;QAAM;KAAE;AACzD,EAAC;AAKD,sEAAsE,GACtE,OAAO,MAAMC,qBAAsC;IACjDP,MAAM;IACNQ,IAAI;IACJC,OAAO;AACT,EAAC;AAED;;;CAGC,GACD,OAAO,SAASC,oBACdC,UAAoC,EACpCC,UAAkB;IAElB,OAAO;QACL;YAAEZ,MAAML;YAA2Ba,IAAI;YAAkBC,OAAOG;QAAW;WACvED,eAAe,YAAY;YAACJ;SAAmB,GAAG,EAAE;KACzD;AACH;AAEA,wDAAwD,GACxD,OAAO,MAAMM,iCACX,2CAA0C;AAE5C;;;;CAIC,GACD,OAAO,SAASC,4BACdC,KAAwB;IAExB,MAAMC,QAAQD,MACXE,GAAG,CAAC,CAACC,OAASA,KAAKC,IAAI,IACvBC,MAAM,CAACC,SACPC,IAAI,CAAC;IACR,OAAON,QAAQ;QAAEO,OAAO;QAAQf,IAAI;QAAcC,OAAOO;IAAM,IAAI;AACrE"}

package/src/lib/model/campaign-revenue.d.ts

@@ -0,0 +1,327 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type CampaignCaveat } from '@aglyn/shared-ui-email-campaigns/model/campaign-report';
+/**
+ * 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';
+/** One currency's totals as the rollup stores them. */
+export interface CampaignRevenueCurrencyStored {
+    /** Minor units credited to this campaign, gross of refunds. */
+    grossCents?: number;
+    /** Minor units handed back on orders that had been credited. */
+    refundedCents?: number;
+    /** Orders credited to this campaign. */
+    orders?: number;
+    /** Of those, how many ended fully reversed. */
+    refundedOrders?: number;
+}
+/**
+ * The stored shape of `campaigns/{campaignId}/reports/revenue`.
+ *
+ * Its own document, for the reason the link rollup is its own document: the
+ * campaign document is read by the history list, the glance widget and the
+ * send path, and a map that grows with the campaign's sales would make every
+ * one of those reads larger. Split, it is read by the one screen that draws
+ * it.
+ */
+export interface CampaignRevenueRollup {
+    byCurrency?: Record<string, CampaignRevenueCurrencyStored>;
+    /** The model the orders in this rollup were credited under. */
+    model?: string;
+    /** The window, in days, they were credited inside. */
+    windowDays?: number;
+}
+/**
+ * Money over a population, with the population named — {@link CampaignRate}'s
+ * rule applied to an average instead of a share.
+ *
+ * A percentage and an average go wrong the same way, so they carry the same
+ * guarantee: the denominator travels as data and the screen has to print it.
+ * "$0.42 per recipient" over an audience nobody named is the figure this
+ * whole reporting surface exists to refuse.
+ */
+export interface CampaignMoneyPerMessage {
+    /** Minor units per message of the denominator. Fractional by nature. */
+    cents: number;
+    numeratorCents: number;
+    denominator: number;
+    denominatorLabel: string;
+    currency: string;
+}
+/** One currency's block on screen. */
+export interface CampaignRevenueCurrencyReport {
+    /** Lowercase ISO code as the sale recorded it, e.g. `'usd'`. */
+    currency: string;
+    grossCents: number;
+    refundedCents: number;
+    /** `gross - refunded`, clamped at zero. */
+    netCents: number;
+    orders: number;
+    refundedOrders: number;
+    /**
+     * Net revenue per DELIVERED message, or `null` when it cannot be taken.
+     *
+     * Delivered is the denominator for the same reason every engagement rate on
+     * this report is taken over it: mail that bounced was never in front of a
+     * human, so counting it depresses a figure describing the audience with a
+     * fact about the address list.
+     *
+     * It is deliberately NOT taken over `audienceSize`. That figure is written
+     * by the FIRST batch only and is a floor when audience resolution hit its
+     * read ceiling, so a campaign delivered over six runs would divide six
+     * runs' revenue by one run's measure of the audience — the stale-population
+     * division this surface is built to make impossible.
+     */
+    netPerDelivered: CampaignMoneyPerMessage | null;
+}
+/** Everything the revenue section renders. */
+export interface CampaignRevenueReport {
+    /** One block per currency, largest net first. Never summed together. */
+    currencies: CampaignRevenueCurrencyReport[];
+    /** Orders credited to this campaign, across every currency. */
+    attributedOrders: number;
+    /**
+     * Whether any attribution has ever been recorded for this campaign.
+     *
+     * `false` means the rollup document does not exist, which is NOT the same
+     * as "this campaign earned nothing" — it is also every campaign sent before
+     * the join existed, and every campaign on a site with no store. The screen
+     * renders the difference rather than printing a zero for both.
+     */
+    recorded: boolean;
+    /** More than one currency is present, so no total may be shown. */
+    multiCurrency: boolean;
+    /** The model these figures were credited under, as stored. */
+    model: string;
+    /** The window they were credited inside, as stored. */
+    windowDays: number;
+    caveats: CampaignCaveat[];
+}
+/**
+ * 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 declare const REVENUE_MULTI_CURRENCY_MESSAGE: string;
+/**
+ * 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 declare function campaignMoneyPerMessage(numeratorCents: number, denominator: number | undefined, denominatorLabel: string, currency: string): CampaignMoneyPerMessage | null;
+/**
+ * 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 declare function campaignRevenueReport(options: {
+    rollup: CampaignRevenueRollup | undefined;
+    /** `stats.delivered`, or `null` when it was never recorded. */
+    delivered: number | null;
+    /** True while the send is still working through its audience. */
+    midFlight?: boolean;
+}): CampaignRevenueReport;
+/** One currency's totals, merged across a campaign's emails. */
+export interface CampaignRevenueCurrencyAcrossSends {
+    /** Lowercase ISO code as the sales recorded it, e.g. `'usd'`. */
+    currency: string;
+    grossCents: number;
+    refundedCents: number;
+    /** `gross - refunded` over the whole campaign, clamped once at zero. */
+    netCents: number;
+    orders: number;
+    refundedOrders: number;
+    /** Emails of the campaign whose revenue record holds this currency. */
+    emails: number;
+}
+/** Everything a campaign container's revenue section renders. */
+export interface CampaignRevenueAcrossSends {
+    /** One block per currency, largest net first. Never summed together. */
+    currencies: CampaignRevenueCurrencyAcrossSends[];
+    /**
+     * Orders credited across every currency.
+     *
+     * A COUNT, which is why it may cross currencies when the money may not: an
+     * order is one order whatever it was paid in, and counting two of them
+     * loses nothing. Adding their amounts loses the unit.
+     */
+    attributedOrders: number;
+    /** Emails whose revenue record was looked for. */
+    read: number;
+    /**
+     * Of those, how many have a revenue record at all.
+     *
+     * The rollup is created by the attribution writer on the first order it
+     * credits, so an email with no record has never been credited with one.
+     * Zero across the whole campaign is therefore the container's version of
+     * {@link CampaignRevenueReport.recorded} being `false`: it is not "this
+     * campaign earned nothing", it is also every campaign sent before the join
+     * existed and every campaign on a site with no store.
+     */
+    recorded: number;
+    /** More than one currency is present, so no total may be shown. */
+    multiCurrency: boolean;
+    /** The models these emails were credited under, distinct and sorted. */
+    models: string[];
+    /** The windows, in days, they were credited inside, distinct and sorted. */
+    windowDays: number[];
+    caveats: CampaignCaveat[];
+}
+/**
+ * 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 declare function campaignRevenueAcrossSends(rollups: readonly (CampaignRevenueRollup | undefined)[]): CampaignRevenueAcrossSends;