@lynxflow/seo-engine 1.0.0 → 1.3.0

package/README.md

@@ -1,66 +1,239 @@
-# 👑 @lynxflow/seo-engine — Universal Integration Guide
+# 🦁 @lynxflow/seo-engine — Guide Complet & Documentation Développeur
 
-> **Proprietary High-Performance pSEO & AI Search Engine SDK by LynxFlow Technologies.**
+> **Le Moteur Universel de SEO Programmatique (pSEO), Optimisation Moteurs IA (AEO/GEO), Indexation Instantanée & Analytics Embarqués.**
 
-`@lynxflow/seo-engine` allows **ANY website** (Next.js, Astro, WordPress, Shopify, Laravel, Webflow, Wix) to dynamically serve thousands of programmatic landing pages, Schema.org 4.9/5 gold star snippets, and Generative Engine Optimization (GEO) direct-answer blocks in **under 0.05 ms** with **zero server load** on the master LynxFlow platform.
+`@lynxflow/seo-engine` est un SDK TypeScript haute performance conçu pour générer, servir et indexer des millions de landing pages dynamiques, des avis 4.9/5★ Schema.org et des réponses directes pour les intelligences artificielles (ChatGPT Search, Perplexity, Google AI Overviews) en **moins de 0.05 milliseconde** avec **0% de charge sur votre base de données SQL**.
 
 ---
 
-## 📑 Sommaire des Intégrations
+## 📑 Sommaire
+1. [🌟 Présentation Générale](#1--présentation-générale)
+2. [🔑 L'API Key Better Auth, Sécurité & Quotas](#2--lapi-key-better-auth-sécurité--quotas)
+3. [🏛️ Les 8 Matrices Programmatiques & Multiplicateurs](#3--les-8-matrices-programmatiques--multiplicateurs)
+4. [🚀 Tutoriel d'Intégration Pas-à-Pas (Next.js 15/16 & React 19)](#4--tutoriel-dintégration-pas-à-pas-nextjs-1516--react-19)
+5. [🔌 Intégration sur Autres Frameworks (WordPress, Shopify, Cloudflare, Laravel, Astro)](#5--intégration-sur-autres-frameworks)
+6. [🧰 Les 7 Modules Embarqués du SDK (Analytics, SERP, Backlinks, IA, IndexNow)](#6--les-7-modules-embarqués-du-sdk)
+7. [🌍 Internationalisation & Zéro Contenu Dupliqué (10 Langues & Hreflang)](#7--internationalisation--zéro-contenu-dupliqué)
+8. [📘 Référence Complète des Types TypeScript](#8--référence-complète-des-types-typescript)
 
-1. [⚡ Next.js 14 / 15 / 16 (App Router)](#1--nextjs-14--15--16-app-router)
-2. [🚀 Astro (SSG & SSR)](#2--astro-ssg--ssr)
-3. [📦 WordPress / WooCommerce (Mini Plugin 1 Fichier)](#3--wordpress--woocommerce)
-4. [🛍️ Shopify, Webflow, Wix, Framer (Cloudflare Worker)](#4--shopify-webflow-wix-framer-cloudflare-worker)
-5. [🐘 PHP / Laravel](#5--php--laravel)
+---
+
+## 1. 🌟 Présentation Générale
+
+### Pourquoi utiliser `@lynxflow/seo-engine` ?
+* ⚡ **Résolution Ultra-Rapide (< 0.05ms) :** Les pages et métadonnées sont résolues en mémoire vive sans requête SQL bloquante.
+* 🤖 **Conçu pour le Search IA (AEO / GEO) :** Génère des blocs de synthèse directe optimisés pour être cités en source n°1 par **ChatGPT Search**, **Perplexity** et **Google AI Overviews**.
+* 🛡️ **Fonctionne à 100% en Local / Sans Dépendance API Bloquante :** La validation cryptographique HMAC de votre clé d'API s'exécute directement sur votre serveur pour garantir un affichage instantané même en cas de panne réseau.
+* 📈 **Suite Complète Embarquée :** Accédez directement à vos analytics de trafic, votre détection de bots IA, vos positions de mots-clés Google et vos backlinks sans quitter votre application.
 
 ---
 
-## 1. ⚡ Next.js 14 / 15 / 16 (App Router)
+## 2. 🔑 L'API Key Better Auth, Sécurité & Quotas
 
-### Installation
+### Étape 1 : Obtenir votre Clé d'API
+Rendez-vous dans votre cockpit LynxFlow dans **Paramètres ➔ Clés d'API & Sécurité** et générez votre clé (`ba_key_...` ou `lynx_api_...`).
+
+### Étape 2 : Configuration dans votre fichier `.env` ou `.env.local`
+```bash
+# 🔑 Clé d'API Better Auth
+LYNXFLOW_API_KEY=ba_key_growth_tenant_acme_a8f93e
+
+# 🌐 Domaine de votre site web
+NEXT_PUBLIC_SITE_URL=https://mon-entreprise.com
+```
+
+### Grille des Forfaits & Règles de Sécurité :
+
+| Forfait (Tier) | Préfixe de Clé | Quota de Pages Uniques | Nombre de Domaines Autorisés | Budget Crédits IA / mois |
+|---|---|---|---|---|
+| **Starter** | `ba_test_*` ou `ba_key_starter_*` | **50 000 pages uniques** | **1 seul domaine** (Verrouillage Monosite) | 1 000 crédits ($10) |
+| **Growth** | `ba_key_*` ou `ba_key_growth_*` | **500 000 pages uniques** | **Jusqu'à 3 domaines** | 10 000 crédits ($100) |
+| **Enterprise** | `ba_admin_*` ou `lynx_enterprise_*` | **Illimité (5 000 000+)** | **Domaines illimités** | 100 000 crédits ($1 000) |
+
+### 🧠 Comment fonctionne la Comptabilité des Pages (URLs Uniques vs Hits) ?
+* **Une Page = Une URL Unique :** Si vous avez 500 villes pour 2 services, votre catalogue contient **1 000 pages uniques**.
+* **Trafic / Visites Illimité & Gratuit :** Si 100 000 visiteurs visitent `/solutions/crm/paris`, cela compte pour **1 seule page unique** dans votre quota, pas 100 000 !
+
+---
+
+## 3. 🏛️ Les 8 Matrices Programmatiques & Multiplicateurs
+
+Le moteur intègre nativement les 8 familles stratégiques de pages :
+
+```
+┌────┬───────────────────────────────────┬──────────────────────────────────────────┬────────────────────────────────────────────────────────┐
+│ #  │ FAMILLE DE MATRICE                │ FORMULE D'URL PROGRAMMATIQUE             │ EXEMPLE RÉSOLU EN < 0.05MS                             │
+├────┼───────────────────────────────────┼──────────────────────────────────────────┼────────────────────────────────────────────────────────┤
+│ 1  │ 📍 1. Local & GEO                 │ `/solutions/{module}/{ville}`            │ `/solutions/crm-pipeline/lyon`                         │
+│ 2  │ 🥊 2. VS Comparatifs              │ `/comparatif/{module}-vs-{concurrent}`  │ `/comparatif/crm-pipeline-vs-hubspot`                  │
+│ 3  │ 🔄 3. Alternatives Logiciels      │ `/alternatives/alternative-a-{nom}`      │ `/alternatives/alternative-a-aircall`                  │
+│ 4  │ 🏢 4. Secteurs & Métiers B2B      │ `/secteurs/{module}-pour-{secteur}`      │ `/secteurs/crm-pipeline-pour-avocats`                  │
+│ 5  │ 🔌 5. Intégrations & Tech         │ `/integrations/{module}-avec-{logiciel}` │ `/integrations/crm-pipeline-avec-shopify`              │
+│ 6  │ 👤 6. Personas & Décideurs        │ `/metiers/{module}-pour-{role}`          │ `/metiers/crm-pipeline-pour-directeur-commercial`      │
+│ 7  │ 🎯 7. Cas d'Usage Opérationnels   │ `/cas-usage/{module}-{sujet}`            │ `/cas-usage/crm-pipeline-relance-devis`                │
+│ 8  │ 🧮 8. Calculateurs & Outils ROI   │ `/outils/simulateur-roi-{module}`        │ `/outils/simulateur-roi-crm-pipeline`                  │
+└────┴───────────────────────────────────┴──────────────────────────────────────────┴────────────────────────────────────────────────────────┘
+```
+
+### 🌟 Le Lien Unique Ultra-Combiné (8 Slugs en 1 Seule URL) :
+Si vous souhaitez cibler une requête ultra-précise combinant tous les critères dans une seule URL :
+```
+https://mon-entreprise.com/solutions/crm-pipeline/avocats/hubspot/gmail/directeur-commercial/paris/simulateur-roi
+```
+
+---
+
+## 4. 🚀 Tutoriel d'Intégration Pas-à-Pas (Next.js 15/16 & React 19)
+
+### Étape 1 : Installation
 ```bash
-bun add @lynxflow/seo-engine
-# ou
 npm install @lynxflow/seo-engine
+# ou
+bun add @lynxflow/seo-engine
 ```
 
-### Route Dynamique : `app/solutions/[service]/[country]/[city]/page.tsx`
+### Étape 2 : Initialisation dans `lib/seo.ts`
 ```typescript
+// lib/seo.ts
 import { createLynxSeoEngine } from "@lynxflow/seo-engine";
-import type { Metadata } from "next";
 
-const engine = createLynxSeoEngine({
-  licenseKey: process.env.LYNXFLOW_LICENSE_KEY!,
-  domain: "https://votre-site.com",
-  brandName: "Votre Entreprise",
+export const seoEngine = createLynxSeoEngine({
+  apiKey: process.env.LYNXFLOW_API_KEY!,
+  domain: process.env.NEXT_PUBLIC_SITE_URL || "https://mon-entreprise.com",
+  brandName: "Acme Corp",
+  defaultLocale: "fr",
+  supportedLocales: ["fr", "en", "es", "pt", "de", "ar", "ja", "zh", "ko", "hi", "id"],
   services: [
-    { slug: "crm-pipeline", name: "CRM Pipeline & Ventes", description: "Automatisation commerciale", pricePerMonth: 49 },
-    { slug: "standard-vocal-ia", name: "Standard Téléphonique Vocal IA 24/7", description: "Décrochage immédiat", pricePerMonth: 79 }
+    {
+      slug: "crm-pipeline",
+      name: "CRM Pipeline Commercial",
+      pricePerMonth: 49,
+      category: "Ventes & CRM",
+      features: ["Kanban interactif", "Relances automatiques IA 24/7", "WhatsApp Sync"],
+      faqs: [
+        { question: "Puis-je importer mes contacts existants ?", answer: "Oui, l'import CSV et Excel se fait en 1 clic." },
+        { question: "Le support technique est-il inclus ?", answer: "Oui, support prioritaire 24/7 par chat et email." }
+      ]
+    },
+    {
+      slug: "standard-vocal-ia",
+      name: "Standard Vocal Téléphonique IA",
+      pricePerMonth: 79,
+      category: "Téléphonie IA",
+      features: ["Décrochage 0 seconde 24/7", "Qualification automatique des prospects"]
+    }
   ]
 });
+```
+
+### Étape 3 : Générateur d'Images Réseaux Sociaux Dynamiques (`app/api/og/route.tsx`)
+```tsx
+// app/api/og/route.tsx
+import { ImageResponse } from "next/og";
+import type { NextRequest } from "next/server";
+
+export const runtime = "edge";
+
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const title = searchParams.get("title") || "Solution SaaS & IA";
+  const brand = searchParams.get("brand") || "LynxFlow";
+  const service = searchParams.get("service") || "Plateforme B2B";
+
+  return new ImageResponse(
+    (
+      <div style={{ height: "100%", width: "100%", display: "flex", flexDirection: "column", justifyContent: "space-between", backgroundColor: "#030712", padding: "60px 80px", fontFamily: "sans-serif" }}>
+        <div style={{ display: "flex", alignItems: "center", gap: "16px" }}>
+          <div style={{ background: "#2563eb", color: "#fff", padding: "8px 20px", borderRadius: "9999px", fontSize: 24, fontWeight: 700 }}>{brand}</div>
+          <div style={{ color: "#94a3b8", fontSize: 24 }}>• {service}</div>
+        </div>
+        <div style={{ color: "#ffffff", fontSize: 54, fontWeight: 900, lineHeight: 1.15 }}>{title}</div>
+        <div style={{ display: "flex", gap: "16px", color: "#e2e8f0", fontSize: 22 }}>
+          <span>⭐ 4.9/5 (1 280 avis vérifiés)</span>
+          <span>•</span>
+          <span>Mise en service immédiate</span>
+        </div>
+      </div>
+    ),
+    { width: 1200, height: 630 }
+  );
+}
+```
+
+### Étape 4 : La Route Catch-All Universelle (`app/[...slug]/page.tsx`)
+```tsx
+// app/[...slug]/page.tsx
+import { seoEngine } from "@/lib/seo";
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
+
+interface PageProps {
+  params: Promise<{ slug: string[] }>;
+}
+
+// 1. Métadonnées SEO, Balises Hreflang et Image Sociale
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const path = "/" + (slug || []).join("/");
+  const page = seoEngine.resolve(path);
 
-export async function generateMetadata({ params }: { params: { service: string; country: string; city: string } }): Promise<Metadata> {
-  const page = engine.resolve(`/solutions/${params.service}/${params.country}/${params.city}`);
   if (!page) return {};
+
   return {
-    title: page.meta.title,
-    description: page.meta.description,
-    alternates: { canonical: page.meta.canonical },
-    openGraph: { images: [page.meta.openGraphImageUrl] }
+    title: page.title,
+    description: page.description,
+    alternates: {
+      canonical: page.url,
+      languages: page.hreflangs?.reduce((acc, h) => ({ ...acc, [h.lang]: h.url }), {})
+    },
+    openGraph: {
+      title: page.title,
+      description: page.description,
+      images: [{ url: page.meta?.openGraphImageUrl || `${page.url}/api/og` }]
+    }
   };
 }
 
-export default async function SolutionPage({ params }: { params: { service: string; country: string; city: string } }) {
-  const page = engine.resolve(`/solutions/${params.service}/${params.country}/${params.city}`);
-  if (!page) return <div>Page non trouvée</div>;
+// 2. Rendu Server Component Ultra-Rapide (< 0.05ms)
+export default async function UniversalCatchAllPage({ params }: PageProps) {
+  const { slug } = await params;
+  const path = "/" + (slug || []).join("/");
+  const page = seoEngine.resolve(path);
+
+  if (!page) notFound();
+
+  // Enregistrer la visite pour les analytics et la détection de bots IA
+  await seoEngine.analytics.trackPageView({ path });
 
   return (
-    <main className="max-w-4xl mx-auto py-12 px-4">
-      <h1 className="text-4xl font-extrabold">{page.meta.h1}</h1>
-      <div dangerouslySetInnerHTML={{ __html: page.content.directAnswerGeoHtml }} />
-      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(page.schemaJsonLd) }} />
-      <article className="prose lg:prose-xl mt-8">{page.content.markdownBody}</article>
+    <main className="max-w-4xl mx-auto py-12 px-6">
+      {/* 🌟 Graphe Schema.org 4.9★ (Product + FAQPage + Speakable) */}
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(page.jsonLd) }}
+      />
+
+      <h1 className="text-4xl font-black text-gray-900 tracking-tight">{page.h1}</h1>
+      <p className="mt-4 text-lg text-gray-600 leading-relaxed">{page.description}</p>
+
+      {/* 🤖 Bloc AEO de Réponse Directe pour ChatGPT / Perplexity */}
+      <div className="my-8 rounded-2xl bg-blue-50 border-l-4 border-blue-600 p-6">
+        <h3 className="text-xs font-bold uppercase tracking-wider text-blue-900">En Résumé (Réponse Directe IA) :</h3>
+        <p className="mt-2 text-base text-blue-950 font-medium leading-relaxed">{page.directAnswer}</p>
+      </div>
+
+      {/* ❓ Section FAQ Interactive */}
+      <section className="mt-12">
+        <h2 className="text-2xl font-bold text-gray-900">Questions Fréquentes</h2>
+        <div className="mt-6 space-y-4">
+          {page.faqs.map((faq, idx) => (
+            <details key={idx} className="rounded-xl border border-gray-200 p-5 bg-white shadow-xs">
+              <summary className="cursor-pointer font-semibold text-gray-900">{faq.question}</summary>
+              <p className="mt-3 text-gray-700 leading-relaxed">{faq.answer}</p>
+            </details>
+          ))}
+        </div>
+      </section>
     </main>
   );
 }
@@ -68,74 +241,152 @@ export default async function SolutionPage({ params }: { params: { service: stri
 
 ---
 
-## 2. 🚀 Astro (SSG & SSR)
+## 5. 🔌 Intégration sur Autres Frameworks
+
+### WordPress (Plugin 100% Autonome)
+1. Téléchargez l'archive [`packages/lynx-seo-engine/connectors/wordpress/lynxseo-connector.zip`](file:///Users/mahjoubhamid/Documents/01-projet_lynxflow/packages/lynx-seo-engine/connectors/wordpress/lynxseo-connector.zip).
+2. Téléversez-la dans vos extensions WordPress (`wp-admin ➔ Extensions ➔ Ajouter`).
+3. Connectez-vous en 1 clic via Better Auth ou renseignez votre `LYNXFLOW_API_KEY`.
+4. Vos 8 matrices et votre sitemap dynamique `/sitemap-solutions.xml` sont immédiatement actifs avec **0% de charge sur votre base MySQL**.
+
+### Cloudflare Edge Worker (Shopify, Webflow, Wix, Squarespace)
+Déployez `connectors/cloudflare-worker/worker.js` sur votre compte Cloudflare pour intercepter et servir vos pages programmatiques au niveau du réseau Edge en moins de 20ms dans plus de 300 villes à travers le monde.
+
+### Laravel / PHP
+```php
+// routes/web.php
+Route::get('/{any}', [LynxSeoController::class, 'resolve'])->where('any', '.*');
+```
 
-### Route : `src/pages/solutions/[service]/[country]/[city].astro`
-```astro
 ---
-import { createLynxSeoEngine } from "@lynxflow/seo-engine";
 
-const { service, country, city } = Astro.params;
+## 6. 🧰 Les 7 Modules Embarqués du SDK
 
-const engine = createLynxSeoEngine({
-  licenseKey: import.meta.env.LYNXFLOW_LICENSE_KEY,
-  domain: "https://votre-site.com",
-  brandName: "Votre Entreprise",
-  services: [
-    { slug: "droit-immobilier", name: "Avocat Droit Immobilier", description: "Conseil juridique", pricePerMonth: 150 }
-  ]
+Vous pouvez utiliser n'importe quel module du SDK de manière autonome dans votre propre code :
+
+### 1. 📊 `engine.analytics` : Trafic Web & Détection des Robots IA
+```typescript
+// Enregistrer un événement de visite
+await seoEngine.analytics.trackPageView({
+  path: "/solutions/crm-pipeline/paris",
+  userAgent: request.headers.get("user-agent") || ""
 });
 
-const page = engine.resolve(`/solutions/${service}/${country}/${city}`);
-if (!page) return Astro.redirect("/404");
----
+// Récupérer le rapport de trafic et les visites des robots IA
+const stats = await seoEngine.analytics.getSummary("30d");
+console.log("Visiteurs Uniques :", stats.uniqueVisitors);
+console.log("Robots IA détectés :", stats.aiBotVisits); // ChatGPT, Perplexity, Googlebot
+```
 
-<html lang="fr">
-<head>
-  <title>{page.meta.title}</title>
-  <meta name="description" content={page.meta.description} />
-  <script type="application/ld+json" set:html={JSON.stringify(page.schemaJsonLd)} />
-</head>
-<body>
-  <h1>{page.meta.h1}</h1>
-  <div set:html={page.content.directAnswerGeoHtml} />
-  <article>{page.content.markdownBody}</article>
-</body>
-</html>
+### 2. 🔎 `engine.serp` : Suivi des Positions Google & Mots-Clés
+```typescript
+const ranking = await seoEngine.serp.trackKeyword("crm pipeline commercial", "FR");
+console.log("Position Google :", ranking.position);
+console.log("Volume Mensuel :", ranking.searchVolume);
+console.log("Présence IA Overview :", ranking.hasAiOverview);
 ```
 
----
+### 3. 🔗 `engine.backlinks` : Suivi des Liens Entrants & Domain Authority
+```typescript
+const backlinks = await seoEngine.backlinks.getProfile("mon-entreprise.com");
+console.log("Domain Authority (DA) :", backlinks.domainAuthority);
+console.log("Total Backlinks :", backlinks.totalBacklinks);
+```
+
+### 4. 🤖 `engine.ai` : Copilote de Rédaction de Contenus IA
+```typescript
+const article = await seoEngine.ai.generateArticle({
+  topic: "Automatisation du CRM pour Avocats",
+  targetKeywords: ["crm avocats", "logiciel cabinet d'avocat"],
+  wordCount: 1500
+});
+
+console.log("Titre :", article.title);
+console.log("Contenu Markdown :", article.markdownContent);
+```
+
+### 5. ⚡ `engine.indexNow` : Indexation Immédiate sur Bing, Yandex, Seznam
+```typescript
+await seoEngine.indexNow.submitUrls([
+  "https://mon-entreprise.com/solutions/crm-pipeline/paris",
+  "https://mon-entreprise.com/solutions/crm-pipeline/lyon"
+]);
+```
 
-## 3. 📦 WordPress / WooCommerce
+### 6. 🔍 `engine.auditor` : Audit Qualité SEO & Validation Meta
+```typescript
+const audit = seoEngine.auditor.inspectMeta({
+  title: "CRM Ventes pour PME | Acme Corp",
+  description: "Accélérez vos ventes grâce à notre CRM automatisé. Essai gratuit.",
+  h1: "Le CRM pensé pour vos commerciaux",
+  directAnswer: "Acme Corp propose le meilleur CRM automatisé pour PME dès 49€/mois."
+});
 
-Pour connecter n'importe quel site WordPress sans modifier le thème :
+console.log("Score SEO :", audit.score); // 100/100
+```
 
-1. Téléchargez le fichier connecteur : [`connectors/wordpress/lynxseo-connector.php`](file:///Users/mahjoubhamid/Documents/01-projet_lynxflow/packages/lynx-seo-engine/connectors/wordpress/lynxseo-connector.php)
-2. Placez-le dans `wp-content/plugins/lynxseo-connector.php`.
-3. Activez le plugin dans l'administration WordPress.
-4. Vos pages `/solutions/votre-service/fr/votre-ville` deviennent instantanément actives avec les étoiles 4.9/5 !
+### 7. 🌟 `engine.schema` : Constructeur de Graphe Schema.org 4.9★
+```typescript
+const schemaJson = seoEngine.schema.buildGraph({
+  url: "https://mon-entreprise.com/ma-page",
+  name: "CRM Pipeline Commercial",
+  brandName: "Acme Corp",
+  price: 49
+});
+```
 
 ---
 
-## 4. 🛍️ Shopify, Webflow, Wix, Framer (Cloudflare Worker)
+## 7. 🌍 Internationalisation & Zéro Contenu Dupliqué
 
-Pour les plateformes SaaS fermées (Shopify, Webflow, Wix, Squarespace) :
+Le moteur génère automatiquement les traductions et l'interconnexion `hreflang` officielle pour **10 langues mondiales** :
 
-1. Déployez le Cloudflare Worker clé en main : [`connectors/cloudflare-worker/worker.js`](file:///Users/mahjoubhamid/Documents/01-projet_lynxflow/packages/lynx-seo-engine/connectors/cloudflare-worker/worker.js)
-2. Ajoutez une route Cloudflare : `votre-site.com/solutions/*`.
-3. Le Worker intercepte les requêtes, calcule la page et met le résultat en cache mondial sur Cloudflare CDN (Edge Cache 7 jours).
+* 🇫🇷 **Français (`fr`) :** `/fr/solutions/crm-pipeline/paris`
+* 🇬🇧 **Anglais (`en`) :** `/en/solutions/crm-pipeline/london`
+* 🇧🇷 **Portugais Brésil (`pt`) :** `/pt/solutions/crm-pipeline/sao-paulo`
+* 🇪🇸 **Espagnol LatAm (`es`) :** `/es/solutions/crm-pipeline/mexico`
+* 🇩🇪 **Allemand (`de`) :** `/de/solutions/crm-pipeline/berlin`
+* 🇸🇦 **Arabe (`ar` RTL) :** `/ar/solutions/crm-pipeline/riyadh`
+* 🇯🇵 **Japonais (`ja`) :** `/ja/solutions/crm-pipeline/tokyo`
+* 🇨🇳 **Chinois (`zh`) :** `/zh/solutions/crm-pipeline/shanghai`
+* 🇰🇷 **Coréen (`ko`) :** `/ko/solutions/crm-pipeline/seoul`
+* 🇮🇳 **Hindi (`hi`) :** `/hi/solutions/crm-pipeline/mumbai`
 
 ---
 
-## 5. 🐘 PHP / Laravel
+## 8. 📘 Référence Complète des Types TypeScript
 
-1. Utilisez le contrôleur Laravel clé en main : [`connectors/laravel/LynxSeoController.php`](file:///Users/mahjoubhamid/Documents/01-projet_lynxflow/packages/lynx-seo-engine/connectors/laravel/LynxSeoController.php)
-2. Dans `routes/web.php` :
-   ```php
-   Route::get('/solutions/{service}/{country}/{city}', [LynxSeoController::class, 'show']);
-   ```
+```typescript
+import {
+  createLynxSeoEngine,
+  LynxSeoEngine,
+  ApiKeyGuardian,
+  LagoTokenMeter,
+  HyperswitchGateway,
+  IndexNowClient,
+  SiteAuditor,
+  SchemaGraphBuilder,
+  LynxAnalyticsClient,
+  SerpClient,
+  BacklinksClient,
+  AiCopilotClient,
+  type LynxSeoConfig,
+  type LynxResolvedPage,
+  type LynxServiceDefinition,
+  type PseoIndustry,
+  type PseoCompetitor,
+  type PseoIntegration,
+  type PseoUseCase,
+  type PseoPersona,
+  type SeoAuditReport,
+  type AnalyticsSummaryReport,
+  type KeywordRankingItem,
+  type BacklinkProfileSummary,
+  type GeneratedArticleResult
+} from "@lynxflow/seo-engine";
+```
 
 ---
 
-## 🛡️ Licence & Droits
-Proprietary Software — © 2026 LynxFlow Technologies. Tous droits réservés.
+## 📄 Licence & Propriété
+Propriétaire © LynxFlow Technologies. Tous droits réservés.

package/connectors/cloudflare-worker/worker.js

@@ -1,34 +1,56 @@
 /**
  * ⚡ Cloudflare Worker Universal Reverse-Proxy Connector
  * 
- * Works for: Shopify, Webflow, Wix, Squarespace, Framer, and any static site.
- * Proxies `/solutions/*` to LynxFlow Engine with sub-20ms edge caching.
+ * Works for: Shopify, Webflow, Wix, Squarespace, Framer, Astro, and any static site.
+ * Intercepts all 8 Programmatic Matrices with sub-20ms edge caching across 300+ PoPs:
+ * 1. 📍 /solutions/* (Local / GEO)
+ * 2. 🥊 /comparatif/*, /comparison/*, /vs/* (Comparatifs)
+ * 3. 🔄 /alternatives/* (Alternatives)
+ * 4. 🏢 /secteurs/*, /industries/* (Secteurs Métiers)
+ * 5. 🔌 /integrations/* (Intégrations Tech)
+ * 6. 👤 /metiers/*, /roles/* (Personas)
+ * 7. 🎯 /cas-usage/*, /use-cases/* (Cas d'Usage)
+ * 8. 🧮 /outils/*, /tools/* (Outils ROI)
  */
 
-const LYNXFLOW_LICENSE_KEY = "lynx_live_sk_votre_cle_ici";
+const LYNXFLOW_LICENSE_KEY = "lynx_growth_votre_cle_ici";
 const LYNXFLOW_ENGINE_URL = "https://lynxintel.io/api/v1/render-page";
 
+const INTERCEPT_PATTERNS = [
+  "/solutions/",
+  "/comparatif/",
+  "/comparison/",
+  "/vs/",
+  "/alternatives/",
+  "/secteurs/",
+  "/industries/",
+  "/integrations/",
+  "/metiers/",
+  "/roles/",
+  "/cas-usage/",
+  "/use-cases/",
+  "/outils/",
+  "/tools/"
+];
+
 export default {
   async fetch(request, env, ctx) {
     const url = new URL(request.url);
+    const cleanPath = url.pathname.toLowerCase();
+
+    // Check if path or localized path matches any of the 8 matrices
+    const isProgrammaticRoute = INTERCEPT_PATTERNS.some((pattern) =>
+      cleanPath.includes(pattern)
+    );
 
-    // Only intercept `/solutions/*` programmatic pages
-    if (url.pathname.startsWith("/solutions/")) {
+    if (isProgrammaticRoute) {
       const cache = caches.default;
       let response = await cache.match(request);
 
       if (!response) {
-        const parts = url.pathname.split("/").filter(Boolean);
-        // e.g. /solutions/droit-immobilier/fr/lyon
-        const service = parts[1];
-        const country = parts[2];
-        const city = parts[3];
-
         const payload = {
           licenseKey: LYNXFLOW_LICENSE_KEY,
-          service,
-          country,
-          city,
+          path: url.pathname,
           domain: url.origin,
           brandName: "Votre Entreprise"
         };
@@ -42,29 +64,35 @@ export default {
         if (res.ok) {
           const data = await res.json();
           const html = `<!DOCTYPE html>
-<html lang="fr">
+<html lang="${data.locale || 'fr'}">
 <head>
   <meta charset="UTF-8">
-  <title>${data.meta.title}</title>
-  <meta name="description" content="${data.meta.description}">
-  <script type="application/ld+json">${JSON.stringify(data.schemaJsonLd)}</script>
-  <style>body{font-family:system-ui,-apple-system,sans-serif;max-width:900px;margin:40px auto;padding:0 20px;line-height:1.6;color:#1e293b}.geo-direct-answer{background:#f8fafc;border-left:4px solid #6366f1;padding:20px;margin:20px 0;border-radius:0 8px 8px 0}</style>
+  <title>${data.title}</title>
+  <meta name="description" content="${data.description}">
+  <script type="application/ld+json">${JSON.stringify(data.jsonLd)}</script>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 900px; margin: 40px auto; padding: 0 20px; line-height: 1.6; color: #1e293b; }
+    h1 { font-size: 2.25rem; font-weight: 800; color: #0f172a; }
+    .direct-answer { background: #eff6ff; border-left: 4px solid #2563eb; padding: 20px; border-radius: 8px; margin: 24px 0; font-size: 1.1rem; }
+  </style>
 </head>
 <body>
-  <h1>${data.meta.h1}</h1>
-  ${data.content.directAnswerGeoHtml}
-  <article>${data.content.markdownBody.replace(/\n/g, "<br>")}</article>
+  <h1>${data.h1}</h1>
+  <p>${data.description}</p>
+  <div class="direct-answer"><strong>En Résumé :</strong> ${data.directAnswer}</div>
+  <article>${data.htmlBody}</article>
 </body>
 </html>`;
 
           response = new Response(html, {
+            status: 200,
             headers: {
-              "Content-Type": "text/html; charset=UTF-8",
-              "Cache-Control": "public, max-age=86400, s-maxage=604800" // 7 days Edge Cache
+              "Content-Type": "text/html; charset=utf-8",
+              "Cache-Control": "public, max-age=604800, s-maxage=604800", // 7 jours de cache Edge
+              "X-Lynx-Engine": "Powered-by-LynxFlow",
             }
           });
 
-          // Cache on Cloudflare Edge globally
           ctx.waitUntil(cache.put(request, response.clone()));
         }
       }
@@ -72,7 +100,7 @@ export default {
       if (response) return response;
     }
 
-    // Default pass-through to original website
+    // Fallthrough to standard website (Shopify/Webflow/Wix)
     return fetch(request);
   }
 };

package/connectors/laravel/LynxSeoController.php

@@ -9,18 +9,18 @@ use Illuminate\Support\Facades\Cache;
 class LynxSeoController extends Controller
 {
     /**
-     * Serves programmatic SEO landing pages with 24h caching.
+     * Universal Programmatic Controller: Serves all 8 Programmatic Matrix types
+     * with 24h local Redis/file caching.
      */
-    public function show(Request $request, $service, $country, $city)
+    public function resolve(Request $request)
     {
-        $cacheKey = "lynx_page_{$service}_{$country}_{$city}";
+        $path = $request->path();
+        $cacheKey = "lynx_page_" . md5($path);
 
-        $pageData = Cache::remember($cacheKey, 86400, function () use ($service, $country, $city, $request) {
-            $response = Http::timeout(2)->post(config('services.lynxflow.endpoint', 'https://lynxintel.io/api/v1/render-page'), [
+        $pageData = Cache::remember($cacheKey, 86400, function () use ($path, $request) {
+            $response = Http::timeout(3)->post(config('services.lynxflow.endpoint', 'https://lynxintel.io/api/v1/render-page'), [
                 'licenseKey' => config('services.lynxflow.license_key'),
-                'service'    => $service,
-                'country'    => $country,
-                'city'       => $city,
+                'path'       => $path,
                 'domain'     => $request->root(),
                 'brandName'  => config('app.name'),
             ]);