@happyvertical/smrt-ads 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,794 @@
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+
+/**
+ * AdDeliveryTier defines priority levels for ad serving.
+ *
+ * Ads are selected by priority (lower = higher priority):
+ * 1. Sponsorship - Guaranteed, premium placements
+ * 2. Standard - Regular programmatic ads
+ * 3. House - Self-promotional/fallback ads
+ *
+ * @example
+ * ```typescript
+ * const sponsorship = await tiers.create({
+ *   name: 'Sponsorship',
+ *   priority: 1,
+ *   pricingModel: PricingModel.FIXED,
+ *   description: 'Premium guaranteed placements'
+ * });
+ * ```
+ */
+export declare class AdDeliveryTier extends SmrtObject {
+    /**
+     * Display name (e.g., "Sponsorship", "Standard", "House")
+     */
+    name: string;
+    /**
+     * Priority level (lower = higher priority: 1, 2, 3...)
+     */
+    priority: number;
+    /**
+     * Pricing model for this tier
+     */
+    pricingModel: PricingModel;
+    /**
+     * Optional description
+     */
+    description: string;
+    constructor(options?: any);
+    /**
+     * Check if this tier is higher priority than another
+     */
+    isHigherPriorityThan(other: AdDeliveryTier): boolean;
+    /**
+     * Check if this is a fixed pricing tier
+     */
+    isFixedPricing(): boolean;
+    /**
+     * Check if this is a performance-based tier (CPC, CPA)
+     */
+    isPerformanceBased(): boolean;
+}
+
+export declare class AdDeliveryTierCollection extends SmrtCollection<AdDeliveryTier> {
+    static readonly _itemClass: typeof AdDeliveryTier;
+    /**
+     * Find tiers ordered by priority (ascending, lower = higher priority)
+     *
+     * @returns Array of tiers ordered by priority
+     */
+    findByPriority(): Promise<AdDeliveryTier[]>;
+    /**
+     * Find tiers by pricing model
+     *
+     * @param pricingModel - Pricing model to filter by
+     * @returns Array of matching tiers
+     */
+    findByPricingModel(pricingModel: PricingModel): Promise<AdDeliveryTier[]>;
+    /**
+     * Get the highest priority tier
+     *
+     * @returns Highest priority tier or null
+     */
+    getHighestPriority(): Promise<AdDeliveryTier | null>;
+    /**
+     * Find fixed pricing tiers
+     */
+    findFixedPricing(): Promise<AdDeliveryTier[]>;
+    /**
+     * Find CPM-based tiers
+     */
+    findCPM(): Promise<AdDeliveryTier[]>;
+    /**
+     * Find performance-based tiers (CPC, CPA)
+     */
+    findPerformanceBased(): Promise<AdDeliveryTier[]>;
+}
+
+/**
+ * AdEvent tracks ad impressions, clicks, and conversions.
+ * Events are immutable (append-only, no update/delete).
+ *
+ * References:
+ * - variationId: FK to AdVariation (within package)
+ * - zoneId: String reference to smrt-properties Zone (cross-package)
+ * - siteId: Denormalized for query efficiency (cross-package)
+ *
+ * @example
+ * ```typescript
+ * // Track an impression
+ * const impression = await events.create({
+ *   variationId: variation.id,
+ *   zoneId: 'zone-uuid',
+ *   siteId: 'site-uuid',
+ *   eventType: AdEventType.IMPRESSION,
+ *   metadata: JSON.stringify({
+ *     ip: '192.168.1.1',
+ *     userAgent: 'Mozilla/5.0...',
+ *     referrer: 'https://example.com'
+ *   })
+ * });
+ *
+ * // Track a click
+ * const click = await events.create({
+ *   variationId: variation.id,
+ *   zoneId: 'zone-uuid',
+ *   siteId: 'site-uuid',
+ *   eventType: AdEventType.CLICK
+ * });
+ * ```
+ */
+export declare class AdEvent extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenancy support
+     */
+    tenantId: string | null;
+    /**
+     * Variation ID (FK to AdVariation)
+     */
+    variationId: string;
+    /**
+     * Zone ID (FK to smrt-properties Zone, cross-package)
+     */
+    zoneId: string;
+    /**
+     * Site ID (denormalized from Zone for query efficiency)
+     */
+    siteId: string;
+    /**
+     * Event type (impression, click, conversion)
+     */
+    eventType: AdEventType;
+    /**
+     * Event timestamp
+     */
+    timestamp: Date;
+    /**
+     * Analytics metadata as JSON string
+     * (IP, user agent, referrer, etc.)
+     */
+    metadata: string;
+    constructor(options?: any);
+    /**
+     * Get metadata as object
+     */
+    getMetadata(): Record<string, any>;
+    /**
+     * Set metadata from object
+     */
+    setMetadata(data: Record<string, any>): void;
+    /**
+     * Check if this is an impression event
+     */
+    isImpression(): boolean;
+    /**
+     * Check if this is a click event
+     */
+    isClick(): boolean;
+    /**
+     * Check if this is a conversion event
+     */
+    isConversion(): boolean;
+}
+
+export declare class AdEventCollection extends SmrtCollection<AdEvent> {
+    static readonly _itemClass: typeof AdEvent;
+    /**
+     * Find events by variation
+     *
+     * @param variationId - Variation ID
+     * @returns Array of events
+     */
+    findByVariation(variationId: string): Promise<AdEvent[]>;
+    /**
+     * Find events by zone
+     *
+     * @param zoneId - Zone ID
+     * @returns Array of events
+     */
+    findByZone(zoneId: string): Promise<AdEvent[]>;
+    /**
+     * Find events by site
+     *
+     * @param siteId - Site ID
+     * @returns Array of events
+     */
+    findBySite(siteId: string): Promise<AdEvent[]>;
+    /**
+     * Find events in date range
+     *
+     * @param start - Start date
+     * @param end - End date
+     * @returns Array of events
+     */
+    findByDateRange(start: Date, end: Date): Promise<AdEvent[]>;
+    /**
+     * Find events by type
+     *
+     * @param eventType - Event type
+     * @returns Array of events
+     */
+    findByType(eventType: AdEventType): Promise<AdEvent[]>;
+    /**
+     * Count events by type for a variation
+     *
+     * @param variationId - Variation ID
+     * @param eventType - Event type
+     * @returns Count of events
+     */
+    countByType(variationId: string, eventType: AdEventType): Promise<number>;
+    /**
+     * Count impressions for a variation
+     */
+    countImpressions(variationId: string): Promise<number>;
+    /**
+     * Count clicks for a variation
+     */
+    countClicks(variationId: string): Promise<number>;
+    /**
+     * Count conversions for a variation
+     */
+    countConversions(variationId: string): Promise<number>;
+    /**
+     * Find all impressions
+     */
+    findImpressions(): Promise<AdEvent[]>;
+    /**
+     * Find all clicks
+     */
+    findClicks(): Promise<AdEvent[]>;
+    /**
+     * Find all conversions
+     */
+    findConversions(): Promise<AdEvent[]>;
+    /**
+     * Get aggregate stats for a variation
+     *
+     * @param variationId - Variation ID
+     * @returns Stats object with impressions, clicks, conversions, CTR
+     */
+    getVariationStats(variationId: string): Promise<{
+        impressions: number;
+        clicks: number;
+        conversions: number;
+        ctr: number;
+        conversionRate: number;
+    }>;
+    /**
+     * Find ad events belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of ad events for the tenant
+     */
+    findByTenant(tenantId: string): Promise<AdEvent[]>;
+    /**
+     * Find global ad events (no tenant association)
+     *
+     * @returns Array of global ad events
+     */
+    findGlobal(): Promise<AdEvent[]>;
+    /**
+     * Find ad events for a tenant including global (shared) events
+     *
+     * @param tenantId - Tenant ID to include
+     * @returns Array of tenant-specific and global ad events
+     */
+    findWithGlobals(tenantId: string): Promise<AdEvent[]>;
+}
+
+/**
+ * Event types for ad tracking
+ */
+export declare enum AdEventType {
+    IMPRESSION = "impression",
+    CLICK = "click",
+    CONVERSION = "conversion"
+}
+
+/**
+ * AdFormat defines standard ad dimensions and types (IAB standards).
+ *
+ * @example
+ * ```typescript
+ * const leaderboard = await formats.create({
+ *   name: 'Leaderboard',
+ *   width: 728,
+ *   height: 90,
+ *   formatType: AdFormatType.BANNER
+ * });
+ * ```
+ */
+export declare class AdFormat extends SmrtObject {
+    /**
+     * Display name (e.g., "Leaderboard", "Medium Rectangle")
+     */
+    name: string;
+    /**
+     * Width in pixels
+     */
+    width: number;
+    /**
+     * Height in pixels
+     */
+    height: number;
+    /**
+     * Format type (banner, native, video)
+     */
+    formatType: AdFormatType;
+    /**
+     * Optional description
+     */
+    description: string;
+    constructor(options?: any);
+    /**
+     * Get dimensions as string (e.g., "728x90")
+     */
+    getDimensions(): string;
+    /**
+     * Check if format matches specific dimensions
+     */
+    matchesDimensions(width: number, height: number): boolean;
+}
+
+export declare class AdFormatCollection extends SmrtCollection<AdFormat> {
+    static readonly _itemClass: typeof AdFormat;
+    /**
+     * Find format by dimensions
+     *
+     * @param width - Width in pixels
+     * @param height - Height in pixels
+     * @returns Matching format or null
+     */
+    findByDimensions(width: number, height: number): Promise<AdFormat | null>;
+    /**
+     * Find formats by type
+     *
+     * @param formatType - Format type (banner, native, video)
+     * @returns Array of matching formats
+     */
+    findByType(formatType: AdFormatType): Promise<AdFormat[]>;
+    /**
+     * Find all banner formats
+     */
+    findBanners(): Promise<AdFormat[]>;
+    /**
+     * Find all native formats
+     */
+    findNative(): Promise<AdFormat[]>;
+    /**
+     * Find all video formats
+     */
+    findVideo(): Promise<AdFormat[]>;
+}
+
+/**
+ * Types and enums for smrt-ads package
+ */
+/**
+ * Ad format types for different creative types
+ */
+export declare enum AdFormatType {
+    BANNER = "banner",
+    NATIVE = "native",
+    VIDEO = "video"
+}
+
+/**
+ * AdGroup organizes ad creatives with targeting and budget controls.
+ *
+ * References:
+ * - tierId: FK to AdDeliveryTier (within package)
+ * - contractId: String reference to smrt-commerce Contract (cross-package)
+ * - zoneIds: JSON array of allowed smrt-properties Zone IDs (cross-package)
+ * - verticalSlug: Tag slug from smrt-tags (cross-package)
+ *
+ * @example
+ * ```typescript
+ * const adGroup = await groups.create({
+ *   contractId: 'contract-uuid',
+ *   tierId: tier.id,
+ *   name: 'Summer Sale - Desktop',
+ *   verticalSlug: 'retail',
+ *   targeting: JSON.stringify({ device: 'desktop' }),
+ *   zoneIds: JSON.stringify(['zone-1', 'zone-2']),
+ *   dailyBudget: 100.00,
+ *   totalBudget: 3000.00,
+ *   startDate: new Date('2024-06-01'),
+ *   endDate: new Date('2024-08-31')
+ * });
+ * ```
+ */
+export declare class AdGroup extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenancy support
+     */
+    tenantId: string | null;
+    /**
+     * Contract ID (FK to smrt-commerce Contract, cross-package)
+     */
+    contractId: string;
+    /**
+     * Delivery tier ID (FK to AdDeliveryTier)
+     */
+    tierId: string;
+    /**
+     * Display name (e.g., "Summer Sale - Desktop")
+     */
+    name: string;
+    /**
+     * Vertical/category tag slug from smrt-tags (context="advertising")
+     */
+    verticalSlug: string;
+    /**
+     * Targeting rules as JSON string
+     */
+    targeting: string;
+    /**
+     * Allowed Zone IDs as JSON array string (FK to smrt-properties Zone)
+     */
+    zoneIds: string;
+    /**
+     * Campaign start date
+     */
+    startDate: Date | null;
+    /**
+     * Campaign end date
+     */
+    endDate: Date | null;
+    /**
+     * Daily budget limit
+     */
+    dailyBudget: number;
+    /**
+     * Total campaign budget
+     */
+    totalBudget: number;
+    /**
+     * Current status
+     */
+    status: AdGroupStatus;
+    constructor(options?: any);
+    /**
+     * Get zone IDs as array
+     */
+    getZoneIds(): string[];
+    /**
+     * Set zone IDs from array
+     */
+    setZoneIds(ids: string[]): void;
+    /**
+     * Add a zone ID
+     */
+    addZoneId(zoneId: string): void;
+    /**
+     * Remove a zone ID
+     */
+    removeZoneId(zoneId: string): void;
+    /**
+     * Check if zone ID is allowed
+     */
+    hasZoneId(zoneId: string): boolean;
+    /**
+     * Get targeting rules as object
+     */
+    getTargeting(): Record<string, any>;
+    /**
+     * Set targeting rules from object
+     */
+    setTargeting(rules: Record<string, any>): void;
+    /**
+     * Check if ad group is currently active
+     */
+    isActive(): boolean;
+    /**
+     * Check if ad group is in draft state
+     */
+    isDraft(): boolean;
+    /**
+     * Check if ad group is paused
+     */
+    isPaused(): boolean;
+    /**
+     * Check if ad group is completed
+     */
+    isCompleted(): boolean;
+    /**
+     * Check if ad group has ended (past end date)
+     */
+    hasEnded(): boolean;
+    /**
+     * Check if ad group has started
+     */
+    hasStarted(): boolean;
+}
+
+export declare class AdGroupCollection extends SmrtCollection<AdGroup> {
+    static readonly _itemClass: typeof AdGroup;
+    /**
+     * Find ad groups by contract
+     *
+     * @param contractId - Contract ID
+     * @returns Array of ad groups
+     */
+    findByContract(contractId: string): Promise<AdGroup[]>;
+    /**
+     * Find ad groups by tier
+     *
+     * @param tierId - Delivery tier ID
+     * @returns Array of ad groups
+     */
+    findByTier(tierId: string): Promise<AdGroup[]>;
+    /**
+     * Find ad groups by status
+     *
+     * @param status - Ad group status
+     * @returns Array of ad groups
+     */
+    findByStatus(status: AdGroupStatus): Promise<AdGroup[]>;
+    /**
+     * Find currently active ad groups
+     * (status=active, started, not ended)
+     *
+     * @returns Array of active ad groups
+     */
+    findActive(): Promise<AdGroup[]>;
+    /**
+     * Find ad groups by vertical slug
+     *
+     * @param verticalSlug - Tag slug from smrt-tags
+     * @returns Array of ad groups
+     */
+    findByVertical(verticalSlug: string): Promise<AdGroup[]>;
+    /**
+     * Find ad groups that can serve to a specific zone
+     *
+     * @param zoneId - Zone ID to check
+     * @returns Array of ad groups containing zone
+     */
+    findByZone(zoneId: string): Promise<AdGroup[]>;
+    /**
+     * Find ad groups eligible to serve for a zone
+     * (active, has zone, within date range)
+     *
+     * @param zoneId - Zone ID to check
+     * @returns Array of eligible ad groups
+     */
+    findEligibleForZone(zoneId: string): Promise<AdGroup[]>;
+    /**
+     * Find all draft ad groups
+     */
+    findDrafts(): Promise<AdGroup[]>;
+    /**
+     * Find all paused ad groups
+     */
+    findPaused(): Promise<AdGroup[]>;
+    /**
+     * Find all completed ad groups
+     */
+    findCompleted(): Promise<AdGroup[]>;
+    /**
+     * Find ad groups belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of ad groups for the tenant
+     */
+    findByTenant(tenantId: string): Promise<AdGroup[]>;
+    /**
+     * Find global ad groups (no tenant association)
+     *
+     * @returns Array of global ad groups
+     */
+    findGlobal(): Promise<AdGroup[]>;
+    /**
+     * Find ad groups for a tenant including global (shared) ad groups
+     *
+     * @param tenantId - Tenant ID to include
+     * @returns Array of tenant-specific and global ad groups
+     */
+    findWithGlobals(tenantId: string): Promise<AdGroup[]>;
+}
+
+/**
+ * Status for ad groups
+ */
+export declare enum AdGroupStatus {
+    DRAFT = "draft",
+    ACTIVE = "active",
+    PAUSED = "paused",
+    COMPLETED = "completed"
+}
+
+/**
+ * AdVariation represents a creative asset within an ad group.
+ * Supports A/B testing via weighted selection.
+ *
+ * References:
+ * - groupId: FK to AdGroup (within package)
+ * - formatId: FK to AdFormat (within package)
+ * - assetId: String reference to smrt-assets Asset (cross-package)
+ *
+ * @example
+ * ```typescript
+ * const variation = await variations.create({
+ *   groupId: adGroup.id,
+ *   formatId: leaderboard.id,
+ *   assetId: 'asset-uuid',
+ *   name: 'Version A - Blue CTA',
+ *   clickUrl: 'https://example.com/landing',
+ *   altText: 'Summer Sale - 50% off',
+ *   weight: 2  // 2x more likely than weight=1
+ * });
+ * ```
+ */
+export declare class AdVariation extends SmrtObject {
+    /**
+     * Tenant ID for multi-tenancy support
+     */
+    tenantId: string | null;
+    /**
+     * Ad group ID (FK to AdGroup)
+     */
+    groupId: string;
+    /**
+     * Ad format ID (FK to AdFormat)
+     */
+    formatId: string;
+    /**
+     * Asset ID (FK to smrt-assets Asset, cross-package)
+     */
+    assetId: string;
+    /**
+     * Display name (e.g., "Version A - Blue CTA")
+     */
+    name: string;
+    /**
+     * Click destination URL
+     */
+    clickUrl: string;
+    /**
+     * Accessibility alt text
+     */
+    altText: string;
+    /**
+     * A/B testing weight (higher = more likely to be selected)
+     */
+    weight: number;
+    /**
+     * Current status
+     */
+    status: AdVariationStatus;
+    /**
+     * Denormalized impression count (updated async)
+     */
+    impressions: number;
+    /**
+     * Denormalized click count (updated async)
+     */
+    clicks: number;
+    constructor(options?: any);
+    /**
+     * Check if variation is active
+     */
+    isActive(): boolean;
+    /**
+     * Check if variation is in draft state
+     */
+    isDraft(): boolean;
+    /**
+     * Check if variation is paused
+     */
+    isPaused(): boolean;
+    /**
+     * Calculate click-through rate (CTR)
+     */
+    getCTR(): number;
+    /**
+     * Increment impression count
+     */
+    recordImpression(): void;
+    /**
+     * Increment click count
+     */
+    recordClick(): void;
+}
+
+export declare class AdVariationCollection extends SmrtCollection<AdVariation> {
+    static readonly _itemClass: typeof AdVariation;
+    /**
+     * Find variations by ad group
+     *
+     * @param groupId - Ad group ID
+     * @returns Array of variations
+     */
+    findByGroup(groupId: string): Promise<AdVariation[]>;
+    /**
+     * Find variations by format
+     *
+     * @param formatId - Ad format ID
+     * @returns Array of variations
+     */
+    findByFormat(formatId: string): Promise<AdVariation[]>;
+    /**
+     * Find active variations for a group
+     *
+     * @param groupId - Ad group ID
+     * @returns Array of active variations
+     */
+    findActiveByGroup(groupId: string): Promise<AdVariation[]>;
+    /**
+     * Select a variation using weighted random selection
+     * Higher weight = more likely to be selected
+     *
+     * @param groupId - Ad group ID
+     * @returns Selected variation or null if none available
+     */
+    selectByWeight(groupId: string): Promise<AdVariation | null>;
+    /**
+     * Find variations by status
+     *
+     * @param status - Variation status
+     * @returns Array of variations
+     */
+    findByStatus(status: AdVariationStatus): Promise<AdVariation[]>;
+    /**
+     * Find all active variations
+     */
+    findActive(): Promise<AdVariation[]>;
+    /**
+     * Find all draft variations
+     */
+    findDrafts(): Promise<AdVariation[]>;
+    /**
+     * Find all paused variations
+     */
+    findPaused(): Promise<AdVariation[]>;
+    /**
+     * Find top performing variations by CTR
+     *
+     * @param limit - Maximum number to return
+     * @returns Array of variations sorted by CTR descending
+     */
+    findTopPerformers(limit?: number): Promise<AdVariation[]>;
+    /**
+     * Find ad variations belonging to a specific tenant
+     *
+     * @param tenantId - Tenant ID to filter by
+     * @returns Array of ad variations for the tenant
+     */
+    findByTenant(tenantId: string): Promise<AdVariation[]>;
+    /**
+     * Find global ad variations (no tenant association)
+     *
+     * @returns Array of global ad variations
+     */
+    findGlobal(): Promise<AdVariation[]>;
+    /**
+     * Find ad variations for a tenant including global (shared) variations
+     *
+     * @param tenantId - Tenant ID to include
+     * @returns Array of tenant-specific and global ad variations
+     */
+    findWithGlobals(tenantId: string): Promise<AdVariation[]>;
+}
+
+/**
+ * Status for ad variations
+ */
+export declare enum AdVariationStatus {
+    DRAFT = "draft",
+    ACTIVE = "active",
+    PAUSED = "paused"
+}
+
+/**
+ * Pricing models for ad delivery tiers
+ */
+export declare enum PricingModel {
+    FIXED = "fixed",
+    CPM = "cpm",
+    CPC = "cpc",
+    CPA = "cpa"
+}
+
+export { }