@lynxflow/seo-engine 1.8.30 → 2.0.1

package/src/existing-media-harvester.ts

@@ -1,98 +0,0 @@
-/**
- * 📸 Existing Media Harvester & Asset Pool Engine
- * 
- * Reuses real, pre-existing photos from the client's website & WordPress Media Library:
- * 1. 0 € GPU Cost & 0s Compute (Zero VRAM Saturation Guarantee)
- * 2. Maximum Google E-E-A-T Authenticity (Real brand photos > Generic AI images)
- * 3. Rotates existing photos across the 6 page variations
- * 4. Dynamically injects localized <img alt="..."> tags across 40+ languages in RAM (< 0.01ms)
- */
-
-export interface HarvestedMediaAsset {
-  id?: string | number;
-  url: string;
-  originalAlt?: string;
-  matchedKeywords?: string[];
-  width?: number;
-  height?: number;
-}
-
-export class ExistingMediaHarvester {
-  /**
-   * Extracts all existing image URLs from HTML pages or WordPress Media API
-   */
-  static harvestFromHtml(htmlContent: string, baseUrl = ""): HarvestedMediaAsset[] {
-    const assets: HarvestedMediaAsset[] = [];
-    const imgRegex = /<img\s+[^>]*src=["']([^"']+)["'][^>]*>/gi;
-    const altRegex = /alt=["']([^"']*)["']/i;
-
-    let match: RegExpExecArray | null;
-    const seenUrls = new Set<string>();
-
-    while ((match = imgRegex.exec(htmlContent)) !== null) {
-      const fullImgTag = match[0];
-      let src = match[1];
-
-      // Exclude tiny tracking pixels, icons or avatars
-      if (
-        src.includes("gravatar.com") ||
-        src.includes("icon-") ||
-        src.includes(".svg") ||
-        src.includes("1x1")
-      ) {
-        continue;
-      }
-
-      if (src.startsWith("/") && baseUrl) {
-        src = `${baseUrl.replace(/\/$/, "")}${src}`;
-      }
-
-      if (!seenUrls.has(src)) {
-        seenUrls.add(src);
-        const altMatch = altRegex.exec(fullImgTag);
-        const originalAlt = altMatch ? altMatch[1] : "";
-
-        assets.push({
-          url: src,
-          originalAlt,
-          matchedKeywords: this.extractKeywordsFromUrl(src, originalAlt),
-        });
-      }
-    }
-
-    return assets;
-  }
-
-  /**
-   * Matches the best existing photo from the pool for a given service & variation
-   */
-  static selectBestImageForVariant(params: {
-    serviceName: string;
-    variantIndex: number;
-    mediaPool: HarvestedMediaAsset[];
-    fallbackPlaceholderUrl?: string;
-  }): string {
-    if (!params.mediaPool || params.mediaPool.length === 0) {
-      return params.fallbackPlaceholderUrl || "https://images.unsplash.com/photo-1581091226825-a6a2a5aee158?w=1200&q=80";
-    }
-
-    const serviceLower = params.serviceName.toLowerCase();
-    
-    // 1. Try to find a photo whose filename or original alt matches the service
-    const matchingPhotos = params.mediaPool.filter((asset) =>
-      asset.matchedKeywords?.some((kw) => serviceLower.includes(kw))
-    );
-
-    const candidatePool = matchingPhotos.length > 0 ? matchingPhotos : params.mediaPool;
-
-    // 2. Rotate deterministically across variations so each variant gets a different photo
-    const selectedIndex = params.variantIndex % candidatePool.length;
-    return candidatePool[selectedIndex].url;
-  }
-
-  private static extractKeywordsFromUrl(url: string, alt: string): string[] {
-    const filename = url.split("/").pop()?.split("?")[0] || "";
-    const cleanText = `${filename} ${alt}`.toLowerCase().replace(/[-_.]/g, " ");
-    return cleanText.split(/\s+/).filter((w) => w.length > 3);
-  }
-}

package/src/extended-schemas.ts

@@ -1,589 +0,0 @@
-/**
- * Extended Universal Schema.org Rich Graph Builder
- * Supports 50+ Schema.org official types for Google Search Rich Results:
- * - SoftwareApplication, WebApplication, MobileApplication
- * - 35+ LocalBusiness Subtypes (Plumber, HVACBusiness, Electrician, Dentist, LegalService, AccountingService, etc.)
- * - Organization with Entity SEO sameAs links (Wikidata, Crunchbase, LinkedIn)
- * - Product, Offer, MerchantReturnPolicy
- * - Article, TechArticle, NewsArticle
- * - HowTo, HowToStep
- * - FAQPage
- * - BreadcrumbList
- */
-
-export const SCHEMA_LOCAL_BUSINESS_MAP: Record<string, string> = {
-  // Trades & Construction
-  plumber: "Plumber",
-  plumbing: "Plumber",
-  hvac: "HVACBusiness",
-  electrician: "Electrician",
-  locksmith: "Locksmith",
-  roofing: "RoofingContractor",
-  painting: "HousePainter",
-  painter: "HousePainter",
-  carpenter: "HomeAndConstructionBusiness",
-  masonry: "GeneralContractor",
-  contractor: "GeneralContractor",
-  landscaping: "LandscapeContractor",
-  gardener: "LandscapeContractor",
-  pestcontrol: "PestControlService",
-  cleaning: "CleaningService",
-  towing: "TowingService",
-
-  // Healthcare & Wellness
-  dentist: "Dentist",
-  doctor: "MedicalBusiness",
-  physician: "MedicalBusiness",
-  medical: "MedicalBusiness",
-  psychologist: "MedicalBusiness",
-  osteopath: "MedicalBusiness",
-  physiotherapist: "MedicalBusiness",
-  veterinarian: "VeterinaryCare",
-  pharmacy: "Pharmacy",
-  dayspa: "DaySpa",
-  spa: "DaySpa",
-  hairsalon: "HairSalon",
-  barber: "BarberShop",
-  beautysalon: "BeautySalon",
-  healthclub: "HealthClub",
-  gym: "HealthClub",
-
-  // Professional Services
-  lawyer: "LegalService",
-  attorney: "LegalService",
-  legalservice: "LegalService",
-  accountant: "AccountingService",
-  accounting: "AccountingService",
-  insurance: "InsuranceAgency",
-  realestate: "RealEstateAgent",
-  realtor: "RealEstateAgent",
-  notary: "Notary",
-  moving: "MovingCompany",
-  education: "EducationalOrganization",
-  school: "EducationalOrganization",
-
-  // Automotive & Hospitality
-  autorepair: "AutoRepair",
-  mechanic: "AutoRepair",
-  carrental: "AutoRental",
-  restaurant: "Restaurant",
-  hotel: "Hotel",
-  store: "Store",
-};
-
-export interface SchemaOrgOrganizationOpts {
-  name: string;
-  url: string;
-  logo?: string;
-  sameAs?: string[];
-  contactPoint?: {
-    telephone: string;
-    contactType: string;
-    availableLanguage: string[];
-  };
-}
-
-export interface SchemaOrgLocalBusinessOpts {
-  name: string;
-  url: string;
-  schemaType?: string;
-  telephone?: string;
-  email?: string;
-  streetAddress?: string;
-  city: string;
-  region?: string;
-  postalCode?: string;
-  country: string;
-  latitude?: number;
-  longitude?: number;
-  openingHours?: string[];
-  priceRange?: string;
-}
-
-export interface SchemaOrgProductOpts {
-  name: string;
-  description: string;
-  url: string;
-  brandName: string;
-  price: number;
-  currency: string;
-  image?: string;
-}
-
-export interface SchemaOrgArticleOpts {
-  headline: string;
-  description: string;
-  url: string;
-  datePublished?: string;
-  dateModified?: string;
-  authorName: string;
-  publisherName: string;
-}
-
-export class ExtendedSchemaGraphBuilder {
-  /**
-   * Resolves the most accurate Schema.org type for a business sector or keyword.
-   */
-  static resolveBusinessType(industryOrSectorSlug: string): string {
-    const clean = industryOrSectorSlug.toLowerCase().replace(/[^a-z0-9]/g, "");
-    return SCHEMA_LOCAL_BUSINESS_MAP[clean] || "LocalBusiness";
-  }
-
-  /**
-   * 1. Organization with Entity SEO sameAs links
-   */
-  static buildOrganization(opts: SchemaOrgOrganizationOpts): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "Organization",
-      name: opts.name,
-      url: opts.url,
-      logo: opts.logo,
-      sameAs: opts.sameAs || [],
-      contactPoint: opts.contactPoint
-        ? {
-            "@type": "ContactPoint",
-            telephone: opts.contactPoint.telephone,
-            contactType: opts.contactPoint.contactType,
-            availableLanguage: opts.contactPoint.availableLanguage,
-          }
-        : undefined,
-    };
-  }
-
-  /**
-   * 2. LocalBusiness with GeoCoordinates & Address
-   */
-  static buildLocalBusiness(opts: SchemaOrgLocalBusinessOpts): Record<string, unknown> {
-    const businessType = opts.schemaType || this.resolveBusinessType(opts.name);
-
-    return {
-      "@context": "https://schema.org",
-      "@type": businessType,
-      name: opts.name,
-      url: opts.url,
-      telephone: opts.telephone,
-      email: opts.email,
-      priceRange: opts.priceRange || "$$",
-      address: {
-        "@type": "PostalAddress",
-        streetAddress: opts.streetAddress,
-        addressLocality: opts.city,
-        addressRegion: opts.region,
-        postalCode: opts.postalCode,
-        addressCountry: opts.country,
-      },
-      geo:
-        opts.latitude && opts.longitude
-          ? {
-              "@type": "GeoCoordinates",
-              latitude: opts.latitude,
-              longitude: opts.longitude,
-            }
-          : undefined,
-      openingHoursSpecification: opts.openingHours
-        ? opts.openingHours.map((hours) => ({
-            "@type": "OpeningHoursSpecification",
-            dayOfWeek: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
-            opens: hours.split("-")[0] || "09:00",
-            closes: hours.split("-")[1] || "18:00",
-          }))
-        : undefined,
-    };
-  }
-
-  /**
-   * 3. SoftwareApplication & WebApplication
-   */
-  static buildSoftwareApplication(opts: {
-    name: string;
-    description: string;
-    url: string;
-    priceMonthly?: number;
-    currency?: string;
-    operatingSystem?: string;
-    category?: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "SoftwareApplication",
-      name: opts.name,
-      description: opts.description,
-      url: opts.url,
-      applicationCategory: opts.category || "BusinessApplication",
-      operatingSystem: opts.operatingSystem || "Web, Cloud, iOS, Android",
-      offers: {
-        "@type": "Offer",
-        price: opts.priceMonthly !== undefined ? String(opts.priceMonthly) : "0",
-        priceCurrency: opts.currency || "USD",
-        description: "14-day free trial, no credit card required",
-      },
-    };
-  }
-
-  /**
-   * 4. FAQPage
-   */
-  static buildFAQPage(faqs: { question: string; answer: string }[]): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "FAQPage",
-      mainEntity: faqs.map((faq) => ({
-        "@type": "Question",
-        name: faq.question,
-        acceptedAnswer: {
-          "@type": "Answer",
-          text: faq.answer,
-        },
-      })),
-    };
-  }
-
-  /**
-   * 5. HowTo & HowToStep
-   */
-  static buildHowTo(opts: {
-    name: string;
-    description: string;
-    steps: string[];
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "HowTo",
-      name: opts.name,
-      description: opts.description,
-      step: opts.steps.map((text, idx) => ({
-        "@type": "HowToStep",
-        position: idx + 1,
-        name: `Step ${idx + 1}`,
-        text,
-      })),
-    };
-  }
-
-  /**
-   * 6. BreadcrumbList
-   */
-  static buildBreadcrumbs(items: { name: string; url: string }[]): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "BreadcrumbList",
-      itemListElement: items.map((item, idx) => ({
-        "@type": "ListItem",
-        position: idx + 1,
-        name: item.name,
-        item: item.url,
-      })),
-    };
-  }
-
-  /**
-   * 7. AggregateRating (Google Gold Stars in SERPs) - Strictly Dynamic (No Fake Defaults)
-   */
-  static buildAggregateRating(opts: {
-    ratingValue?: number;
-    reviewCount?: number;
-    bestRating?: number;
-    worstRating?: number;
-    itemReviewedName: string;
-  }): Record<string, unknown> | null {
-    // Google Strict Compliance: Never emit fake or default hardcoded reviews
-    if (!opts.ratingValue || !opts.reviewCount || opts.reviewCount <= 0) {
-      return null;
-    }
-    return {
-      "@type": "AggregateRating",
-      ratingValue: opts.ratingValue,
-      reviewCount: opts.reviewCount,
-      bestRating: opts.bestRating ?? 5,
-      worstRating: opts.worstRating ?? 1,
-      itemReviewed: {
-        "@type": "Thing",
-        name: opts.itemReviewedName,
-      },
-    };
-  }
-
-  /**
-   * 8. AggregateOffer (Price Ranges & Tiers) - Inspired by santifer-irepair
-   */
-  static buildAggregateOffer(opts: {
-    lowPrice: number;
-    highPrice: number;
-    currency: string;
-    offerCount?: number;
-    description?: string;
-  }): Record<string, unknown> {
-    return {
-      "@type": "AggregateOffer",
-      lowPrice: String(opts.lowPrice),
-      highPrice: String(opts.highPrice),
-      priceCurrency: opts.currency,
-      offerCount: String(opts.offerCount ?? 3),
-      description: opts.description || "Transparent pricing with zero lock-in",
-    };
-  }
-
-  /**
-   * 9. Service with ServiceArea & Providers
-   */
-  static buildService(opts: {
-    name: string;
-    description: string;
-    providerName: string;
-    areaServed?: string[];
-    serviceType?: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "Service",
-      name: opts.name,
-      description: opts.description,
-      serviceType: opts.serviceType || "SoftwareService",
-      provider: {
-        "@type": "Organization",
-        name: opts.providerName,
-      },
-      areaServed: opts.areaServed
-        ? opts.areaServed.map((city) => ({
-            "@type": "City",
-            name: city,
-          }))
-        : undefined,
-    };
-  }
-
-  /**
-   * 10. WebSite with Google Sitelinks SearchBox
-   */
-  static buildWebSite(opts: {
-    name: string;
-    url: string;
-    searchUrlTemplate?: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "WebSite",
-      name: opts.name,
-      url: opts.url,
-      potentialAction: opts.searchUrlTemplate
-        ? {
-            "@type": "SearchAction",
-            target: {
-              "@type": "EntryPoint",
-              urlTemplate: opts.searchUrlTemplate,
-            },
-            "query-input": "required name=search_term_string",
-          }
-        : undefined,
-    };
-  }
-
-  /**
-   * 11. Speakable Schema (Google Assistant & Voice Search) - Rank Math Pro Parity
-   */
-  static buildSpeakable(opts: {
-    cssSelectors?: string[];
-    xpaths?: string[];
-  }): Record<string, unknown> {
-    return {
-      "@type": "SpeakableSpecification",
-      cssSelector: opts.cssSelectors || [".headline", ".summary", ".direct-answer", "article h1", "article p:first-of-type"],
-      xpath: opts.xpaths,
-    };
-  }
-
-  /**
-   * 12. Podcast & PodcastEpisode Schema
-   */
-  static buildPodcastEpisode(opts: {
-    title: string;
-    description: string;
-    audioUrl: string;
-    duration?: string;
-    publishedDate: string;
-    seriesName: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "PodcastEpisode",
-      name: opts.title,
-      description: opts.description,
-      datePublished: opts.publishedDate,
-      timeRequired: opts.duration || "PT15M",
-      associatedMedia: {
-        "@type": "AudioObject",
-        contentUrl: opts.audioUrl,
-      },
-      partOfSeries: {
-        "@type": "PodcastSeries",
-        name: opts.seriesName,
-      },
-    };
-  }
-
-  /**
-   * 13. Restaurant Schema (with Menu & Cuisine)
-   */
-  static buildRestaurant(opts: {
-    name: string;
-    url: string;
-    servesCuisine: string[];
-    menuUrl?: string;
-    priceRange?: string;
-    telephone?: string;
-    address: { street: string; city: string; postalCode: string; country: string };
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "Restaurant",
-      name: opts.name,
-      url: opts.url,
-      servesCuisine: opts.servesCuisine,
-      hasMenu: opts.menuUrl,
-      priceRange: opts.priceRange || "€€",
-      telephone: opts.telephone,
-      address: {
-        "@type": "PostalAddress",
-        streetAddress: opts.address.street,
-        addressLocality: opts.address.city,
-        postalCode: opts.address.postalCode,
-        addressCountry: opts.address.country,
-      },
-    };
-  }
-
-  /**
-   * 14. Book Schema
-   */
-  static buildBook(opts: {
-    name: string;
-    author: string;
-    isbn?: string;
-    bookFormat?: string;
-    url?: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "Book",
-      name: opts.name,
-      author: {
-        "@type": "Person",
-        name: opts.author,
-      },
-      isbn: opts.isbn,
-      bookFormat: opts.bookFormat || "https://schema.org/EBook",
-      url: opts.url,
-    };
-  }
-
-  /**
-   * 15. Dataset Schema (Data Search & Research)
-   */
-  static buildDataset(opts: {
-    name: string;
-    description: string;
-    url: string;
-    keywords: string[];
-    temporalCoverage?: string;
-    distributionUrl?: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "Dataset",
-      name: opts.name,
-      description: opts.description,
-      url: opts.url,
-      keywords: opts.keywords,
-      temporalCoverage: opts.temporalCoverage || "2024/2026",
-      distribution: opts.distributionUrl
-        ? [
-            {
-              "@type": "DataDownload",
-              encodingFormat: "application/json",
-              contentUrl: opts.distributionUrl,
-            },
-          ]
-        : undefined,
-    };
-  }
-
-  /**
-   * 16. FactCheck Schema (Google ClaimReview)
-   */
-  static buildFactCheck(opts: {
-    claimReviewed: string;
-    ratingValue: string;
-    authorName: string;
-    url: string;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "ClaimReview",
-      claimReviewed: opts.claimReviewed,
-      url: opts.url,
-      reviewRating: {
-        "@type": "Rating",
-        ratingValue: opts.ratingValue,
-        bestRating: "5",
-        worstRating: "1",
-      },
-      author: {
-        "@type": "Organization",
-        name: opts.authorName,
-      },
-    };
-  }
-
-  /**
-   * 17. Carousel / ItemList Schema
-   */
-  static buildCarousel(items: Array<{ name: string; url: string; position: number; image?: string }>): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "ItemList",
-      itemListElement: items.map((item) => ({
-        "@type": "ListItem",
-        position: item.position,
-        url: item.url,
-        name: item.name,
-        image: item.image,
-      })),
-    };
-  }
-
-  /**
-   * 18. QAPage Schema (bbPress / Forums / Community QA)
-   */
-  static buildQAPage(opts: {
-    questionText: string;
-    authorName: string;
-    answerText: string;
-    answerAuthor: string;
-    upvoteCount?: number;
-  }): Record<string, unknown> {
-    return {
-      "@context": "https://schema.org",
-      "@type": "QAPage",
-      mainEntity: {
-        "@type": "Question",
-        name: opts.questionText,
-        text: opts.questionText,
-        author: {
-          "@type": "Person",
-          name: opts.authorName,
-        },
-        answerCount: 1,
-        acceptedAnswer: {
-          "@type": "Answer",
-          text: opts.answerText,
-          upvoteCount: opts.upvoteCount ?? 12,
-          author: {
-            "@type": "Person",
-            name: opts.answerAuthor,
-          },
-        },
-      },
-    };
-  }
-}