@mostajs/agora-sourcing 0.0.1

package/dist/landed.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @mostajs/agora-sourcing — coût RENDU (landed cost) + normalisation FX.
+ * Convertit chaque offre vers une devise cible et intègre livraison + droits → un **prix unitaire
+ * comparable**. On normalise PUIS on optimise → l'optimisation porte sur le coût réel, pas le prix nu.
+ * Prérequis du multi-objectif (NSGA-II, ro-pla ⏳).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { Offer } from "./types.js";
+/** Taux de change : `rates[devise]` = valeur de 1 unité de cette devise dans la devise CIBLE. */
+export type FxRates = Record<string, number>;
+export interface LandedOptions {
+    /** Devise cible (ex. "EUR"). */
+    target: string;
+    /** Table FX (cible → 1). Devise absente ⇒ 1 (supposée déjà cible). */
+    rates?: FxRates;
+    /** Taux de droits/douane appliqué à la marchandise (ex. 0.05 = 5 %). */
+    dutyRate?: number;
+}
+/** Convertit un montant de `from` vers la cible via la table FX. */
+export declare function convert(amount: number, from: string | undefined, opts: LandedOptions): number;
+/** Prix unitaire RENDU dans la devise cible : (prix·(1+droits) + livraison/u), converti. */
+export declare function landedUnit(unitPrice: number, offer: Offer, opts: LandedOptions): number;
+/**
+ * Normalise des offres vers la devise cible en **coût rendu** : `unitPrice` (et chaque palier)
+ * deviennent le landed cost en `target`. L'original est conservé dans `raw.nominal`.
+ * On peut ensuite passer ces offres à `optimizeOffers` → optimisation sur le coût réel.
+ */
+export declare function normalizeOffers(offers: Offer[], opts: LandedOptions): Offer[];

package/dist/landed.js

@@ -0,0 +1,32 @@
+/** Convertit un montant de `from` vers la cible via la table FX. */
+export function convert(amount, from, opts) {
+    const f = (from || opts.target).toUpperCase();
+    if (f === opts.target.toUpperCase())
+        return amount;
+    const rate = opts.rates?.[f];
+    return rate != null ? amount * rate : amount; // taux inconnu → pas de conversion (prudence)
+}
+/** Prix unitaire RENDU dans la devise cible : (prix·(1+droits) + livraison/u), converti. */
+export function landedUnit(unitPrice, offer, opts) {
+    const goods = convert(unitPrice, offer.currency, opts) * (1 + (opts.dutyRate ?? 0));
+    const ship = convert(offer.shippingCost ?? 0, offer.currency, opts);
+    return goods + ship;
+}
+/**
+ * Normalise des offres vers la devise cible en **coût rendu** : `unitPrice` (et chaque palier)
+ * deviennent le landed cost en `target`. L'original est conservé dans `raw.nominal`.
+ * On peut ensuite passer ces offres à `optimizeOffers` → optimisation sur le coût réel.
+ */
+export function normalizeOffers(offers, opts) {
+    return offers.map((o) => {
+        const tiers = o.priceTiers?.map((t) => ({ minQty: t.minQty, unitPrice: landedUnit(t.unitPrice, o, opts) }));
+        return {
+            ...o,
+            unitPrice: landedUnit(o.unitPrice, o, opts),
+            currency: opts.target.toUpperCase().slice(0, 3),
+            priceTiers: tiers,
+            shippingCost: 0, // déjà intégré au prix rendu
+            raw: { ...o.raw, nominal: { unitPrice: o.unitPrice, currency: o.currency, shippingCost: o.shippingCost } },
+        };
+    });
+}

package/dist/optimize.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @mostajs/agora-sourcing — OPTIMISATION d'achat (le différenciateur vs LLM).
+ * Transforme des offres scrappées en problème résolu EXACTEMENT par @mostajs/ro-pla
+ * (solveur injecté, DI) : achat fractionné (min-cost-flow), sélection sous contraintes (MILP).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { Offer, Allocation, OptimizeConstraints, SolverPort } from "./types.js";
+/** Top-N par prix croissant (référence — ce que fait un LLM « au mieux »). */
+export declare function topNByPrice(offers: Offer[], n?: number): Offer[];
+/**
+ * Achat FRACTIONNÉ multi-fournisseurs au coût total minimal sous capacité (stock).
+ * Modèle flot : source → fournisseur (cap=stock, cost=prix u.) → puits (cap=stock, cost=0).
+ * `arcFlows[2i]` = quantité achetée au fournisseur i. Sans capacité suffisante → flot maximal (partial).
+ */
+export declare function optimizeSplitBuy(offers: Offer[], qty: number, solver: SolverPort, c?: OptimizeConstraints): Promise<Allocation>;
+/**
+ * Sélection SOUS CONTRAINTES (budget, nb max de fournisseurs, MOQ par fournisseur) via MILP.
+ * Variables : q_i (entiers, qté par fournisseur) puis y_i (binaires, fournisseur retenu).
+ * Objectif : min Σ prix_i·q_i. Contraintes : Σq=qty ; q_i≤cap·y_i ; q_i≥moq·y_i ; Σy≤max ; Σprix·q≤budget ; y_i≤1.
+ */
+export declare function optimizeConstrained(offers: Offer[], qty: number, c: OptimizeConstraints, solver: SolverPort): Promise<Allocation>;
+/**
+ * Optimisation avec PALIERS de prix dégressifs (B2B « all-units » : Alibaba/1688). Pour chaque
+ * (offre, palier) éligible (minQty ≤ qté) : variable entière `q` + binaire `z`. Un fournisseur
+ * n'opère qu'UN palier (Σz ≤ 1) ; `q ∈ [minQty, borne_sup]` du palier actif ; Σq = qté ;
+ * objectif min Σ prix_palier·q. Résolu en **MILP** par `@mostajs/ro-pla` (branch-and-bound).
+ */
+export declare function optimizeTiered(offers: Offer[], qty: number, solver: SolverPort, c?: OptimizeConstraints): Promise<Allocation>;
+export interface AssignLine {
+    key: string;
+    qty: number;
+    offers: Offer[];
+}
+export interface LineAssignment {
+    line: string;
+    supplier: string;
+    unitPrice: number;
+    qty: number;
+    cost: number;
+    url: string;
+}
+/** Wrapper direct du dialecte `assignment` (hongrois) : matrice de coûts → affectation optimale. */
+export declare function optimizeAssignment(cost: number[][], solver: SolverPort): Promise<{
+    assignment: number[];
+    total: number;
+}>;
+/**
+ * Affecte N **lignes** de commande à des fournisseurs **distincts** (diversification / 1 fournisseur
+ * par produit), au coût total minimal — via le **hongrois** (ro-pla). Colonnes = fournisseurs candidats.
+ */
+export declare function assignLinesToSuppliers(lines: AssignLine[], solver: SolverPort): Promise<{
+    assignment: LineAssignment[];
+    totalCost: number;
+    status: "optimal" | "infeasible";
+}>;
+/**
+ * Allocation **continue** (biens divisibles : vrac/poids/volume) au coût min, avec contraintes
+ * linéaires — notamment une **part maximale par fournisseur** que le flot n'exprime pas simplement.
+ * Résolu en **LP (simplexe)** par ro-pla.
+ */
+export declare function optimizeContinuous(offers: Offer[], qty: number, solver: SolverPort, c?: OptimizeConstraints & {
+    maxSharePerSupplier?: number;
+}): Promise<Allocation>;
+/** Optimise : paliers (B2B) → MILP par paliers ; sinon contraintes → MILP ; sinon achat fractionné (flot). */
+export declare function optimizeOffers(offers: Offer[], qty: number, solver: SolverPort, c?: OptimizeConstraints): Promise<Allocation>;

package/dist/optimize.js

@@ -0,0 +1,332 @@
+/** Top-N par prix croissant (référence — ce que fait un LLM « au mieux »). */
+export function topNByPrice(offers, n = 5) {
+    return offers.filter((o) => Number.isFinite(o.unitPrice)).sort((a, b) => a.unitPrice - b.unitPrice).slice(0, n);
+}
+function eligible(offers, c) {
+    let xs = offers.filter((o) => Number.isFinite(o.unitPrice) && o.unitPrice >= 0);
+    if (c?.allowedCountries?.length) {
+        const set = new Set(c.allowedCountries.map((s) => s.toUpperCase()));
+        xs = xs.filter((o) => !o.country || set.has(o.country.toUpperCase()));
+    }
+    return xs;
+}
+/**
+ * Achat FRACTIONNÉ multi-fournisseurs au coût total minimal sous capacité (stock).
+ * Modèle flot : source → fournisseur (cap=stock, cost=prix u.) → puits (cap=stock, cost=0).
+ * `arcFlows[2i]` = quantité achetée au fournisseur i. Sans capacité suffisante → flot maximal (partial).
+ */
+export async function optimizeSplitBuy(offers, qty, solver, c) {
+    const items = eligible(offers, c);
+    if (!items.length || qty <= 0)
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const n = items.length;
+    const source = 0;
+    const sink = n + 1;
+    const cap = (o) => (Number.isFinite(o.stock) && o.stock > 0 ? o.stock : qty);
+    const arcs = [];
+    for (let i = 0; i < n; i++) {
+        arcs.push({ from: source, to: i + 1, capacity: cap(items[i]), cost: items[i].unitPrice });
+        arcs.push({ from: i + 1, to: sink, capacity: cap(items[i]), cost: 0 });
+    }
+    const totalCap = items.reduce((s, o) => s + cap(o), 0);
+    const problem = { kind: "flow", arcs, source, sink, nodes: n + 2, ...(totalCap >= qty ? { value: qty } : {}) };
+    const sol = (await solver.solve(problem));
+    if (!sol || sol.status === "infeasible")
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const bySupplier = [];
+    for (let i = 0; i < n; i++) {
+        const q = sol.arcFlows[2 * i] ?? 0;
+        if (q > 0) {
+            const o = items[i];
+            bySupplier.push({ supplier: o.supplier, qty: q, unitPrice: o.unitPrice, currency: o.currency, cost: q * o.unitPrice, url: o.url });
+        }
+    }
+    const filled = bySupplier.reduce((s, b) => s + b.qty, 0);
+    return { bySupplier, totalCost: sol.cost, filled, status: filled >= qty ? "optimal" : "partial" };
+}
+/**
+ * Sélection SOUS CONTRAINTES (budget, nb max de fournisseurs, MOQ par fournisseur) via MILP.
+ * Variables : q_i (entiers, qté par fournisseur) puis y_i (binaires, fournisseur retenu).
+ * Objectif : min Σ prix_i·q_i. Contraintes : Σq=qty ; q_i≤cap·y_i ; q_i≥moq·y_i ; Σy≤max ; Σprix·q≤budget ; y_i≤1.
+ */
+export async function optimizeConstrained(offers, qty, c, solver) {
+    const items = eligible(offers, c);
+    if (!items.length || qty <= 0)
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const n = items.length;
+    const cap = (o) => (Number.isFinite(o.stock) && o.stock > 0 ? Math.min(o.stock, qty) : qty);
+    const nv = 2 * n; // [q_0..q_{n-1}, y_0..y_{n-1}]
+    const c_obj = [...items.map((o) => o.unitPrice), ...new Array(n).fill(0)];
+    const A = [];
+    const b = [];
+    const rel = [];
+    const row = () => new Array(nv).fill(0);
+    // Σ q_i = qty
+    {
+        const r = row();
+        for (let i = 0; i < n; i++)
+            r[i] = 1;
+        A.push(r);
+        b.push(qty);
+        rel.push("=");
+    }
+    for (let i = 0; i < n; i++) {
+        // q_i - cap_i·y_i <= 0
+        {
+            const r = row();
+            r[i] = 1;
+            r[n + i] = -cap(items[i]);
+            A.push(r);
+            b.push(0);
+            rel.push("<=");
+        }
+        // q_i - moq_i·y_i >= 0
+        const moq = items[i].moq ?? 0;
+        if (moq > 0) {
+            const r = row();
+            r[i] = 1;
+            r[n + i] = -moq;
+            A.push(r);
+            b.push(0);
+            rel.push(">=");
+        }
+        // y_i <= 1
+        {
+            const r = row();
+            r[n + i] = 1;
+            A.push(r);
+            b.push(1);
+            rel.push("<=");
+        }
+    }
+    if (c.maxSuppliers != null) {
+        const r = row();
+        for (let i = 0; i < n; i++)
+            r[n + i] = 1;
+        A.push(r);
+        b.push(c.maxSuppliers);
+        rel.push("<=");
+    }
+    if (c.budget != null) {
+        const r = row();
+        for (let i = 0; i < n; i++)
+            r[i] = items[i].unitPrice;
+        A.push(r);
+        b.push(c.budget);
+        rel.push("<=");
+    }
+    const problem = { kind: "milp", c: c_obj, A, b, relations: rel, objective: "min", integers: Array.from({ length: nv }, (_v, i) => i) };
+    const sol = (await solver.solve(problem));
+    if (!sol || sol.status !== "optimal")
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const bySupplier = [];
+    for (let i = 0; i < n; i++) {
+        const q = Math.round(sol.x[i] ?? 0);
+        if (q > 0) {
+            const o = items[i];
+            bySupplier.push({ supplier: o.supplier, qty: q, unitPrice: o.unitPrice, currency: o.currency, cost: q * o.unitPrice, url: o.url });
+        }
+    }
+    const filled = bySupplier.reduce((s, b2) => s + b2.qty, 0);
+    return { bySupplier, totalCost: bySupplier.reduce((s, b2) => s + b2.cost, 0), filled, status: filled >= qty ? "optimal" : "partial" };
+}
+/**
+ * Optimisation avec PALIERS de prix dégressifs (B2B « all-units » : Alibaba/1688). Pour chaque
+ * (offre, palier) éligible (minQty ≤ qté) : variable entière `q` + binaire `z`. Un fournisseur
+ * n'opère qu'UN palier (Σz ≤ 1) ; `q ∈ [minQty, borne_sup]` du palier actif ; Σq = qté ;
+ * objectif min Σ prix_palier·q. Résolu en **MILP** par `@mostajs/ro-pla` (branch-and-bound).
+ */
+export async function optimizeTiered(offers, qty, solver, c) {
+    const items = eligible(offers, c);
+    if (!items.length || qty <= 0)
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const pairs = [];
+    const offerPairs = items.map(() => []);
+    items.forEach((o, i) => {
+        const tiers = (o.priceTiers && o.priceTiers.length
+            ? [...o.priceTiers]
+            : [{ minQty: o.moq && o.moq > 0 ? o.moq : 1, unitPrice: o.unitPrice }]).sort((a, b) => a.minQty - b.minQty);
+        tiers.forEach((t, k) => {
+            if (t.minQty > qty)
+                return; // palier inatteignable seul
+            const upper = Math.min(tiers[k + 1] ? tiers[k + 1].minQty - 1 : qty, qty);
+            if (upper < t.minQty)
+                return;
+            offerPairs[i].push(pairs.length);
+            pairs.push({ i, price: t.unitPrice, minQty: t.minQty, upper });
+        });
+    });
+    if (!pairs.length)
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const nP = pairs.length;
+    const nv = 2 * nP; // [q_0..q_{nP-1}, z_0..z_{nP-1}]
+    const cObj = [...pairs.map((p) => p.price), ...new Array(nP).fill(0)];
+    const A = [];
+    const b = [];
+    const rel = [];
+    const row = () => new Array(nv).fill(0);
+    {
+        const r = row();
+        for (let p = 0; p < nP; p++)
+            r[p] = 1;
+        A.push(r);
+        b.push(qty);
+        rel.push("=");
+    } // Σq = qty
+    for (let p = 0; p < nP; p++) {
+        {
+            const r = row();
+            r[p] = 1;
+            r[nP + p] = -pairs[p].minQty;
+            A.push(r);
+            b.push(0);
+            rel.push(">=");
+        } // q ≥ minQty·z
+        {
+            const r = row();
+            r[p] = 1;
+            r[nP + p] = -pairs[p].upper;
+            A.push(r);
+            b.push(0);
+            rel.push("<=");
+        } // q ≤ upper·z
+        {
+            const r = row();
+            r[nP + p] = 1;
+            A.push(r);
+            b.push(1);
+            rel.push("<=");
+        } // z ≤ 1
+    }
+    for (const ps of offerPairs) { // un seul palier/offre
+        if (ps.length <= 1)
+            continue;
+        const r = row();
+        for (const p of ps)
+            r[nP + p] = 1;
+        A.push(r);
+        b.push(1);
+        rel.push("<=");
+    }
+    if (c?.maxSuppliers != null) {
+        const r = row();
+        for (let p = 0; p < nP; p++)
+            r[nP + p] = 1;
+        A.push(r);
+        b.push(c.maxSuppliers);
+        rel.push("<=");
+    }
+    if (c?.budget != null) {
+        const r = row();
+        for (let p = 0; p < nP; p++)
+            r[p] = pairs[p].price;
+        A.push(r);
+        b.push(c.budget);
+        rel.push("<=");
+    }
+    const problem = { kind: "milp", c: cObj, A, b, relations: rel, objective: "min", integers: Array.from({ length: nv }, (_v, i) => i) };
+    const sol = (await solver.solve(problem, { maxNodes: 20000 }));
+    if (!sol || sol.status !== "optimal")
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const bySupplier = [];
+    for (let p = 0; p < nP; p++) {
+        const q = Math.round(sol.x[p] ?? 0);
+        if (q > 0) {
+            const o = items[pairs[p].i];
+            bySupplier.push({ supplier: o.supplier, qty: q, unitPrice: pairs[p].price, currency: o.currency, cost: q * pairs[p].price, url: o.url });
+        }
+    }
+    const filled = bySupplier.reduce((s, x) => s + x.qty, 0);
+    return { bySupplier, totalCost: bySupplier.reduce((s, x) => s + x.cost, 0), filled, status: filled >= qty ? "optimal" : "partial" };
+}
+/** Wrapper direct du dialecte `assignment` (hongrois) : matrice de coûts → affectation optimale. */
+export async function optimizeAssignment(cost, solver) {
+    const sol = (await solver.solve({ kind: "assignment", cost }));
+    return sol ? { assignment: sol.assignment, total: sol.total } : { assignment: [], total: 0 };
+}
+/**
+ * Affecte N **lignes** de commande à des fournisseurs **distincts** (diversification / 1 fournisseur
+ * par produit), au coût total minimal — via le **hongrois** (ro-pla). Colonnes = fournisseurs candidats.
+ */
+export async function assignLinesToSuppliers(lines, solver) {
+    if (!lines.length)
+        return { assignment: [], totalCost: 0, status: "infeasible" };
+    // Colonnes = union des fournisseurs (par url unique).
+    const cols = [];
+    const colIdx = new Map();
+    for (const ln of lines)
+        for (const o of ln.offers)
+            if (!colIdx.has(o.url)) {
+                colIdx.set(o.url, cols.length);
+                cols.push({ url: o.url, supplier: o.supplier });
+            }
+    if (cols.length < lines.length)
+        return { assignment: [], totalCost: 0, status: "infeasible" }; // pas assez de fournisseurs distincts
+    const BIG = 1e9;
+    const cost = lines.map((ln) => cols.map((c) => {
+        const o = ln.offers.find((x) => x.url === c.url);
+        return o ? ln.qty * o.unitPrice : BIG; // fournisseur sans offre pour cette ligne → coût prohibitif
+    }));
+    const { assignment } = await optimizeAssignment(cost, solver);
+    const out = [];
+    let total = 0;
+    lines.forEach((ln, i) => {
+        const j = assignment[i];
+        const col = cols[j];
+        const o = col && ln.offers.find((x) => x.url === col.url);
+        if (!o)
+            return;
+        const cst = ln.qty * o.unitPrice;
+        total += cst;
+        out.push({ line: ln.key, supplier: o.supplier, unitPrice: o.unitPrice, qty: ln.qty, cost: cst, url: o.url });
+    });
+    return { assignment: out, totalCost: total, status: out.length === lines.length ? "optimal" : "infeasible" };
+}
+// ── Simplex/LP : allocation CONTINUE (divisible) avec contraintes linéaires (part max/fournisseur) ──
+/**
+ * Allocation **continue** (biens divisibles : vrac/poids/volume) au coût min, avec contraintes
+ * linéaires — notamment une **part maximale par fournisseur** que le flot n'exprime pas simplement.
+ * Résolu en **LP (simplexe)** par ro-pla.
+ */
+export async function optimizeContinuous(offers, qty, solver, c) {
+    const items = eligible(offers, c);
+    if (!items.length || qty <= 0)
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const n = items.length;
+    const cObj = items.map((o) => o.unitPrice);
+    const A = [];
+    const b = [];
+    const rel = [];
+    {
+        const r = new Array(n).fill(1);
+        A.push(r);
+        b.push(qty);
+        rel.push("=");
+    } // Σx = qty
+    items.forEach((o, i) => {
+        const cap = Number.isFinite(o.stock) && o.stock > 0 ? o.stock : qty;
+        const lim = c?.maxSharePerSupplier ? Math.min(cap, c.maxSharePerSupplier * qty) : cap;
+        const r = new Array(n).fill(0);
+        r[i] = 1;
+        A.push(r);
+        b.push(lim);
+        rel.push("<="); // x_i ≤ limite
+    });
+    const sol = (await solver.solve({ kind: "lp", c: cObj, A, b, relations: rel, objective: "min" }));
+    if (!sol || sol.status !== "optimal")
+        return { bySupplier: [], totalCost: 0, filled: 0, status: "infeasible" };
+    const bySupplier = [];
+    items.forEach((o, i) => { const q = sol.x[i] ?? 0; if (q > 1e-9)
+        bySupplier.push({ supplier: o.supplier, qty: q, unitPrice: o.unitPrice, currency: o.currency, cost: q * o.unitPrice, url: o.url }); });
+    const filled = bySupplier.reduce((s, x) => s + x.qty, 0);
+    return { bySupplier, totalCost: sol.objective, filled, status: filled >= qty - 1e-6 ? "optimal" : "partial" };
+}
+/** Optimise : paliers (B2B) → MILP par paliers ; sinon contraintes → MILP ; sinon achat fractionné (flot). */
+export async function optimizeOffers(offers, qty, solver, c) {
+    const elig = eligible(offers, c);
+    if (elig.some((o) => (o.priceTiers?.length ?? 0) > 0))
+        return optimizeTiered(offers, qty, solver, c);
+    if (c && (c.budget != null || c.maxSuppliers != null))
+        return optimizeConstrained(offers, qty, c, solver);
+    return optimizeSplitBuy(offers, qty, solver, c);
+}

package/dist/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @mostajs/agora-sourcing — registre de scrapers (forme « dialectes » façon ORM/ro-pla/llm).
+ * Un scraper = un dialecte ; sélection par clé ; auto-enregistrement des built-ins.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { ScraperDialect, DiscoveryDialect } from "./types.js";
+/** Enregistre (ou remplace) un dialecte de scraper. */
+export declare function registerScraper(d: ScraperDialect): void;
+/** Récupère un scraper par clé (null si absent). */
+export declare function getScraper(key: string): ScraperDialect | null;
+/** Liste les scrapers enregistrés. */
+export declare function listScrapers(): ScraperDialect[];
+/** Vide le registre (tests). */
+export declare function clearScrapers(): void;
+/**
+ * Scrapers exposés à l'app, filtrés par `AGORA_SCRAPERS` (CSV) façon `CHATBOT_PROVIDERS`.
+ * Vide ⇒ tous.
+ */
+export declare function activeScrapers(env?: Record<string, string | undefined>): ScraperDialect[];
+/** Route une URL vers le scraper dont un `hosts[]` correspond, sinon le scraper générique. */
+export declare function pickScraper(url: string): ScraperDialect | null;
+export declare function registerDiscovery(d: DiscoveryDialect): void;
+export declare function getDiscovery(key: string): DiscoveryDialect | null;
+export declare function listDiscovery(): DiscoveryDialect[];
+export declare function clearDiscovery(): void;

package/dist/registry.js

@@ -0,0 +1,47 @@
+const SCRAPERS = new Map();
+const DISCOVERY = new Map();
+/** Enregistre (ou remplace) un dialecte de scraper. */
+export function registerScraper(d) {
+    SCRAPERS.set(d.key, d);
+}
+/** Récupère un scraper par clé (null si absent). */
+export function getScraper(key) {
+    return SCRAPERS.get(key) ?? null;
+}
+/** Liste les scrapers enregistrés. */
+export function listScrapers() {
+    return [...SCRAPERS.values()];
+}
+/** Vide le registre (tests). */
+export function clearScrapers() {
+    SCRAPERS.clear();
+}
+/**
+ * Scrapers exposés à l'app, filtrés par `AGORA_SCRAPERS` (CSV) façon `CHATBOT_PROVIDERS`.
+ * Vide ⇒ tous.
+ */
+export function activeScrapers(env = process.env) {
+    const csv = (env.AGORA_SCRAPERS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const all = listScrapers();
+    return csv.length ? all.filter((s) => csv.includes(s.key)) : all;
+}
+/** Route une URL vers le scraper dont un `hosts[]` correspond, sinon le scraper générique. */
+export function pickScraper(url) {
+    let host = "";
+    try {
+        host = new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return getScraper("generic");
+    }
+    for (const s of listScrapers()) {
+        if (s.hosts?.some((h) => host === h || host.endsWith("." + h) || host.endsWith(h)))
+            return s;
+    }
+    return getScraper("generic");
+}
+// ── Registre de découverte (moteur de recherche : requête → URLs) ──
+export function registerDiscovery(d) { DISCOVERY.set(d.key, d); }
+export function getDiscovery(key) { return DISCOVERY.get(key) ?? null; }
+export function listDiscovery() { return [...DISCOVERY.values()]; }
+export function clearDiscovery() { DISCOVERY.clear(); }

package/dist/relevance.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @mostajs/agora-sourcing — filtre de PERTINENCE (titre/url ↔ requête).
+ * Évite que le scraper générique ramasse un prix hors-sujet (ex. « lames de broyeur » $15 pris pour
+ * le broyeur). Pur, testable. Appliqué entre le scrape et l'optimisation.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { Offer } from "./types.js";
+/** Tokens significatifs (minuscule, sans accents, ≥2 car., hors stopwords). */
+export declare function tokens(s: string): string[];
+/** Score 0..1 = part des tokens de la requête retrouvés dans le texte (avec sous-chaîne tolérée). */
+export declare function relevanceScore(text: string, query: string): number;
+/** Garde les offres dont le titre/url/fournisseur matche assez la requête (défaut ≥ 0.34). */
+export declare function filterRelevant(offers: Offer[], query: string, min?: number): Offer[];

package/dist/relevance.js

@@ -0,0 +1,25 @@
+const STOP = new Set(["the", "and", "for", "with", "de", "la", "le", "les", "des", "du", "un", "une", "of", "to", "in", "series", "model", "type", "new", "and"]);
+/** Tokens significatifs (minuscule, sans accents, ≥2 car., hors stopwords). */
+export function tokens(s) {
+    return ((s || "").toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").match(/[a-z0-9./-]{2,}/g) ?? []).filter((t) => !STOP.has(t));
+}
+/** Score 0..1 = part des tokens de la requête retrouvés dans le texte (avec sous-chaîne tolérée). */
+export function relevanceScore(text, query) {
+    const q = tokens(query);
+    if (!q.length)
+        return 1;
+    const t = tokens(text);
+    const set = new Set(t);
+    let hit = 0;
+    for (const w of q)
+        if (set.has(w) || t.some((x) => x.includes(w) || w.includes(x)))
+            hit++;
+    return hit / q.length;
+}
+/** Garde les offres dont le titre/url/fournisseur matche assez la requête (défaut ≥ 0.34). */
+export function filterRelevant(offers, query, min = 0.34) {
+    return offers.filter((o) => {
+        const title = o.raw?.title ?? "";
+        return relevanceScore(`${title} ${o.url} ${o.supplier}`, query) >= min;
+    });
+}

package/dist/rfq.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @mostajs/agora-sourcing — pont RFQ : compose **@mostajs/sourcing** (`sendRfqs`), pas de réécriture.
+ * Mappe les offres scrappées (Offer agora) vers le modèle Offer de sourcing, puis délègue l'envoi
+ * (dispatchers injectés ; `dryRun` par défaut = brouillon, human-in-the-loop DEVRULES §11).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { Offer } from "./types.js";
+/** Offre au format attendu par @mostajs/sourcing (sous-ensemble suffisant pour la RFQ). */
+export interface SourcingOffer {
+    supplier: string;
+    productMatch: string;
+    unitPrice?: number;
+    currency?: string;
+    moq?: number;
+    leadTimeDays?: number;
+    country?: string;
+    sourceUrl?: string;
+    contactEmail?: string;
+    contacts?: Record<string, string | undefined>;
+    connector?: string;
+    confidence: number;
+}
+/** Convertit des offres scrappées (faits) en offres sourcing. `confidence=1` (donnée vérifiée). */
+export declare function toSourcingOffers(offers: Offer[], query: string): SourcingOffer[];
+/** Signature minimale du `sendRfqs` de @mostajs/sourcing (injectable). */
+export type SendRfqs = (offers: SourcingOffer[], query: string, opts?: Record<string, unknown>) => Promise<unknown>;
+export interface RfqDeps {
+    /** `sendRfqs` injecté (tests) ; défaut = `@mostajs/sourcing` (peer, chargé au runtime). */
+    sendRfqs?: SendRfqs;
+    dispatchers?: unknown[];
+    from?: string;
+    ref?: string;
+    /** Brouillon par défaut (humain-in-the-loop) ; passer `false` pour acheminer réellement. */
+    dryRun?: boolean;
+}
+/** Émet des RFQ pour les offres retenues, en composant @mostajs/sourcing. */
+export declare function sendAgoraRfqs(offers: Offer[], query: string, deps?: RfqDeps): Promise<unknown>;

package/dist/rfq.js

@@ -0,0 +1,28 @@
+/** Convertit des offres scrappées (faits) en offres sourcing. `confidence=1` (donnée vérifiée). */
+export function toSourcingOffers(offers, query) {
+    return offers.map((o) => ({
+        supplier: o.supplier,
+        productMatch: query,
+        unitPrice: o.unitPrice,
+        currency: o.currency,
+        moq: o.moq,
+        country: o.country,
+        sourceUrl: o.url,
+        connector: "agora",
+        confidence: 1,
+    }));
+}
+/** Émet des RFQ pour les offres retenues, en composant @mostajs/sourcing. */
+export async function sendAgoraRfqs(offers, query, deps = {}) {
+    let send = deps.sendRfqs;
+    if (!send) {
+        const spec = "@mostajs/sourcing";
+        send = (await import(spec)).sendRfqs;
+    }
+    return send(toSourcingOffers(offers, query), query, {
+        from: deps.from,
+        ref: deps.ref,
+        dryRun: deps.dryRun ?? true,
+        dispatchers: deps.dispatchers,
+    });
+}

package/dist/scrapers/aliexpress.d.ts

@@ -0,0 +1,31 @@
+import type { Offer, ScraperDialect } from "../types.js";
+/** Récupère du JSON à une URL (DI ; défaut = fetch global). */
+export type JsonFetch = (url: string) => Promise<unknown>;
+export interface AliexpressConfig {
+    appKey?: string;
+    appSecret?: string;
+    /** Endpoint système (défaut : passerelle internationale). */
+    endpoint?: string;
+    /** Devise/langue/pays cibles. */
+    targetCurrency?: string;
+    targetLanguage?: string;
+    shipToCountry?: string;
+    /** HTTP injectable (tests). */
+    httpJson?: JsonFetch;
+    /** Horloge injectable (signature déterministe en test). */
+    now?: () => number;
+}
+/**
+ * Signe un jeu de paramètres (schéma TOP) : trie les clés, concatène `clé+valeur`, puis
+ * HMAC-SHA256 (clé = app_secret) en hex MAJUSCULE. (`md5` legacy : secret+base+secret.)
+ */
+export declare function signTop(params: Record<string, string>, appSecret: string, method?: "sha256" | "md5"): string;
+/** Construit l'URL signée d'un appel API TOP. */
+export declare function buildSignedUrl(cfg: Required<Pick<AliexpressConfig, "appKey" | "appSecret">> & AliexpressConfig, apiMethod: string, business: Record<string, string>): string;
+/** Extrait les produits d'une réponse `aliexpress.affiliate.product.query` → Offer[]. */
+export declare function mapProducts(json: unknown): Offer[];
+/**
+ * Dialecte scraper AliExpress (clé `aliexpress`). Sans `appKey`/`appSecret` → renvoie vide
+ * (le sourcing se rabat sur les autres connecteurs / le cache).
+ */
+export declare function aliexpressConnector(cfg?: AliexpressConfig): ScraperDialect;