@mostajs/agora-sourcing 0.0.1

package/README.md

@@ -0,0 +1,54 @@
+# @mostajs/agora-sourcing
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+**Statut** : ⚠️ **proposition / scaffold (0.0.1)** — non implémenté, périmètre à valider (cas C).
+
+**Le sourcing maison — « moins d'IA, plus d'outils ».** Au lieu de demander à un LLM de *chercher* les
+offres (où il hallucine et ne sait pas optimiser), `agora-sourcing` **scrape les faits**, **calcule la
+meilleure décision d'achat**, puis ne laisse au LLM que la **synthèse**.
+
+```
+SCRAPE (faits)              OPTIMISE (décision)               RFQ / PRÉSENTE
+moteur agora (cheerio)  →   @mostajs/ro-pla (solve)        →  @mostajs/sourcing (sendRfqs)
+registre de scrapers       min-cost-flow / MILP / hungarian    + Top-N
+   prix, devise, lien          allocation optimale
+```
+
+## Trois briques composées
+
+| Brique | Module | Rôle |
+|---|---|---|
+| **Collecte** | moteur **agora** (extrait d'`AgoraScope-Studio`) | scraping `cheerio` (+ puppeteer optionnel), **registre de scrapers façon ORM**, anti-bot (rate-limit/retries/CloudFlare), `search`/`scrape` |
+| **Optimisation** | **`@mostajs/ro-pla`** (composé) | transforme les offres en problème exact : achat fractionné (`min-cost-flow`), sélection sous contraintes (`MILP`), affectation (`hungarian`) |
+| **RFQ** | **`@mostajs/sourcing`** (composé) | `sendRfqs`, modèle `Offer`, dispatchers — **réutilisé, pas réécrit** |
+
+## API (esquisse)
+
+```ts
+agoraSource(query | order, { qty, constraints }) → {
+  offers,       // offres scrappées (faits : fournisseur, prix+devise, MOQ, pays, lien)
+  allocation,   // décision d'achat optimale (ro-pla) : combien acheter chez qui
+  topN          // Top-N par prix (référence)
+}
+```
+
+**Tout injecté (DI)** : scrapers, solveur `ro-pla`, dispatchers RFQ — le module est agnostique et testable
+par stub (règle d'or).
+
+## Périmètre
+
+- **Numérique** : réutilise les 21 scrapers d'`AgoraScope-Studio` (templates/code/apps).
+- **Physique (négoce)** : ajoute **connecteurs e-commerce** (Amazon/AliExpress/Alibaba…) + **découverte
+  moteur de recherche** (query → URLs candidates → scrape). *(Hypothèse de travail : négoce = physique ;
+  ajustable.)*
+
+## Conformité
+Respect **robots.txt / CGU** par défaut, rate-limit, identification UA ; pas de contournement abusif.
+Voir livrable #15 (sécurité/abus) avant prod.
+
+## Livrables (DEVRULES §14)
+- #1 Étude : `docs/01-ETUDE-AGORA-SOURCING.md`
+- #2 Audit : `docs/02-AUDIT-AGORA-SOURCING.md`
+- #3 Plan dev/test : `docs/03-PLAN-DEV-TEST-AGORA-SOURCING.md`
+
+> ⚠️ Non implémenté : ce README décrit l'**intention**. Voir le plan pour le séquencement.

package/dist/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @mostajs/agora-sourcing — persistance des résultats (cache) via **@mostajs/orm**.
+ * But : sur une nouvelle recherche, si le live échoue/ne renvoie rien, servir le DERNIER résultat
+ * connu (« au moins du disponible »). Persistance SUR FICHIER (sqljs/sqlite…), pas en mémoire.
+ * Composition stricte de @mostajs/orm (jamais de SQL direct). DI : la connexion est injectée.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { EntitySchema, IDialect } from "@mostajs/orm";
+import type { CachePort, SourcingResult } from "./types.js";
+/** Schéma ORM du cache (une ligne par requête). `payload` = JSON sérialisé du SourcingResult. */
+export declare const AGORA_SEARCH_SCHEMA: EntitySchema;
+/** Cache adossé à une connexion ORM déjà ouverte (DI). Aucune dépendance directe à un SGBD. */
+export declare function makeOrmCache(conn: IDialect): CachePort;
+/**
+ * Ouvre un cache persistant SUR FICHIER (compose @mostajs/orm, dialecte au choix, défaut sqljs).
+ * `uri` = chemin du fichier (ex. './sourcing-cache.db'). Renvoie le cache + `close()`.
+ * @mostajs/orm (et son driver, ex. sql.js) sont des PEERS — chargés au runtime.
+ */
+export declare function openFileCache(uri: string, dialect?: string): Promise<CachePort & {
+    close(): Promise<void>;
+}>;
+/** Cache mémoire (défaut/tests rapides ; NON persistant — préférer openFileCache en prod). */
+export declare class MemoryCache implements CachePort {
+    private m;
+    get(queryKey: string): Promise<{
+        result: SourcingResult;
+        at: number;
+    } | null>;
+    put(queryKey: string, result: SourcingResult): Promise<void>;
+}

package/dist/cache.js

@@ -0,0 +1,52 @@
+/** Schéma ORM du cache (une ligne par requête). `payload` = JSON sérialisé du SourcingResult. */
+export const AGORA_SEARCH_SCHEMA = {
+    name: "AgoraSearch",
+    collection: "agora_searches",
+    fields: {
+        queryKey: { type: "string", required: true, unique: true },
+        payload: { type: "text", required: true },
+        at: { type: "number", required: true },
+    },
+    relations: {},
+    indexes: [],
+    timestamps: false,
+};
+/** Cache adossé à une connexion ORM déjà ouverte (DI). Aucune dépendance directe à un SGBD. */
+export function makeOrmCache(conn) {
+    return {
+        async get(queryKey) {
+            const row = await conn.findOne(AGORA_SEARCH_SCHEMA, { queryKey });
+            if (!row)
+                return null;
+            try {
+                return { result: JSON.parse(row.payload), at: Number(row.at) };
+            }
+            catch {
+                return null;
+            }
+        },
+        async put(queryKey, result) {
+            const payload = JSON.stringify({ ...result, fromCache: undefined });
+            await conn.upsert(AGORA_SEARCH_SCHEMA, { queryKey }, { queryKey, payload, at: Date.now() });
+        },
+    };
+}
+/**
+ * Ouvre un cache persistant SUR FICHIER (compose @mostajs/orm, dialecte au choix, défaut sqljs).
+ * `uri` = chemin du fichier (ex. './sourcing-cache.db'). Renvoie le cache + `close()`.
+ * @mostajs/orm (et son driver, ex. sql.js) sont des PEERS — chargés au runtime.
+ */
+export async function openFileCache(uri, dialect = "sqljs") {
+    const orm = (await import("@mostajs/orm"));
+    // createIsolatedDialect : connexion INDÉPENDANTE (pas le singleton global) → réouvertures sûres ;
+    // sqljs recharge le fichier au connect et le flush après chaque write/disconnect (persistance fichier).
+    const conn = await orm.createIsolatedDialect({ dialect: dialect, uri, schemaStrategy: "update" }, [AGORA_SEARCH_SCHEMA]);
+    const cache = makeOrmCache(conn);
+    return { ...cache, async close() { await conn.disconnect(); } };
+}
+/** Cache mémoire (défaut/tests rapides ; NON persistant — préférer openFileCache en prod). */
+export class MemoryCache {
+    m = new Map();
+    async get(queryKey) { return this.m.get(queryKey) ?? null; }
+    async put(queryKey, result) { this.m.set(queryKey, { result: { ...result, fromCache: undefined }, at: Date.now() }); }
+}

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+/** Couple clé/secret d'une API marketplace officielle. */
+export interface ApiCredential {
+    appKey: string;
+    appSecret: string;
+}
+export interface AgoraConfig {
+    scrapers: string[];
+    discovery: string;
+    currency: string;
+    locale: string;
+    maxPages: number;
+    maxUrls: number;
+    cacheTtlMs: number;
+    proxyUrl?: string;
+    credentials: Partial<Record<"aliexpress" | "alibaba" | "dhgate" | "i1688", ApiCredential>>;
+}
+/** Lecteur d'env (str/num). Défaut = cascade @mostajs/config ; injectable pour les tests. */
+export interface EnvReader {
+    str(key: string, fallback?: string): string | undefined;
+    num(key: string, fallback: number): number;
+}
+/** Construit un lecteur depuis un objet plat (tests). */
+export declare function readerFromObject(env: Record<string, string | undefined>): EnvReader;
+/**
+ * Charge la config. Sans argument → cascade `@mostajs/config` (prod). Avec un objet env → lecture
+ * directe (tests). On peut aussi passer un `EnvReader` custom.
+ */
+export declare function loadConfig(env?: Record<string, string | undefined> | EnvReader): AgoraConfig;
+/** Un connecteur est-il actif ? (liste vide ⇒ tous). */
+export declare function isEnabled(cfg: AgoraConfig, key: string): boolean;
+/** Connecteurs API dont les identifiants sont présents ET actifs. */
+export declare function configuredApis(cfg: AgoraConfig): string[];

package/dist/config.js

@@ -0,0 +1,54 @@
+/**
+ * @mostajs/agora-sourcing — configuration TYPÉE, composée sur **@mostajs/config** (cascade de profils).
+ * On ne réimplémente PAS la lecture d'env : `@mostajs/config` (getEnv/getEnvNumber) gère la cascade
+ * `.env` + profils (MOSTA_ENV). Ce fichier ne fait que MAPPER ces clés vers un objet typé.
+ * Reste injectable (objet env) pour les tests. Les SECRETS vivent dans le `.env` (jamais committés).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import { getEnv, getEnvNumber } from "@mostajs/config";
+const cascadeReader = { str: (k, d) => getEnv(k, d), num: (k, d) => getEnvNumber(k, d) };
+/** Construit un lecteur depuis un objet plat (tests). */
+export function readerFromObject(env) {
+    return {
+        str: (k, d) => (env[k] ?? d),
+        num: (k, d) => { const n = Number.parseInt(env[k] ?? "", 10); return Number.isFinite(n) ? n : d; },
+    };
+}
+const csv = (v) => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+function cred(r, prefix) {
+    const appKey = r.str(`${prefix}_APP_KEY`);
+    const appSecret = r.str(`${prefix}_APP_SECRET`);
+    return appKey && appSecret ? { appKey, appSecret } : undefined;
+}
+/**
+ * Charge la config. Sans argument → cascade `@mostajs/config` (prod). Avec un objet env → lecture
+ * directe (tests). On peut aussi passer un `EnvReader` custom.
+ */
+export function loadConfig(env) {
+    const r = !env ? cascadeReader : ("str" in env && typeof env.str === "function" ? env : readerFromObject(env));
+    return {
+        scrapers: csv(r.str("AGORA_SCRAPERS")),
+        discovery: r.str("AGORA_DISCOVERY", "ddg"),
+        currency: r.str("AGORA_CURRENCY", "EUR").toUpperCase().slice(0, 3),
+        locale: r.str("AGORA_LOCALE", "fr"),
+        maxPages: r.num("AGORA_MAX_PAGES", 3),
+        maxUrls: r.num("AGORA_MAX_URLS", 8),
+        cacheTtlMs: r.num("AGORA_CACHE_TTL_MS", 86_400_000),
+        proxyUrl: r.str("AGORA_PROXY_URL") || undefined,
+        credentials: {
+            aliexpress: cred(r, "ALIEXPRESS"),
+            alibaba: cred(r, "ALIBABA"),
+            dhgate: cred(r, "DHGATE"),
+            i1688: cred(r, "ALI1688"),
+        },
+    };
+}
+/** Un connecteur est-il actif ? (liste vide ⇒ tous). */
+export function isEnabled(cfg, key) {
+    return cfg.scrapers.length === 0 || cfg.scrapers.includes(key);
+}
+/** Connecteurs API dont les identifiants sont présents ET actifs. */
+export function configuredApis(cfg) {
+    return Object.keys(cfg.credentials)
+        .filter((k) => cfg.credentials[k] && isEnabled(cfg, k));
+}

package/dist/discover-llm.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @mostajs/agora-sourcing — découverte par LLM (ex. Claude + web_search) : la force du LLM est de
+ * COMPRENDRE le produit et de CIBLER des pages pertinentes. Le LLM ne renvoie que des URLs ; c'est
+ * agora qui scrape ensuite les FAITS (prix vérifiables) → hybride. LLM injecté (DI), aucun SDK en dur.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { DiscoveryDialect } from "./types.js";
+/** Port LLM minimal (mêmes contours que `SourcingLlm` de @mostajs/sourcing). */
+export interface DiscoveryLlm {
+    complete(prompt: string): Promise<string>;
+}
+/** Extrait des URLs http(s) d'un texte libre (réponse LLM). Dé-doublonne. */
+export declare function parseUrlList(text: string): string[];
+/** Dialecte de découverte adossé à un LLM (Claude/…) : requête → URLs candidates pertinentes. */
+export declare function makeLlmDiscovery(llm: DiscoveryLlm, key?: string): DiscoveryDialect;

package/dist/discover-llm.js

@@ -0,0 +1,23 @@
+/** Extrait des URLs http(s) d'un texte libre (réponse LLM). Dé-doublonne. */
+export function parseUrlList(text) {
+    const urls = (text.match(/https?:\/\/[^\s"'<>)\]]+/g) ?? []).map((u) => u.replace(/[.,);]+$/, ""));
+    return [...new Set(urls)];
+}
+/** Dialecte de découverte adossé à un LLM (Claude/…) : requête → URLs candidates pertinentes. */
+export function makeLlmDiscovery(llm, key = "llm") {
+    return {
+        key,
+        kind: "discovery",
+        async discover(query, opts) {
+            const n = opts?.limit ?? 8;
+            const prompt = `Trouve ${n} URLs de PAGES PRODUIT réelles (fournisseurs / marketplaces, dont B2B chinois si pertinent) ` +
+                `pour acheter : « ${query} ». Donne UNIQUEMENT les URLs, une par ligne, sans autre texte.`;
+            try {
+                return parseUrlList(await llm.complete(prompt)).slice(0, n);
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}

package/dist/discover.d.ts

@@ -0,0 +1,6 @@
+import type { DiscoveryDialect } from "./types.js";
+import { type HttpOpts } from "./http.js";
+/** Extrait les URLs de résultats d'une page HTML DuckDuckGo. Pur (cheerio). */
+export declare function parseDdgResults(html: string, limit?: number): string[];
+/** Dialecte de découverte DuckDuckGo HTML. */
+export declare function ddgDiscovery(http?: HttpOpts): DiscoveryDialect;

package/dist/discover.js

@@ -0,0 +1,51 @@
+/**
+ * @mostajs/agora-sourcing — découverte par moteur de recherche : requête → URLs candidates.
+ * DuckDuckGo HTML (sans clé API). Pur `parseDdgResults` (testable hors réseau) + dialecte `ddg`.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import * as cheerio from "cheerio";
+import { getText } from "./http.js";
+/** Décode un lien de redirection DDG (`/l/?uddg=<encoded>`) ou renvoie l'URL http(s) directe. */
+function resolveDdgHref(href) {
+    if (!href)
+        return null;
+    const m = href.match(/[?&]uddg=([^&]+)/);
+    if (m) {
+        try {
+            const u = decodeURIComponent(m[1]);
+            return /^https?:\/\//.test(u) ? u : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return /^https?:\/\//.test(href) ? href : null;
+}
+/** Extrait les URLs de résultats d'une page HTML DuckDuckGo. Pur (cheerio). */
+export function parseDdgResults(html, limit = 10) {
+    const $ = cheerio.load(html);
+    const out = [];
+    const seen = new Set();
+    $('a.result__a, a.result__url, a[href*="uddg="]').each((_i, el) => {
+        if (out.length >= limit)
+            return;
+        const url = resolveDdgHref($(el).attr("href") ?? "");
+        if (url && !seen.has(url)) {
+            seen.add(url);
+            out.push(url);
+        }
+    });
+    return out;
+}
+/** Dialecte de découverte DuckDuckGo HTML. */
+export function ddgDiscovery(http = {}) {
+    return {
+        key: "ddg",
+        kind: "discovery",
+        async discover(query, opts) {
+            const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+            const html = await getText(url, { ...http, checkRobots: http.checkRobots ?? false });
+            return parseDdgResults(html, opts?.limit ?? 10);
+        },
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @mostajs/agora-sourcing — accès HTTP responsable : robots.txt + rate-limit + retries.
+ * Repris/condensé du moteur AgoraScope-Studio, sans état global ni couplage framework. DI fetch.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { FetchFn } from "./types.js";
+/**
+ * Vérifie un chemin contre un robots.txt (groupe `User-agent: *`), de façon volontairement
+ * simple : on refuse si un `Disallow:` non vide est préfixe du chemin (et qu'aucun `Allow:`
+ * plus spécifique ne l'autorise). Pure → testable hors réseau.
+ */
+export declare function isAllowedByRobots(robotsTxt: string, path: string, ua?: string): boolean;
+export interface HttpOpts {
+    fetch?: FetchFn;
+    retries?: number;
+    minIntervalMs?: number;
+    checkRobots?: boolean;
+    /** User-Agent à présenter (défaut : navigateur). */
+    userAgent?: string;
+    /** horloge injectable (tests). */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** GET texte avec robots.txt + rate-limit + retries (backoff). Retourne le HTML. */
+export declare function getText(url: string, opts?: HttpOpts): Promise<string>;

package/dist/http.js

@@ -0,0 +1,101 @@
+// UA navigateur par défaut : de nombreux sites (et moteurs) renvoient une page vide/challenge à un UA
+// « bot » (constaté : DuckDuckGo HTML → 202 sans résultats). On reste correct via robots.txt (vérifié
+// séparément) + rate-limit. Surchargable par `opts.userAgent`.
+const UA = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+/** fetch global par défaut (Node ≥ 18). */
+const defaultFetch = (url, init) => globalThis.fetch(url, init);
+/**
+ * Vérifie un chemin contre un robots.txt (groupe `User-agent: *`), de façon volontairement
+ * simple : on refuse si un `Disallow:` non vide est préfixe du chemin (et qu'aucun `Allow:`
+ * plus spécifique ne l'autorise). Pure → testable hors réseau.
+ */
+export function isAllowedByRobots(robotsTxt, path, ua = "*") {
+    const lines = robotsTxt.split(/\r?\n/).map((l) => l.replace(/#.*$/, "").trim());
+    let inGroup = false;
+    let applies = false;
+    const rules = [];
+    for (const line of lines) {
+        const m = /^([A-Za-z-]+)\s*:\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const field = m[1].toLowerCase();
+        const val = m[2].trim();
+        if (field === "user-agent") {
+            if (inGroup && applies)
+                break; // fin du groupe pertinent
+            inGroup = true;
+            if (val === "*" || val.toLowerCase() === ua.toLowerCase())
+                applies = true;
+            else if (!applies)
+                applies = false;
+        }
+        else if (applies && (field === "allow" || field === "disallow")) {
+            rules.push({ allow: field === "allow", path: val });
+        }
+    }
+    // règle la plus spécifique (plus long préfixe) l'emporte ; Disallow vide = tout autorisé.
+    let decision = true;
+    let best = -1;
+    for (const r of rules) {
+        if (r.path === "") {
+            if (!r.allow)
+                continue;
+        }
+        if (path.startsWith(r.path) && r.path.length > best) {
+            best = r.path.length;
+            decision = r.allow;
+        }
+    }
+    return decision;
+}
+const lastHit = new Map();
+/** Petite limitation de débit par hôte (intervalle minimal). */
+async function rateLimit(host, minIntervalMs, now, sleep) {
+    const prev = lastHit.get(host) ?? 0;
+    const wait = prev + minIntervalMs - now();
+    if (wait > 0)
+        await sleep(wait);
+    lastHit.set(host, now());
+}
+/** GET texte avec robots.txt + rate-limit + retries (backoff). Retourne le HTML. */
+export async function getText(url, opts = {}) {
+    const f = opts.fetch ?? defaultFetch;
+    const retries = opts.retries ?? 2;
+    const minInterval = opts.minIntervalMs ?? 1000;
+    const now = opts.now ?? (() => Date.now());
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const ua = opts.userAgent ?? UA;
+    const u = new URL(url);
+    if (opts.checkRobots !== false) {
+        try {
+            const res = await f(`${u.origin}/robots.txt`, { headers: { "user-agent": ua } });
+            if (res.status === 200) {
+                const txt = await res.text();
+                if (!isAllowedByRobots(txt, u.pathname, UA)) {
+                    throw new Error(`robots.txt interdit l'accès à ${u.pathname}`);
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.startsWith("robots.txt"))
+                throw e;
+            /* robots inaccessible → on continue prudemment */
+        }
+    }
+    await rateLimit(u.host, minInterval, now, sleep);
+    let lastErr = "?";
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const res = await f(url, { headers: { "user-agent": ua, accept: "text/html,application/xhtml+xml" } });
+            if (res.status >= 200 && res.status < 300)
+                return res.text();
+            lastErr = `HTTP ${res.status}`;
+        }
+        catch (e) {
+            lastErr = e;
+        }
+        if (attempt < retries)
+            await sleep(250 * Math.pow(2, attempt));
+    }
+    throw new Error(`getText échec après ${retries + 1} tentatives : ${String(lastErr)}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @mostajs/agora-sourcing — sourcing maison : SCRAPE (faits) → OPTIMISE (ro-pla) → RFQ (sourcing).
+ * « Moins d'IA, plus d'outils » : l'algorithme collecte et décide ; le LLM ne fait que synthétiser.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export * from "./types.js";
+export { registerScraper, getScraper, listScrapers, clearScrapers, activeScrapers, pickScraper, registerDiscovery, getDiscovery, listDiscovery, clearDiscovery, } from "./registry.js";
+export { getText, isAllowedByRobots, type HttpOpts } from "./http.js";
+export { genericScraper, parseOffer, parsePrice } from "./scrapers/generic.js";
+export { makeSiteScraper, parseWithProfile, BUILTIN_PROFILES, type SiteProfile } from "./scrapers/site-profile.js";
+export { ddgDiscovery, parseDdgResults } from "./discover.js";
+export { optimizeOffers, optimizeSplitBuy, optimizeConstrained, optimizeTiered, optimizeAssignment, assignLinesToSuppliers, optimizeContinuous, topNByPrice, type AssignLine, type LineAssignment } from "./optimize.js";
+export { sendAgoraRfqs, toSourcingOffers, type RfqDeps, type SourcingOffer, type SendRfqs } from "./rfq.js";
+export { makeAgoraSourcingTool, type AgoraToolDeps } from "./tool.js";
+export { normalizeOffers, landedUnit, convert, type FxRates, type LandedOptions } from "./landed.js";
+export { filterRelevant, relevanceScore, tokens } from "./relevance.js";
+export { makeLlmDiscovery, parseUrlList, type DiscoveryLlm } from "./discover-llm.js";
+export { loadConfig, isEnabled, configuredApis, readerFromObject, type AgoraConfig, type ApiCredential, type EnvReader } from "./config.js";
+export { makeOrmCache, openFileCache, MemoryCache, AGORA_SEARCH_SCHEMA } from "./cache.js";
+export { aliexpressConnector, signTop, buildSignedUrl, mapProducts, type AliexpressConfig, type JsonFetch } from "./scrapers/aliexpress.js";
+import { type JsonFetch as AxJsonFetch } from "./scrapers/aliexpress.js";
+import { type AgoraConfig } from "./config.js";
+import type { HttpOpts } from "./http.js";
+import type { Offer, OptimizeConstraints, SolverPort, SourcingResult, CachePort } from "./types.js";
+/** Enregistre les built-ins : scraper générique + profils e-commerce + découverte DDG. */
+export declare function registerBuiltins(http?: HttpOpts): void;
+/**
+ * Enregistre les connecteurs par API officielle dont les identifiants `.env` sont présents ET actifs
+ * (`AGORA_SCRAPERS`). Sans clé, le connecteur n'est pas enregistré (repli sur autres sources/cache).
+ * Renvoie les clés enregistrées.
+ */
+export declare function registerApis(cfg: AgoraConfig, deps?: {
+    httpJson?: AxJsonFetch;
+}): string[];
+/**
+ * Solveur par défaut = `@mostajs/ro-pla` (peer), chargé paresseusement pour ne pas le rendre
+ * obligatoire au build. L'app/test peut injecter son propre `SolverPort` (DI).
+ */
+export declare function defaultSolver(): Promise<SolverPort>;
+export interface AgoraSourceOpts {
+    qty: number;
+    constraints?: OptimizeConstraints;
+    topN?: number;
+    solver?: SolverPort;
+    /** Filtre appliqué aux offres scrappées AVANT optimisation (ex. pertinence). */
+    filter?: (offers: Offer[]) => Offer[];
+}
+/**
+ * Sourcing de bout en bout à partir d'URLs déjà découvertes (la découverte moteur de recherche
+ * arrive en Phase 3) : scrape chaque URL → offres → optimise (ro-pla) → { offers, topN, allocation }.
+ */
+export declare function agoraSourceFromUrls(urls: string[], opts: AgoraSourceOpts, scrape: (url: string) => Promise<Offer | null>): Promise<SourcingResult>;
+/** Options de la recherche par requête (découverte/scrape injectables + cache de persistance). */
+export interface QuerySourceOpts extends AgoraSourceOpts {
+    http?: HttpOpts;
+    maxUrls?: number;
+    /** Clé de cache (défaut : requête normalisée). */
+    queryKey?: string;
+    /** Cache ORM (persistance fichier) — repli « au moins du disponible ». */
+    cache?: CachePort;
+    /** Fraîcheur : sous ce TTL, on sert le cache sans re-scraper. 0/absent ⇒ pas de hit frais. */
+    cacheTtlMs?: number;
+    /** Découverte injectable (défaut : registre `ddg`). */
+    discover?: (query: string) => Promise<string[]>;
+    /** Clé de découverte à utiliser dans le registre (ex. "ddg", "llm"). Défaut "ddg". */
+    discoveryKey?: string;
+    /** Scrape injectable (défaut : routage par hôte). */
+    scrape?: (url: string) => Promise<Offer | null>;
+    /** Filtre de pertinence titre↔requête : `true`/seuil (défaut 0.34) ou `false` pour désactiver. */
+    relevance?: boolean | number;
+}
+/**
+ * Sourcing complet à partir d'une REQUÊTE produit, avec **persistance** :
+ *  1. hit cache FRAIS (< TTL) → servi sans re-scraper ;
+ *  2. sinon live : découverte → scrape routé → optimisation ; succès → on PERSISTE ;
+ *  3. si le live échoue / ne renvoie rien → **repli sur le dernier résultat connu** (cache).
+ * `registerBuiltins()` doit avoir été appelé (sinon découverte/scraper sont injectés en repli).
+ */
+export declare function agoraSourceFromQuery(query: string, opts: QuerySourceOpts): Promise<SourcingResult>;

package/dist/index.js

@@ -0,0 +1,121 @@
+/**
+ * @mostajs/agora-sourcing — sourcing maison : SCRAPE (faits) → OPTIMISE (ro-pla) → RFQ (sourcing).
+ * « Moins d'IA, plus d'outils » : l'algorithme collecte et décide ; le LLM ne fait que synthétiser.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export * from "./types.js";
+export { registerScraper, getScraper, listScrapers, clearScrapers, activeScrapers, pickScraper, registerDiscovery, getDiscovery, listDiscovery, clearDiscovery, } from "./registry.js";
+export { getText, isAllowedByRobots } from "./http.js";
+export { genericScraper, parseOffer, parsePrice } from "./scrapers/generic.js";
+export { makeSiteScraper, parseWithProfile, BUILTIN_PROFILES } from "./scrapers/site-profile.js";
+export { ddgDiscovery, parseDdgResults } from "./discover.js";
+export { optimizeOffers, optimizeSplitBuy, optimizeConstrained, optimizeTiered, optimizeAssignment, assignLinesToSuppliers, optimizeContinuous, topNByPrice } from "./optimize.js";
+export { sendAgoraRfqs, toSourcingOffers } from "./rfq.js";
+export { makeAgoraSourcingTool } from "./tool.js";
+export { normalizeOffers, landedUnit, convert } from "./landed.js";
+export { filterRelevant, relevanceScore, tokens } from "./relevance.js";
+export { makeLlmDiscovery, parseUrlList } from "./discover-llm.js";
+export { loadConfig, isEnabled, configuredApis, readerFromObject } from "./config.js";
+export { makeOrmCache, openFileCache, MemoryCache, AGORA_SEARCH_SCHEMA } from "./cache.js";
+export { aliexpressConnector, signTop, buildSignedUrl, mapProducts } from "./scrapers/aliexpress.js";
+import { registerScraper, registerDiscovery, getDiscovery, pickScraper } from "./registry.js";
+import { genericScraper } from "./scrapers/generic.js";
+import { makeSiteScraper, BUILTIN_PROFILES } from "./scrapers/site-profile.js";
+import { ddgDiscovery } from "./discover.js";
+import { aliexpressConnector } from "./scrapers/aliexpress.js";
+import { isEnabled as cfgIsEnabled } from "./config.js";
+import { optimizeOffers, topNByPrice } from "./optimize.js";
+import { filterRelevant } from "./relevance.js";
+const EMPTY = { offers: [], topN: [], allocation: { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" } };
+/** Enregistre les built-ins : scraper générique + profils e-commerce + découverte DDG. */
+export function registerBuiltins(http = {}) {
+    registerScraper(genericScraper(http));
+    for (const p of BUILTIN_PROFILES)
+        registerScraper(makeSiteScraper(p, http));
+    registerDiscovery(ddgDiscovery(http));
+}
+/**
+ * Enregistre les connecteurs par API officielle dont les identifiants `.env` sont présents ET actifs
+ * (`AGORA_SCRAPERS`). Sans clé, le connecteur n'est pas enregistré (repli sur autres sources/cache).
+ * Renvoie les clés enregistrées.
+ */
+export function registerApis(cfg, deps = {}) {
+    const done = [];
+    const ax = cfg.credentials.aliexpress;
+    if (ax && cfgIsEnabled(cfg, "aliexpress")) {
+        registerScraper(aliexpressConnector({ appKey: ax.appKey, appSecret: ax.appSecret, httpJson: deps.httpJson, targetCurrency: cfg.currency }));
+        done.push("aliexpress");
+    }
+    return done;
+}
+/**
+ * Solveur par défaut = `@mostajs/ro-pla` (peer), chargé paresseusement pour ne pas le rendre
+ * obligatoire au build. L'app/test peut injecter son propre `SolverPort` (DI).
+ */
+export async function defaultSolver() {
+    // peer optionnel chargé au runtime — specifier indirect pour ne pas le résoudre au build
+    const spec = "@mostajs/ro-pla";
+    const rp = (await import(spec));
+    rp.registerBuiltinSolvers();
+    return { solve: (problem, opts) => rp.solve(problem, opts) };
+}
+/**
+ * Sourcing de bout en bout à partir d'URLs déjà découvertes (la découverte moteur de recherche
+ * arrive en Phase 3) : scrape chaque URL → offres → optimise (ro-pla) → { offers, topN, allocation }.
+ */
+export async function agoraSourceFromUrls(urls, opts, scrape) {
+    const settled = await Promise.all(urls.map((u) => scrape(u).catch(() => null)));
+    const collected = settled.filter((o) => o != null);
+    const offers = opts.filter ? opts.filter(collected) : collected;
+    if (!offers.length)
+        return { ...EMPTY };
+    const solver = opts.solver ?? (await defaultSolver());
+    const allocation = await optimizeOffers(offers, opts.qty, solver, opts.constraints);
+    return { offers, topN: topNByPrice(offers, opts.topN ?? 5), allocation };
+}
+/**
+ * Sourcing complet à partir d'une REQUÊTE produit, avec **persistance** :
+ *  1. hit cache FRAIS (< TTL) → servi sans re-scraper ;
+ *  2. sinon live : découverte → scrape routé → optimisation ; succès → on PERSISTE ;
+ *  3. si le live échoue / ne renvoie rien → **repli sur le dernier résultat connu** (cache).
+ * `registerBuiltins()` doit avoir été appelé (sinon découverte/scraper sont injectés en repli).
+ */
+export async function agoraSourceFromQuery(query, opts) {
+    const http = opts.http ?? {};
+    const key = opts.queryKey ?? query.trim().toLowerCase();
+    // 1) hit cache frais
+    if (opts.cache && opts.cacheTtlMs && opts.cacheTtlMs > 0) {
+        const c = await opts.cache.get(key);
+        if (c && Date.now() - c.at <= opts.cacheTtlMs)
+            return { ...c.result, fromCache: true, cachedAt: c.at };
+    }
+    // 2) live
+    let result = null;
+    try {
+        const discover = opts.discover ?? (async (q) => {
+            const d = getDiscovery(opts.discoveryKey ?? "ddg") ?? ddgDiscovery(http);
+            return d.discover(q, { limit: opts.maxUrls ?? 8 });
+        });
+        const fb = genericScraper(http);
+        const scrape = opts.scrape ?? ((url) => (pickScraper(url) ?? fb).scrape(url));
+        const rel = opts.relevance === false ? undefined
+            : (offers) => filterRelevant(offers, query, typeof opts.relevance === "number" ? opts.relevance : 0.34);
+        const urls = await discover(query);
+        result = await agoraSourceFromUrls(urls, { ...opts, filter: opts.filter ?? rel }, scrape);
+    }
+    catch {
+        result = null;
+    }
+    // 3) succès → persiste ; échec/vide → repli dernier connu
+    if (result && result.offers.length) {
+        if (opts.cache)
+            await opts.cache.put(key, result);
+        return result;
+    }
+    if (opts.cache) {
+        const c = await opts.cache.get(key);
+        if (c)
+            return { ...c.result, fromCache: true, cachedAt: c.at };
+    }
+    return result ?? { ...EMPTY };
+}