@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/clickhouse/client.d.ts

@@ -0,0 +1,21 @@
+export interface ClickHouseConfig {
+    url: string;
+    database?: string;
+    username?: string;
+    password?: string;
+    timeoutMs?: number;
+}
+export interface QueryOptions {
+    queryId?: string;
+    params?: Record<string, unknown>;
+    format?: string;
+}
+export declare class ClickHouseClient {
+    private cfg;
+    constructor(cfg: ClickHouseConfig);
+    private headers;
+    query<T = unknown>(sql: string, opts?: QueryOptions): Promise<T[]>;
+    stream<T = unknown>(sql: string, opts?: QueryOptions): AsyncGenerator<T>;
+    insert(table: string, rows: unknown[]): Promise<void>;
+    cancel(queryId: string): Promise<void>;
+}

package/dist/clickhouse/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./migrate";

package/dist/clickhouse/migrate-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clickhouse/migrate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ClickHouse Migration Runner
+ */
+import { ClickHouseClient } from "./client";
+export declare function runClickHouseMigrations(client: ClickHouseClient): Promise<void>;
+export default runClickHouseMigrations;

package/dist/clickhouse/migrations/001_raw_events.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS seo_events_raw (
+  event_id String,
+  project_id String,
+  type String,
+  domain String,
+  event_date DateTime64(3),
+  payload String,
+  inserted_at DateTime64(3) DEFAULT now64(3)
+)
+ENGINE = ReplacingMergeTree(inserted_at)
+PARTITION BY toYYYYMM(event_date)
+ORDER BY (project_id, event_date, event_id)
+TTL event_date + INTERVAL 90 DAY TO VOLUME 'hot',
+    event_date + INTERVAL 365 DAY DELETE;

package/dist/clickhouse/migrations/002_analytics.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS seo_events_analytics (
+  project_id String,
+  metric_name String,
+  metric_value Float64,
+  bucket DateTime64(3),
+  inserted_at DateTime64(3) DEFAULT now64(3)
+)
+ENGINE = ReplacingMergeTree(inserted_at)
+PARTITION BY toYYYYMM(bucket)
+ORDER BY (project_id, bucket, metric_name);

package/dist/clickhouse/migrations/003_crawl.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS seo_crawl_logs (
+  crawl_id String,
+  project_id String,
+  url String,
+  status_code UInt16,
+  duration_ms UInt32,
+  event_date DateTime64(3),
+  inserted_at DateTime64(3) DEFAULT now64(3)
+)
+ENGINE = ReplacingMergeTree(inserted_at)
+PARTITION BY toYYYYMM(event_date)
+ORDER BY (project_id, event_date, crawl_id);

package/dist/clickhouse/migrations/004_rank.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS seo_rank_snapshots (
+  snapshot_id String,
+  project_id String,
+  keyword String,
+  position Float64,
+  event_date DateTime64(3),
+  inserted_at DateTime64(3) DEFAULT now64(3)
+)
+ENGINE = ReplacingMergeTree(inserted_at)
+PARTITION BY toYYYYMM(event_date)
+ORDER BY (project_id, event_date, keyword);

package/dist/clickhouse/migrations/005_backlink.sql

@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS seo_backlink_checks (
+  check_id String,
+  project_id String,
+  source_url String,
+  target_url String,
+  status String,
+  event_date DateTime64(3),
+  inserted_at DateTime64(3) DEFAULT now64(3)
+)
+ENGINE = ReplacingMergeTree(inserted_at)
+PARTITION BY toYYYYMM(event_date)
+ORDER BY (project_id, event_date, check_id);

package/dist/clickhouse/migrations/006_mv_hourly.sql

@@ -0,0 +1,11 @@
+CREATE MATERIALIZED VIEW IF NOT EXISTS seo_events_hourly_mv
+ENGINE = SummingMergeTree()
+PARTITION BY toYYYYMM(bucket)
+ORDER BY (project_id, bucket, type)
+AS SELECT
+  project_id,
+  type,
+  toStartOfHour(event_date) AS bucket,
+  count() AS events_count
+FROM seo_events_raw
+GROUP BY project_id, type, bucket;

package/dist/clickhouse/migrations/007_pulse_mv_hourly.sql

@@ -0,0 +1,26 @@
+-- Agrégats horaires Pulse (table créée par apps/lynx-pulse-go, store ClickHouse).
+-- Alimente les séries du dashboard sans rescanner les événements bruts.
+-- Lecture : countMergeIf(events_state, …) pour les pageviews/conversions,
+-- uniqMerge(sessions_state) et uniqMerge(visitors_state) pour les uniques.
+--
+-- Filtre humain identique à analytics.IsHuman : ni robots ni web vitals, pour
+-- que la MV et le repli sur les lignes brutes produisent les mêmes chiffres.
+-- Une session active sur deux heures compte dans les deux (uniq par heure).
+-- Définition dupliquée dans apps/lynx-pulse-go/internal/store/clickhouse.go :
+-- les deux doivent rester identiques (nom par défaut pulse_events_hourly_mv).
+CREATE MATERIALIZED VIEW IF NOT EXISTS pulse_events_hourly_mv
+ENGINE = AggregatingMergeTree()
+PARTITION BY toYYYYMM(bucket)
+ORDER BY (project_id, bucket, type, event_name)
+POPULATE
+AS SELECT
+  project_id,
+  type,
+  event_name,
+  toStartOfHour(timestamp) AS bucket,
+  countState() AS events_state,
+  uniqState(session_id) AS sessions_state,
+  uniqState(visitor_id) AS visitors_state
+FROM pulse_events
+WHERE is_bot = 0 AND type NOT IN ('bot', 'web_vital')
+GROUP BY project_id, type, event_name, bucket;

package/dist/clickhouse/migrations/008_pulse_events_codec.sql

@@ -0,0 +1,34 @@
+-- ZSTD + projections de tri sur la table d'événements Pulse.
+--
+-- Les déploiements existants ont été créés par apps/lynx-pulse-go avec
+-- `CREATE TABLE IF NOT EXISTS` : leur table ne prend pas ces options toute
+-- seule. Les nouvelles installations les reçoivent directement dans le DDL Go
+-- (apps/lynx-pulse-go/internal/store/clickhouse.go, fonction `Init`) — les deux
+-- definitions doivent rester identiques.
+--
+-- Coût : chaque statement ci-dessous est une mutation (réécriture en
+-- arrière-plan des parties existantes). Lancer la migration hors de pointe et
+-- surveiller system.mutations avant d'enchaîner. Les colonnes compressées sont
+-- celles qui pèsent le plus et ne sont jamais dans une clé de tri ; `timestamp`
+-- garde Delta (série quasi monotone) avant ZSTD.
+ALTER TABLE pulse_events MODIFY COLUMN timestamp DateTime64(3, 'UTC') CODEC(Delta(8), ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN hostname String CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN pathname String CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN querystring String DEFAULT '' CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN page_title String DEFAULT '' CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN referrer String DEFAULT '' CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN city String DEFAULT '' CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN bot_reasons String DEFAULT '' CODEC(ZSTD(1));
+ALTER TABLE pulse_events MODIFY COLUMN props String DEFAULT '{}' CODEC(ZSTD(3));
+
+-- Deux secondes clés pour les filtres d'égalité des explorateurs : rapports par
+-- page (pathname) et drill-down d'une session. Sans elles, `WHERE project_id
+-- = … AND pathname = …` lit toutes les lignes de la fenêtre du projet.
+-- Projections `SELECT *` : compter un doublement du volume stocké.
+ALTER TABLE pulse_events ADD PROJECTION IF NOT EXISTS proj_pathname (SELECT * ORDER BY (project_id, pathname, timestamp));
+ALTER TABLE pulse_events ADD PROJECTION IF NOT EXISTS proj_session (SELECT * ORDER BY (project_id, session_id, timestamp));
+
+-- Rendre les parties déjà écrites dans les nouvelles clés (les insertions
+-- suivantes y passent seules).
+ALTER TABLE pulse_events MATERIALIZE PROJECTION proj_pathname;
+ALTER TABLE pulse_events MATERIALIZE PROJECTION proj_session;

package/dist/clickhouse-functions.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 🏭 ClickHouse — catalogue de fonctions, builder et DDL
+ *
+ * Deux besoins réels derrière ce module :
+ * 1. **stocker les flux vidéo (Session Replay) et les événements** dans une
+ *    base colonnaire, avec des agrégats qui ne s'effondrent pas à 10⁹ lignes ;
+ * 2. **laisser un utilisateur écrire du SQL analytique** (Metabase-like) sans
+ *    lui ouvrir une porte d'injection.
+ *
+ * Le catalogue expose les fonctions ClickHouse réellement disponibles, avec
+ * leur arité et leur catégorie. Il sert à trois choses : validation avant
+ * envoi (une fonction inconnue échoue côté serveur, pas côté base), rendu sûr
+ * des identifiants/littéraux, et autocomplétion dans l'éditeur SQL.
+ *
+ * Le builder et les helpers DDL ne concatènent **jamais** une valeur : les
+ * valeurs passent par des placeholders typés `{pN:Type}` (le protocole HTTP de
+ * ClickHouse), et les identifiants sont validés par `assertIdentifier`.
+ */
+export declare const CLICKHOUSE_FUNCTION_CATEGORIES: readonly ["aggregate", "window", "arithmetic", "date", "string", "array", "json", "conditional", "type", "url", "ip", "geo", "hash", "encoding", "search"];
+export type ClickHouseFunctionCategory = (typeof CLICKHOUSE_FUNCTION_CATEGORIES)[number];
+export interface ClickHouseFunctionSpec {
+    name: string;
+    category: ClickHouseFunctionCategory;
+    /** Paramètres attendus (noms indicatifs, pour l'aide et l'arité). */
+    params: readonly string[];
+    /** Si vrai, `params.length` est un minimum au lieu d'une arité exacte. */
+    variadic?: boolean;
+    returns: string;
+    description: string;
+}
+/**
+ * Catalogue des fonctions exposées.
+ *
+ * Volontairement limité aux fonctions stables et documentées : une entrée
+ * fausse ici produirait du SQL refusé par le serveur. Les fonctions
+ * expérimentales (`*_experimental`) sont exclues.
+ */
+export declare const CLICKHOUSE_FUNCTIONS: readonly ClickHouseFunctionSpec[];
+export declare function getFunctionSpec(name: string): ClickHouseFunctionSpec | null;
+export declare function listFunctions(category?: ClickHouseFunctionCategory): ClickHouseFunctionSpec[];
+/** Recherche insensible à la casse sur le nom et la description. */
+export declare function searchFunctions(query: string): ClickHouseFunctionSpec[];
+export declare function assertIdentifier(name: string): string;
+export declare function quoteIdentifier(name: string): string;
+export type ClickHouseArg = {
+    kind: "identifier";
+    value: string;
+} | {
+    kind: "literal";
+    value: string | number | boolean | null;
+} | {
+    kind: "expression";
+    value: string;
+};
+export declare function chIdent(name: string): ClickHouseArg;
+export declare function chLiteral(value: string | number | boolean | null): ClickHouseArg;
+export declare function chExpr(sql: string): ClickHouseArg;
+/**
+ * Valide une expression SQL fournie par l'appelant : pas de point-virgule, pas
+ * de commentaire, pas de mot-clé d'écriture. Ce n'est pas un parseur complet —
+ * c'est une barrière contre la concaténation accidentelle côté éditeur.
+ */
+export declare function assertSafeExpression(expression: string): string;
+/**
+ * Valide une clause `TTL` : elle contient légitimement le mot `DELETE` (et
+ * `TO VOLUME`/`TO DISK`), donc elle ne peut pas passer par
+ * `assertSafeExpression`, qui refuse les mots-clés d'écriture.
+ */
+export declare function assertTtlClause(clause: string): string;
+export declare function renderLiteral(value: string | number | boolean | null): string;
+export declare function renderArg(arg: ClickHouseArg): string;
+/** Rend `<fonction>(<args>)` après validation du nom et de l'arité. */
+export declare function renderFunctionCall(name: string, args: readonly ClickHouseArg[]): string;
+export interface ClickHouseQuery {
+    sql: string;
+    params: Record<string, unknown>;
+}
+export interface ClickHouseOrderBy {
+    expression: string;
+    direction?: "ASC" | "DESC";
+    nulls?: "NULLS FIRST" | "NULLS LAST";
+}
+export declare class ClickHouseQueryBuilder {
+    private selectParts;
+    private fromTable;
+    private readonly whereParts;
+    private readonly groupParts;
+    private readonly havingParts;
+    private readonly orderParts;
+    private limitValue;
+    private offsetValue;
+    private formatValue;
+    private readonly settingsMap;
+    private readonly params;
+    private paramIndex;
+    select(expression: string, alias?: string): this;
+    selectParam(value: string | number, alias: string, type?: "string" | "number" | "integer"): this;
+    from(table: string): this;
+    where(expression: string): this;
+    /** `col = {pN:Type}` — la valeur n'est jamais interpolée dans le SQL. */
+    equals(column: string, value: string | number | boolean, type?: "string" | "number" | "integer"): this;
+    groupBy(...expressions: string[]): this;
+    having(expression: string): this;
+    orderBy(expression: string, direction?: "ASC" | "DESC", nulls?: "NULLS FIRST" | "NULLS LAST"): this;
+    limit(value: number): this;
+    offset(value: number): this;
+    format(value: "JSONEachRow" | "JSON" | "CSV" | "TSV"): this;
+    setting(key: string, value: string | number): this;
+    /** Enregistre une valeur liée et renvoie son placeholder typé. */
+    param(value: string | number | boolean, type?: "string" | "number" | "integer"): string;
+    toSQL(): ClickHouseQuery;
+}
+export interface ClickHouseColumn {
+    name: string;
+    type: string;
+    defaultValue?: string;
+    comment?: string;
+}
+export interface MergeTreeDdlOptions {
+    table: string;
+    columns: readonly ClickHouseColumn[];
+    orderBy: readonly string[];
+    partitionBy?: string;
+    primaryKey?: string;
+    ttlClause?: string;
+    engine?: "MergeTree" | "ReplacingMergeTree" | "SummingMergeTree" | "AggregatingMergeTree";
+    settings?: Readonly<Record<string, number>>;
+}
+/** Génère `CREATE TABLE ... ENGINE = MergeTree() ORDER BY ...`. */
+export declare function buildMergeTreeDDL(options: MergeTreeDdlOptions): string;
+export interface MaterializedViewDdlOptions {
+    name: string;
+    targetTable: string;
+    select: string;
+    /** `POPULATE` remplit la vue avec l'historique existant. */
+    populate?: boolean;
+}
+/** Génère une vue matérialisée `TO` (recommandé pour les agrégats temps réel). */
+export declare function buildMaterializedViewDDL(options: MaterializedViewDdlOptions): string;
+/** `ALTER TABLE ... MODIFY TTL ...` à partir d'une clause générée. */
+export declare function buildTtlAlterStatement(table: string, ttlClause: string): string;

package/dist/cluster-generator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 🏭 Universal Programmatic SEO Cluster Generator (2026 Gold Standard)
+ *
+ * Fusion of:
+ * 1. Local landing-page builder: 4-layer data architecture, strict 5-FAQ rule, geo-mesh nearby linking
+ * 2. Dynamic anti-doorway auto-mutation (Instead of hiding duplicates, auto-mutates hooks, angles & FAQs)
+ * 3. Copy frameworks (PAS structure, transparent price ranges, 4 process steps)
+ * 4. `PersistentPageStore` (Persistent JSON / SQLite / WordPress Zero-DB-Saturation Edge Storage)
+ */
+import { ProgrammaticPageDocument, PageStoreAdapter } from "./persistent-page-store";
+export interface PseoBusinessConfig {
+    name: string;
+    legalName?: string;
+    owner?: string;
+    phone: string;
+    phoneHref: string;
+    email: string;
+    website: string;
+    license?: string;
+    yearEstablished?: number;
+    schemaType: string;
+    address?: {
+        street?: string;
+        city: string;
+        state?: string;
+        zip: string;
+        country?: string;
+    };
+    coordinates?: {
+        lat: number;
+        lng: number;
+    };
+}
+export interface PseoServiceDefinition {
+    slug: string;
+    name: string;
+    shortDescription: string;
+    priceRange: {
+        min: number;
+        max: number;
+        currency: string;
+    };
+    emergency: boolean;
+    processSteps: Array<{
+        title: string;
+        description: string;
+    }>;
+}
+export interface PseoAreaDefinition {
+    slug: string;
+    name: string;
+    region?: string;
+    zipCodes: string[];
+    responseTime: string;
+    nearby: string[];
+    coordinates?: {
+        lat: number;
+        lng: number;
+    };
+}
+export interface ClusterGenerationResult {
+    totalPages: number;
+    publishedCount: number;
+    mutatedCount: number;
+    documents: ProgrammaticPageDocument[];
+}
+export declare class PseoClusterEngine {
+    private store;
+    constructor(adapter?: PageStoreAdapter);
+    /**
+     * Generates the strict 5-FAQ items per location according to 2026 pSEO guidelines
+     */
+    generate5Faqs(params: {
+        business: PseoBusinessConfig;
+        service: PseoServiceDefinition;
+        area: PseoAreaDefinition;
+        mutationAngleIndex?: number;
+    }): Array<{
+        question: string;
+        answer: string;
+    }>;
+    /**
+     * Generates a single combination page with dynamic mutation angle
+     */
+    generateComboPage(params: {
+        business: PseoBusinessConfig;
+        service: PseoServiceDefinition;
+        area: PseoAreaDefinition;
+        allAreasMap: Map<string, PseoAreaDefinition>;
+        allServices: PseoServiceDefinition[];
+        angleIndex?: number;
+    }): Promise<ProgrammaticPageDocument>;
+    /**
+     * Generates an entire cluster (All Services x All Areas)
+     * WITH AUTO-MUTATION: If Jaccard >= 0.85, the page is AUTOMATICALLY RE-MUTATED
+     * with a new editorial angle instead of being hidden!
+     */
+    generateCluster(params: {
+        business: PseoBusinessConfig;
+        services: PseoServiceDefinition[];
+        areas: PseoAreaDefinition[];
+    }): Promise<ClusterGenerationResult>;
+}

package/dist/cms-publication-client.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 🚀 CmsPublicationClient — Direct CMS & commerce publishing client
+ *
+ *
+ * Supports:
+ * - WordPress REST API (/wp/v2/posts) with Application Password
+ * - Yoast SEO & RankMath custom meta fields injection
+ * - Webflow CMS API Collection Items
+ * - Contentful Management API (entries + publish)
+ * - Sanity mutations API (documents + drafts)
+ * - Strapi REST API
+ * - WooCommerce products API
+ * - BigCommerce content pages API
+ */
+export interface WordPressConfig {
+    baseUrl: string;
+    username: string;
+    applicationPassword: string;
+}
+export interface WebflowConfig {
+    apiToken: string;
+    collectionId: string;
+}
+export interface PublishPostPayload {
+    title: string;
+    content: string;
+    slug?: string;
+    status: "draft" | "publish" | "future";
+    metaDescription?: string;
+    tags?: string[];
+    canonicalUrl?: string;
+    featuredImageUrl?: string;
+}
+export interface ContentfulConfig {
+    spaceId: string;
+    accessToken: string;
+    contentType: string;
+    environmentId?: string;
+    locale?: string;
+    /** Overrides the Contentful field ids; defaults to title/body/slug/metaDescription. */
+    fieldMap?: {
+        title?: string;
+        body?: string;
+        slug?: string;
+        metaDescription?: string;
+    };
+}
+export interface SanityConfig {
+    projectId: string;
+    dataset: string;
+    token: string;
+    documentType?: string;
+    apiVersion?: string;
+}
+export interface StrapiConfig {
+    baseUrl: string;
+    apiToken: string;
+    contentType?: string;
+}
+export interface WooCommerceConfig {
+    baseUrl: string;
+    consumerKey: string;
+    consumerSecret: string;
+}
+export interface BigCommerceConfig {
+    storeHash: string;
+    accessToken: string;
+}
+export interface PublishResult {
+    success: boolean;
+    targetCms: "wordpress" | "webflow" | "contentful" | "sanity" | "strapi" | "woocommerce" | "bigcommerce";
+    remotePostId?: string | number;
+    publishedUrl?: string;
+    status: "draft" | "publish" | "future";
+    error?: string;
+}
+export declare class CmsPublicationClient {
+    /**
+     * Publishes or drafts an article to WordPress REST API with Yoast SEO meta tags.
+     */
+    static publishToWordPress(config: WordPressConfig, payload: PublishPostPayload): Promise<PublishResult>;
+    /**
+     * Publishes or drafts an item to Webflow CMS Collection API.
+     */
+    static publishToWebflow(config: WebflowConfig, payload: PublishPostPayload): Promise<PublishResult>;
+    /**
+     * Creates a Contentful entry, then publishes it when the payload asks for it.
+     * Field ids default to title/body/slug/metaDescription and can be remapped.
+     */
+    static publishToContentful(config: ContentfulConfig, payload: PublishPostPayload): Promise<PublishResult>;
+    /**
+     * Creates a Sanity document. Drafts are written to the `drafts.` id namespace
+     * so they stay out of the published dataset until promoted.
+     */
+    static publishToSanity(config: SanityConfig, payload: PublishPostPayload): Promise<PublishResult>;
+    /**
+     * Creates an entry through the Strapi REST API.
+     */
+    static publishToStrapi(config: StrapiConfig, payload: PublishPostPayload): Promise<PublishResult>;
+    /**
+     * Creates a WooCommerce product with Yoast meta fields attached.
+     */
+    static publishToWooCommerce(config: WooCommerceConfig, payload: PublishPostPayload): Promise<PublishResult>;
+    /**
+     * Creates a BigCommerce content page.
+     */
+    static publishToBigCommerce(config: BigCommerceConfig, payload: PublishPostPayload): Promise<PublishResult>;
+}

package/dist/competitor-backlink-import.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 🥊 Competitor backlink import (G2)
+ *
+ * Tool exports (Ahrefs, Semrush, Majestic, Search Console, hand-made CSVs) all
+ * describe the same thing with different header names. This module turns any of
+ * them into one normalized shape so the app can index a competitor's backlinks
+ * without paying per call or re-deriving the mapping in the route.
+ *
+ * Pure and dependency-free: no network, no clock, no storage. The same input
+ * always yields the same output, so an import is replayable and testable.
+ */
+export type CompetitorImportFormat = "csv" | "json";
+export interface CompetitorBacklinkRow {
+    /** Competitor the row was imported for, normalized (`example.com`). */
+    competitorDomain: string;
+    /** URL of the linking page. */
+    sourceUrl: string;
+    /** Domain of the linking page, derived from `sourceUrl`. */
+    sourceDomain: string;
+    /** URL the competitor was linked from, when the export provides it. */
+    targetUrl: string | null;
+    anchor: string | null;
+    /** `null` when the export does not say (never guessed). */
+    isDofollow: boolean | null;
+    /** 0-100 authority metric (DA / DR / Trust Flow), whichever the export has. */
+    domainAuthority: number | null;
+    spamScore: number | null;
+    firstSeenAt: string | null;
+}
+export interface CompetitorBacklinkImportResult {
+    competitorDomain: string;
+    format: CompetitorImportFormat;
+    totalRows: number;
+    validRows: number;
+    skippedRows: number;
+    warnings: string[];
+    rows: CompetitorBacklinkRow[];
+}
+export interface CompetitorBacklinkImportOptions {
+    competitorDomain: string;
+    content: string;
+    format?: CompetitorImportFormat;
+    maxRows?: number;
+}
+/** `https://www.Example.com/path/` → `example.com`. */
+export declare function normalizeCompetitorDomain(value: string): string;
+/**
+ * Parses a competitor backlink export into normalized rows.
+ *
+ * Rows without a usable source URL are counted in `skippedRows` instead of
+ * silently disappearing, and duplicates (`sourceUrl` + anchor) collapse so a
+ * re-import of an overlapping export does not inflate the profile.
+ */
+export declare function parseCompetitorBacklinkImport(options: CompetitorBacklinkImportOptions): CompetitorBacklinkImportResult;

package/dist/competitor-insights.d.ts

@@ -0,0 +1,35 @@
+export interface SerpCompetitor {
+    domain: string;
+    position: number;
+    url: string;
+    title?: string;
+    snippet?: string;
+}
+export interface DomainOverview {
+    domain: string;
+    organicTraffic?: number;
+    organicKeywords?: number;
+    authorityScore?: number;
+    backlinks?: number;
+}
+export interface KeywordGap {
+    keyword: string;
+    gapType: "missing" | "weak";
+    opportunityScore: number;
+    searchVolume?: number;
+}
+export interface KeywordOverlap {
+    keyword: string;
+    sharedWith: string[];
+}
+export declare function discoverSerpCompetitors(keyword: string, limit?: number): SerpCompetitor[];
+export declare function getDomainOverview(domain: string): DomainOverview;
+export declare function computeKeywordGap(_yourDomain: string, _competitors: string[], keywords: string[]): KeywordGap[];
+export declare function computeKeywordOverlap(_yourDomain: string, competitors: string[], keywords: string[]): KeywordOverlap[];
+export declare function paginateResults<T>(items: T[], page?: number, pageSize?: number): {
+    items: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+};