@happyvertical/smrt-marketing 0.39.16

package/AGENTS.md

@@ -0,0 +1,79 @@
+# @happyvertical/smrt-marketing
+
+Cross-channel campaign coordination for SMRT. This package owns Campaign
+identity, budgets, lifecycle, execution links, immutable performance evidence,
+computed pacing, and props-driven Svelte surfaces. It does not execute ads,
+publish social posts, send messages, or own sales attribution.
+
+## Validation
+
+Run `pnpm --filter @happyvertical/smrt-marketing test` and
+`pnpm --filter @happyvertical/smrt-marketing typecheck`; use `test:coverage`
+to exercise the model/service and component coverage configurations.
+Natural-key changes must also run
+`pnpm --filter @happyvertical/smrt-marketing test:postgres` when
+the disposable PostgreSQL harness is available. Use
+`pnpm --filter @happyvertical/smrt-marketing build` and `verify:pack` for
+publish-surface changes.
+
+## Models
+
+- **Campaign**: optional-tenant umbrella with stable natural key
+  `(tenant_id, campaign_key)`, open objective, integer-cent budget, currency,
+  schedule, 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.
+- **CampaignChannel**: one generic execution link per
+  `(campaign_id, channel_kind, channel_ref)`. `channelKind`/`channelRef` are
+  intentionally plain strings so ads, social, messages, content, events, and
+  referral programs remain peer packages. Allocation and schedule overrides
+  use integer cents and dates.
+- **CampaignMetricSnapshot**: immutable period evidence with a global
+  `dedupe_key` natural key. A snapshot always carries `campaignId`; a null
+  `campaignChannelId` means campaign-level rollup evidence; when present, the
+  channel must belong to that same campaign. API/MCP/CLI expose create/list/get
+  only, and the save guard rejects hydrated edits, blind-id overwrites, and
+  natural-key overwrites. Programmatic deletion is rejected.
+
+Every model is `@TenantScoped({ mode: 'optional' })` with nullable `tenantId`.
+All generated surfaces are explicit; never omit `api`, `mcp`, or `cli` config.
+
+## Services
+
+- **CampaignLifecycleService** loads the current row before applying one legal
+  transition. Paused campaigns may resume; completed campaigns may only be
+  archived; archived campaigns are terminal.
+- **MetricIngestionService** validates required scope/source/period fields and
+  delegates to `getOrCreateByDedupeKey()`. A replay returns the original row
+  unchanged even if the replay payload differs.
+- **BudgetPacingService** computes campaign/channel pacing from snapshots and
+  never persists derived balances. For each exact reporting period, campaign
+  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.
+
+## Svelte
+
+`@happyvertical/smrt-marketing/svelte` exports `MarketingDashboard`,
+`CampaignList`, `CampaignDetail`, `ChannelMix`, and `BudgetPacing`, plus view
+interfaces and pure helpers. Components are props-only: no fetching, no model
+imports, no providers. Use Provider-free `smrt-ui` primitives, `--smrt-*`
+tokens, named `$props()` interfaces, and integer-cent inputs formatted only at
+render time.
+
+## Boundaries and gotchas
+
+- Runtime dependencies stay limited to `smrt-core`, `smrt-tenancy`, and
+  `smrt-ui`. Never statically import sibling domain packages.
+- 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
+  evidence only.
+- Campaign rollups and channel snapshots may describe the same period. The
+  pacing service deliberately chooses one evidence level instead of summing
+  both.
+- Corrections append a new metric snapshot with a new dedupe key; never edit
+  persisted evidence.
+- Table names are global: `campaigns`, `campaign_channels`, and
+  `campaign_metric_snapshots`.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @happyvertical/smrt-marketing
+
+Cross-channel Campaign models, immutable performance snapshots, computed
+budget pacing, and reusable Svelte marketing surfaces for SMRT.
+
+```bash
+pnpm add @happyvertical/smrt-marketing
+```
+
+```ts
+import {
+  BudgetPacingService,
+  CampaignChannelCollection,
+  CampaignCollection,
+  MetricIngestionService,
+} from '@happyvertical/smrt-marketing';
+
+const campaigns = await CampaignCollection.create({ db });
+const channels = await CampaignChannelCollection.create({ db });
+const campaign = await campaigns.create({
+  tenantId,
+  campaignKey: 'summer-demand-2026',
+  name: 'Summer demand 2026',
+  objective: 'demand_generation',
+  budgetCents: 200_000,
+  currency: 'CAD',
+});
+if (!campaign.id) throw new Error('Campaign did not persist');
+
+const adGroup = await channels.create({
+  tenantId,
+  campaignId: campaign.id,
+  channelKind: 'ad_group',
+  channelRef: 'ad-group-42',
+  allocatedBudgetCents: 150_000,
+});
+if (!adGroup.id) throw new Error('Campaign channel did not persist');
+
+const ingestion = await MetricIngestionService.create({ db });
+await ingestion.ingest({
+  tenantId,
+  campaignId: campaign.id,
+  campaignChannelId: adGroup.id,
+  periodStart: new Date('2026-07-01T00:00:00Z'),
+  periodEnd: new Date('2026-07-01T23:59:59Z'),
+  spendCents: 12_500,
+  impressions: 25_000,
+  clicks: 800,
+  conversions: 35,
+  leads: 20,
+  source: 'ad-platform',
+  dedupeKey: `${tenantId}:summer-demand-2026:ad-group-42:2026-07-01`,
+});
+
+// Channel-scoped evidence is accepted only when the channel belongs to the
+// supplied campaign. Reporting periods are required valid date-like values.
+
+const pacing = await BudgetPacingService.create({ db });
+console.log(await pacing.getCampaignPacing(campaign.id));
+```
+
+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.
+
+See [AGENTS.md](./AGENTS.md) for lifecycle, evidence, and package-boundary
+invariants.

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/collections/CampaignChannelCollection.d.ts

@@ -0,0 +1,9 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { CampaignChannel } from '../models/CampaignChannel.js';
+export declare class CampaignChannelCollection extends SmrtCollection<CampaignChannel> {
+    static readonly _itemClass: typeof CampaignChannel;
+    findByCampaign(campaignId: string): Promise<CampaignChannel[]>;
+    findByExecutionRef(channelKind: string, channelRef: string): Promise<CampaignChannel[]>;
+}
+export default CampaignChannelCollection;
+//# sourceMappingURL=CampaignChannelCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CampaignChannelCollection.d.ts","sourceRoot":"","sources":["../../src/collections/CampaignChannelCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,qBAAa,yBAA0B,SAAQ,cAAc,CAAC,eAAe,CAAC;IAC5E,MAAM,CAAC,QAAQ,CAAC,UAAU,yBAAmB;IAEvC,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAO9D,kBAAkB,CACtB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,EAAE,CAAC;CAG9B;AAED,eAAe,yBAAyB,CAAC"}

package/dist/collections/CampaignCollection.d.ts

@@ -0,0 +1,10 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Campaign } from '../models/Campaign.js';
+import { CampaignStatus } from '../types.js';
+export declare class CampaignCollection extends SmrtCollection<Campaign> {
+    static readonly _itemClass: typeof Campaign;
+    findByCampaignKey(campaignKey: string, tenantId?: string | null): Promise<Campaign | null>;
+    findByStatus(status: CampaignStatus): Promise<Campaign[]>;
+}
+export default CampaignCollection;
+//# sourceMappingURL=CampaignCollection.d.ts.map

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

@@ -0,0 +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"}

package/dist/collections/CampaignMetricSnapshotCollection.d.ts

@@ -0,0 +1,15 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { CampaignMetricSnapshot } from '../models/CampaignMetricSnapshot.js';
+import { CampaignMetricSnapshotOptions } from '../types.js';
+export declare class CampaignMetricSnapshotCollection extends SmrtCollection<CampaignMetricSnapshot> {
+    static readonly _itemClass: typeof CampaignMetricSnapshot;
+    findByDedupeKey(dedupeKey: string): Promise<CampaignMetricSnapshot | null>;
+    getOrCreateByDedupeKey(options: CampaignMetricSnapshotOptions): Promise<{
+        snapshot: CampaignMetricSnapshot;
+        created: boolean;
+    }>;
+    findByCampaign(campaignId: string): Promise<CampaignMetricSnapshot[]>;
+    findByChannel(campaignChannelId: string): Promise<CampaignMetricSnapshot[]>;
+}
+export default CampaignMetricSnapshotCollection;
+//# sourceMappingURL=CampaignMetricSnapshotCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CampaignMetricSnapshotCollection.d.ts","sourceRoot":"","sources":["../../src/collections/CampaignMetricSnapshotCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAEjE,qBAAa,gCAAiC,SAAQ,cAAc,CAAC,sBAAsB,CAAC;IAC1F,MAAM,CAAC,QAAQ,CAAC,UAAU,gCAA0B;IAE9C,eAAe,CACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAMnC,sBAAsB,CAC1B,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC;QAAE,QAAQ,EAAE,sBAAsB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IA8B5D,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAOrE,aAAa,CACjB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,sBAAsB,EAAE,CAAC;CAMrC;AAED,eAAe,gCAAgC,CAAC"}

package/dist/collections/index.d.ts

@@ -0,0 +1,4 @@
+export * from './CampaignChannelCollection.js';
+export * from './CampaignCollection.js';
+export * from './CampaignMetricSnapshotCollection.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collections/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uCAAuC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './collections/index.js';
+export * from './models/index.js';
+export * from './services/index.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}