@happyvertical/smrt-marketing 0.42.7 → 0.43.0

package/AGENTS.md

@@ -20,7 +20,8 @@ publish-surface changes.
 
 - **Campaign**: optional-tenant umbrella with stable natural key
   `(tenant_id, campaign_key)`, open objective, integer-cent budget, currency,
-  schedule, guarded metadata helpers, and lifecycle
+  schedule, optional native UUID reference to the canonical commerce Customer,
+  guarded metadata helpers, and lifecycle
   `draft → scheduled → active ↔ paused → completed → archived`. Raw saves are
   protected by an authoritative prior-status re-read; use
   `CampaignLifecycleService` for lifecycle writes.
@@ -52,6 +53,11 @@ All generated surfaces are explicit; never omit `api`, `mcp`, or `cli` config.
   pacing prefers campaign rollups and otherwise sums channel snapshots,
   preventing double counting without dropping channel-only periods. Status
   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.
 
 ## Svelte
 
@@ -66,6 +72,13 @@ render time.
 
 - Runtime dependencies stay limited to `smrt-core`, `smrt-tenancy`, and
   `smrt-ui`. Never statically import sibling domain packages.
+- `Campaign.customerId` targets `@happyvertical/smrt-commerce:Customer` through
+  `@crossPackageRef`. Saves and customer-scoped reads require exact tenant
+  agreement (including global-to-global only) and fail without revealing
+  whether a Customer is absent or belongs elsewhere. Associated saves validate
+  and persist through one transaction-bound Campaign instance; scoped reads
+  validate and query through one fresh transaction-bound collection. PostgreSQL
+  locks the validated Customer rows for the duration of each operation.
 - Lead loop-closing is conventional: CRM stores `sourceKind: 'campaign'` and a
   campaign key in `sourceId`; marketing does not import or mutate Lead.
 - Attribution math remains in sales/referrals. Marketing stores performance

package/README.md

@@ -19,6 +19,7 @@ const campaigns = await CampaignCollection.create({ db });
 const channels = await CampaignChannelCollection.create({ db });
 const campaign = await campaigns.create({
   tenantId,
+  customerId,
   campaignKey: 'summer-demand-2026',
   name: 'Summer demand 2026',
   objective: 'demand_generation',
@@ -59,6 +60,50 @@ const pacing = await BudgetPacingService.create({ db });
 console.log(await pacing.getCampaignPacing(campaign.id));
 ```
 
+## Customer-scoped campaign reads
+
+`Campaign.customerId` is the native UUID relationship to the canonical
+`@happyvertical/smrt-commerce:Customer`. A campaign and its Customer must have
+exactly the same tenant, and customer-scoped reads require that tenant
+explicitly (`null` selects the global/global scope). Associated Campaign saves
+validate and persist in one transaction; customer-scoped reads validate and
+query in one transaction. Missing and cross-tenant Customers fail with
+`CampaignCustomerScopeError` without disclosing which condition occurred.
+
+```ts
+const firstPage = await campaigns.listByCustomer(tenantId, customerId, {
+  limit: 50,
+});
+const secondPage = firstPage.nextCursor
+  ? await campaigns.listByCustomer(tenantId, customerId, {
+      limit: 50,
+      after: firstPage.nextCursor,
+    })
+  : null;
+
+const summaries = await campaigns.summarizeByCustomers(tenantId, customerIds);
+// [{ customerId, totalCount, activeCount, latestStartAt }]
+```
+
+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.
+
+### Migrating metadata-backed associations
+
+1. Apply the generated schema migration that adds nullable native-UUID
+   `campaigns.customer_id` and the
+   `(tenant_id, customer_id, start_at, id)` index.
+2. In an operator-owned data migration, extract the old metadata Customer id,
+   validate that it exists in commerce and has the exact same `tenant_id`, then
+   write `customer_id`. Stop on missing, malformed, or mismatched values.
+3. Verify every expected association through `listByCustomer()` or
+   `summarizeByCustomers()`, then update consumers to use these APIs.
+4. Remove the old metadata key after verification. Marketing never reads it as
+   a compatibility fallback, so there is no tenant-wide JSON or raw-SQL path to
+   keep in sync.
+
 Svelte components are exported from `@happyvertical/smrt-marketing/svelte`.
 They are presentational and accept plain view models; consumers remain in
 control of fetching and mutations.

package/dist/collections/CampaignCollection.d.ts

@@ -1,10 +1,37 @@
-import { SmrtCollection } from '@happyvertical/smrt-core';
+import { CollectionCacheConfig, SmrtCollection, SmrtListOptions, SmrtSelectedRow, SmrtSelectField, SmrtWhereClause } from '@happyvertical/smrt-core';
 import { Campaign } from '../models/Campaign.js';
-import { CampaignStatus } from '../types.js';
+import { CampaignCustomerPage, CampaignCustomerSummary, CampaignStatus, 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> {
     static readonly _itemClass: typeof Campaign;
+    get(filter: string | SmrtWhereClause<Campaign>, options?: {
+        cache?: CollectionCacheConfig | false;
+    }): Promise<Campaign | null>;
+    list<const Select extends readonly SmrtSelectField<Campaign>[]>(options: SmrtListOptions<Campaign> & {
+        select: Select;
+        include?: never;
+    }): Promise<SmrtSelectedRow<Campaign, Select>[]>;
+    list(options?: Omit<SmrtListOptions<Campaign>, 'select'> & {
+        select?: undefined;
+    }): Promise<Campaign[]>;
     findByCampaignKey(campaignKey: string, tenantId?: string | null): Promise<Campaign | null>;
     findByStatus(status: CampaignStatus): Promise<Campaign[]>;
+    /**
+     * List one tenant/customer lane newest-first using a stable UUID tiebreaker.
+     * Null start times follow all scheduled rows on every supported database.
+     */
+    listByCustomer(tenantId: string | null, customerId: string, options?: ListCampaignsByCustomerOptions): Promise<CampaignCustomerPage>;
+    private listByCustomerInTransaction;
+    /**
+     * Summarize a bounded customer batch with one scope check and one grouped
+     * aggregate query. Every requested customer receives a row, including zeros.
+     */
+    summarizeByCustomers(tenantId: string | null, customerIds: string[]): Promise<CampaignCustomerSummary[]>;
+    private summarizeByCustomersInTransaction;
+    private inCustomerReadTransaction;
+    private listScheduledLane;
+    private listNullStartLane;
 }
 export default CampaignCollection;
 //# sourceMappingURL=CampaignCollection.d.ts.map

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,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,CAAC;IAC9D,MAAM,CAAC,QAAQ,CAAC,UAAU,kBAAY;IAEhC,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;CAMhE;AAED,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;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"}

package/dist/customer-scope.d.ts

@@ -0,0 +1,14 @@
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+interface DatabaseOptions {
+    db?: SmrtObjectOptions['db'];
+}
+/**
+ * Verify a bounded set of canonical commerce Customers in one database read.
+ * The generic failure deliberately does not reveal whether an id is missing or
+ * belongs to another tenant.
+ */
+export declare function assertCustomersBelongToTenant(options: DatabaseOptions, tenantId: string | null, customerIds: readonly string[], label: string, lock?: 'none' | 'share' | 'update'): Promise<void>;
+/** Parse and canonicalize one UUID without echoing the rejected value. */
+export declare function normalizeUuid(value: string, label: string): string;
+export {};
+//# sourceMappingURL=customer-scope.d.ts.map

package/dist/customer-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customer-scope.d.ts","sourceRoot":"","sources":["../src/customer-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAWlC,UAAU,eAAe;IACvB,EAAE,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;CAC9B;AA+BD;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,GACzC,OAAO,CAAC,IAAI,CAAC,CAgCf;AAUD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlE"}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** Fail-closed customer/tenant mismatch without revealing row existence. */
+export declare class CampaignCustomerScopeError extends Error {
+    readonly code = "CAMPAIGN_CUSTOMER_SCOPE";
+    constructor(label: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,6BAA6B;gBAE9B,KAAK,EAAE,MAAM;CAI1B"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './collections/index.js';
+export * from './errors.js';
 export * from './models/index.js';
 export * from './services/index.js';
 export * from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,wBAAwB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,wBAAwB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}