@happyvertical/smrt-ads 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/AGENTS.md +47 -0
  2. package/CLAUDE.md +1 -0
  3. package/LICENSE +7 -0
  4. package/README.md +112 -0
  5. package/dist/index.d.ts +794 -0
  6. package/dist/index.js +1121 -0
  7. package/dist/index.js.map +1 -0
  8. package/dist/manifest.json +3506 -0
  9. package/dist/smrt-knowledge.json +1438 -0
  10. package/package.json +63 -0
package/dist/smrt-knowledge.json ADDED
@@ -0,0 +1,1438 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "generatedAt": "2026-06-23T01:11:45.048Z",
4
+ "packageName": "@happyvertical/smrt-ads",
5
+ "packageVersion": "0.30.0",
6
+ "sourceManifestPath": "dist/manifest.json",
7
+ "agentDocPath": "AGENTS.md",
8
+ "sourceHashes": {
9
+ "manifest": "e1b1958c441e792bb4cc15fbcd2beabd8d86fc91f0e41fd11a404035fafc284b",
10
+ "packageJson": "83ff544318094278c4d3bf07ff7b85f4854d3394e09bc6ac327ec557781810b3",
11
+ "agents": "38d00ca384af711a76359907e4d9806733168d7b4b31f7610cd0c418fc72d566"
12
+ },
13
+ "exports": [
14
+ ".",
15
+ "./manifest",
16
+ "./manifest.json"
17
+ ],
18
+ "dependencies": {
19
+ "@happyvertical/smrt-core": "workspace:*",
20
+ "@happyvertical/smrt-tenancy": "workspace:*",
21
+ "@happyvertical/smrt-commerce": "workspace:*",
22
+ "@happyvertical/smrt-vitest": "workspace:*",
23
+ "@happyvertical/sql": "catalog:",
24
+ "@types/node": "25.0.9",
25
+ "fast-glob": "3.3.3",
26
+ "typescript": "^5.9.3",
27
+ "vite": "^7.3.1",
28
+ "vitest": "^4.0.17"
29
+ },
30
+ "smrtDependencies": [
31
+ "@happyvertical/smrt-commerce",
32
+ "@happyvertical/smrt-core",
33
+ "@happyvertical/smrt-tenancy",
34
+ "@happyvertical/smrt-vitest"
35
+ ],
36
+ "sdkDependencies": [
37
+ "@happyvertical/sql"
38
+ ],
39
+ "tags": [],
40
+ "risks": [],
41
+ "objects": [
42
+ {
43
+ "name": "AdDeliveryTierCollection",
44
+ "qualifiedName": "@happyvertical/smrt-ads:AdDeliveryTierCollection",
45
+ "collection": "addeliverytiers",
46
+ "tableName": "ad_delivery_tier_collections",
47
+ "packageName": "@happyvertical/smrt-ads",
48
+ "extends": "SmrtCollection",
49
+ "fields": [],
50
+ "relationships": [],
51
+ "methods": [
52
+ "findByPricingModel",
53
+ "findByPriority",
54
+ "findCPM",
55
+ "findFixedPricing",
56
+ "findPerformanceBased",
57
+ "getHighestPriority"
58
+ ],
59
+ "surfaces": [],
60
+ "relationshipFeatures": [
61
+ "uuidColumns"
62
+ ],
63
+ "tags": [],
64
+ "risks": []
65
+ },
66
+ {
67
+ "name": "AdEventCollection",
68
+ "qualifiedName": "@happyvertical/smrt-ads:AdEventCollection",
69
+ "collection": "adevents",
70
+ "tableName": "ad_event_collections",
71
+ "packageName": "@happyvertical/smrt-ads",
72
+ "extends": "SmrtCollection",
73
+ "fields": [],
74
+ "relationships": [],
75
+ "methods": [
76
+ "countByType",
77
+ "countClicks",
78
+ "countConversions",
79
+ "countImpressions",
80
+ "findByDateRange",
81
+ "findBySite",
82
+ "findByTenant",
83
+ "findByType",
84
+ "findByVariation",
85
+ "findByZone",
86
+ "findClicks",
87
+ "findConversions",
88
+ "findGlobal",
89
+ "findImpressions",
90
+ "findWithGlobals",
91
+ "getVariationStats"
92
+ ],
93
+ "surfaces": [],
94
+ "relationshipFeatures": [
95
+ "uuidColumns"
96
+ ],
97
+ "tags": [],
98
+ "risks": []
99
+ },
100
+ {
101
+ "name": "AdFormatCollection",
102
+ "qualifiedName": "@happyvertical/smrt-ads:AdFormatCollection",
103
+ "collection": "adformats",
104
+ "tableName": "ad_format_collections",
105
+ "packageName": "@happyvertical/smrt-ads",
106
+ "extends": "SmrtCollection",
107
+ "fields": [],
108
+ "relationships": [],
109
+ "methods": [
110
+ "findBanners",
111
+ "findByDimensions",
112
+ "findByType",
113
+ "findNative",
114
+ "findVideo"
115
+ ],
116
+ "surfaces": [],
117
+ "relationshipFeatures": [
118
+ "uuidColumns"
119
+ ],
120
+ "tags": [],
121
+ "risks": []
122
+ },
123
+ {
124
+ "name": "AdGroupCollection",
125
+ "qualifiedName": "@happyvertical/smrt-ads:AdGroupCollection",
126
+ "collection": "adgroups",
127
+ "tableName": "ad_group_collections",
128
+ "packageName": "@happyvertical/smrt-ads",
129
+ "extends": "SmrtCollection",
130
+ "fields": [],
131
+ "relationships": [],
132
+ "methods": [
133
+ "findActive",
134
+ "findByContract",
135
+ "findByStatus",
136
+ "findByTenant",
137
+ "findByTier",
138
+ "findByVertical",
139
+ "findByZone",
140
+ "findCompleted",
141
+ "findDrafts",
142
+ "findEligibleForZone",
143
+ "findGlobal",
144
+ "findPaused",
145
+ "findWithGlobals"
146
+ ],
147
+ "surfaces": [],
148
+ "relationshipFeatures": [
149
+ "uuidColumns"
150
+ ],
151
+ "tags": [],
152
+ "risks": []
153
+ },
154
+ {
155
+ "name": "AdVariationCollection",
156
+ "qualifiedName": "@happyvertical/smrt-ads:AdVariationCollection",
157
+ "collection": "advariations",
158
+ "tableName": "ad_variation_collections",
159
+ "packageName": "@happyvertical/smrt-ads",
160
+ "extends": "SmrtCollection",
161
+ "fields": [],
162
+ "relationships": [],
163
+ "methods": [
164
+ "findActive",
165
+ "findActiveByGroup",
166
+ "findByFormat",
167
+ "findByGroup",
168
+ "findByStatus",
169
+ "findByTenant",
170
+ "findDrafts",
171
+ "findGlobal",
172
+ "findPaused",
173
+ "findTopPerformers",
174
+ "findWithGlobals",
175
+ "selectByWeight"
176
+ ],
177
+ "surfaces": [],
178
+ "relationshipFeatures": [
179
+ "uuidColumns"
180
+ ],
181
+ "tags": [],
182
+ "risks": []
183
+ },
184
+ {
185
+ "name": "AdDeliveryTier",
186
+ "qualifiedName": "@happyvertical/smrt-ads:AdDeliveryTier",
187
+ "collection": "addeliverytiers",
188
+ "tableName": "ad_delivery_tiers",
189
+ "packageName": "@happyvertical/smrt-ads",
190
+ "extends": "SmrtObject",
191
+ "fields": [
192
+ {
193
+ "name": "name",
194
+ "type": "text",
195
+ "required": false,
196
+ "columnType": "TEXT"
197
+ },
198
+ {
199
+ "name": "priority",
200
+ "type": "integer",
201
+ "required": false,
202
+ "columnType": "INTEGER"
203
+ },
204
+ {
205
+ "name": "pricingModel",
206
+ "type": "text",
207
+ "required": false,
208
+ "columnType": "TEXT"
209
+ },
210
+ {
211
+ "name": "description",
212
+ "type": "text",
213
+ "required": false,
214
+ "columnType": "TEXT"
215
+ }
216
+ ],
217
+ "relationships": [],
218
+ "methods": [
219
+ "isFixedPricing",
220
+ "isHigherPriorityThan",
221
+ "isPerformanceBased"
222
+ ],
223
+ "surfaces": [
224
+ {
225
+ "kind": "api",
226
+ "name": "addeliverytiers.list",
227
+ "operation": "list",
228
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
229
+ "path": "/addeliverytiers",
230
+ "method": "GET"
231
+ },
232
+ {
233
+ "kind": "api",
234
+ "name": "addeliverytiers.get",
235
+ "operation": "get",
236
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
237
+ "path": "/addeliverytiers/[id]",
238
+ "method": "GET"
239
+ },
240
+ {
241
+ "kind": "api",
242
+ "name": "addeliverytiers.create",
243
+ "operation": "create",
244
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
245
+ "path": "/addeliverytiers",
246
+ "method": "POST"
247
+ },
248
+ {
249
+ "kind": "api",
250
+ "name": "addeliverytiers.update",
251
+ "operation": "update",
252
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
253
+ "path": "/addeliverytiers/[id]",
254
+ "method": "PATCH"
255
+ },
256
+ {
257
+ "kind": "cli",
258
+ "name": "addeliverytier_list",
259
+ "operation": "list",
260
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
261
+ },
262
+ {
263
+ "kind": "cli",
264
+ "name": "addeliverytier_get",
265
+ "operation": "get",
266
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
267
+ },
268
+ {
269
+ "kind": "cli",
270
+ "name": "addeliverytier_create",
271
+ "operation": "create",
272
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
273
+ },
274
+ {
275
+ "kind": "cli",
276
+ "name": "addeliverytier_update",
277
+ "operation": "update",
278
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
279
+ },
280
+ {
281
+ "kind": "cli",
282
+ "name": "addeliverytier_delete",
283
+ "operation": "delete",
284
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
285
+ },
286
+ {
287
+ "kind": "mcp",
288
+ "name": "addeliverytier_list",
289
+ "operation": "list",
290
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
291
+ },
292
+ {
293
+ "kind": "mcp",
294
+ "name": "addeliverytier_get",
295
+ "operation": "get",
296
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
297
+ }
298
+ ],
299
+ "relationshipFeatures": [
300
+ "uuidColumns"
301
+ ],
302
+ "tags": [],
303
+ "risks": []
304
+ },
305
+ {
306
+ "name": "AdEvent",
307
+ "qualifiedName": "@happyvertical/smrt-ads:AdEvent",
308
+ "collection": "adevents",
309
+ "tableName": "ad_events",
310
+ "packageName": "@happyvertical/smrt-ads",
311
+ "extends": "SmrtObject",
312
+ "fields": [
313
+ {
314
+ "name": "created_at",
315
+ "type": "datetime",
316
+ "required": false,
317
+ "columnType": "TIMESTAMP"
318
+ },
319
+ {
320
+ "name": "updated_at",
321
+ "type": "datetime",
322
+ "required": false,
323
+ "columnType": "TIMESTAMP"
324
+ },
325
+ {
326
+ "name": "tenantId",
327
+ "type": "text",
328
+ "required": false,
329
+ "columnType": "UUID"
330
+ },
331
+ {
332
+ "name": "variationId",
333
+ "type": "foreignKey",
334
+ "required": false,
335
+ "related": "AdVariation",
336
+ "columnType": "UUID"
337
+ },
338
+ {
339
+ "name": "zoneId",
340
+ "type": "crossPackageRef",
341
+ "required": false,
342
+ "related": "@happyvertical/smrt-properties:Zone",
343
+ "columnType": "UUID"
344
+ },
345
+ {
346
+ "name": "siteId",
347
+ "type": "text",
348
+ "required": false,
349
+ "columnType": "TEXT"
350
+ },
351
+ {
352
+ "name": "eventType",
353
+ "type": "text",
354
+ "required": false,
355
+ "columnType": "TEXT"
356
+ },
357
+ {
358
+ "name": "timestamp",
359
+ "type": "datetime",
360
+ "required": false,
361
+ "columnType": "TIMESTAMP"
362
+ },
363
+ {
364
+ "name": "metadata",
365
+ "type": "text",
366
+ "required": false,
367
+ "columnType": "TEXT"
368
+ }
369
+ ],
370
+ "relationships": [
371
+ {
372
+ "name": "variationId",
373
+ "type": "foreignKey",
374
+ "required": false,
375
+ "related": "AdVariation",
376
+ "columnType": "UUID"
377
+ },
378
+ {
379
+ "name": "zoneId",
380
+ "type": "crossPackageRef",
381
+ "required": false,
382
+ "related": "@happyvertical/smrt-properties:Zone",
383
+ "columnType": "UUID"
384
+ }
385
+ ],
386
+ "methods": [
387
+ "classifyConstraintError",
388
+ "clearEmbeddings",
389
+ "delete",
390
+ "describe",
391
+ "destroy",
392
+ "do",
393
+ "executeToolCall",
394
+ "forget",
395
+ "forgetScope",
396
+ "generateEmbeddings",
397
+ "getAiUsageSnapshot",
398
+ "getAvailableTools",
399
+ "getEmbedding",
400
+ "getFields",
401
+ "getId",
402
+ "getMetadata",
403
+ "getRelated",
404
+ "getSavedId",
405
+ "getSlug",
406
+ "hasStaleEmbeddings",
407
+ "initialize",
408
+ "is",
409
+ "isClick",
410
+ "isConversion",
411
+ "isImpression",
412
+ "isRelatedLoaded",
413
+ "isSaved",
414
+ "listAiUsage",
415
+ "loadDataFromDb",
416
+ "loadFromId",
417
+ "loadFromSlug",
418
+ "loadRelated",
419
+ "loadRelatedMany",
420
+ "markAsPersisted",
421
+ "recall",
422
+ "recallAll",
423
+ "remember",
424
+ "resetAiUsage",
425
+ "save",
426
+ "setMetadata",
427
+ "summarizeAiUsage",
428
+ "toJSON",
429
+ "toPlainObject",
430
+ "toPublicJSON"
431
+ ],
432
+ "surfaces": [
433
+ {
434
+ "kind": "api",
435
+ "name": "adevents.create",
436
+ "operation": "create",
437
+ "objectName": "@happyvertical/smrt-ads:AdEvent",
438
+ "path": "/adevents",
439
+ "method": "POST"
440
+ },
441
+ {
442
+ "kind": "api",
443
+ "name": "adevents.list",
444
+ "operation": "list",
445
+ "objectName": "@happyvertical/smrt-ads:AdEvent",
446
+ "path": "/adevents",
447
+ "method": "GET"
448
+ },
449
+ {
450
+ "kind": "mcp",
451
+ "name": "adevent_create",
452
+ "operation": "create",
453
+ "objectName": "@happyvertical/smrt-ads:AdEvent"
454
+ }
455
+ ],
456
+ "relationshipFeatures": [
457
+ "crossPackageRef",
458
+ "foreignKey",
459
+ "uuidColumns"
460
+ ],
461
+ "tags": [],
462
+ "risks": []
463
+ },
464
+ {
465
+ "name": "AdFormat",
466
+ "qualifiedName": "@happyvertical/smrt-ads:AdFormat",
467
+ "collection": "adformats",
468
+ "tableName": "ad_formats",
469
+ "packageName": "@happyvertical/smrt-ads",
470
+ "extends": "SmrtObject",
471
+ "fields": [
472
+ {
473
+ "name": "name",
474
+ "type": "text",
475
+ "required": false,
476
+ "columnType": "TEXT"
477
+ },
478
+ {
479
+ "name": "width",
480
+ "type": "integer",
481
+ "required": false,
482
+ "columnType": "INTEGER"
483
+ },
484
+ {
485
+ "name": "height",
486
+ "type": "integer",
487
+ "required": false,
488
+ "columnType": "INTEGER"
489
+ },
490
+ {
491
+ "name": "formatType",
492
+ "type": "text",
493
+ "required": false,
494
+ "columnType": "TEXT"
495
+ },
496
+ {
497
+ "name": "description",
498
+ "type": "text",
499
+ "required": false,
500
+ "columnType": "TEXT"
501
+ }
502
+ ],
503
+ "relationships": [],
504
+ "methods": [
505
+ "getDimensions",
506
+ "matchesDimensions"
507
+ ],
508
+ "surfaces": [
509
+ {
510
+ "kind": "api",
511
+ "name": "adformats.list",
512
+ "operation": "list",
513
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
514
+ "path": "/adformats",
515
+ "method": "GET"
516
+ },
517
+ {
518
+ "kind": "api",
519
+ "name": "adformats.get",
520
+ "operation": "get",
521
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
522
+ "path": "/adformats/[id]",
523
+ "method": "GET"
524
+ },
525
+ {
526
+ "kind": "api",
527
+ "name": "adformats.create",
528
+ "operation": "create",
529
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
530
+ "path": "/adformats",
531
+ "method": "POST"
532
+ },
533
+ {
534
+ "kind": "api",
535
+ "name": "adformats.update",
536
+ "operation": "update",
537
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
538
+ "path": "/adformats/[id]",
539
+ "method": "PATCH"
540
+ },
541
+ {
542
+ "kind": "cli",
543
+ "name": "adformat_list",
544
+ "operation": "list",
545
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
546
+ },
547
+ {
548
+ "kind": "cli",
549
+ "name": "adformat_get",
550
+ "operation": "get",
551
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
552
+ },
553
+ {
554
+ "kind": "cli",
555
+ "name": "adformat_create",
556
+ "operation": "create",
557
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
558
+ },
559
+ {
560
+ "kind": "cli",
561
+ "name": "adformat_update",
562
+ "operation": "update",
563
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
564
+ },
565
+ {
566
+ "kind": "cli",
567
+ "name": "adformat_delete",
568
+ "operation": "delete",
569
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
570
+ },
571
+ {
572
+ "kind": "mcp",
573
+ "name": "adformat_list",
574
+ "operation": "list",
575
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
576
+ },
577
+ {
578
+ "kind": "mcp",
579
+ "name": "adformat_get",
580
+ "operation": "get",
581
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
582
+ }
583
+ ],
584
+ "relationshipFeatures": [
585
+ "uuidColumns"
586
+ ],
587
+ "tags": [],
588
+ "risks": []
589
+ },
590
+ {
591
+ "name": "AdGroup",
592
+ "qualifiedName": "@happyvertical/smrt-ads:AdGroup",
593
+ "collection": "adgroups",
594
+ "tableName": "ad_groups",
595
+ "packageName": "@happyvertical/smrt-ads",
596
+ "extends": "SmrtObject",
597
+ "fields": [
598
+ {
599
+ "name": "created_at",
600
+ "type": "datetime",
601
+ "required": false,
602
+ "columnType": "TIMESTAMP"
603
+ },
604
+ {
605
+ "name": "updated_at",
606
+ "type": "datetime",
607
+ "required": false,
608
+ "columnType": "TIMESTAMP"
609
+ },
610
+ {
611
+ "name": "tenantId",
612
+ "type": "text",
613
+ "required": false,
614
+ "columnType": "UUID"
615
+ },
616
+ {
617
+ "name": "contractId",
618
+ "type": "crossPackageRef",
619
+ "required": false,
620
+ "related": "@happyvertical/smrt-commerce:Contract",
621
+ "columnType": "UUID"
622
+ },
623
+ {
624
+ "name": "tierId",
625
+ "type": "foreignKey",
626
+ "required": false,
627
+ "related": "AdDeliveryTier",
628
+ "columnType": "UUID"
629
+ },
630
+ {
631
+ "name": "name",
632
+ "type": "text",
633
+ "required": false,
634
+ "columnType": "TEXT"
635
+ },
636
+ {
637
+ "name": "verticalSlug",
638
+ "type": "text",
639
+ "required": false,
640
+ "columnType": "TEXT"
641
+ },
642
+ {
643
+ "name": "targeting",
644
+ "type": "text",
645
+ "required": false,
646
+ "columnType": "TEXT"
647
+ },
648
+ {
649
+ "name": "zoneIds",
650
+ "type": "text",
651
+ "required": false,
652
+ "columnType": "TEXT"
653
+ },
654
+ {
655
+ "name": "startDate",
656
+ "type": "datetime",
657
+ "required": false,
658
+ "columnType": "TIMESTAMP"
659
+ },
660
+ {
661
+ "name": "endDate",
662
+ "type": "datetime",
663
+ "required": false,
664
+ "columnType": "TIMESTAMP"
665
+ },
666
+ {
667
+ "name": "dailyBudget",
668
+ "type": "decimal",
669
+ "required": false,
670
+ "columnType": "REAL"
671
+ },
672
+ {
673
+ "name": "totalBudget",
674
+ "type": "decimal",
675
+ "required": false,
676
+ "columnType": "REAL"
677
+ },
678
+ {
679
+ "name": "status",
680
+ "type": "text",
681
+ "required": false,
682
+ "columnType": "TEXT"
683
+ }
684
+ ],
685
+ "relationships": [
686
+ {
687
+ "name": "contractId",
688
+ "type": "crossPackageRef",
689
+ "required": false,
690
+ "related": "@happyvertical/smrt-commerce:Contract",
691
+ "columnType": "UUID"
692
+ },
693
+ {
694
+ "name": "tierId",
695
+ "type": "foreignKey",
696
+ "required": false,
697
+ "related": "AdDeliveryTier",
698
+ "columnType": "UUID"
699
+ }
700
+ ],
701
+ "methods": [
702
+ "addZoneId",
703
+ "classifyConstraintError",
704
+ "clearEmbeddings",
705
+ "delete",
706
+ "describe",
707
+ "destroy",
708
+ "do",
709
+ "executeToolCall",
710
+ "forget",
711
+ "forgetScope",
712
+ "generateEmbeddings",
713
+ "getAiUsageSnapshot",
714
+ "getAvailableTools",
715
+ "getEmbedding",
716
+ "getFields",
717
+ "getId",
718
+ "getRelated",
719
+ "getSavedId",
720
+ "getSlug",
721
+ "getTargeting",
722
+ "getZoneIds",
723
+ "hasEnded",
724
+ "hasStaleEmbeddings",
725
+ "hasStarted",
726
+ "hasZoneId",
727
+ "initialize",
728
+ "is",
729
+ "isActive",
730
+ "isCompleted",
731
+ "isDraft",
732
+ "isPaused",
733
+ "isRelatedLoaded",
734
+ "isSaved",
735
+ "listAiUsage",
736
+ "loadDataFromDb",
737
+ "loadFromId",
738
+ "loadFromSlug",
739
+ "loadRelated",
740
+ "loadRelatedMany",
741
+ "markAsPersisted",
742
+ "recall",
743
+ "recallAll",
744
+ "remember",
745
+ "removeZoneId",
746
+ "resetAiUsage",
747
+ "save",
748
+ "setTargeting",
749
+ "setZoneIds",
750
+ "summarizeAiUsage",
751
+ "toJSON",
752
+ "toPlainObject",
753
+ "toPublicJSON"
754
+ ],
755
+ "surfaces": [
756
+ {
757
+ "kind": "api",
758
+ "name": "adgroups.list",
759
+ "operation": "list",
760
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
761
+ "path": "/adgroups",
762
+ "method": "GET"
763
+ },
764
+ {
765
+ "kind": "api",
766
+ "name": "adgroups.get",
767
+ "operation": "get",
768
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
769
+ "path": "/adgroups/[id]",
770
+ "method": "GET"
771
+ },
772
+ {
773
+ "kind": "api",
774
+ "name": "adgroups.create",
775
+ "operation": "create",
776
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
777
+ "path": "/adgroups",
778
+ "method": "POST"
779
+ },
780
+ {
781
+ "kind": "api",
782
+ "name": "adgroups.update",
783
+ "operation": "update",
784
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
785
+ "path": "/adgroups/[id]",
786
+ "method": "PATCH"
787
+ },
788
+ {
789
+ "kind": "cli",
790
+ "name": "adgroup_list",
791
+ "operation": "list",
792
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
793
+ },
794
+ {
795
+ "kind": "cli",
796
+ "name": "adgroup_get",
797
+ "operation": "get",
798
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
799
+ },
800
+ {
801
+ "kind": "cli",
802
+ "name": "adgroup_create",
803
+ "operation": "create",
804
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
805
+ },
806
+ {
807
+ "kind": "cli",
808
+ "name": "adgroup_update",
809
+ "operation": "update",
810
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
811
+ },
812
+ {
813
+ "kind": "cli",
814
+ "name": "adgroup_delete",
815
+ "operation": "delete",
816
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
817
+ },
818
+ {
819
+ "kind": "mcp",
820
+ "name": "adgroup_list",
821
+ "operation": "list",
822
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
823
+ },
824
+ {
825
+ "kind": "mcp",
826
+ "name": "adgroup_get",
827
+ "operation": "get",
828
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
829
+ },
830
+ {
831
+ "kind": "mcp",
832
+ "name": "adgroup_create",
833
+ "operation": "create",
834
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
835
+ }
836
+ ],
837
+ "relationshipFeatures": [
838
+ "crossPackageRef",
839
+ "foreignKey",
840
+ "uuidColumns"
841
+ ],
842
+ "tags": [],
843
+ "risks": []
844
+ },
845
+ {
846
+ "name": "AdVariation",
847
+ "qualifiedName": "@happyvertical/smrt-ads:AdVariation",
848
+ "collection": "advariations",
849
+ "tableName": "ad_variations",
850
+ "packageName": "@happyvertical/smrt-ads",
851
+ "extends": "SmrtObject",
852
+ "fields": [
853
+ {
854
+ "name": "created_at",
855
+ "type": "datetime",
856
+ "required": false,
857
+ "columnType": "TIMESTAMP"
858
+ },
859
+ {
860
+ "name": "updated_at",
861
+ "type": "datetime",
862
+ "required": false,
863
+ "columnType": "TIMESTAMP"
864
+ },
865
+ {
866
+ "name": "tenantId",
867
+ "type": "text",
868
+ "required": false,
869
+ "columnType": "UUID"
870
+ },
871
+ {
872
+ "name": "groupId",
873
+ "type": "foreignKey",
874
+ "required": false,
875
+ "related": "AdGroup",
876
+ "columnType": "UUID"
877
+ },
878
+ {
879
+ "name": "formatId",
880
+ "type": "foreignKey",
881
+ "required": false,
882
+ "related": "AdFormat",
883
+ "columnType": "UUID"
884
+ },
885
+ {
886
+ "name": "assetId",
887
+ "type": "crossPackageRef",
888
+ "required": false,
889
+ "related": "@happyvertical/smrt-assets:Asset",
890
+ "columnType": "UUID"
891
+ },
892
+ {
893
+ "name": "name",
894
+ "type": "text",
895
+ "required": false,
896
+ "columnType": "TEXT"
897
+ },
898
+ {
899
+ "name": "clickUrl",
900
+ "type": "text",
901
+ "required": false,
902
+ "columnType": "TEXT"
903
+ },
904
+ {
905
+ "name": "altText",
906
+ "type": "text",
907
+ "required": false,
908
+ "columnType": "TEXT"
909
+ },
910
+ {
911
+ "name": "weight",
912
+ "type": "integer",
913
+ "required": false,
914
+ "columnType": "INTEGER"
915
+ },
916
+ {
917
+ "name": "status",
918
+ "type": "text",
919
+ "required": false,
920
+ "columnType": "TEXT"
921
+ },
922
+ {
923
+ "name": "impressions",
924
+ "type": "integer",
925
+ "required": false,
926
+ "columnType": "INTEGER"
927
+ },
928
+ {
929
+ "name": "clicks",
930
+ "type": "integer",
931
+ "required": false,
932
+ "columnType": "INTEGER"
933
+ }
934
+ ],
935
+ "relationships": [
936
+ {
937
+ "name": "groupId",
938
+ "type": "foreignKey",
939
+ "required": false,
940
+ "related": "AdGroup",
941
+ "columnType": "UUID"
942
+ },
943
+ {
944
+ "name": "formatId",
945
+ "type": "foreignKey",
946
+ "required": false,
947
+ "related": "AdFormat",
948
+ "columnType": "UUID"
949
+ },
950
+ {
951
+ "name": "assetId",
952
+ "type": "crossPackageRef",
953
+ "required": false,
954
+ "related": "@happyvertical/smrt-assets:Asset",
955
+ "columnType": "UUID"
956
+ }
957
+ ],
958
+ "methods": [
959
+ "classifyConstraintError",
960
+ "clearEmbeddings",
961
+ "delete",
962
+ "describe",
963
+ "destroy",
964
+ "do",
965
+ "executeToolCall",
966
+ "forget",
967
+ "forgetScope",
968
+ "generateEmbeddings",
969
+ "getAiUsageSnapshot",
970
+ "getAvailableTools",
971
+ "getCTR",
972
+ "getEmbedding",
973
+ "getFields",
974
+ "getId",
975
+ "getRelated",
976
+ "getSavedId",
977
+ "getSlug",
978
+ "hasStaleEmbeddings",
979
+ "initialize",
980
+ "is",
981
+ "isActive",
982
+ "isDraft",
983
+ "isPaused",
984
+ "isRelatedLoaded",
985
+ "isSaved",
986
+ "listAiUsage",
987
+ "loadDataFromDb",
988
+ "loadFromId",
989
+ "loadFromSlug",
990
+ "loadRelated",
991
+ "loadRelatedMany",
992
+ "markAsPersisted",
993
+ "recall",
994
+ "recallAll",
995
+ "recordClick",
996
+ "recordImpression",
997
+ "remember",
998
+ "resetAiUsage",
999
+ "save",
1000
+ "summarizeAiUsage",
1001
+ "toJSON",
1002
+ "toPlainObject",
1003
+ "toPublicJSON"
1004
+ ],
1005
+ "surfaces": [
1006
+ {
1007
+ "kind": "api",
1008
+ "name": "advariations.list",
1009
+ "operation": "list",
1010
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1011
+ "path": "/advariations",
1012
+ "method": "GET"
1013
+ },
1014
+ {
1015
+ "kind": "api",
1016
+ "name": "advariations.get",
1017
+ "operation": "get",
1018
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1019
+ "path": "/advariations/[id]",
1020
+ "method": "GET"
1021
+ },
1022
+ {
1023
+ "kind": "api",
1024
+ "name": "advariations.create",
1025
+ "operation": "create",
1026
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1027
+ "path": "/advariations",
1028
+ "method": "POST"
1029
+ },
1030
+ {
1031
+ "kind": "api",
1032
+ "name": "advariations.update",
1033
+ "operation": "update",
1034
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1035
+ "path": "/advariations/[id]",
1036
+ "method": "PATCH"
1037
+ },
1038
+ {
1039
+ "kind": "cli",
1040
+ "name": "advariation_list",
1041
+ "operation": "list",
1042
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1043
+ },
1044
+ {
1045
+ "kind": "cli",
1046
+ "name": "advariation_get",
1047
+ "operation": "get",
1048
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1049
+ },
1050
+ {
1051
+ "kind": "cli",
1052
+ "name": "advariation_create",
1053
+ "operation": "create",
1054
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1055
+ },
1056
+ {
1057
+ "kind": "cli",
1058
+ "name": "advariation_update",
1059
+ "operation": "update",
1060
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1061
+ },
1062
+ {
1063
+ "kind": "cli",
1064
+ "name": "advariation_delete",
1065
+ "operation": "delete",
1066
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1067
+ },
1068
+ {
1069
+ "kind": "mcp",
1070
+ "name": "advariation_list",
1071
+ "operation": "list",
1072
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1073
+ },
1074
+ {
1075
+ "kind": "mcp",
1076
+ "name": "advariation_get",
1077
+ "operation": "get",
1078
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1079
+ },
1080
+ {
1081
+ "kind": "mcp",
1082
+ "name": "advariation_create",
1083
+ "operation": "create",
1084
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1085
+ }
1086
+ ],
1087
+ "relationshipFeatures": [
1088
+ "crossPackageRef",
1089
+ "foreignKey",
1090
+ "uuidColumns"
1091
+ ],
1092
+ "tags": [],
1093
+ "risks": []
1094
+ }
1095
+ ],
1096
+ "surfaces": [
1097
+ {
1098
+ "kind": "api",
1099
+ "name": "addeliverytiers.list",
1100
+ "operation": "list",
1101
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
1102
+ "path": "/addeliverytiers",
1103
+ "method": "GET"
1104
+ },
1105
+ {
1106
+ "kind": "api",
1107
+ "name": "addeliverytiers.get",
1108
+ "operation": "get",
1109
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
1110
+ "path": "/addeliverytiers/[id]",
1111
+ "method": "GET"
1112
+ },
1113
+ {
1114
+ "kind": "api",
1115
+ "name": "addeliverytiers.create",
1116
+ "operation": "create",
1117
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
1118
+ "path": "/addeliverytiers",
1119
+ "method": "POST"
1120
+ },
1121
+ {
1122
+ "kind": "api",
1123
+ "name": "addeliverytiers.update",
1124
+ "operation": "update",
1125
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier",
1126
+ "path": "/addeliverytiers/[id]",
1127
+ "method": "PATCH"
1128
+ },
1129
+ {
1130
+ "kind": "cli",
1131
+ "name": "addeliverytier_list",
1132
+ "operation": "list",
1133
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1134
+ },
1135
+ {
1136
+ "kind": "cli",
1137
+ "name": "addeliverytier_get",
1138
+ "operation": "get",
1139
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1140
+ },
1141
+ {
1142
+ "kind": "cli",
1143
+ "name": "addeliverytier_create",
1144
+ "operation": "create",
1145
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1146
+ },
1147
+ {
1148
+ "kind": "cli",
1149
+ "name": "addeliverytier_update",
1150
+ "operation": "update",
1151
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1152
+ },
1153
+ {
1154
+ "kind": "cli",
1155
+ "name": "addeliverytier_delete",
1156
+ "operation": "delete",
1157
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1158
+ },
1159
+ {
1160
+ "kind": "mcp",
1161
+ "name": "addeliverytier_list",
1162
+ "operation": "list",
1163
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1164
+ },
1165
+ {
1166
+ "kind": "mcp",
1167
+ "name": "addeliverytier_get",
1168
+ "operation": "get",
1169
+ "objectName": "@happyvertical/smrt-ads:AdDeliveryTier"
1170
+ },
1171
+ {
1172
+ "kind": "api",
1173
+ "name": "adevents.create",
1174
+ "operation": "create",
1175
+ "objectName": "@happyvertical/smrt-ads:AdEvent",
1176
+ "path": "/adevents",
1177
+ "method": "POST"
1178
+ },
1179
+ {
1180
+ "kind": "api",
1181
+ "name": "adevents.list",
1182
+ "operation": "list",
1183
+ "objectName": "@happyvertical/smrt-ads:AdEvent",
1184
+ "path": "/adevents",
1185
+ "method": "GET"
1186
+ },
1187
+ {
1188
+ "kind": "mcp",
1189
+ "name": "adevent_create",
1190
+ "operation": "create",
1191
+ "objectName": "@happyvertical/smrt-ads:AdEvent"
1192
+ },
1193
+ {
1194
+ "kind": "api",
1195
+ "name": "adformats.list",
1196
+ "operation": "list",
1197
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
1198
+ "path": "/adformats",
1199
+ "method": "GET"
1200
+ },
1201
+ {
1202
+ "kind": "api",
1203
+ "name": "adformats.get",
1204
+ "operation": "get",
1205
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
1206
+ "path": "/adformats/[id]",
1207
+ "method": "GET"
1208
+ },
1209
+ {
1210
+ "kind": "api",
1211
+ "name": "adformats.create",
1212
+ "operation": "create",
1213
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
1214
+ "path": "/adformats",
1215
+ "method": "POST"
1216
+ },
1217
+ {
1218
+ "kind": "api",
1219
+ "name": "adformats.update",
1220
+ "operation": "update",
1221
+ "objectName": "@happyvertical/smrt-ads:AdFormat",
1222
+ "path": "/adformats/[id]",
1223
+ "method": "PATCH"
1224
+ },
1225
+ {
1226
+ "kind": "cli",
1227
+ "name": "adformat_list",
1228
+ "operation": "list",
1229
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1230
+ },
1231
+ {
1232
+ "kind": "cli",
1233
+ "name": "adformat_get",
1234
+ "operation": "get",
1235
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1236
+ },
1237
+ {
1238
+ "kind": "cli",
1239
+ "name": "adformat_create",
1240
+ "operation": "create",
1241
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1242
+ },
1243
+ {
1244
+ "kind": "cli",
1245
+ "name": "adformat_update",
1246
+ "operation": "update",
1247
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1248
+ },
1249
+ {
1250
+ "kind": "cli",
1251
+ "name": "adformat_delete",
1252
+ "operation": "delete",
1253
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1254
+ },
1255
+ {
1256
+ "kind": "mcp",
1257
+ "name": "adformat_list",
1258
+ "operation": "list",
1259
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1260
+ },
1261
+ {
1262
+ "kind": "mcp",
1263
+ "name": "adformat_get",
1264
+ "operation": "get",
1265
+ "objectName": "@happyvertical/smrt-ads:AdFormat"
1266
+ },
1267
+ {
1268
+ "kind": "api",
1269
+ "name": "adgroups.list",
1270
+ "operation": "list",
1271
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
1272
+ "path": "/adgroups",
1273
+ "method": "GET"
1274
+ },
1275
+ {
1276
+ "kind": "api",
1277
+ "name": "adgroups.get",
1278
+ "operation": "get",
1279
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
1280
+ "path": "/adgroups/[id]",
1281
+ "method": "GET"
1282
+ },
1283
+ {
1284
+ "kind": "api",
1285
+ "name": "adgroups.create",
1286
+ "operation": "create",
1287
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
1288
+ "path": "/adgroups",
1289
+ "method": "POST"
1290
+ },
1291
+ {
1292
+ "kind": "api",
1293
+ "name": "adgroups.update",
1294
+ "operation": "update",
1295
+ "objectName": "@happyvertical/smrt-ads:AdGroup",
1296
+ "path": "/adgroups/[id]",
1297
+ "method": "PATCH"
1298
+ },
1299
+ {
1300
+ "kind": "cli",
1301
+ "name": "adgroup_list",
1302
+ "operation": "list",
1303
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1304
+ },
1305
+ {
1306
+ "kind": "cli",
1307
+ "name": "adgroup_get",
1308
+ "operation": "get",
1309
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1310
+ },
1311
+ {
1312
+ "kind": "cli",
1313
+ "name": "adgroup_create",
1314
+ "operation": "create",
1315
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1316
+ },
1317
+ {
1318
+ "kind": "cli",
1319
+ "name": "adgroup_update",
1320
+ "operation": "update",
1321
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1322
+ },
1323
+ {
1324
+ "kind": "cli",
1325
+ "name": "adgroup_delete",
1326
+ "operation": "delete",
1327
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1328
+ },
1329
+ {
1330
+ "kind": "mcp",
1331
+ "name": "adgroup_list",
1332
+ "operation": "list",
1333
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1334
+ },
1335
+ {
1336
+ "kind": "mcp",
1337
+ "name": "adgroup_get",
1338
+ "operation": "get",
1339
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1340
+ },
1341
+ {
1342
+ "kind": "mcp",
1343
+ "name": "adgroup_create",
1344
+ "operation": "create",
1345
+ "objectName": "@happyvertical/smrt-ads:AdGroup"
1346
+ },
1347
+ {
1348
+ "kind": "api",
1349
+ "name": "advariations.list",
1350
+ "operation": "list",
1351
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1352
+ "path": "/advariations",
1353
+ "method": "GET"
1354
+ },
1355
+ {
1356
+ "kind": "api",
1357
+ "name": "advariations.get",
1358
+ "operation": "get",
1359
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1360
+ "path": "/advariations/[id]",
1361
+ "method": "GET"
1362
+ },
1363
+ {
1364
+ "kind": "api",
1365
+ "name": "advariations.create",
1366
+ "operation": "create",
1367
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1368
+ "path": "/advariations",
1369
+ "method": "POST"
1370
+ },
1371
+ {
1372
+ "kind": "api",
1373
+ "name": "advariations.update",
1374
+ "operation": "update",
1375
+ "objectName": "@happyvertical/smrt-ads:AdVariation",
1376
+ "path": "/advariations/[id]",
1377
+ "method": "PATCH"
1378
+ },
1379
+ {
1380
+ "kind": "cli",
1381
+ "name": "advariation_list",
1382
+ "operation": "list",
1383
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1384
+ },
1385
+ {
1386
+ "kind": "cli",
1387
+ "name": "advariation_get",
1388
+ "operation": "get",
1389
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1390
+ },
1391
+ {
1392
+ "kind": "cli",
1393
+ "name": "advariation_create",
1394
+ "operation": "create",
1395
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1396
+ },
1397
+ {
1398
+ "kind": "cli",
1399
+ "name": "advariation_update",
1400
+ "operation": "update",
1401
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1402
+ },
1403
+ {
1404
+ "kind": "cli",
1405
+ "name": "advariation_delete",
1406
+ "operation": "delete",
1407
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1408
+ },
1409
+ {
1410
+ "kind": "mcp",
1411
+ "name": "advariation_list",
1412
+ "operation": "list",
1413
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1414
+ },
1415
+ {
1416
+ "kind": "mcp",
1417
+ "name": "advariation_get",
1418
+ "operation": "get",
1419
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1420
+ },
1421
+ {
1422
+ "kind": "mcp",
1423
+ "name": "advariation_create",
1424
+ "operation": "create",
1425
+ "objectName": "@happyvertical/smrt-ads:AdVariation"
1426
+ }
1427
+ ],
1428
+ "prompts": [],
1429
+ "relationshipsV2": {
1430
+ "foreignKeyFields": 4,
1431
+ "crossPackageRefFields": 3,
1432
+ "junctionCollections": 0,
1433
+ "hierarchicalObjects": 0,
1434
+ "polymorphicAssociations": 0,
1435
+ "uuidColumns": 20
1436
+ },
1437
+ "agentDoc": "# @happyvertical/smrt-ads\n\nAd delivery with priority waterfall, weighted A/B testing, and immutable event tracking.\n\n## Models\n\n- **AdFormat**: IAB standard dimensions (width, height, type: banner/native/video)\n- **AdDeliveryTier**: priority levels — Sponsorship (1, FIXED pricing) > Standard (2, CPM) > House (3, fallback)\n- **AdGroup**: campaign with targeting, budget, zone restrictions\n- **AdVariation** (STI): creative variant with weighted selection for A/B. `weight=2` is 2x more likely than `weight=1`. Denormalized `impressions`/`clicks` fields.\n- **AdEvent** (STI, immutable): impression/click/conversion tracking. **Create-only** — no update/delete in API/MCP. `cli: false` (high-volume).\n\n## Cross-Package References (all plain string IDs)\n\n`contractId` → smrt-commerce, `zoneId`/`siteId` → smrt-properties, `assetId` → smrt-assets, `verticalSlug` → smrt-tags\n\n## Tenancy\n\nOptional tenancy via `@TenantScoped({ mode: 'optional' })` is applied to the\nthree transactional models — `AdGroup`, `AdVariation`, and `AdEvent` — which\nparticipate in per-tenant ad serving and event tracking.\n\n`AdFormat` and `AdDeliveryTier` are deliberately **NOT** tenant-scoped: they\nare shared catalog/lookup tables.\n\n- `AdFormat` rows describe IAB standard ad dimensions (e.g. `728x90`\n Leaderboard, `300x250` Medium Rectangle). The dimensions are an industry\n standard, not a tenant-specific configuration.\n- `AdDeliveryTier` rows describe the priority waterfall for ad selection\n (Sponsorship → Standard → House). Tiers are part of the package's\n ad-serving contract; per-tenant tier definitions would fragment the\n selection algorithm without a clear use case.\n\nEither model can still be filtered by tenant manually if a deployment ever\nneeds tenant-specific overrides, but the default is global. This mirrors the\ndocumented exception pattern in `packages/secrets/AGENTS.md` (`TenantKey`).\nEach `@smrt(...)` block on these two classes carries an inline comment\npointing back here.\n\n## Gotchas\n\n- **Priority waterfall**: lower priority number = higher priority in selection\n- **Weight is relative integer**: not percentage — probability calculated from total weight across variations\n- **Denormalized counts need async refresh**: impressions/clicks on AdVariation are eventually consistent\n- **No frequency capping or budget enforcement built-in**: external responsibility\n- **Targeting rules stored as JSON string**: no schema validation\n- **Optional tenancy** on `AdGroup`, `AdVariation`, `AdEvent` only — see Tenancy section above for `AdFormat`/`AdDeliveryTier` rationale\n"
1438
+ }