@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/serp/serp-features.d.ts

@@ -0,0 +1,10 @@
+export type SerpFeature = 'ai_overview' | 'featured_snippet' | 'people_also_ask' | 'knowledge_panel' | 'local_pack' | 'image_pack' | 'video_carousel' | 'sitelinks' | 'shopping' | 'top_stories' | 'reviews' | 'faq' | 'other';
+export declare const SERP_FEATURES: SerpFeature[];
+export declare function classifyFeatures(raw: string[]): SerpFeature[];
+export declare function aiOverviewImpact(rows: Array<{
+    inAiOverview?: boolean;
+    position?: number;
+}>): {
+    aiOverviewCount: number;
+    avgPositionWhenAiOverview: number;
+};

package/dist/serp/serp-history.d.ts

@@ -0,0 +1,21 @@
+export interface SerpSnapshot {
+    siteId: string;
+    keywordId: string;
+    keyword: string;
+    device: 'desktop' | 'mobile';
+    location: string;
+    date: string;
+    position?: number;
+    url?: string;
+    title?: string;
+    serpFeatures: string[];
+    inAiOverview?: boolean;
+    checkedAt: string;
+}
+export declare function visibilityScore(rows: SerpSnapshot[]): {
+    top1: number;
+    top3: number;
+    top10: number;
+    visibility: number;
+};
+export declare function rankDelta(a?: number, b?: number): number | null;

package/dist/serp-alert-dispatcher.d.ts

@@ -0,0 +1,119 @@
+/**
+ * serp-alert-dispatcher.ts
+ *
+ * Dispatcher d'alertes SERP pour Discord, Slack et webhooks génériques.
+ * Calcule les deltas de positions entre deux snapshots et génère des payloads
+ * formatés pour chaque canal de notification.
+ */
+export interface RankSnapshot {
+    keyword: string;
+    url: string;
+    position: number;
+    hasFeaturedSnippet?: boolean;
+    hasPaa?: boolean;
+    hasLocalPack?: boolean;
+    snapshotDate: string;
+}
+export interface RankDelta {
+    keyword: string;
+    url: string;
+    previousPosition: number;
+    currentPosition: number;
+    positionChange: number;
+    previousFeaturedSnippet: boolean;
+    currentFeaturedSnippet: boolean;
+    lostFeaturedSnippet: boolean;
+    gainedFeaturedSnippet: boolean;
+    alertLevel: 'critical' | 'warning' | 'info' | 'positive';
+    alertReason: string;
+}
+export interface AlertThresholds {
+    criticalDropPositions?: number;
+    warningDropPositions?: number;
+    top3EntryPositions?: number;
+    top10ExitPositions?: number;
+    featuredSnippetLoss?: boolean;
+}
+export interface DiscordEmbedField {
+    name: string;
+    value: string;
+    inline?: boolean;
+}
+export interface DiscordEmbed {
+    title: string;
+    description: string;
+    color: number;
+    fields: DiscordEmbedField[];
+    footer: {
+        text: string;
+    };
+    timestamp: string;
+}
+export interface DiscordWebhookPayload {
+    username: string;
+    avatar_url?: string;
+    embeds: DiscordEmbed[];
+}
+export interface SlackBlock {
+    type: string;
+    text?: {
+        type: string;
+        text: string;
+    };
+    fields?: Array<{
+        type: string;
+        text: string;
+    }>;
+    elements?: Array<{
+        type: string;
+        text?: {
+            type: string;
+            text: string;
+        };
+        url?: string;
+    }>;
+}
+export interface SlackWebhookPayload {
+    text: string;
+    blocks: SlackBlock[];
+}
+export interface GenericWebhookPayload {
+    event: 'serp_alert';
+    timestamp: string;
+    domain: string;
+    alertLevel: string;
+    deltas: RankDelta[];
+    summary: string;
+}
+export interface AlertDispatchOptions {
+    domain?: string;
+    thresholds?: AlertThresholds;
+    maxAlertsPerPayload?: number;
+}
+export interface AlertDispatchResult {
+    deltas: RankDelta[];
+    criticalCount: number;
+    warningCount: number;
+    positiveCount: number;
+    discordPayload: DiscordWebhookPayload;
+    slackPayload: SlackWebhookPayload;
+    genericPayload: GenericWebhookPayload;
+    summaryMarkdown: string;
+    hasAlerts: boolean;
+}
+export declare class SerpAlertDispatcher {
+    static computeDeltas(previous: RankSnapshot[], current: RankSnapshot[], thresholds?: AlertThresholds): RankDelta[];
+    static buildDiscordPayload(deltas: RankDelta[], domain?: string, maxAlerts?: number): DiscordWebhookPayload;
+    static buildSlackPayload(deltas: RankDelta[], domain?: string, maxAlerts?: number): SlackWebhookPayload;
+    static buildGenericPayload(deltas: RankDelta[], domain?: string): GenericWebhookPayload;
+    private static buildSummaryMarkdown;
+    static dispatch(previous: RankSnapshot[], current: RankSnapshot[], options?: AlertDispatchOptions): AlertDispatchResult;
+    /**
+     * Envoie directement les alertes à un endpoint webhook (Discord, Slack, ou API personnalisée).
+     */
+    static sendWebhook(webhookUrl: string, result: AlertDispatchResult, channel?: 'discord' | 'slack' | 'generic', fetchFn?: typeof fetch): Promise<{
+        success: boolean;
+        status?: number;
+        error?: string;
+    }>;
+}

package/dist/serp-client.d.ts

@@ -1,9 +1,104 @@
 /**
- * 🔎 LynxFlow SERP & Keyword Ranking Client
+ * 🔎 LynxSEO SERP & Keyword Ranking Client
  *
- * Tracks keyword rankings on Google across multiple countries and languages,
- * discovers search volume, and analyzes AI Overview features.
+ * Free-first, multi-engine SERP client. No proprietary endpoint is baked in.
+ *
+ * Provider priority (first configured wins, then free fallback):
+ *   1. OpenSERP  — self-hosted Go microservice, no API key  → OPENSERP_URL
+ *   2. SearXNG   — self-hosted meta-search engine, no key   → SEARXNG_URL
+ *   3. DuckDuckGo HTML endpoint — free, no key, always works (final fallback)
+ *
+ * Keyword suggestions use the public DuckDuckGo autocomplete endpoint (free).
  */
+import { type FailedSerpCheck, type SerpRetryQueueState } from "./serp-retry-queue";
+export type SerpEngine = "google" | "bing" | "duckduckgo" | "yandex" | "baidu";
+export type SerpProvider = "openserp" | "searxng" | "serper" | "valueserp" | "searchapi" | "spaceserp" | "duckduckgo";
+export interface SerpResultItem {
+    position: number;
+    title: string;
+    url: string;
+    snippet: string;
+    domain: string;
+    /** Données de crawl natif (robots.txt, crawlabilité) enrichies a posteriori. */
+    crawlData?: SerpCrawlData;
+}
+/** Données de crawl natif pour une URL SERP. */
+export interface SerpCrawlData {
+    robotsAllowed: boolean;
+    crawlDelay?: number;
+    sitemap?: string;
+    fetchedAt: string;
+}
+export interface SerpProviderConfig {
+    name: SerpProvider;
+    apiKey?: string;
+    baseUrl?: string;
+    enabled: boolean;
+}
+export interface SerpFeatureItem {
+    id?: string;
+    type: "ai_overview" | "answer_box" | "people_also_ask" | "related_searches" | "knowledge_graph" | string;
+    title?: string;
+    text?: string;
+    url?: string;
+}
+export interface ExtractedUrlContent {
+    url: string;
+    title: string;
+    description: string;
+    markdown: string;
+    text: string;
+    canonical?: string;
+    lang?: string;
+    tookMs?: number;
+}
+export interface SerpAnalysisResult {
+    keyword: string;
+    country: string;
+    engine: SerpEngine;
+    totalResults: number;
+    rankings: SerpResultItem[];
+    aiOverviewSnippet?: string;
+    peopleAlsoAsk: string[];
+    features?: SerpFeatureItem[];
+    provider: string;
+    /** True when results come from a live network call, false on graceful degradation. */
+    isLive: boolean;
+}
+/** Résultat brut d'une seule source SERP. */
+export interface SerpSourceResult {
+    provider: string;
+    items: SerpResultItem[];
+    aiOverview?: string;
+    peopleAlsoAsk: string[];
+    features: SerpFeatureItem[];
+    tookMs: number;
+    error?: string;
+}
+/** Résultat d'agrégation de plusieurs sources SERP. */
+export interface SerpAggregationResult {
+    keyword: string;
+    country: string;
+    engine: SerpEngine;
+    /** Résultats fusionnés et dédupliqués, triés par score de confiance. */
+    rankings: SerpResultItem[];
+    /** Nombre total de résultats uniques. */
+    totalResults: number;
+    /** Vue d'ensemble par source. */
+    sources: SerpSourceResult[];
+    /** Meilleur snippet AI Overview trouvé. */
+    aiOverviewSnippet?: string;
+    /** Questions "People Also Ask" fusionnées. */
+    peopleAlsoAsk: string[];
+    /** Features SERP fusionnées. */
+    features: SerpFeatureItem[];
+    /** Source qui a fourni le plus de résultats. */
+    primaryProvider: string;
+    /** Tous les résultats sont-ils en direct (live) ? */
+    isLive: boolean;
+    /** Timestamp de l'agrégation. */
+    aggregatedAt: string;
+}
 export interface KeywordRankingItem {
     keyword: string;
     position: number;
@@ -14,29 +109,106 @@ export interface KeywordRankingItem {
     hasAiOverview: boolean;
     country: string;
 }
-export interface SerpAnalysisResult {
-    keyword: string;
-    country: string;
-    totalResults: number;
-    rankings: {
-        position: number;
-        title: string;
-        url: string;
-        snippet: string;
-    }[];
-    aiOverviewSnippet?: string;
-    peopleAlsoAsk: string[];
+export interface SerpClientOptions {
+    /** Base URL of a self-hosted OpenSERP instance, e.g. "http://127.0.0.1:7000". */
+    openSerpUrl?: string;
+    /** Base URL of a self-hosted SearXNG instance, e.g. "http://127.0.0.1:8888". */
+    searxngUrl?: string;
+    /** Engines requested from OpenSERP / SearXNG providers. Defaults to ["google"]. */
+    engines?: SerpEngine[];
+    /** Fournisseurs SERP payants avec clés API, ordonnés par priorité. */
+    paidProviders?: SerpProviderConfig[];
 }
+export declare function normalizeSerpDomain(input: string): string;
 export declare class SerpClient {
-    private apiKey;
-    private endpoint;
-    constructor(apiKey: string, endpoint?: string);
+    private openSerpUrl?;
+    private searxngUrl?;
+    private engines;
+    private dragonfly;
+    /** État de la file de reprise pour les vérifications SERP échouées (G9). */
+    private retryQueue;
+    /** Fournisseurs SERP payants avec clé API, ordonnés par priorité. */
+    private paidProviders;
+    constructor(options?: SerpClientOptions | string);
+    /** Which live provider will be used, in priority order. */
+    getProviderName(): string;
+    private fetchOpenSerp;
+    private fetchSearxng;
+    private fetchSerper;
+    private fetchValueSerp;
+    private fetchSearchApi;
+    private fetchSpaceSerp;
+    private fetchDuckDuckGoHtml;
+    /**
+     * Runs a live SERP query. AGRÉGATION (pas de fallback) : interroge toutes
+     * les sources disponibles en parallèle, fusionne et déduplique les résultats.
+     *
+     * Ordre de priorité pour le score de confiance :
+     *   1. OpenSERP  (self-hosté, données structurées SEO)
+     *   2. SearXNG   (self-hosté, métamoteur 100+ sources)
+     *   3. Fournisseurs payants (Serper, ValueSERP, SearchAPI, SpaceSERP)
+     *   4. DuckDuckGo (gratuit, dernier recours)
+     *
+     * Les résultats sont fusionnés par URL (déduplication), triés par score
+     * de confiance de la source puis par position.
+     */
+    search(keyword: string, country?: string, engine?: SerpEngine, options?: {
+        limit?: number;
+    }): Promise<SerpAnalysisResult>;
+    /**
+     * Agrégation détaillée : retourne un `SerpAggregationResult` avec le détail
+     * par source, idéal pour les tableaux de bord de transparence SERP.
+     */
+    aggregateSearch(keyword: string, country?: string, engine?: SerpEngine, options?: {
+        limit?: number;
+    }): Promise<SerpAggregationResult>;
+    /**
+     * Appelle le fournisseur payant approprié selon son nom.
+     */
+    private fetchPaidProvider;
+    /**
+     * Fusionne et déduplique une liste de résultats SERP par URL normalisée.
+     * Garde la première occurrence (la source la plus prioritaire vient en premier
+     * dans `allItems` grâce à l'ordre d'ajout dans `search()`).
+     */
+    private mergeAndDeduplicateSources;
+    /**
+     * Déduplique les features SERP par (type, title).
+     */
+    private deduplicateFeatures;
+    /**
+     * Enrichit un résultat SERP avec les données de crawl natif (robots.txt)
+     * pour chaque domaine unique. Limite le nombre de requêtes pour éviter le
+     * sur-sollicitation des serveurs cibles.
+     */
+    private enrichWithCrawlData;
+    /**
+     * Extracts clean Markdown content and metadata from any URL using OpenSERP's /extract
+     * endpoint, with automatic fallback to basic readability extraction and Dragonfly caching.
+     */
+    extractMarkdown(targetUrl: string, options?: {
+        clean?: boolean;
+        useLLMSTxt?: boolean;
+    }): Promise<ExtractedUrlContent | null>;
     /**
-     * Tracks a keyword ranking on Google for the client's domain.
+     * Real keyword ranking check: runs a live SERP query and locates the domain.
+     * There is no search-volume or difficulty source without a paid provider, so those
+     * are reported as 0 rather than invented.
+     *
+     * When a tracked domain is not found (position 0), the check is enqueued in the
+     * retry queue so it can be retried with backoff (G9).
      */
     trackKeyword(keyword: string, country?: string, domain?: string): Promise<KeywordRankingItem>;
+    /** Returns the current retry queue state. */
+    getRetryQueueState(): SerpRetryQueueState;
+    /** Returns checks that are due for retry, ordered by next attempt. */
+    getDueRetryChecks(limit?: number): FailedSerpCheck[];
+    /** Marks a retry queue entry as succeeded and removes it. */
+    markRetrySucceeded(id: string): void;
+    /** Manually enqueues a keyword/domain/engine combination for retry. */
+    enqueueRetry(keyword: string, domain: string, engine?: SerpEngine, error?: string, lastKnownPosition?: number | null): void;
     /**
-     * Discovers related keywords, search volume, and People Also Ask questions.
+     * Real keyword suggestions via the free DuckDuckGo autocomplete endpoint.
      */
-    getKeywordSuggestions(seedKeyword: string, country?: string): Promise<string[]>;
+    getKeywordSuggestions(seedKeyword: string, _country?: string): Promise<string[]>;
 }

package/dist/serp-features-scorer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 📊 SERP Features Visibility Scorer
+ *
+ * Evaluates a domain's presence across modern Google SERP Rich Features:
+ * - AI Overviews (SGE / Gemini summaries)
+ * - Featured Snippets (Position 0)
+ * - People Also Ask (PAA)
+ * - Local 3-Pack
+ * - Image & Video Carousels
+ * - Sitelinks & Knowledge Panels
+ *
+ * Computes an overall SERP Feature Dominance Score (0-100%) and actionable win-rate metrics.
+ */
+export type SerpFeatureType = "ai_overview" | "featured_snippet" | "people_also_ask" | "local_pack" | "image_carousel" | "video_carousel" | "sitelinks" | "knowledge_panel";
+export interface KeywordSerpFeatureEntry {
+    keyword: string;
+    url: string;
+    organicPosition: number;
+    serpFeaturesPresent: SerpFeatureType[];
+    domainFeaturesOwned: SerpFeatureType[];
+}
+export interface SerpFeaturesAuditResult {
+    totalKeywordsAnalyzed: number;
+    overallFeatureDominanceScore: number;
+    aiOverviewWinRate: number;
+    featuredSnippetWinRate: number;
+    paaPresenceRate: number;
+    localPackPresenceRate: number;
+    mediaCarouselsPresenceRate: number;
+    richFeaturesCount: Record<SerpFeatureType, {
+        presentOnSerp: number;
+        ownedByDomain: number;
+    }>;
+    topOpportunities: string[];
+    summary: string;
+}
+export declare class SerpFeaturesScorer {
+    private static readonly FEATURE_WEIGHTS;
+    /**
+     * Computes comprehensive SERP feature dominance metrics for a list of target queries.
+     */
+    static evaluateDomain(entries: KeywordSerpFeatureEntry[]): SerpFeaturesAuditResult;
+}

package/dist/serp-retry-queue.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Retry queue and pagination planning for failed SERP rank checks.
+ *
+ * Everything here is pure and synchronous: callers persist the returned
+ * state wherever they like (KV, D1, Postgres) and drive the retries.
+ */
+export interface FailedSerpCheck {
+    id: string;
+    keyword: string;
+    domain: string;
+    engine: string;
+    attempts: number;
+    lastError: string;
+    firstFailedAt: string;
+    lastAttemptAt: string;
+    nextAttemptAt: string;
+    lastKnownPosition?: number | null;
+}
+export interface SerpRetryQueueState {
+    entries: FailedSerpCheck[];
+    updatedAt: string;
+}
+export declare function serpCheckId(keyword: string, domain: string, engine: string): string;
+export declare function backoffDelayMs(attempts: number, baseDelayMs?: number, maxDelayMs?: number): number;
+export declare function enqueueFailedCheck(state: SerpRetryQueueState | null, input: {
+    keyword: string;
+    domain: string;
+    engine: string;
+    error: string;
+    lastKnownPosition?: number | null;
+    now?: Date;
+}, options?: {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}): SerpRetryQueueState;
+export declare function markCheckSucceeded(state: SerpRetryQueueState, id: string, now?: Date): SerpRetryQueueState;
+export declare function dueChecks(state: SerpRetryQueueState, now?: Date, limit?: number): FailedSerpCheck[];
+export declare function buildSmartPaginationPlan(lastKnownPosition: number | null | undefined, options?: {
+    resultsPerPage?: number;
+    maxResults?: number;
+    pagesAround?: number;
+}): {
+    pages: number[];
+    start: number;
+    depth: number;
+};
+export declare function matchesTrackedDomain(resultUrl: string, trackedDomain: string, options?: {
+    includeSubdomains?: boolean;
+}): boolean;

package/dist/server-log-parser.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Apache/Nginx access-log parser used to reconcile server traffic with
+ * analytics: real Googlebot/AI-crawler hits, 404s, status mix and top paths.
+ * Parsing is bounded by line count and line length so a hostile log file
+ * cannot exhaust the worker.
+ */
+export interface ParsedServerLogEntry {
+    ip: string;
+    timestamp: string | null;
+    method: string;
+    path: string;
+    protocol: string;
+    status: number;
+    bytes: number;
+    referrer: string | null;
+    userAgent: string | null;
+}
+export interface ServerLogSummary {
+    totalLines: number;
+    parsedLines: number;
+    malformedLines: number;
+    uniqueIps: number;
+    humanRequests: number;
+    botRequests: number;
+    unknownUserAgentRequests: number;
+    notFoundRequests: number;
+    serverErrorRequests: number;
+    bandwidthBytes: number;
+    statusClasses: {
+        "2xx": number;
+        "3xx": number;
+        "4xx": number;
+        "5xx": number;
+        other: number;
+    };
+    topPaths: Array<{
+        path: string;
+        hits: number;
+    }>;
+    aiCrawlers: Array<{
+        operator: string;
+        hits: number;
+    }>;
+    topBots: Array<{
+        bot: string;
+        hits: number;
+    }>;
+}
+export interface ServerLogSummaryOptions {
+    maxLines?: number;
+    maxLineLength?: number;
+    topPathsLimit?: number;
+    topBotsLimit?: number;
+}
+export declare function parseServerLogLine(line: string, maxLineLength?: number): ParsedServerLogEntry | null;
+export declare function summarizeServerLog(input: string | Iterable<string>, options?: ServerLogSummaryOptions): ServerLogSummary;

package/dist/session-replay-adapted.d.ts

@@ -0,0 +1,27 @@
+/**
+ * LynxSEO Session Replay Integration Bridge
+ *
+ * Copies and integrates OpenReplay adapted modules with LynxSEO's existing
+ * session replay system. All source references are to private local files,
+ * not the inspiration/ directory (per provenance-guard).
+ *
+ * Licensed under AGPLv3 - adapted from OpenReplay tracker (AGPLv3).
+ * Original licenses preserved per AGENTS.md §8.
+ */
+export * from "./tracker-adapted/console-adapted";
+export * from "./tracker-adapted/network-adapted";
+export * from "./tracker-adapted/performance-adapted";
+export * from "./tracker-adapted/mouse-adapted";
+export * from "./tracker-adapted/input-adapted";
+export * from "./tracker-adapted/exception-adapted";
+export * from "./tracker-adapted/state-adapted";
+/**
+ * Utility functions for OpenReplay integration
+ */
+export { patchConsole as patchConsoleAdapted } from "./tracker-adapted/console-adapted";
+export { isIgnoredHeader } from "./tracker-adapted/network-adapted";
+export { computeSpeedIndex } from "./tracker-adapted/performance-adapted";
+export { getCSSPath } from "./tracker-adapted/mouse-adapted";
+export { getMaskType, maskInputValue, MaskType, } from "./tracker-adapted/input-adapted";
+export { parseStack, formatException, } from "./tracker-adapted/exception-adapted";
+export { initStateTracker, takeStateSnapshot, } from "./tracker-adapted/state-adapted";

package/dist/session-replay-recorder.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session replay recorder for the Pulse tracking snippet.
+ *
+ * The dashboard replays recordings with the real `rrweb` player, so this
+ * generator emits the same event format rather than a private one:
+ *  - `type: 2` FullSnapshot, `type: 4` Meta, `type: 3` IncrementalSnapshot;
+ *  - incremental sources 1 (mousemove), 2 (mouse interaction), 3 (scroll),
+ *    4 (viewport resize), 5 (input).
+ *
+ * It is intentionally small (no rrweb dependency on the customer's site) and
+ * privacy-first: input values and `[data-lynx-private]` subtrees are masked,
+ * `on*` handlers are never serialized, and every chunk is authorised by a
+ * short-lived signed token minted by `/api/pulse/v1/replay-token`.
+ */
+export interface SessionReplayRecorderOptions {
+    /** Project/domain identifier used by the tracker (`data-domain`). */
+    projectId: string;
+    /** Chunk ingest endpoint. Defaults to `/api/pulse/v1/replay`. */
+    endpointUrl?: string;
+    /** Token endpoint. Defaults to `/api/pulse/v1/replay-token`. */
+    tokenUrl?: string;
+    /** 0..1. A sampled-out visitor records nothing. Defaults to 1. */
+    sampleRate?: number;
+    /** Masks every input value. Defaults to true. */
+    maskAllInputs?: boolean;
+    /** Masks every text node. Defaults to false. */
+    maskAllText?: boolean;
+    /** Selector whose subtree is fully masked. Defaults to `[data-lynx-private]`. */
+    maskTextSelector?: string;
+    /** Hard cap on serialized nodes, so a huge DOM cannot blow up the chunk. */
+    maxNodes?: number;
+    /** Buffer flush cadence in milliseconds. Defaults to 15000. */
+    flushIntervalMs?: number;
+    /** Maximum events per chunk. Defaults to 60. */
+    maxEventsPerChunk?: number;
+    /**
+     * Hard cap on a recording, in milliseconds. Past it the recorder flushes
+     * and stops capturing. Defaults to 5 minutes, matching the ingest cap.
+     */
+    maxDurationMs?: number;
+    /**
+     * Reads `data-replay`, `data-replay-sample`, `data-mask-inputs`,
+     * `data-site-id` and `data-domain` from the script tag at runtime (CDN
+     * bundle). In this mode recording is opt-in: `data-replay="true"` enables it.
+     */
+    readScriptTag?: boolean;
+    /**
+     * Forces recording regardless of `data-replay`. Only for callers that have
+     * an explicit server-side opt-in (tests, self-hosted embed).
+     */
+    enabled?: boolean;
+}
+export declare function generateSessionReplayRecorderJs(options: SessionReplayRecorderOptions): string;

package/dist/shopify-autopilot-bridge.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 🛍️ Shopify Autopilot Bridge
+ *
+ * Implements the signature e-commerce content monetization:
+ * - Automatically matches Shopify product catalog against SEO / GEO article topics
+ * - Injects high-converting responsive product showcase cards directly into the blog article
+ * - Embeds Google Rich Snippets Schema.org "Product" microdata
+ * - Generates ready-to-publish payloads for Shopify REST & GraphQL Admin APIs
+ */
+export interface ShopifyProduct {
+    id: string | number;
+    title: string;
+    handle: string;
+    vendor?: string;
+    productType?: string;
+    tags?: string[];
+    price: number | string;
+    compareAtPrice?: number | string;
+    currency?: string;
+    imageUrl?: string;
+    rating?: number;
+    reviewCount?: number;
+    variantId?: string | number;
+    url?: string;
+}
+export interface MatchedProductCard {
+    product: ShopifyProduct;
+    relevanceScore: number;
+    injectionPosition: "middle" | "bottom" | "after_heading";
+    buyButtonUrl: string;
+}
+export interface ShopifyArticleInput {
+    title: string;
+    bodyHtml: string;
+    author?: string;
+    tags?: string[];
+    summary?: string;
+    publishedAt?: string;
+    featuredImageUrl?: string;
+}
+export interface ShopifyRestPayload {
+    article: {
+        title: string;
+        body_html: string;
+        author?: string;
+        tags?: string;
+        summary_html?: string;
+        published_at?: string;
+        image?: {
+            src: string;
+        };
+    };
+}
+export declare class ShopifyAutopilotBridge {
+    /**
+     * Matches products from a store catalog against the text of an SEO article.
+     */
+    static matchProducts(articleText: string, catalog: ShopifyProduct[], maxProducts?: number): MatchedProductCard[];
+    /**
+     * Injects styled product showcase cards into an HTML article.
+     */
+    static injectProductCards(bodyHtml: string, matchedProducts: MatchedProductCard[], options?: {
+        currencySymbol?: string;
+    }): string;
+    /**
+     * Formats an article into the exact Shopify REST Admin API JSON payload.
+     */
+    static formatShopifyRestPayload(input: ShopifyArticleInput): ShopifyRestPayload;
+}