@happyvertical/smrt-ads 0.51.32 → 0.51.33

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 (34) hide show
  1. package/dist/__smrt-register__.d.ts +2 -0
  2. package/dist/__smrt-register__.d.ts.map +1 -0
  3. package/dist/collections/AdDeliveryTierCollection.d.ts +42 -0
  4. package/dist/collections/AdDeliveryTierCollection.d.ts.map +1 -0
  5. package/dist/collections/AdEventCollection.d.ts +119 -0
  6. package/dist/collections/AdEventCollection.d.ts.map +1 -0
  7. package/dist/collections/AdFormatCollection.d.ts +38 -0
  8. package/dist/collections/AdFormatCollection.d.ts.map +1 -0
  9. package/dist/collections/AdGroupCollection.d.ts +100 -0
  10. package/dist/collections/AdGroupCollection.d.ts.map +1 -0
  11. package/dist/collections/AdVariationCollection.d.ts +93 -0
  12. package/dist/collections/AdVariationCollection.d.ts.map +1 -0
  13. package/dist/collections/index.d.ts +10 -0
  14. package/dist/collections/index.d.ts.map +1 -0
  15. package/dist/index.d.ts +12 -885
  16. package/dist/index.d.ts.map +1 -0
  17. package/dist/index.js +1 -1
  18. package/dist/manifest.json +1 -1
  19. package/dist/models/AdDeliveryTier.d.ts +66 -0
  20. package/dist/models/AdDeliveryTier.d.ts.map +1 -0
  21. package/dist/models/AdEvent.d.ts +105 -0
  22. package/dist/models/AdEvent.d.ts.map +1 -0
  23. package/dist/models/AdFormat.d.ts +62 -0
  24. package/dist/models/AdFormat.d.ts.map +1 -0
  25. package/dist/models/AdGroup.d.ts +153 -0
  26. package/dist/models/AdGroup.d.ts.map +1 -0
  27. package/dist/models/AdVariation.d.ts +117 -0
  28. package/dist/models/AdVariation.d.ts.map +1 -0
  29. package/dist/models/index.d.ts +10 -0
  30. package/dist/models/index.d.ts.map +1 -0
  31. package/dist/smrt-knowledge.json +4 -4
  32. package/dist/types/index.d.ts +46 -0
  33. package/dist/types/index.d.ts.map +1 -0
  34. package/package.json +6 -6
package/dist/index.d.ts CHANGED
@@ -1,885 +1,12 @@
1
- import { SmrtCollection } from '@happyvertical/smrt-core';
2
- import { SmrtObject } from '@happyvertical/smrt-core';
3
- import { SmrtObjectOptions } from '@happyvertical/smrt-core';
4
-
5
- /**
6
- * AdDeliveryTier defines priority levels for ad serving.
7
- *
8
- * Ads are selected by priority (lower = higher priority):
9
- * 1. Sponsorship - Guaranteed, premium placements
10
- * 2. Standard - Regular programmatic ads
11
- * 3. House - Self-promotional/fallback ads
12
- *
13
- * @example
14
- * ```typescript
15
- * const sponsorship = await tiers.create({
16
- * name: 'Sponsorship',
17
- * priority: 1,
18
- * pricingModel: PricingModel.FIXED,
19
- * description: 'Premium guaranteed placements'
20
- * });
21
- * ```
22
- */
23
- export declare class AdDeliveryTier extends SmrtObject {
24
- /**
25
- * Display name (e.g., "Sponsorship", "Standard", "House")
26
- */
27
- name: string;
28
- /**
29
- * Priority level (lower = higher priority: 1, 2, 3...)
30
- */
31
- priority: number;
32
- /**
33
- * Pricing model for this tier
34
- */
35
- pricingModel: PricingModel;
36
- /**
37
- * Optional description
38
- */
39
- description: string;
40
- constructor(options?: AdDeliveryTierOptions);
41
- /**
42
- * Check if this tier is higher priority than another
43
- */
44
- isHigherPriorityThan(other: AdDeliveryTier): boolean;
45
- /**
46
- * Check if this is a fixed pricing tier
47
- */
48
- isFixedPricing(): boolean;
49
- /**
50
- * Check if this is a performance-based tier (CPC, CPA)
51
- */
52
- isPerformanceBased(): boolean;
53
- }
54
-
55
- export declare class AdDeliveryTierCollection extends SmrtCollection<AdDeliveryTier> {
56
- static readonly _itemClass: typeof AdDeliveryTier;
57
- /**
58
- * Find tiers ordered by priority (ascending, lower = higher priority)
59
- *
60
- * @returns Array of tiers ordered by priority
61
- */
62
- findByPriority(): Promise<AdDeliveryTier[]>;
63
- /**
64
- * Find tiers by pricing model
65
- *
66
- * @param pricingModel - Pricing model to filter by
67
- * @returns Array of matching tiers
68
- */
69
- findByPricingModel(pricingModel: PricingModel): Promise<AdDeliveryTier[]>;
70
- /**
71
- * Get the highest priority tier
72
- *
73
- * @returns Highest priority tier or null
74
- */
75
- getHighestPriority(): Promise<AdDeliveryTier | null>;
76
- /**
77
- * Find fixed pricing tiers
78
- */
79
- findFixedPricing(): Promise<AdDeliveryTier[]>;
80
- /**
81
- * Find CPM-based tiers
82
- */
83
- findCPM(): Promise<AdDeliveryTier[]>;
84
- /**
85
- * Find performance-based tiers (CPC, CPA)
86
- */
87
- findPerformanceBased(): Promise<AdDeliveryTier[]>;
88
- }
89
-
90
- /**
91
- * Options for constructing an {@link AdDeliveryTier}.
92
- */
93
- declare interface AdDeliveryTierOptions extends SmrtObjectOptions {
94
- name?: string;
95
- priority?: number;
96
- pricingModel?: PricingModel;
97
- description?: string;
98
- }
99
-
100
- /**
101
- * AdEvent tracks ad impressions, clicks, and conversions.
102
- * Events are immutable (append-only, no update/delete).
103
- *
104
- * References:
105
- * - variationId: FK to AdVariation (within package)
106
- * - zoneId: String reference to smrt-properties Zone (cross-package)
107
- * - siteId: Denormalized for query efficiency (cross-package)
108
- *
109
- * @example
110
- * ```typescript
111
- * // Track an impression
112
- * const impression = await events.create({
113
- * variationId: variation.id,
114
- * zoneId: 'zone-uuid',
115
- * siteId: 'site-uuid',
116
- * eventType: AdEventType.IMPRESSION,
117
- * metadata: JSON.stringify({
118
- * ip: '192.168.1.1',
119
- * userAgent: 'Mozilla/5.0...',
120
- * referrer: 'https://example.com'
121
- * })
122
- * });
123
- *
124
- * // Track a click
125
- * const click = await events.create({
126
- * variationId: variation.id,
127
- * zoneId: 'zone-uuid',
128
- * siteId: 'site-uuid',
129
- * eventType: AdEventType.CLICK
130
- * });
131
- * ```
132
- */
133
- export declare class AdEvent extends SmrtObject {
134
- /**
135
- * Tenant ID for multi-tenancy support
136
- */
137
- tenantId: string | null;
138
- /**
139
- * Variation ID (FK to AdVariation)
140
- */
141
- variationId: string;
142
- /**
143
- * Zone ID (FK to smrt-properties Zone, cross-package)
144
- */
145
- zoneId: string;
146
- /**
147
- * Site ID (denormalized from Zone for query efficiency)
148
- */
149
- siteId: string;
150
- /**
151
- * Event type (impression, click, conversion)
152
- */
153
- eventType: AdEventType;
154
- /**
155
- * Event timestamp
156
- */
157
- timestamp: Date;
158
- /**
159
- * Analytics metadata as JSON string
160
- * (IP, user agent, referrer, etc.)
161
- */
162
- metadata: string;
163
- constructor(options?: AdEventOptions);
164
- /**
165
- * Get metadata as object
166
- */
167
- getMetadata(): Record<string, unknown>;
168
- /**
169
- * Set metadata from object
170
- */
171
- setMetadata(data: Record<string, unknown>): void;
172
- /**
173
- * Check if this is an impression event
174
- */
175
- isImpression(): boolean;
176
- /**
177
- * Check if this is a click event
178
- */
179
- isClick(): boolean;
180
- /**
181
- * Check if this is a conversion event
182
- */
183
- isConversion(): boolean;
184
- }
185
-
186
- export declare class AdEventCollection extends SmrtCollection<AdEvent> {
187
- static readonly _itemClass: typeof AdEvent;
188
- /**
189
- * Find events by variation
190
- *
191
- * @param variationId - Variation ID
192
- * @returns Array of events
193
- */
194
- findByVariation(variationId: string): Promise<AdEvent[]>;
195
- /**
196
- * Find events by zone
197
- *
198
- * @param zoneId - Zone ID
199
- * @returns Array of events
200
- */
201
- findByZone(zoneId: string): Promise<AdEvent[]>;
202
- /**
203
- * Find events by site
204
- *
205
- * @param siteId - Site ID
206
- * @returns Array of events
207
- */
208
- findBySite(siteId: string): Promise<AdEvent[]>;
209
- /**
210
- * Find events in date range
211
- *
212
- * @param start - Start date
213
- * @param end - End date
214
- * @returns Array of events
215
- */
216
- findByDateRange(start: Date, end: Date): Promise<AdEvent[]>;
217
- /**
218
- * Find events by type
219
- *
220
- * @param eventType - Event type
221
- * @returns Array of events
222
- */
223
- findByType(eventType: AdEventType): Promise<AdEvent[]>;
224
- /**
225
- * Count events by type for a variation
226
- *
227
- * @param variationId - Variation ID
228
- * @param eventType - Event type
229
- * @returns Count of events
230
- */
231
- countByType(variationId: string, eventType: AdEventType): Promise<number>;
232
- /**
233
- * Count impressions for a variation
234
- */
235
- countImpressions(variationId: string): Promise<number>;
236
- /**
237
- * Count clicks for a variation
238
- */
239
- countClicks(variationId: string): Promise<number>;
240
- /**
241
- * Count conversions for a variation
242
- */
243
- countConversions(variationId: string): Promise<number>;
244
- /**
245
- * Find all impressions
246
- */
247
- findImpressions(): Promise<AdEvent[]>;
248
- /**
249
- * Find all clicks
250
- */
251
- findClicks(): Promise<AdEvent[]>;
252
- /**
253
- * Find all conversions
254
- */
255
- findConversions(): Promise<AdEvent[]>;
256
- /**
257
- * Get aggregate stats for a variation
258
- *
259
- * @param variationId - Variation ID
260
- * @returns Stats object with impressions, clicks, conversions, CTR
261
- */
262
- getVariationStats(variationId: string): Promise<{
263
- impressions: number;
264
- clicks: number;
265
- conversions: number;
266
- ctr: number;
267
- conversionRate: number;
268
- }>;
269
- /**
270
- * Find ad events belonging to a specific tenant
271
- *
272
- * @param tenantId - Tenant ID to filter by
273
- * @returns Array of ad events for the tenant
274
- */
275
- findByTenant(tenantId: string): Promise<AdEvent[]>;
276
- /**
277
- * Find global ad events (no tenant association).
278
- *
279
- * Routes through the shared tenant-global helper so it does not throw under
280
- * an active tenant context (an explicit `tenant_id IS NULL` filter would be
281
- * flagged as an isolation violation). (#1600)
282
- *
283
- * @returns Array of global ad events
284
- */
285
- findGlobal(): Promise<AdEvent[]>;
286
- /**
287
- * Find ad events for a tenant including global (shared) events.
288
- *
289
- * Fails closed if an active tenant context requests a different tenant's
290
- * rows; the admin/system path keeps the cross-tenant capability. (#1600)
291
- *
292
- * @param tenantId - Tenant ID to include
293
- * @returns Array of tenant-specific and global ad events
294
- */
295
- findWithGlobals(tenantId: string): Promise<AdEvent[]>;
296
- }
297
-
298
- /**
299
- * Options for constructing an {@link AdEvent}.
300
- */
301
- declare interface AdEventOptions extends SmrtObjectOptions {
302
- tenantId?: string | null;
303
- variationId?: string;
304
- zoneId?: string;
305
- siteId?: string;
306
- eventType?: AdEventType;
307
- timestamp?: Date;
308
- metadata?: string;
309
- }
310
-
311
- /**
312
- * Event types for ad tracking
313
- */
314
- export declare enum AdEventType {
315
- IMPRESSION = "impression",
316
- CLICK = "click",
317
- CONVERSION = "conversion"
318
- }
319
-
320
- /**
321
- * AdFormat defines standard ad dimensions and types (IAB standards).
322
- *
323
- * @example
324
- * ```typescript
325
- * const leaderboard = await formats.create({
326
- * name: 'Leaderboard',
327
- * width: 728,
328
- * height: 90,
329
- * formatType: AdFormatType.BANNER
330
- * });
331
- * ```
332
- */
333
- export declare class AdFormat extends SmrtObject {
334
- /**
335
- * Display name (e.g., "Leaderboard", "Medium Rectangle")
336
- */
337
- name: string;
338
- /**
339
- * Width in pixels
340
- */
341
- width: number;
342
- /**
343
- * Height in pixels
344
- */
345
- height: number;
346
- /**
347
- * Format type (banner, native, video)
348
- */
349
- formatType: AdFormatType;
350
- /**
351
- * Optional description
352
- */
353
- description: string;
354
- constructor(options?: AdFormatOptions);
355
- /**
356
- * Get dimensions as string (e.g., "728x90")
357
- */
358
- getDimensions(): string;
359
- /**
360
- * Check if format matches specific dimensions
361
- */
362
- matchesDimensions(width: number, height: number): boolean;
363
- }
364
-
365
- export declare class AdFormatCollection extends SmrtCollection<AdFormat> {
366
- static readonly _itemClass: typeof AdFormat;
367
- /**
368
- * Find format by dimensions
369
- *
370
- * @param width - Width in pixels
371
- * @param height - Height in pixels
372
- * @returns Matching format or null
373
- */
374
- findByDimensions(width: number, height: number): Promise<AdFormat | null>;
375
- /**
376
- * Find formats by type
377
- *
378
- * @param formatType - Format type (banner, native, video)
379
- * @returns Array of matching formats
380
- */
381
- findByType(formatType: AdFormatType): Promise<AdFormat[]>;
382
- /**
383
- * Find all banner formats
384
- */
385
- findBanners(): Promise<AdFormat[]>;
386
- /**
387
- * Find all native formats
388
- */
389
- findNative(): Promise<AdFormat[]>;
390
- /**
391
- * Find all video formats
392
- */
393
- findVideo(): Promise<AdFormat[]>;
394
- }
395
-
396
- /**
397
- * Options for constructing an {@link AdFormat}.
398
- */
399
- declare interface AdFormatOptions extends SmrtObjectOptions {
400
- name?: string;
401
- width?: number;
402
- height?: number;
403
- formatType?: AdFormatType;
404
- description?: string;
405
- }
406
-
407
- /**
408
- * Types and enums for smrt-ads package
409
- */
410
- /**
411
- * Ad format types for different creative types
412
- */
413
- export declare enum AdFormatType {
414
- BANNER = "banner",
415
- NATIVE = "native",
416
- VIDEO = "video"
417
- }
418
-
419
- /**
420
- * AdGroup organizes ad creatives with targeting and budget controls.
421
- *
422
- * References:
423
- * - tierId: FK to AdDeliveryTier (within package)
424
- * - contractId: String reference to smrt-commerce Contract (cross-package)
425
- * - zoneIds: JSON array of allowed smrt-properties Zone IDs (cross-package)
426
- * - verticalSlug: Tag slug from smrt-tags (cross-package)
427
- *
428
- * @example
429
- * ```typescript
430
- * const adGroup = await groups.create({
431
- * contractId: 'contract-uuid',
432
- * tierId: tier.id,
433
- * name: 'Summer Sale - Desktop',
434
- * verticalSlug: 'retail',
435
- * targeting: JSON.stringify({ device: 'desktop' }),
436
- * zoneIds: JSON.stringify(['zone-1', 'zone-2']),
437
- * dailyBudget: 100.00,
438
- * totalBudget: 3000.00,
439
- * startDate: new Date('2024-06-01'),
440
- * endDate: new Date('2024-08-31')
441
- * });
442
- * ```
443
- */
444
- export declare class AdGroup extends SmrtObject {
445
- /**
446
- * Tenant ID for multi-tenancy support
447
- */
448
- tenantId: string | null;
449
- /**
450
- * Contract ID (FK to smrt-commerce Contract, cross-package)
451
- */
452
- contractId: string;
453
- /**
454
- * Delivery tier ID (FK to AdDeliveryTier)
455
- */
456
- tierId: string;
457
- /**
458
- * Display name (e.g., "Summer Sale - Desktop")
459
- */
460
- name: string;
461
- /**
462
- * Vertical/category tag slug from smrt-tags (context="advertising")
463
- */
464
- verticalSlug: string;
465
- /**
466
- * Targeting rules as JSON string
467
- */
468
- targeting: string;
469
- /**
470
- * Allowed Zone IDs as JSON array string (FK to smrt-properties Zone)
471
- */
472
- zoneIds: string;
473
- /**
474
- * Campaign start date
475
- */
476
- startDate: Date | null;
477
- /**
478
- * Campaign end date
479
- */
480
- endDate: Date | null;
481
- /**
482
- * Daily budget limit
483
- */
484
- dailyBudget: number;
485
- /**
486
- * Total campaign budget
487
- */
488
- totalBudget: number;
489
- /**
490
- * Current status
491
- */
492
- status: AdGroupStatus;
493
- constructor(options?: AdGroupOptions);
494
- /**
495
- * Get zone IDs as array
496
- */
497
- getZoneIds(): string[];
498
- /**
499
- * Set zone IDs from array
500
- */
501
- setZoneIds(ids: string[]): void;
502
- /**
503
- * Add a zone ID
504
- */
505
- addZoneId(zoneId: string): void;
506
- /**
507
- * Remove a zone ID
508
- */
509
- removeZoneId(zoneId: string): void;
510
- /**
511
- * Check if zone ID is allowed
512
- */
513
- hasZoneId(zoneId: string): boolean;
514
- /**
515
- * Get targeting rules as object
516
- */
517
- getTargeting(): Record<string, unknown>;
518
- /**
519
- * Set targeting rules from object
520
- */
521
- setTargeting(rules: Record<string, unknown>): void;
522
- /**
523
- * Check if ad group is currently active
524
- */
525
- isActive(): boolean;
526
- /**
527
- * Check if ad group is in draft state
528
- */
529
- isDraft(): boolean;
530
- /**
531
- * Check if ad group is paused
532
- */
533
- isPaused(): boolean;
534
- /**
535
- * Check if ad group is completed
536
- */
537
- isCompleted(): boolean;
538
- /**
539
- * Check if ad group has ended (past end date)
540
- */
541
- hasEnded(): boolean;
542
- /**
543
- * Check if ad group has started
544
- */
545
- hasStarted(): boolean;
546
- }
547
-
548
- export declare class AdGroupCollection extends SmrtCollection<AdGroup> {
549
- static readonly _itemClass: typeof AdGroup;
550
- /**
551
- * Find ad groups by contract
552
- *
553
- * @param contractId - Contract ID
554
- * @returns Array of ad groups
555
- */
556
- findByContract(contractId: string): Promise<AdGroup[]>;
557
- /**
558
- * Find ad groups by tier
559
- *
560
- * @param tierId - Delivery tier ID
561
- * @returns Array of ad groups
562
- */
563
- findByTier(tierId: string): Promise<AdGroup[]>;
564
- /**
565
- * Find ad groups by status
566
- *
567
- * @param status - Ad group status
568
- * @returns Array of ad groups
569
- */
570
- findByStatus(status: AdGroupStatus): Promise<AdGroup[]>;
571
- /**
572
- * Find currently active ad groups
573
- * (status=active, started, not ended)
574
- *
575
- * @returns Array of active ad groups
576
- */
577
- findActive(): Promise<AdGroup[]>;
578
- /**
579
- * Find ad groups by vertical slug
580
- *
581
- * @param verticalSlug - Tag slug from smrt-tags
582
- * @returns Array of ad groups
583
- */
584
- findByVertical(verticalSlug: string): Promise<AdGroup[]>;
585
- /**
586
- * Find ad groups that can serve to a specific zone
587
- *
588
- * @param zoneId - Zone ID to check
589
- * @returns Array of ad groups containing zone
590
- */
591
- findByZone(zoneId: string): Promise<AdGroup[]>;
592
- /**
593
- * Find ad groups eligible to serve for a zone
594
- * (active, has zone, within date range)
595
- *
596
- * @param zoneId - Zone ID to check
597
- * @returns Array of eligible ad groups
598
- */
599
- findEligibleForZone(zoneId: string): Promise<AdGroup[]>;
600
- /**
601
- * Find all draft ad groups
602
- */
603
- findDrafts(): Promise<AdGroup[]>;
604
- /**
605
- * Find all paused ad groups
606
- */
607
- findPaused(): Promise<AdGroup[]>;
608
- /**
609
- * Find all completed ad groups
610
- */
611
- findCompleted(): Promise<AdGroup[]>;
612
- /**
613
- * Find ad groups belonging to a specific tenant
614
- *
615
- * @param tenantId - Tenant ID to filter by
616
- * @returns Array of ad groups for the tenant
617
- */
618
- findByTenant(tenantId: string): Promise<AdGroup[]>;
619
- /**
620
- * Find global ad groups (no tenant association).
621
- *
622
- * Routes through the shared tenant-global helper so it does not throw under
623
- * an active tenant context (an explicit `tenant_id IS NULL` filter would be
624
- * flagged as an isolation violation). (#1600)
625
- *
626
- * @returns Array of global ad groups
627
- */
628
- findGlobal(): Promise<AdGroup[]>;
629
- /**
630
- * Find ad groups for a tenant including global (shared) ad groups.
631
- *
632
- * Fails closed if an active tenant context requests a different tenant's
633
- * rows; the admin/system path keeps the cross-tenant capability. (#1600)
634
- *
635
- * @param tenantId - Tenant ID to include
636
- * @returns Array of tenant-specific and global ad groups
637
- */
638
- findWithGlobals(tenantId: string): Promise<AdGroup[]>;
639
- }
640
-
641
- /**
642
- * Options for constructing an {@link AdGroup}.
643
- */
644
- declare interface AdGroupOptions extends SmrtObjectOptions {
645
- tenantId?: string | null;
646
- contractId?: string;
647
- tierId?: string;
648
- name?: string;
649
- verticalSlug?: string;
650
- targeting?: string;
651
- zoneIds?: string;
652
- startDate?: Date | null;
653
- endDate?: Date | null;
654
- dailyBudget?: number;
655
- totalBudget?: number;
656
- status?: AdGroupStatus;
657
- }
658
-
659
- /**
660
- * Status for ad groups
661
- */
662
- export declare enum AdGroupStatus {
663
- DRAFT = "draft",
664
- ACTIVE = "active",
665
- PAUSED = "paused",
666
- COMPLETED = "completed"
667
- }
668
-
669
- /**
670
- * AdVariation represents a creative asset within an ad group.
671
- * Supports A/B testing via weighted selection.
672
- *
673
- * References:
674
- * - groupId: FK to AdGroup (within package)
675
- * - formatId: FK to AdFormat (within package)
676
- * - assetId: String reference to smrt-assets Asset (cross-package)
677
- *
678
- * @example
679
- * ```typescript
680
- * const variation = await variations.create({
681
- * groupId: adGroup.id,
682
- * formatId: leaderboard.id,
683
- * assetId: 'asset-uuid',
684
- * name: 'Version A - Blue CTA',
685
- * clickUrl: 'https://example.com/landing',
686
- * altText: 'Summer Sale - 50% off',
687
- * weight: 2 // 2x more likely than weight=1
688
- * });
689
- * ```
690
- */
691
- export declare class AdVariation extends SmrtObject {
692
- /**
693
- * Tenant ID for multi-tenancy support
694
- */
695
- tenantId: string | null;
696
- /**
697
- * Ad group ID (FK to AdGroup)
698
- */
699
- groupId: string;
700
- /**
701
- * Ad format ID (FK to AdFormat)
702
- */
703
- formatId: string;
704
- /**
705
- * Asset ID (FK to smrt-assets Asset, cross-package)
706
- */
707
- assetId: string;
708
- /**
709
- * Display name (e.g., "Version A - Blue CTA")
710
- */
711
- name: string;
712
- /**
713
- * Click destination URL
714
- */
715
- clickUrl: string;
716
- /**
717
- * Accessibility alt text
718
- */
719
- altText: string;
720
- /**
721
- * A/B testing weight (higher = more likely to be selected)
722
- */
723
- weight: number;
724
- /**
725
- * Current status
726
- */
727
- status: AdVariationStatus;
728
- /**
729
- * Denormalized impression count (updated async)
730
- */
731
- impressions: number;
732
- /**
733
- * Denormalized click count (updated async)
734
- */
735
- clicks: number;
736
- constructor(options?: AdVariationOptions);
737
- /**
738
- * Check if variation is active
739
- */
740
- isActive(): boolean;
741
- /**
742
- * Check if variation is in draft state
743
- */
744
- isDraft(): boolean;
745
- /**
746
- * Check if variation is paused
747
- */
748
- isPaused(): boolean;
749
- /**
750
- * Calculate click-through rate (CTR)
751
- */
752
- getCTR(): number;
753
- /**
754
- * Increment impression count
755
- */
756
- recordImpression(): void;
757
- /**
758
- * Increment click count
759
- */
760
- recordClick(): void;
761
- }
762
-
763
- export declare class AdVariationCollection extends SmrtCollection<AdVariation> {
764
- static readonly _itemClass: typeof AdVariation;
765
- /**
766
- * Find variations by ad group
767
- *
768
- * @param groupId - Ad group ID
769
- * @returns Array of variations
770
- */
771
- findByGroup(groupId: string): Promise<AdVariation[]>;
772
- /**
773
- * Find variations by format
774
- *
775
- * @param formatId - Ad format ID
776
- * @returns Array of variations
777
- */
778
- findByFormat(formatId: string): Promise<AdVariation[]>;
779
- /**
780
- * Find active variations for a group
781
- *
782
- * @param groupId - Ad group ID
783
- * @returns Array of active variations
784
- */
785
- findActiveByGroup(groupId: string): Promise<AdVariation[]>;
786
- /**
787
- * Select a variation using weighted random selection
788
- * Higher weight = more likely to be selected
789
- *
790
- * @param groupId - Ad group ID
791
- * @returns Selected variation or null if none available
792
- */
793
- selectByWeight(groupId: string): Promise<AdVariation | null>;
794
- /**
795
- * Find variations by status
796
- *
797
- * @param status - Variation status
798
- * @returns Array of variations
799
- */
800
- findByStatus(status: AdVariationStatus): Promise<AdVariation[]>;
801
- /**
802
- * Find all active variations
803
- */
804
- findActive(): Promise<AdVariation[]>;
805
- /**
806
- * Find all draft variations
807
- */
808
- findDrafts(): Promise<AdVariation[]>;
809
- /**
810
- * Find all paused variations
811
- */
812
- findPaused(): Promise<AdVariation[]>;
813
- /**
814
- * Find top performing variations by CTR
815
- *
816
- * @param limit - Maximum number to return
817
- * @returns Array of variations sorted by CTR descending
818
- */
819
- findTopPerformers(limit?: number): Promise<AdVariation[]>;
820
- /**
821
- * Find ad variations belonging to a specific tenant
822
- *
823
- * @param tenantId - Tenant ID to filter by
824
- * @returns Array of ad variations for the tenant
825
- */
826
- findByTenant(tenantId: string): Promise<AdVariation[]>;
827
- /**
828
- * Find global ad variations (no tenant association).
829
- *
830
- * Routes through the shared tenant-global helper so it does not throw under
831
- * an active tenant context (an explicit `tenant_id IS NULL` filter would be
832
- * flagged as an isolation violation). (#1600)
833
- *
834
- * @returns Array of global ad variations
835
- */
836
- findGlobal(): Promise<AdVariation[]>;
837
- /**
838
- * Find ad variations for a tenant including global (shared) variations.
839
- *
840
- * Fails closed if an active tenant context requests a different tenant's
841
- * rows; the admin/system path keeps the cross-tenant capability. (#1600)
842
- *
843
- * @param tenantId - Tenant ID to include
844
- * @returns Array of tenant-specific and global ad variations
845
- */
846
- findWithGlobals(tenantId: string): Promise<AdVariation[]>;
847
- }
848
-
849
- /**
850
- * Options for constructing an {@link AdVariation}.
851
- */
852
- declare interface AdVariationOptions extends SmrtObjectOptions {
853
- tenantId?: string | null;
854
- groupId?: string;
855
- formatId?: string;
856
- assetId?: string;
857
- name?: string;
858
- clickUrl?: string;
859
- altText?: string;
860
- weight?: number;
861
- status?: AdVariationStatus;
862
- impressions?: number;
863
- clicks?: number;
864
- }
865
-
866
- /**
867
- * Status for ad variations
868
- */
869
- export declare enum AdVariationStatus {
870
- DRAFT = "draft",
871
- ACTIVE = "active",
872
- PAUSED = "paused"
873
- }
874
-
875
- /**
876
- * Pricing models for ad delivery tiers
877
- */
878
- export declare enum PricingModel {
879
- FIXED = "fixed",
880
- CPM = "cpm",
881
- CPC = "cpc",
882
- CPA = "cpa"
883
- }
884
-
885
- export { }
1
+ /**
2
+ * @happyvertical/smrt-ads
3
+ *
4
+ * Advertising delivery and tracking models for SMRT framework.
5
+ *
6
+ * @packageDocumentation
7
+ */
8
+ import './__smrt-register__.js';
9
+ export { AdDeliveryTierCollection, AdEventCollection, AdFormatCollection, AdGroupCollection, AdVariationCollection, } from './collections/index.js';
10
+ export { AdDeliveryTier, AdEvent, AdFormat, AdGroup, AdVariation, } from './models/index.js';
11
+ export { AdEventType, AdFormatType, AdGroupStatus, AdVariationStatus, PricingModel, } from './types/index.js';
12
+ //# sourceMappingURL=index.d.ts.map