digital-tools 2.0.1

package/dist/entities/marketing.js

@@ -0,0 +1,1611 @@
+/**
+ * Marketing Entity Types (Nouns)
+ *
+ * Semantic type definitions for marketing digital tools that can be used by
+ * both remote human workers AND AI agents. Each entity defines:
+ * - Properties: The data fields
+ * - Actions: Operations that can be performed (Verbs)
+ * - Events: State changes that occur
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Campaign
+// =============================================================================
+/**
+ * Marketing campaign entity
+ *
+ * Represents a marketing campaign with goals, budget, and tracking
+ */
+export const Campaign = {
+    singular: 'campaign',
+    plural: 'campaigns',
+    description: 'A marketing campaign with goals, budget, and performance tracking',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Campaign name',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Campaign description and goals',
+        },
+        // Type & Classification
+        type: {
+            type: 'string',
+            description: 'Campaign type: email, social, paid-ads, content, event, webinar, seo',
+            examples: ['email', 'social', 'paid-ads', 'content', 'event', 'webinar', 'seo'],
+        },
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'Campaign category for organization',
+        },
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for categorization and filtering',
+        },
+        // Status & Timing
+        status: {
+            type: 'string',
+            description: 'Campaign status: draft, scheduled, active, paused, completed, archived',
+            examples: ['draft', 'scheduled', 'active', 'paused', 'completed', 'archived'],
+        },
+        startDate: {
+            type: 'datetime',
+            optional: true,
+            description: 'Campaign start date',
+        },
+        endDate: {
+            type: 'datetime',
+            optional: true,
+            description: 'Campaign end date',
+        },
+        // Budget & Finance
+        budget: {
+            type: 'number',
+            optional: true,
+            description: 'Total campaign budget',
+        },
+        spent: {
+            type: 'number',
+            optional: true,
+            description: 'Amount spent so far',
+        },
+        currency: {
+            type: 'string',
+            optional: true,
+            description: 'Currency code (USD, EUR, etc.)',
+            examples: ['USD', 'EUR', 'GBP'],
+        },
+        // Goals & KPIs
+        goal: {
+            type: 'string',
+            optional: true,
+            description: 'Campaign goal: awareness, leads, sales, engagement, traffic',
+            examples: ['awareness', 'leads', 'sales', 'engagement', 'traffic'],
+        },
+        targetImpressions: {
+            type: 'number',
+            optional: true,
+            description: 'Target number of impressions',
+        },
+        targetClicks: {
+            type: 'number',
+            optional: true,
+            description: 'Target number of clicks',
+        },
+        targetConversions: {
+            type: 'number',
+            optional: true,
+            description: 'Target number of conversions',
+        },
+        targetRevenue: {
+            type: 'number',
+            optional: true,
+            description: 'Target revenue amount',
+        },
+        // Performance Metrics
+        impressions: {
+            type: 'number',
+            optional: true,
+            description: 'Total impressions delivered',
+        },
+        clicks: {
+            type: 'number',
+            optional: true,
+            description: 'Total clicks received',
+        },
+        conversions: {
+            type: 'number',
+            optional: true,
+            description: 'Total conversions',
+        },
+        revenue: {
+            type: 'number',
+            optional: true,
+            description: 'Total revenue generated',
+        },
+        ctr: {
+            type: 'number',
+            optional: true,
+            description: 'Click-through rate (percentage)',
+        },
+        conversionRate: {
+            type: 'number',
+            optional: true,
+            description: 'Conversion rate (percentage)',
+        },
+        roi: {
+            type: 'number',
+            optional: true,
+            description: 'Return on investment (percentage)',
+        },
+    },
+    relationships: {
+        audience: {
+            type: 'Audience',
+            required: false,
+            description: 'Target audience for this campaign',
+        },
+        emailTemplates: {
+            type: 'EmailTemplate[]',
+            description: 'Email templates used in this campaign',
+        },
+        landingPages: {
+            type: 'LandingPage[]',
+            description: 'Landing pages associated with this campaign',
+        },
+        socialPosts: {
+            type: 'SocialPost[]',
+            description: 'Social media posts in this campaign',
+        },
+        adCreatives: {
+            type: 'AdCreative[]',
+            description: 'Ad creatives used in this campaign',
+        },
+        utmLinks: {
+            type: 'UTMLink[]',
+            description: 'Tracked URLs for this campaign',
+        },
+        formSubmissions: {
+            type: 'FormSubmission[]',
+            description: 'Form submissions generated by this campaign',
+        },
+        owner: {
+            type: 'Contact',
+            description: 'Campaign owner/manager',
+        },
+        team: {
+            type: 'Contact[]',
+            description: 'Team members working on this campaign',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'schedule',
+        'launch',
+        'pause',
+        'resume',
+        'complete',
+        'archive',
+        'duplicate',
+        'export',
+        'analyze',
+        'optimize',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'scheduled',
+        'launched',
+        'paused',
+        'resumed',
+        'completed',
+        'archived',
+        'duplicated',
+        'goalReached',
+        'budgetExceeded',
+    ],
+};
+// =============================================================================
+// Audience
+// =============================================================================
+/**
+ * Target audience or segment entity
+ *
+ * Represents a group of people targeted by marketing efforts
+ */
+export const Audience = {
+    singular: 'audience',
+    plural: 'audiences',
+    description: 'A target audience or customer segment for marketing',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Audience name',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Audience description',
+        },
+        // Size & Stats
+        size: {
+            type: 'number',
+            optional: true,
+            description: 'Estimated or actual audience size',
+        },
+        activeCount: {
+            type: 'number',
+            optional: true,
+            description: 'Number of active/engaged members',
+        },
+        // Segmentation Criteria
+        criteria: {
+            type: 'json',
+            optional: true,
+            description: 'Segmentation criteria (demographics, behavior, etc.)',
+        },
+        demographics: {
+            type: 'json',
+            optional: true,
+            description: 'Demographic filters (age, gender, location, etc.)',
+        },
+        interests: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Interest categories',
+        },
+        behaviors: {
+            type: 'json',
+            optional: true,
+            description: 'Behavioral targeting criteria',
+        },
+        // Geographic
+        countries: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Target countries',
+        },
+        regions: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Target regions/states',
+        },
+        cities: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Target cities',
+        },
+        languages: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Target languages',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Audience status: active, archived, building',
+            examples: ['active', 'archived', 'building'],
+        },
+        // Source & Type
+        source: {
+            type: 'string',
+            optional: true,
+            description: 'How the audience was created: manual, imported, dynamic, lookalike',
+            examples: ['manual', 'imported', 'dynamic', 'lookalike'],
+        },
+        type: {
+            type: 'string',
+            optional: true,
+            description: 'Audience type: email-list, custom, retargeting, lookalike',
+            examples: ['email-list', 'custom', 'retargeting', 'lookalike'],
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+        lastUpdated: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the audience was last updated',
+        },
+    },
+    relationships: {
+        campaigns: {
+            type: 'Campaign[]',
+            description: 'Campaigns targeting this audience',
+        },
+        contacts: {
+            type: 'Contact[]',
+            description: 'Contacts in this audience',
+        },
+        parentAudience: {
+            type: 'Audience',
+            required: false,
+            description: 'Parent audience if this is a sub-segment',
+        },
+        subAudiences: {
+            type: 'Audience[]',
+            description: 'Sub-segments of this audience',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'segment',
+        'export',
+        'import',
+        'refresh',
+        'merge',
+        'duplicate',
+        'archive',
+        'analyze',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'segmented',
+        'exported',
+        'imported',
+        'refreshed',
+        'merged',
+        'archived',
+        'sizeChanged',
+    ],
+};
+// =============================================================================
+// EmailTemplate
+// =============================================================================
+/**
+ * Email template entity
+ *
+ * Represents an email template with subject, body, and variables
+ */
+export const EmailTemplate = {
+    singular: 'email template',
+    plural: 'email templates',
+    description: 'A reusable email template for marketing campaigns',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Template name',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Template description',
+        },
+        // Email Content
+        subject: {
+            type: 'string',
+            description: 'Email subject line (may contain variables)',
+        },
+        preheader: {
+            type: 'string',
+            optional: true,
+            description: 'Email preheader/preview text',
+        },
+        body: {
+            type: 'string',
+            description: 'Plain text email body',
+        },
+        html: {
+            type: 'string',
+            optional: true,
+            description: 'HTML email body',
+        },
+        // Sender Info
+        fromName: {
+            type: 'string',
+            optional: true,
+            description: 'Sender name',
+        },
+        fromEmail: {
+            type: 'string',
+            optional: true,
+            description: 'Sender email address',
+        },
+        replyTo: {
+            type: 'string',
+            optional: true,
+            description: 'Reply-to email address',
+        },
+        // Variables & Personalization
+        variables: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Variable placeholders (e.g., {{firstName}}, {{company}})',
+        },
+        personalizationTags: {
+            type: 'json',
+            optional: true,
+            description: 'Available personalization tags and their descriptions',
+        },
+        // Design & Layout
+        category: {
+            type: 'string',
+            optional: true,
+            description: 'Template category: newsletter, promotional, transactional, welcome, abandoned-cart',
+            examples: ['newsletter', 'promotional', 'transactional', 'welcome', 'abandoned-cart'],
+        },
+        designFormat: {
+            type: 'string',
+            optional: true,
+            description: 'Design format: html, drag-drop, rich-text, plain-text',
+            examples: ['html', 'drag-drop', 'rich-text', 'plain-text'],
+        },
+        thumbnailUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Preview thumbnail URL',
+        },
+        // Status & Version
+        status: {
+            type: 'string',
+            description: 'Template status: draft, active, archived',
+            examples: ['draft', 'active', 'archived'],
+        },
+        version: {
+            type: 'number',
+            optional: true,
+            description: 'Template version number',
+        },
+        // Performance
+        timesSent: {
+            type: 'number',
+            optional: true,
+            description: 'Number of times this template has been sent',
+        },
+        avgOpenRate: {
+            type: 'number',
+            optional: true,
+            description: 'Average open rate (percentage)',
+        },
+        avgClickRate: {
+            type: 'number',
+            optional: true,
+            description: 'Average click rate (percentage)',
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+    },
+    relationships: {
+        campaign: {
+            type: 'Campaign',
+            required: false,
+            description: 'Campaign this template belongs to',
+        },
+        author: {
+            type: 'Contact',
+            description: 'Template creator',
+        },
+        utmLinks: {
+            type: 'UTMLink[]',
+            description: 'Tracked links in this template',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'duplicate',
+        'preview',
+        'test',
+        'send',
+        'schedule',
+        'archive',
+        'restore',
+        'export',
+        'import',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'duplicated',
+        'previewed',
+        'tested',
+        'sent',
+        'scheduled',
+        'archived',
+        'restored',
+    ],
+};
+// =============================================================================
+// LandingPage
+// =============================================================================
+/**
+ * Landing page entity
+ *
+ * Represents a marketing landing page with form and conversion tracking
+ */
+export const LandingPage = {
+    singular: 'landing page',
+    plural: 'landing pages',
+    description: 'A marketing landing page designed for conversion',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Landing page name',
+        },
+        title: {
+            type: 'string',
+            description: 'Page title (HTML title tag)',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Page description (meta description)',
+        },
+        // URL & Slug
+        url: {
+            type: 'url',
+            description: 'Full landing page URL',
+        },
+        slug: {
+            type: 'string',
+            optional: true,
+            description: 'URL slug',
+        },
+        domain: {
+            type: 'string',
+            optional: true,
+            description: 'Custom domain if applicable',
+        },
+        // Content
+        headline: {
+            type: 'string',
+            optional: true,
+            description: 'Main headline',
+        },
+        subheadline: {
+            type: 'string',
+            optional: true,
+            description: 'Subheadline',
+        },
+        body: {
+            type: 'markdown',
+            optional: true,
+            description: 'Page body content',
+        },
+        // Design
+        template: {
+            type: 'string',
+            optional: true,
+            description: 'Template used for this page',
+        },
+        theme: {
+            type: 'string',
+            optional: true,
+            description: 'Color theme or style',
+        },
+        thumbnailUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Page screenshot/thumbnail URL',
+        },
+        // Form & CTA
+        hasForm: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether page includes a form',
+        },
+        formFields: {
+            type: 'json',
+            optional: true,
+            description: 'Form field definitions',
+        },
+        ctaText: {
+            type: 'string',
+            optional: true,
+            description: 'Call-to-action button text',
+        },
+        ctaUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Call-to-action destination URL',
+        },
+        // Conversion Tracking
+        conversionGoal: {
+            type: 'string',
+            optional: true,
+            description: 'Conversion goal: form-submission, click, purchase, signup',
+            examples: ['form-submission', 'click', 'purchase', 'signup'],
+        },
+        trackingPixels: {
+            type: 'json',
+            optional: true,
+            description: 'Tracking pixels/scripts (GA, Facebook Pixel, etc.)',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Page status: draft, published, archived, testing',
+            examples: ['draft', 'published', 'archived', 'testing'],
+        },
+        publishedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'When the page was published',
+        },
+        // SEO
+        metaTitle: {
+            type: 'string',
+            optional: true,
+            description: 'SEO meta title',
+        },
+        metaDescription: {
+            type: 'string',
+            optional: true,
+            description: 'SEO meta description',
+        },
+        keywords: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'SEO keywords',
+        },
+        // Performance Metrics
+        visits: {
+            type: 'number',
+            optional: true,
+            description: 'Total page visits',
+        },
+        uniqueVisits: {
+            type: 'number',
+            optional: true,
+            description: 'Unique visitors',
+        },
+        conversions: {
+            type: 'number',
+            optional: true,
+            description: 'Total conversions',
+        },
+        conversionRate: {
+            type: 'number',
+            optional: true,
+            description: 'Conversion rate (percentage)',
+        },
+        bounceRate: {
+            type: 'number',
+            optional: true,
+            description: 'Bounce rate (percentage)',
+        },
+        avgTimeOnPage: {
+            type: 'number',
+            optional: true,
+            description: 'Average time on page in seconds',
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+    },
+    relationships: {
+        campaign: {
+            type: 'Campaign',
+            required: false,
+            description: 'Campaign this landing page belongs to',
+        },
+        formSubmissions: {
+            type: 'FormSubmission[]',
+            backref: 'landingPage',
+            description: 'Form submissions from this page',
+        },
+        utmLinks: {
+            type: 'UTMLink[]',
+            description: 'Tracked links on this page',
+        },
+        owner: {
+            type: 'Contact',
+            description: 'Page owner/creator',
+        },
+        variants: {
+            type: 'LandingPage[]',
+            description: 'A/B test variants of this page',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'publish',
+        'unpublish',
+        'duplicate',
+        'preview',
+        'test',
+        'archive',
+        'restore',
+        'optimize',
+        'export',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'published',
+        'unpublished',
+        'duplicated',
+        'previewed',
+        'visited',
+        'converted',
+        'archived',
+    ],
+};
+// =============================================================================
+// FormSubmission
+// =============================================================================
+/**
+ * Form submission entity
+ *
+ * Represents a lead capture or form submission from a landing page
+ */
+export const FormSubmission = {
+    singular: 'form submission',
+    plural: 'form submissions',
+    description: 'A form submission or lead capture from a marketing form',
+    properties: {
+        // Form Data
+        formData: {
+            type: 'json',
+            description: 'Submitted form field data (key-value pairs)',
+        },
+        // Common Fields (duplicated for easier access)
+        email: {
+            type: 'string',
+            optional: true,
+            description: 'Submitted email address',
+        },
+        name: {
+            type: 'string',
+            optional: true,
+            description: 'Submitted name',
+        },
+        phone: {
+            type: 'string',
+            optional: true,
+            description: 'Submitted phone number',
+        },
+        company: {
+            type: 'string',
+            optional: true,
+            description: 'Submitted company name',
+        },
+        message: {
+            type: 'string',
+            optional: true,
+            description: 'Submitted message or comments',
+        },
+        // Source & Attribution
+        source: {
+            type: 'string',
+            optional: true,
+            description: 'Traffic source',
+        },
+        medium: {
+            type: 'string',
+            optional: true,
+            description: 'Traffic medium',
+        },
+        referrer: {
+            type: 'url',
+            optional: true,
+            description: 'Referring URL',
+        },
+        // User Agent & Device
+        userAgent: {
+            type: 'string',
+            optional: true,
+            description: 'Browser user agent string',
+        },
+        device: {
+            type: 'string',
+            optional: true,
+            description: 'Device type: desktop, mobile, tablet',
+            examples: ['desktop', 'mobile', 'tablet'],
+        },
+        browser: {
+            type: 'string',
+            optional: true,
+            description: 'Browser name',
+        },
+        os: {
+            type: 'string',
+            optional: true,
+            description: 'Operating system',
+        },
+        // Location
+        ipAddress: {
+            type: 'string',
+            optional: true,
+            description: 'Submitter IP address',
+        },
+        country: {
+            type: 'string',
+            optional: true,
+            description: 'Country from IP geolocation',
+        },
+        region: {
+            type: 'string',
+            optional: true,
+            description: 'Region/state from IP geolocation',
+        },
+        city: {
+            type: 'string',
+            optional: true,
+            description: 'City from IP geolocation',
+        },
+        // Status & Processing
+        status: {
+            type: 'string',
+            description: 'Submission status: new, contacted, qualified, converted, spam, deleted',
+            examples: ['new', 'contacted', 'qualified', 'converted', 'spam', 'deleted'],
+        },
+        qualityScore: {
+            type: 'number',
+            optional: true,
+            description: 'Lead quality score (0-100)',
+        },
+        spam: {
+            type: 'boolean',
+            optional: true,
+            description: 'Whether flagged as spam',
+        },
+        // Notes & Follow-up
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Internal notes about this submission',
+        },
+        assignedTo: {
+            type: 'string',
+            optional: true,
+            description: 'User ID this submission is assigned to',
+        },
+        // Metadata
+        submittedAt: {
+            type: 'datetime',
+            description: 'Submission timestamp',
+        },
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+    },
+    relationships: {
+        landingPage: {
+            type: 'LandingPage',
+            backref: 'formSubmissions',
+            required: false,
+            description: 'Landing page where form was submitted',
+        },
+        campaign: {
+            type: 'Campaign',
+            required: false,
+            description: 'Campaign this submission is attributed to',
+        },
+        contact: {
+            type: 'Contact',
+            required: false,
+            description: 'Created or matched contact record',
+        },
+        utmLink: {
+            type: 'UTMLink',
+            required: false,
+            description: 'UTM link that drove this submission',
+        },
+        assignee: {
+            type: 'Contact',
+            required: false,
+            description: 'Person assigned to follow up',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'qualify',
+        'contact',
+        'convert',
+        'assign',
+        'markSpam',
+        'markNotSpam',
+        'export',
+        'merge',
+    ],
+    events: [
+        'submitted',
+        'updated',
+        'deleted',
+        'qualified',
+        'contacted',
+        'converted',
+        'assigned',
+        'markedSpam',
+        'exported',
+    ],
+};
+// =============================================================================
+// SocialPost
+// =============================================================================
+/**
+ * Social media post entity
+ *
+ * Represents a social media post scheduled or published across platforms
+ */
+export const SocialPost = {
+    singular: 'social post',
+    plural: 'social posts',
+    description: 'A social media post for one or more platforms',
+    properties: {
+        // Content
+        message: {
+            type: 'string',
+            description: 'Post text content',
+        },
+        mediaUrls: {
+            type: 'url',
+            array: true,
+            optional: true,
+            description: 'Attached media URLs (images, videos)',
+        },
+        mediaType: {
+            type: 'string',
+            optional: true,
+            description: 'Media type: image, video, gif, carousel',
+            examples: ['image', 'video', 'gif', 'carousel'],
+        },
+        link: {
+            type: 'url',
+            optional: true,
+            description: 'Shared link URL',
+        },
+        linkPreview: {
+            type: 'json',
+            optional: true,
+            description: 'Link preview card data',
+        },
+        // Platform & Targeting
+        platform: {
+            type: 'string',
+            description: 'Social platform: facebook, instagram, twitter, linkedin, tiktok, youtube',
+            examples: ['facebook', 'instagram', 'twitter', 'linkedin', 'tiktok', 'youtube'],
+        },
+        accountId: {
+            type: 'string',
+            optional: true,
+            description: 'Platform account/page identifier',
+        },
+        accountName: {
+            type: 'string',
+            optional: true,
+            description: 'Platform account/page name',
+        },
+        // Scheduling
+        status: {
+            type: 'string',
+            description: 'Post status: draft, scheduled, published, failed, deleted',
+            examples: ['draft', 'scheduled', 'published', 'failed', 'deleted'],
+        },
+        scheduledAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Scheduled publish time',
+        },
+        publishedAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Actual publish time',
+        },
+        // Platform-specific
+        platformPostId: {
+            type: 'string',
+            optional: true,
+            description: 'Post ID on the platform',
+        },
+        platformUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Direct URL to the post on the platform',
+        },
+        // Hashtags & Mentions
+        hashtags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Hashtags used in the post',
+        },
+        mentions: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'User handles mentioned',
+        },
+        // Engagement Metrics
+        likes: {
+            type: 'number',
+            optional: true,
+            description: 'Number of likes/reactions',
+        },
+        comments: {
+            type: 'number',
+            optional: true,
+            description: 'Number of comments',
+        },
+        shares: {
+            type: 'number',
+            optional: true,
+            description: 'Number of shares/retweets',
+        },
+        clicks: {
+            type: 'number',
+            optional: true,
+            description: 'Number of link clicks',
+        },
+        impressions: {
+            type: 'number',
+            optional: true,
+            description: 'Total impressions',
+        },
+        reach: {
+            type: 'number',
+            optional: true,
+            description: 'Unique reach',
+        },
+        engagementRate: {
+            type: 'number',
+            optional: true,
+            description: 'Engagement rate (percentage)',
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Internal tags for organization',
+        },
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Internal notes',
+        },
+    },
+    relationships: {
+        campaign: {
+            type: 'Campaign',
+            required: false,
+            description: 'Campaign this post belongs to',
+        },
+        utmLink: {
+            type: 'UTMLink',
+            required: false,
+            description: 'Tracked URL included in post',
+        },
+        author: {
+            type: 'Contact',
+            description: 'Post creator',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'schedule',
+        'publish',
+        'cancel',
+        'reschedule',
+        'boost',
+        'preview',
+        'analyze',
+        'export',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'scheduled',
+        'published',
+        'failed',
+        'canceled',
+        'rescheduled',
+        'boosted',
+        'liked',
+        'commented',
+        'shared',
+    ],
+};
+// =============================================================================
+// AdCreative
+// =============================================================================
+/**
+ * Ad creative entity
+ *
+ * Represents an advertisement creative with copy, images, and CTA
+ */
+export const AdCreative = {
+    singular: 'ad creative',
+    plural: 'ad creatives',
+    description: 'An advertisement creative for paid campaigns',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            description: 'Creative name (internal)',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Internal description',
+        },
+        // Format & Type
+        format: {
+            type: 'string',
+            description: 'Ad format: image, video, carousel, collection, story, banner',
+            examples: ['image', 'video', 'carousel', 'collection', 'story', 'banner'],
+        },
+        adType: {
+            type: 'string',
+            optional: true,
+            description: 'Ad type: display, search, social, video, native',
+            examples: ['display', 'search', 'social', 'video', 'native'],
+        },
+        // Creative Assets
+        headline: {
+            type: 'string',
+            optional: true,
+            description: 'Primary headline',
+        },
+        body: {
+            type: 'string',
+            optional: true,
+            description: 'Ad body copy',
+        },
+        adDescription: {
+            type: 'string',
+            optional: true,
+            description: 'Ad description text',
+        },
+        imageUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Primary image URL',
+        },
+        videoUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Video URL',
+        },
+        thumbnailUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Video thumbnail or creative preview',
+        },
+        mediaUrls: {
+            type: 'url',
+            array: true,
+            optional: true,
+            description: 'Multiple media assets (for carousel, etc.)',
+        },
+        // Call to Action
+        ctaText: {
+            type: 'string',
+            optional: true,
+            description: 'Call-to-action button text',
+        },
+        ctaType: {
+            type: 'string',
+            optional: true,
+            description: 'CTA type: learn-more, shop-now, sign-up, download, contact',
+            examples: ['learn-more', 'shop-now', 'sign-up', 'download', 'contact'],
+        },
+        destinationUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Landing page URL',
+        },
+        // Dimensions & Specs
+        dimensions: {
+            type: 'json',
+            optional: true,
+            description: 'Creative dimensions (width x height)',
+        },
+        aspectRatio: {
+            type: 'string',
+            optional: true,
+            description: 'Aspect ratio (16:9, 1:1, 9:16, etc.)',
+            examples: ['16:9', '1:1', '9:16', '4:5'],
+        },
+        fileSize: {
+            type: 'number',
+            optional: true,
+            description: 'File size in bytes',
+        },
+        duration: {
+            type: 'number',
+            optional: true,
+            description: 'Video duration in seconds',
+        },
+        // Platform & Placement
+        platform: {
+            type: 'string',
+            optional: true,
+            description: 'Target platform: facebook, instagram, google, linkedin, twitter',
+            examples: ['facebook', 'instagram', 'google', 'linkedin', 'twitter'],
+        },
+        placement: {
+            type: 'string',
+            optional: true,
+            description: 'Ad placement: feed, story, search, display, video',
+            examples: ['feed', 'story', 'search', 'display', 'video'],
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Creative status: draft, active, paused, archived, rejected',
+            examples: ['draft', 'active', 'paused', 'archived', 'rejected'],
+        },
+        approvalStatus: {
+            type: 'string',
+            optional: true,
+            description: 'Platform approval status: pending, approved, rejected',
+            examples: ['pending', 'approved', 'rejected'],
+        },
+        rejectionReason: {
+            type: 'string',
+            optional: true,
+            description: 'Reason for rejection if applicable',
+        },
+        // Performance Metrics
+        impressions: {
+            type: 'number',
+            optional: true,
+            description: 'Total impressions',
+        },
+        clicks: {
+            type: 'number',
+            optional: true,
+            description: 'Total clicks',
+        },
+        conversions: {
+            type: 'number',
+            optional: true,
+            description: 'Total conversions',
+        },
+        ctr: {
+            type: 'number',
+            optional: true,
+            description: 'Click-through rate (percentage)',
+        },
+        conversionRate: {
+            type: 'number',
+            optional: true,
+            description: 'Conversion rate (percentage)',
+        },
+        spend: {
+            type: 'number',
+            optional: true,
+            description: 'Total spend on this creative',
+        },
+        cpc: {
+            type: 'number',
+            optional: true,
+            description: 'Cost per click',
+        },
+        cpm: {
+            type: 'number',
+            optional: true,
+            description: 'Cost per thousand impressions',
+        },
+        cpa: {
+            type: 'number',
+            optional: true,
+            description: 'Cost per acquisition',
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+    },
+    relationships: {
+        campaign: {
+            type: 'Campaign',
+            required: false,
+            description: 'Campaign this creative belongs to',
+        },
+        utmLink: {
+            type: 'UTMLink',
+            required: false,
+            description: 'Tracked URL for this creative',
+        },
+        audience: {
+            type: 'Audience',
+            required: false,
+            description: 'Target audience',
+        },
+        creator: {
+            type: 'Contact',
+            description: 'Creative designer/creator',
+        },
+        variants: {
+            type: 'AdCreative[]',
+            description: 'A/B test variants',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'preview',
+        'submit',
+        'approve',
+        'reject',
+        'activate',
+        'pause',
+        'duplicate',
+        'archive',
+        'test',
+        'export',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'submitted',
+        'approved',
+        'rejected',
+        'activated',
+        'paused',
+        'duplicated',
+        'archived',
+    ],
+};
+// =============================================================================
+// UTMLink
+// =============================================================================
+/**
+ * UTM tracked link entity
+ *
+ * Represents a URL with UTM parameters for tracking campaign performance
+ */
+export const UTMLink = {
+    singular: 'utm link',
+    plural: 'utm links',
+    description: 'A tracked URL with UTM parameters for campaign attribution',
+    properties: {
+        // Identity
+        name: {
+            type: 'string',
+            optional: true,
+            description: 'Link name (internal)',
+        },
+        description: {
+            type: 'string',
+            optional: true,
+            description: 'Link description',
+        },
+        // URLs
+        destinationUrl: {
+            type: 'url',
+            description: 'Original destination URL (without UTM parameters)',
+        },
+        fullUrl: {
+            type: 'url',
+            description: 'Complete URL with UTM parameters',
+        },
+        shortUrl: {
+            type: 'url',
+            optional: true,
+            description: 'Shortened URL (bit.ly, etc.)',
+        },
+        // UTM Parameters
+        utmSource: {
+            type: 'string',
+            description: 'Traffic source (utm_source): google, facebook, newsletter',
+        },
+        utmMedium: {
+            type: 'string',
+            description: 'Marketing medium (utm_medium): email, cpc, social, organic',
+        },
+        utmCampaign: {
+            type: 'string',
+            description: 'Campaign name (utm_campaign)',
+        },
+        utmTerm: {
+            type: 'string',
+            optional: true,
+            description: 'Paid keyword (utm_term)',
+        },
+        utmContent: {
+            type: 'string',
+            optional: true,
+            description: 'Content variant (utm_content) for A/B testing',
+        },
+        // Additional Tracking
+        customParameters: {
+            type: 'json',
+            optional: true,
+            description: 'Additional custom tracking parameters',
+        },
+        trackingId: {
+            type: 'string',
+            optional: true,
+            description: 'Internal tracking identifier',
+        },
+        // Context
+        platform: {
+            type: 'string',
+            optional: true,
+            description: 'Platform where link is used: email, social, ad, website',
+            examples: ['email', 'social', 'ad', 'website'],
+        },
+        placement: {
+            type: 'string',
+            optional: true,
+            description: 'Specific placement location',
+        },
+        // Performance Metrics
+        clicks: {
+            type: 'number',
+            optional: true,
+            description: 'Total clicks',
+        },
+        uniqueClicks: {
+            type: 'number',
+            optional: true,
+            description: 'Unique clicks',
+        },
+        conversions: {
+            type: 'number',
+            optional: true,
+            description: 'Total conversions attributed',
+        },
+        revenue: {
+            type: 'number',
+            optional: true,
+            description: 'Revenue attributed to this link',
+        },
+        // Status
+        status: {
+            type: 'string',
+            description: 'Link status: active, expired, archived',
+            examples: ['active', 'expired', 'archived'],
+        },
+        expiresAt: {
+            type: 'datetime',
+            optional: true,
+            description: 'Link expiration date',
+        },
+        // Metadata
+        tags: {
+            type: 'string',
+            array: true,
+            optional: true,
+            description: 'Tags for organization',
+        },
+        notes: {
+            type: 'string',
+            optional: true,
+            description: 'Internal notes',
+        },
+    },
+    relationships: {
+        campaign: {
+            type: 'Campaign',
+            required: false,
+            description: 'Campaign this link belongs to',
+        },
+        emailTemplate: {
+            type: 'EmailTemplate',
+            required: false,
+            description: 'Email template using this link',
+        },
+        landingPage: {
+            type: 'LandingPage',
+            required: false,
+            description: 'Landing page where this link appears',
+        },
+        socialPost: {
+            type: 'SocialPost',
+            required: false,
+            description: 'Social post using this link',
+        },
+        adCreative: {
+            type: 'AdCreative',
+            required: false,
+            description: 'Ad creative using this link',
+        },
+        formSubmissions: {
+            type: 'FormSubmission[]',
+            description: 'Form submissions attributed to this link',
+        },
+        creator: {
+            type: 'Contact',
+            description: 'Link creator',
+        },
+    },
+    actions: [
+        'create',
+        'update',
+        'delete',
+        'shorten',
+        'copy',
+        'share',
+        'test',
+        'archive',
+        'expire',
+        'renew',
+        'export',
+    ],
+    events: [
+        'created',
+        'updated',
+        'deleted',
+        'shortened',
+        'clicked',
+        'converted',
+        'archived',
+        'expired',
+        'renewed',
+    ],
+};
+// =============================================================================
+// Export all entities as a schema
+// =============================================================================
+/**
+ * All marketing entity types
+ */
+export const MarketingEntities = {
+    Campaign,
+    Audience,
+    EmailTemplate,
+    LandingPage,
+    FormSubmission,
+    SocialPost,
+    AdCreative,
+    UTMLink,
+};
+/**
+ * Entity categories for organization
+ */
+export const MarketingCategories = {
+    core: ['Campaign', 'Audience'],
+    content: ['EmailTemplate', 'LandingPage', 'SocialPost', 'AdCreative'],
+    tracking: ['UTMLink', 'FormSubmission'],
+};
+//# sourceMappingURL=marketing.js.map