@happyvertical/smrt-marketing 0.43.9 → 0.44.0

package/AGENTS.md

@@ -55,9 +55,11 @@ All generated surfaces are explicit; never omit `api`, `mcp`, or `cli` config.
   uses a five-percent budget tolerance around schedule-derived expected spend.
 - **CampaignCollection** exposes bounded, tenant-and-Customer-scoped cursor
   pages ordered by `start_at DESC, id DESC` and bounded batch summaries for
-  total count, active count, and latest start time. Customer scope is validated
-  through runtime relationship metadata; there is no static commerce import or
-  tenant-wide campaign materialization.
+  total count, active count, and latest start time. Its reporting-page variant
+  preserves that order/cursor and adds channel count/mix, immutable metric
+  totals, and canonical pacing with two page-wide grouped reads. Customer scope
+  is validated through runtime relationship metadata; there is no static
+  commerce import, per-campaign callback, or tenant-wide materialization.
 
 ## Svelte
 

package/README.md

@@ -83,12 +83,31 @@ const secondPage = firstPage.nextCursor
 
 const summaries = await campaigns.summarizeByCustomers(tenantId, customerIds);
 // [{ customerId, totalCount, activeCount, latestStartAt }]
+
+const reporting = await campaigns.listReportingByCustomer(
+  tenantId,
+  customerId,
+  {
+    limit: 50,
+    after: firstPage.nextCursor ?? undefined,
+    at: new Date('2026-08-15T00:00:00Z'),
+  },
+);
+// reporting.items keeps the same newest-first page order. Every item contains:
+// { campaign, channelCount, channelMix, metricTotals, pacing }
 ```
 
-Pages and summary batches are capped at 100 items and reject larger inputs.
-Pagination is newest-first by `startAt`, then UUID; campaigns without a start
-time follow scheduled campaigns. Summary resolution uses a bounded grouped
-query rather than loading tenant campaigns or issuing one query per Customer.
+Pages, reporting pages, and summary batches are capped at 100 items and reject
+larger inputs. Pagination is newest-first by `startAt`, then UUID; campaigns
+without a start time follow scheduled campaigns. `listReportingByCustomer()`
+validates Customer scope and reads the page in one transaction, then performs
+one grouped channel read and one grouped immutable-evidence read regardless of
+page size. `metricTotals` use the same evidence selection as
+`BudgetPacingService`: for each exact period, a campaign rollup replaces its
+channel snapshots while channel-only periods remain. `pacing` is therefore
+equivalent to `getCampaignPacing()` without per-campaign callbacks or lazy
+loads. Summary resolution likewise uses a bounded grouped query rather than
+loading tenant campaigns or issuing one query per Customer.
 
 ### Migrating metadata-backed associations
 

package/dist/collections/CampaignCollection.d.ts

@@ -1,6 +1,6 @@
 import { CollectionCacheConfig, SmrtCollection, SmrtListOptions, SmrtSelectedRow, SmrtSelectField, SmrtWhereClause } from '@happyvertical/smrt-core';
 import { Campaign } from '../models/Campaign.js';
-import { CampaignCustomerPage, CampaignCustomerSummary, CampaignStatus, ListCampaignsByCustomerOptions } from '../types.js';
+import { CampaignCustomerPage, CampaignCustomerSummary, CampaignReportingPage, CampaignStatus, ListCampaignReportingByCustomerOptions, ListCampaignsByCustomerOptions } from '../types.js';
 export declare const MAX_CAMPAIGN_CUSTOMER_PAGE_SIZE = 100;
 export declare const MAX_CAMPAIGN_CUSTOMER_BATCH_SIZE = 100;
 export declare class CampaignCollection extends SmrtCollection<Campaign> {
@@ -22,6 +22,15 @@ export declare class CampaignCollection extends SmrtCollection<Campaign> {
      * Null start times follow all scheduled rows on every supported database.
      */
     listByCustomer(tenantId: string | null, customerId: string, options?: ListCampaignsByCustomerOptions): Promise<CampaignCustomerPage>;
+    /**
+     * Return one bounded customer page with its complete read-only reporting
+     * projection. Channels and immutable evidence are aggregated in two grouped
+     * reads, independent of page size; no campaign callback or lazy load runs.
+     */
+    listReportingByCustomer(tenantId: string | null, customerId: string, options?: ListCampaignReportingByCustomerOptions): Promise<CampaignReportingPage>;
+    private projectReportingPage;
+    private loadChannelMixRows;
+    private loadMetricRows;
     private listByCustomerInTransaction;
     /**
      * Summarize a bounded customer batch with one scope check and one grouped

package/dist/collections/CampaignCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CampaignCollection.d.ts","sourceRoot":"","sources":["../../src/collections/CampaignCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAE1B,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAalC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAGV,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEvB,GAAG,CAChB,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,EAC1C,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAA;KAAO,GACtD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAMZ,IAAI,CACjB,KAAK,CAAC,MAAM,SAAS,SAAS,eAAe,CAAC,QAAQ,CAAC,EAAE,EAEzD,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,CAAA;KAAE,GACvE,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;IAChC,IAAI,CACjB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,GAAG;QACpD,MAAM,CAAC,EAAE,SAAS,CAAC;KACpB,GACA,OAAO,CAAC,QAAQ,EAAE,CAAC;IAYhB,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQrB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO/D;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,oBAAoB,CAAC;YAgClB,2BAA2B;IA2BzC;;;OAGG;IACG,oBAAoB,CACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,uBAAuB,EAAE,CAAC;YAgCvB,iCAAiC;YAkDjC,yBAAyB;YAoBzB,iBAAiB;YA4BjB,iBAAiB;CAiBhC;AA4JD,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"CampaignCollection.d.ts","sourceRoot":"","sources":["../../src/collections/CampaignCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAE1B,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAalC,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,KAAK,EAIV,oBAAoB,EACpB,uBAAuB,EAEvB,qBAAqB,EACrB,cAAc,EACd,sCAAsC,EACtC,8BAA8B,EAC/B,MAAM,aAAa,CAAC;AAIrB,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEvB,GAAG,CAChB,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,EAC1C,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAA;KAAO,GACtD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAMZ,IAAI,CACjB,KAAK,CAAC,MAAM,SAAS,SAAS,eAAe,CAAC,QAAQ,CAAC,EAAE,EAEzD,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,CAAA;KAAE,GACvE,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;IAChC,IAAI,CACjB,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,GAAG;QACpD,MAAM,CAAC,EAAE,SAAS,CAAC;KACpB,GACA,OAAO,CAAC,QAAQ,EAAE,CAAC;IAYhB,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQrB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAO/D;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,oBAAoB,CAAC;IAiChC;;;;OAIG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sCAA2C,GACnD,OAAO,CAAC,qBAAqB,CAAC;YAoCnB,oBAAoB;YAkDpB,kBAAkB;YA2BlB,cAAc;YA6Dd,2BAA2B;IA4BzC;;;OAGG;IACG,oBAAoB,CACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,uBAAuB,EAAE,CAAC;YAgCvB,iCAAiC;YAkDjC,yBAAyB;YAoBzB,iBAAiB;YA4BjB,iBAAiB;CAiBhC;AA4PD,eAAe,kBAAkB,CAAC"}