@happyvertical/smrt-ads 0.51.32 → 0.51.34

package/dist/models/AdGroup.d.ts

@@ -0,0 +1,153 @@
+/**
+ * AdGroup model - Campaign targeting and creative organization
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { AdGroupStatus } from '../types/index.js';
+/**
+ * Options for constructing an {@link AdGroup}.
+ */
+export interface AdGroupOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    contractId?: string;
+    tierId?: string;
+    name?: string;
+    verticalSlug?: string;
+    targeting?: string;
+    zoneIds?: string;
+    startDate?: Date | null;
+    endDate?: Date | null;
+    dailyBudget?: number;
+    totalBudget?: number;
+    status?: AdGroupStatus;
+}
+/**
+ * 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?: AdGroupOptions);
+    /**
+     * 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, unknown>;
+    /**
+     * Set targeting rules from object
+     */
+    setTargeting(rules: Record<string, unknown>): 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 default AdGroup;
+//# sourceMappingURL=AdGroup.d.ts.map

package/dist/models/AdGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdGroup.d.ts","sourceRoot":"","sources":["../../src/models/AdGroup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAOa,OAAQ,SAAQ,UAAU;IACrC;;OAEG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,UAAU,EAAE,MAAM,CAAM;IAExB;;OAEG;IAEH,MAAM,EAAE,MAAM,CAAM;IAEpB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAM;IAElB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAM;IAE1B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAM;IAEvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IACH,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B;;OAEG;IACH,OAAO,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE5B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAO;IAE1B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAO;IAE1B;;OAEG;IACH,MAAM,EAAE,aAAa,CAAuB;gBAEhC,OAAO,GAAE,cAAmB;IAmBxC;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAStB;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAI/B;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ/B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlC;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IASvC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIlD;;OAEG;IACH,QAAQ,IAAI,OAAO;IAQnB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAKnB;;OAEG;IACH,UAAU,IAAI,OAAO;CAItB;AAED,eAAe,OAAO,CAAC"}

package/dist/models/AdVariation.d.ts

@@ -0,0 +1,117 @@
+/**
+ * AdVariation model - Creative asset with A/B testing support
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { AdVariationStatus } from '../types/index.js';
+/**
+ * Options for constructing an {@link AdVariation}.
+ */
+export interface AdVariationOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    groupId?: string;
+    formatId?: string;
+    assetId?: string;
+    name?: string;
+    clickUrl?: string;
+    altText?: string;
+    weight?: number;
+    status?: AdVariationStatus;
+    impressions?: number;
+    clicks?: number;
+}
+/**
+ * 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?: AdVariationOptions);
+    /**
+     * 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 default AdVariation;
+//# sourceMappingURL=AdVariation.d.ts.map

package/dist/models/AdVariation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdVariation.d.ts","sourceRoot":"","sources":["../../src/models/AdVariation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAOa,WAAY,SAAQ,UAAU;IACzC;;OAEG;IAEH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;OAEG;IAEH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IAEH,QAAQ,EAAE,MAAM,CAAM;IAEtB;;OAEG;IAEH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAM;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAM;IAEtB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAM;IAErB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAK;IAEnB;;OAEG;IACH,MAAM,EAAE,iBAAiB,CAA2B;IAEpD;;OAEG;IACH,WAAW,EAAE,MAAM,CAAK;IAExB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAK;gBAEP,OAAO,GAAE,kBAAuB;IAgB5C;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,MAAM,IAAI,MAAM;IAKhB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAIxB;;OAEG;IACH,WAAW,IAAI,IAAI;CAGpB;AAED,eAAe,WAAW,CAAC"}

package/dist/models/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Model exports for smrt-ads
+ * @packageDocumentation
+ */
+export { AdDeliveryTier } from './AdDeliveryTier.js';
+export { AdEvent } from './AdEvent.js';
+export { AdFormat } from './AdFormat.js';
+export { AdGroup } from './AdGroup.js';
+export { AdVariation } from './AdVariation.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-ads",
-  "packageVersion": "0.51.32",
+  "packageVersion": "0.51.34",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "6df4ec28375eb736f2793c487f06a5e4fdd6f4af53ed4797af0a3d10bf47bcf8",
-    "packageJson": "649054387e1ee455b0eb56bd251cddbadeaf998c8617a148fe1b6ae0bfae1826",
+    "manifest": "b4eff248c2f9a12b34197e3cfc0d1c251d900842cefeefbf124764921027715a",
+    "packageJson": "f10ecd629e4229ef4890f3e3d8b44af026214bd39ab89a956ef278c273cbf035",
     "agents": "38d00ca384af711a76359907e4d9806733168d7b4b31f7610cd0c418fc72d566"
   },
   "exports": [
@@ -24,7 +24,7 @@
     "@happyvertical/sql": "catalog:",
     "@types/node": "24.13.6",
     "fast-glob": "3.3.3",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },

package/dist/types/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Types and enums for smrt-ads package
+ */
+/**
+ * Ad format types for different creative types
+ */
+export declare enum AdFormatType {
+    BANNER = "banner",
+    NATIVE = "native",
+    VIDEO = "video"
+}
+/**
+ * Pricing models for ad delivery tiers
+ */
+export declare enum PricingModel {
+    FIXED = "fixed",
+    CPM = "cpm",
+    CPC = "cpc",
+    CPA = "cpa"
+}
+/**
+ * Status for ad groups
+ */
+export declare enum AdGroupStatus {
+    DRAFT = "draft",
+    ACTIVE = "active",
+    PAUSED = "paused",
+    COMPLETED = "completed"
+}
+/**
+ * Status for ad variations
+ */
+export declare enum AdVariationStatus {
+    DRAFT = "draft",
+    ACTIVE = "active",
+    PAUSED = "paused"
+}
+/**
+ * Event types for ad tracking
+ */
+export declare enum AdEventType {
+    IMPRESSION = "impression",
+    CLICK = "click",
+    CONVERSION = "conversion"
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,KAAK,UAAU;IACf,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,GAAG,QAAQ;CACZ;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,oBAAY,WAAW;IACrB,UAAU,eAAe;IACzB,KAAK,UAAU;IACf,UAAU,eAAe;CAC1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-ads",
-  "version": "0.51.32",
+  "version": "0.51.34",
   "description": "Advertising delivery and tracking models for SMRT framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,16 +19,16 @@
     "./manifest.json": "./dist/manifest.json"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.51.32",
-    "@happyvertical/smrt-tenancy": "0.51.32"
+    "@happyvertical/smrt-core": "0.51.34",
+    "@happyvertical/smrt-tenancy": "0.51.34"
   },
   "devDependencies": {
-    "@happyvertical/smrt-commerce": "0.51.32",
-    "@happyvertical/smrt-vitest": "0.51.32",
+    "@happyvertical/smrt-commerce": "0.51.34",
+    "@happyvertical/smrt-vitest": "0.51.34",
     "@happyvertical/sql": "^0.94.1",
     "@types/node": "24.13.6",
     "fast-glob": "3.3.3",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },