@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/shopify-discount-engine.d.ts

@@ -0,0 +1,51 @@
+export interface DiscountCodeGenerationOptions {
+    prefix?: string;
+    length?: number;
+    type: "percentage" | "fixed_amount" | "free_shipping";
+    value: number;
+    currencyCode?: string;
+    durationHours?: number;
+    minSubtotalCents?: number;
+    usageLimit?: number;
+}
+export interface ShopifyDiscountMutationPayload {
+    query: string;
+    variables: {
+        basicCodeDiscount: {
+            title: string;
+            code: string;
+            startsAt: string;
+            endsAt?: string;
+            usageLimit: number;
+            appliesOncePerCustomer: boolean;
+            customerGets: {
+                value: {
+                    percentage?: number;
+                    discountAmount?: {
+                        amount: number;
+                        appliesOnEachItem: boolean;
+                    };
+                };
+                items: {
+                    all: boolean;
+                };
+            };
+            minimumRequirement?: {
+                subtotal?: {
+                    greaterThanOrEqualToSubtotal: number;
+                };
+            };
+        };
+    };
+}
+export declare class ShopifyDiscountEngine {
+    private static readonly CHARSET;
+    /**
+     * Génère un code promo aléatoire unique et lisible (ex: `PULSE-8K2MN9`).
+     */
+    static generateCode(prefix?: string, randomLength?: number): string;
+    /**
+     * Construit la mutation GraphQL standard Shopify `discountCodeBasicCreate`.
+     */
+    static buildShopifyDiscountMutation(code: string, options: DiscountCodeGenerationOptions): ShopifyDiscountMutationPayload;
+}

package/dist/shopify-seo-connector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 🛍️ Shopify SEO Connector & Reverse Proxy Engine
+ *
+ * Integrates Shopify stores with LynxSEO:
+ * 1. Shopify Admin API (GraphQL) mutations for SEO Title, Meta Description, and Metafields.
+ * 2. E-Commerce Schema.org Product JSON-LD with Offer, Availability, and AggregateRating.
+ * 3. Cloudflare Edge Reverse-Proxy Worker generator to serve 10,000+ pSEO pages on the
+ *    store's custom domain without impacting the Shopify Liquid theme.
+ * 4. Product SEO Health Auditor (Title, Meta, Alt text, Handle hygiene).
+ */
+export interface ShopifyProductInput {
+    id: string;
+    title: string;
+    handle: string;
+    descriptionHtml?: string;
+    vendor?: string;
+    price: number;
+    currency?: string;
+    sku?: string;
+    images?: Array<{
+        url: string;
+        altText?: string;
+    }>;
+    ratingValue?: number;
+    reviewCount?: number;
+    inStock?: boolean;
+}
+export interface ShopifySeoAudit {
+    score: number;
+    titleTagRecommendation: string;
+    descriptionTagRecommendation: string;
+    missingAltImagesCount: number;
+    issues: string[];
+    recommendations: string[];
+}
+export declare class ShopifySeoConnector {
+    /**
+     * Generates a standard Shopify Admin GraphQL mutation to update SEO fields.
+     */
+    static generateProductSeoMutation(params: {
+        productId: string;
+        seoTitle: string;
+        seoDescription: string;
+    }): {
+        query: string;
+        variables: Record<string, unknown>;
+    };
+    /**
+     * Generates Google-compliant Schema.org Product JSON-LD.
+     */
+    static generateProductJsonLd(product: ShopifyProductInput, storeDomain?: string): Record<string, unknown>;
+    /**
+     * Audits a Shopify product's SEO readiness and generates optimized suggestions.
+     */
+    static auditProductSeo(product: ShopifyProductInput): ShopifySeoAudit;
+    /**
+     * Generates a turnkey Cloudflare Worker script for serving programmatic SEO pages
+     * on a custom Shopify domain without slowing down the Shopify Liquid theme.
+     */
+    static generateCloudflareReverseProxyScript(params: {
+        shopifyOrigin: string;
+        pSeoPrefix?: string;
+        edgeApiEndpoint?: string;
+    }): string;
+    /**
+     * Executes a live GraphQL productUpdate mutation on the official Shopify Admin API.
+     */
+    static executeProductSeoMutation(params: {
+        shopifyDomain: string;
+        adminAccessToken: string;
+        productId: string;
+        seoTitle: string;
+        seoDescription: string;
+        apiVersion?: string;
+    }): Promise<{
+        success: boolean;
+        data?: unknown;
+        errors?: unknown[];
+    }>;
+}

package/dist/short-links.d.ts

@@ -0,0 +1,59 @@
+export interface ShortLinkRecord {
+    id: string;
+    projectId: string;
+    slug: string;
+    targetUrl: string;
+    campaign?: string | null;
+    expiresAt?: string | null;
+    createdAt: string;
+    clicks: number;
+    lastClickedAt?: string | null;
+}
+export interface ShortLinkResolution {
+    status: "active" | "expired" | "invalid";
+    targetUrl?: string;
+    reason?: string;
+}
+export declare function normalizeShortSlug(input: string): string;
+export declare function isValidShortSlug(slug: string): boolean;
+export declare function isReservedShortSlug(slug: string): boolean;
+export declare function generateShortSlug(seed: string, attempt?: number): string;
+export declare function buildShortLinkUrl(origin: string, slug: string): string;
+export declare function appendUtmParams(targetUrl: string, params: Record<string, string | undefined | null>): string;
+export declare function resolveShortLink(link: Pick<ShortLinkRecord, "targetUrl" | "expiresAt">, now?: Date, options?: {
+    allowedProtocols?: string[];
+}): ShortLinkResolution;
+export type PixelEvent = "page_view" | "click" | "conversion";
+export interface ShortLinkPixelConfig {
+    /** Measurement pixel endpoint, e.g. "https://pix.example.com/collect". */
+    endpoint: string;
+    /** Project/organization id attached to every pixel hit. */
+    projectId: string;
+    /** Optional campaign tag. */
+    campaign?: string | null;
+    /** Optional content tag. */
+    content?: string | null;
+}
+/**
+ * Builds a 1x1 tracking pixel URL for a short link resolution event.
+ * Appends the link slug, event type, UTM-style params and a cache-buster so
+ * each hit is counted separately by the pixel endpoint.
+ */
+export declare function buildPixelUrl(config: ShortLinkPixelConfig, slug: string, event: PixelEvent, options?: {
+    referrer?: string | null;
+    timestamp?: number;
+}): string;
+/**
+ * Returns the HTML for a transparent 1x1 pixel that fires the tracking
+ * endpoint when loaded. Safe to embed in redirect pages or confirmation emails.
+ */
+export declare function pixelHtml(url: string): string;
+/**
+ * Creates a short link record pre-populated with pixel configuration.
+ * The caller persists `record` and renders `pixelHtml(buildPixelUrl(...))`
+ * on the destination page to count conversions.
+ */
+export declare function createShortLinkWithPixel(projectId: string, slug: string, targetUrl: string, pixel: ShortLinkPixelConfig, now?: Date): {
+    record: ShortLinkRecord;
+    pixelUrl: string;
+};

package/dist/shortlinks/shortlinks.d.ts

@@ -0,0 +1,14 @@
+export interface ShortLink {
+    id: string;
+    slug: string;
+    targetUrl: string;
+    siteId?: string;
+    clicks: number;
+    active: boolean;
+    expiresAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function normalizeSlug(s: string): string;
+export declare function isValidUrl(u: string): boolean;
+export declare function trackClick(sl: ShortLink): ShortLink;

package/dist/site-crawler.d.ts

@@ -1,11 +1,14 @@
 /**
- * 🕷️ Deep Site Crawler & Technical SEO Auditor (Inspired by CrawlSEO & Seonaut)
+ * 🕷️ Deep Site Crawler & Technical SEO Auditor (LynxSEO Enterprise Engine)
  *
  * High-performance, zero-dependency recursive site crawler & technical health inspector.
- * - Crawls live websites or crawls pre-rendered HTML snapshots
- * - Analyzes status codes, redirects, canonicals, titles, H1s, meta descriptions, image ALTs
- * - Detects 30+ SEO issues classified by severity (critical, warning, info)
- * - Computes a comprehensive 0-100 SEO Health Score with category breakdowns
+ * Advanced core capabilities:
+ * - Deterministic Indexability classification (Indexable vs Non-Indexable with exact root causes)
+ * - SERP Pixel Width Engine for Desktop & Mobile Titles (575px limit) and Meta Descriptions (960px limit)
+ * - MinHash / Jaccard Shingling near-duplicate content detection (> 85% similarity threshold)
+ * - Multi-hop redirect chain tracer & circular redirect loop detector
+ * - Breadth-First-Search (BFS) crawl depth tracking & internal inlinks/outlinks graph aggregator
+ * - 32-category enterprise issue taxonomy with severity classification & actionable recommendations
  */
 export interface CrawlIssue {
     url: string;
@@ -19,22 +22,68 @@ export interface CrawledPageData {
     url: string;
     statusCode: number;
     responseTimeMs: number;
+    indexability: "Indexable" | "Non-Indexable";
+    indexabilityReason?: string;
     title: string | null;
+    titleCount: number;
+    titlePixelWidth: number;
     description: string | null;
+    descriptionPixelWidth: number;
     h1: string | null;
     h1Count: number;
+    h2Count: number;
     canonical: string | null;
     isCanonicalMatch: boolean;
     wordCount: number;
+    crawlDepth: number;
+    inlinksCount: number;
+    outlinksCount: number;
+    pageSizeBytes: number;
+    nearDuplicateOf?: string;
+    nearDuplicateSimilarity?: number;
     imagesWithoutAlt: number;
+    imagesWithoutDimensions?: number;
     internalLinksCount: number;
     externalLinksCount: number;
+    images?: PageImageDetail[];
     issues: CrawlIssue[];
 }
+export interface PageImageDetail {
+    loc: string;
+    title?: string;
+    caption?: string;
+}
+export interface OrphanInventoryReport {
+    orphanUrls: string[];
+    orphanCount: number;
+    inventoryTotal: number;
+    crawledTotal: number;
+    coveragePercentage: number;
+}
+export interface RedirectChainDetail {
+    source: string;
+    target: string;
+    statusCode: number;
+    chainLength: number;
+    isLoop: boolean;
+    hops: string[];
+}
 export interface SiteAuditSummary {
     domain: string;
     crawledPagesCount: number;
     healthScore: number;
+    grade: "A+" | "A" | "B" | "C" | "D" | "F";
+    indexabilityBreakdown: {
+        indexable: number;
+        nonIndexable: number;
+        percentage: number;
+    };
+    statusCodesSummary: {
+        "2xx": number;
+        "3xx": number;
+        "4xx": number;
+        "5xx": number;
+    };
     categories: {
         metaAndTags: number;
         contentQuality: number;
@@ -46,15 +95,31 @@ export interface SiteAuditSummary {
         warning: number;
         info: number;
     };
+    nearDuplicatesCount: number;
+    orphanPagesCount: number;
+    highCrawlDepthCount: number;
+    redirectLoopsCount: number;
     brokenLinks404: string[];
-    redirectChains: {
-        source: string;
-        target: string;
-        statusCode: number;
-    }[];
+    redirectChains: RedirectChainDetail[];
     pages: CrawledPageData[];
+    orphanReport?: OrphanInventoryReport;
+    imageSitemapXml?: string;
+    htmlSitemap?: string;
+    wcagIssuesCount?: number;
+    spellingIssuesCount?: number;
+    proxyStats?: {
+        totalProxies: number;
+        requestsRouted: number;
+        strategy: "round-robin" | "random";
+    };
     executionTimeMs: number;
 }
+export interface HtmlSitemapOptions {
+    siteTitle?: string;
+    baseUrl?: string;
+    groupBy?: "folder" | "depth";
+    includeDescriptions?: boolean;
+}
 export interface CrawlOptions {
     maxPages?: number;
     maxDepth?: number;
@@ -62,15 +127,160 @@ export interface CrawlOptions {
     concurrency?: number;
     userAgent?: string;
     includeExternalLinksCheck?: boolean;
+    maxRPM?: number;
+    crawlDelayMs?: number;
+    soft404Terms?: string[];
+    enableHtmlValidation?: boolean;
+    inventoryUrls?: string[];
+    blacklistPatterns?: (string | RegExp)[];
+    whitelistPatterns?: (string | RegExp)[];
+    stripQueryParams?: boolean;
+    stripSessionIds?: boolean;
+    keywordStuffingThresholdPercent?: number;
+    enableWcagAudit?: boolean;
+    enableSpellCheck?: boolean;
+    customDictionaryWords?: string[];
+    customHeaders?: Record<string, string>;
+    authCookie?: string;
+    sessionCookies?: Record<string, string>;
+    loginUrl?: string;
+    loginCredentials?: {
+        usernameField?: string;
+        usernameValue?: string;
+        passwordField?: string;
+        passwordValue?: string;
+        customFormData?: Record<string, string>;
+    };
+    respectRobotsTxt?: boolean;
+    proxyUrl?: string;
+    proxyList?: string[];
+    proxyRotationStrategy?: "round-robin" | "random";
+    customFetch?: typeof fetch;
+    proxyAuthHeader?: string;
 }
+/**
+ * 🔄 Proxy Pool and IP Rotation Engine
+ *
+ * Distributes crawling requests across an IP pool using round-robin or random rotation,
+ * preventing target rate limits and IP blocking during high-volume enterprise crawls.
+ */
+export declare class ProxyRotator {
+    private proxies;
+    private strategy;
+    private index;
+    private requestsRouted;
+    constructor(options: {
+        proxyUrl?: string;
+        proxyList?: string[];
+        proxyRotationStrategy?: "round-robin" | "random";
+    });
+    get hasProxies(): boolean;
+    get totalProxies(): number;
+    get routedCount(): number;
+    getNextProxy(): string | null;
+    applyProxyHeaders(proxyUrl: string, baseHeaders: Record<string, string>): Record<string, string>;
+}
+export interface RobotsRule {
+    userAgent: string;
+    disallows: string[];
+    allows: string[];
+    crawlDelay?: number;
+}
+/**
+ * Legacy grouped view over the RFC 9309 policy. Parsing itself is delegated to
+ * `robots-policy.ts`, so this crawler and the simulator can never diverge on
+ * group merging, wildcards or longest-match precedence.
+ */
+export declare function parseRobotsTxt(content: string): RobotsRule[];
+export declare function isRobotsAllowed(urlStr: string, rules: RobotsRule[], userAgent?: string): boolean;
+/**
+ * Calculates rendered pixel width for Google Desktop SERP Title (Limit: ~575px - 600px)
+ */
+export declare function calculateTitlePixelWidth(title: string | null): number;
+/**
+ * Calculates rendered pixel width for Google Desktop SERP Meta Description (Limit: ~960px)
+ */
+export declare function calculateDescPixelWidth(desc: string | null): number;
+/**
+ * MinHash & Shingling Engine for Near-Duplicate Content Detection (Apache Lucene parity)
+ */
+export declare function computeMinHashSignature(text: string, numHashes?: number): number[];
+/**
+ * Jaccard Similarity between two MinHash signatures (0.0 to 1.0)
+ */
+export declare function calculateMinHashSimilarity(sig1: number[], sig2: number[]): number;
+/**
+ * Generates an official Google Image XML Sitemap from crawled pages
+ * Adheres to http://www.google.com/schemas/sitemap-image/1.1
+ */
+export declare function generateImageSitemap(pages: CrawledPageData[]): string;
+/**
+ * Identifies true orphan pages by diffing server-side/sitemap inventory against crawled URLs.
+ */
+export declare function detectOrphanPagesFromInventory(inventoryUrls: string[], crawledPages: CrawledPageData[]): OrphanInventoryReport;
+/**
+ * Normalizes, strips session traps, and checks whitelist/blacklist rules for discovered URLs.
+ */
+export declare function normalizeCrawlUrl(rawHref: string, baseUrl: string, options?: CrawlOptions): string | null;
+/**
+ * Exports all broken links (4xx, 5xx, timeouts) to CSV with source errors and recommendations.
+ * .csv
+ */
+export declare function exportBadLinksCsv(summaryOrPages: SiteAuditSummary | CrawledPageData[]): string;
+/**
+ * Exports duplicate titles with occurrences and full URL sets to CSV.
+ * .csv
+ */
+export declare function exportDuplicateTitlesCsv(summaryOrPages: SiteAuditSummary | CrawledPageData[]): string;
+/**
+ * Exports duplicate meta descriptions with occurrences and full URL sets to CSV.
+ * .csv
+ */
+export declare function exportDuplicateDescriptionsCsv(summaryOrPages: SiteAuditSummary | CrawledPageData[]): string;
+/**
+ * Exports the comprehensive site audit database to CSV.
+ * .csv
+ */
+export declare function exportFullAuditCsv(summaryOrPages: SiteAuditSummary | CrawledPageData[]): string;
+/**
+ * Calculates WCAG 2.1 relative luminance color contrast ratio between two hex colors.
+ * Standard WCAG AA threshold is 4.5:1 for normal text, 3:1 for large text.
+ */
+export declare function calculateColorContrastRatio(foregroundHex: string, backgroundHex: string): number;
+/**
+ * Audits HTML for key WCAG 2.1 accessibility criteria (A & AA).
+ */
+export declare function auditWcagAccessibility(html: string, url: string): CrawlIssue[];
+/**
+ * Checks text content for spelling mistakes, web typos, and accidental consecutive word repetitions.
+ */
+export declare function auditSpellingAndGrammar(cleanText: string, url: string, customWords?: string[]): CrawlIssue[];
+/**
+ * Generates a clean, accessible, human-readable HTML sitemap.
+ */
+export declare function generateHtmlSitemap(summaryOrPages: SiteAuditSummary | CrawledPageData[], options?: HtmlSitemapOptions): string;
 export declare class DeepCrawlerAuditor {
     private static DEFAULT_USER_AGENT;
     /**
      * Performs an instant in-memory technical audit on raw HTML and metadata.
+     * Evaluates deterministic rules and issue classification.
      */
-    static inspectHtmlSnapshot(url: string, html: string, statusCode?: number, responseTimeMs?: number): CrawledPageData;
+    static inspectHtmlSnapshot(url: string, html: string, statusCode?: number, responseTimeMs?: number, crawlDepth?: number, inlinksCount?: number, outlinksCount?: number, customSoft404Terms?: string[], enableHtmlValidation?: boolean, keywordStuffingThresholdPercent?: number, enableWcagAudit?: boolean, enableSpellCheck?: boolean, customDictionaryWords?: string[]): CrawledPageData;
     /**
      * Crawls a full website domain recursively and produces an institutional SEO audit summary.
+     * Full crawl execution with BFS graph analysis.
      */
     static crawlAndAuditDomain(targetUrl: string, options?: CrawlOptions): Promise<SiteAuditSummary>;
+    static crawlSite: typeof DeepCrawlerAuditor.crawlAndAuditDomain;
+    static exportBadLinksCsv: typeof exportBadLinksCsv;
+    static exportDuplicateTitlesCsv: typeof exportDuplicateTitlesCsv;
+    static exportDuplicateDescriptionsCsv: typeof exportDuplicateDescriptionsCsv;
+    static exportFullAuditCsv: typeof exportFullAuditCsv;
+    static generateImageSitemap: typeof generateImageSitemap;
+    static generateHtmlSitemap: typeof generateHtmlSitemap;
+    static detectOrphanPagesFromInventory: typeof detectOrphanPagesFromInventory;
+    static normalizeCrawlUrl: typeof normalizeCrawlUrl;
+    static calculateColorContrastRatio: typeof calculateColorContrastRatio;
+    static auditWcagAccessibility: typeof auditWcagAccessibility;
+    static auditSpellingAndGrammar: typeof auditSpellingAndGrammar;
 }

package/dist/sitemap-chunk-partitioner.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Sitemaps Partitioner & Index Generator (Scaled pSEO Pattern)
+ *
+ * Complies with Google & Bing Sitemaps protocol:
+ * - Strictly limits URLs per sitemap file (Google max 50,000 URLs / 50MB uncompressed, default 10,000 for fast indexing)
+ * - Generates master sitemapindex.xml linking all sub-sitemaps
+ * - Supports hreflang / multilingual alternate links inside sitemap XML
+ * - Supports Google Image Sitemap extension (xmlns:image) with <image:image> nodes
+ * - Handles lastmod, changefreq, and priority
+ */
+/**
+ * Optional image metadata for Google Image Sitemaps.
+ * @see https://developers.google.com/search/docs/crawling-indexing/sitemaps/image-sitemaps
+ */
+export interface SitemapImageEntry {
+    /** Absolute URL of the image (required). */
+    loc: string;
+    /** Human-readable title of the image. */
+    title?: string;
+    /** Caption / alt text of the image. */
+    caption?: string;
+    /** Geographic location, e.g. "Paris, France". */
+    geo_location?: string;
+    /** Optional license URL. */
+    license?: string;
+}
+export interface SitemapUrlEntry {
+    loc: string;
+    lastmod?: string;
+    changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+    priority?: number | string;
+    alternates?: {
+        lang: string;
+        href: string;
+    }[];
+    /** Images to include in the Image Sitemap extension for this URL. */
+    images?: SitemapImageEntry[];
+}
+export interface SitemapChunk {
+    filename: string;
+    urlPath: string;
+    xml: string;
+    count: number;
+}
+export interface PartitionedSitemapsResult {
+    indexXml: string;
+    chunks: SitemapChunk[];
+    totalUrls: number;
+    totalChunks: number;
+}
+export declare class SitemapChunkPartitioner {
+    /**
+     * Partitions an array of URL entries into chunks and emits sub-sitemaps + sitemap index.
+     * Automatically adds xmlns:image namespace and <image:image> nodes when entries contain images.
+     */
+    static partition(domain: string, urls: SitemapUrlEntry[], options?: {
+        maxUrlsPerFile?: number;
+        filePrefix?: string;
+        currentDate?: string;
+    }): PartitionedSitemapsResult;
+    private static escapeXml;
+}

package/dist/slug-engine.d.ts

@@ -30,3 +30,9 @@ export interface SlugValidationResult {
  * Validates a slug against universal SEO golden rules.
  */
 export declare function validateSeoSlug(slug: string): SlugValidationResult;
+/**
+ * Deterministically formats a canonical comparison slug (A vs B).
+ * Enforces alphabetical sorting so that 'salesforce-vs-hubspot' and 'hubspot-vs-salesforce'
+ * always yield the identical canonical slug 'hubspot-vs-salesforce', eliminating reciprocal pSEO duplicates.
+ */
+export declare function formatCanonicalComparisonSlug(itemA: string, itemB: string, delimiter?: string): string;

package/dist/sms-compliance-engine.d.ts

@@ -0,0 +1,47 @@
+export interface SmsNormalizationResult {
+    isValid: boolean;
+    e164: string;
+    countryCode: string;
+    callingCode: string;
+    nationalNumber: string;
+    error?: string;
+}
+export interface TcpaConsentRecord {
+    consentId: string;
+    projectId: string;
+    campaignId?: string;
+    e164Phone: string;
+    ipAddress?: string;
+    userAgent?: string;
+    disclosureText: string;
+    timestamp: string;
+    consentHash: string;
+    doubleOptInRequired: boolean;
+}
+export interface DisclosureOptions {
+    brandName: string;
+    privacyPolicyUrl?: string;
+    termsUrl?: string;
+    language?: "fr" | "en" | "de" | "es";
+    isMarketingPromo?: boolean;
+}
+export declare class SmsComplianceEngine {
+    private static readonly CALLING_CODES;
+    /**
+     * Normalise un numéro de téléphone en format international E.164.
+     */
+    static normalizeToE164(rawPhone: string, defaultCountry?: string): SmsNormalizationResult;
+    /**
+     * Génère le texte de consentement légal obligatoire conforme TCPA & CTIA / RGPD.
+     */
+    static generateTcpaDisclosure(options: DisclosureOptions): string;
+    /**
+     * Crée un enregistrement probatoire de consentement légal horodaté et haché (Audit Proof Ledger).
+     */
+    static createConsentRecord(projectId: string, rawPhone: string, countryCode: string, disclosureOptions: DisclosureOptions, metadata?: {
+        campaignId?: string;
+        ipAddress?: string;
+        userAgent?: string;
+    }): Promise<TcpaConsentRecord>;
+    private static sha256;
+}

package/dist/social-ad-creative-intelligence.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 🎨 Social Ad Creative Intelligence & Carousel Generator
+ *
+ * Provides:
+ * 1. Multi-platform Ad Campaign Briefs & Copywriting Frameworks (Meta, TikTok, LinkedIn).
+ * 2. Vector SVG Carousel Slide Generator (LinkedIn & Instagram 1080x1080 / 1080x1350).
+ * 3. Creative Fatigue & Frequency Decay Diagnostics.
+ */
+export interface AdCampaignBriefInput {
+    brandName: string;
+    offer: string;
+    targetAudience: string;
+    primaryBenefit: string;
+    platform: "meta" | "tiktok" | "linkedin";
+    objective?: "lead_generation" | "conversion" | "brand_awareness";
+}
+export interface SocialAdCampaignBrief {
+    platform: "meta" | "tiktok" | "linkedin";
+    angle: string;
+    hookOptions: string[];
+    primaryText: string;
+    headline: string;
+    callToAction: string;
+    creativeDirection: {
+        format: "single_image" | "carousel" | "short_video_9_16";
+        visualConcept: string;
+        bRollIdeas: string[];
+    };
+}
+export type AdCampaignBrief = SocialAdCampaignBrief;
+export interface SocialAdCarouselSlide {
+    slideNumber: number;
+    totalSlides: number;
+    eyebrow?: string;
+    title: string;
+    description: string;
+    badge?: string;
+}
+export type CarouselSlide = SocialAdCarouselSlide;
+export declare class SocialAdCreativeIntelligence {
+    /**
+     * Generates a platform-native ad brief with hook variations and creative concept.
+     */
+    static generateCampaignBrief(input: AdCampaignBriefInput): AdCampaignBrief;
+    /**
+     * Generates production-ready standalone SVG code for a multi-slide carousel.
+     */
+    static generateCarouselSvgSlides(brandName: string, slides: CarouselSlide[], dimensions?: {
+        width: number;
+        height: number;
+    }): string[];
+    /**
+     * Diagnoses creative fatigue and saturation based on frequency, CTR decline, and impressions.
+     */
+    static auditCreativeFatigue(metrics: {
+        frequency: number;
+        ctrTrendPercent: number;
+        totalImpressions: number;
+        daysActive: number;
+    }): {
+        fatigueStatus: "healthy" | "early_warning" | "severe_fatigue";
+        recommendation: string;
+        fatigueScore: number;
+    };
+}