@mostajs/agora-sourcing 0.0.1

package/dist/scrapers/aliexpress.js

@@ -0,0 +1,123 @@
+/**
+ * @mostajs/agora-sourcing — connecteur AliExpress par API OFFICIELLE (Affiliate / Open Platform).
+ * Requête SIGNÉE (schéma TOP : params triés + HMAC-SHA256, hex MAJUSCULE). Clés via `.env`
+ * (`ALIEXPRESS_APP_KEY/SECRET`). HTTP injectable (DI) → signature & mapping testables hors réseau.
+ * Sans identifiants → `search`/`scrape` renvoient vide proprement (repli sur autres sources/cache).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import { createHmac, createHash } from "node:crypto";
+/**
+ * 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 function signTop(params, appSecret, method = "sha256") {
+    const base = Object.keys(params)
+        .filter((k) => k !== "sign" && params[k] != null && params[k] !== "")
+        .sort()
+        .map((k) => `${k}${params[k]}`)
+        .join("");
+    if (method === "md5")
+        return createHash("md5").update(appSecret + base + appSecret, "utf8").digest("hex").toUpperCase();
+    return createHmac("sha256", appSecret).update(base, "utf8").digest("hex").toUpperCase();
+}
+/** Construit l'URL signée d'un appel API TOP. */
+export function buildSignedUrl(cfg, apiMethod, business) {
+    const endpoint = cfg.endpoint ?? "https://api-sg.aliexpress.com/sync";
+    const now = (cfg.now ?? Date.now)();
+    const params = {
+        app_key: cfg.appKey,
+        method: apiMethod,
+        timestamp: String(now),
+        format: "json",
+        v: "2.0",
+        sign_method: "sha256",
+        ...business,
+    };
+    params.sign = signTop(params, cfg.appSecret, "sha256");
+    const qs = Object.keys(params).map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`).join("&");
+    return `${endpoint}?${qs}`;
+}
+const num = (v) => {
+    if (typeof v === "number" && Number.isFinite(v))
+        return v;
+    const n = Number.parseFloat(String(v ?? "").replace(/[^\d.,-]/g, "").replace(",", "."));
+    return Number.isFinite(n) ? n : null;
+};
+/** Extrait les produits d'une réponse `aliexpress.affiliate.product.query` → Offer[]. */
+export function mapProducts(json) {
+    const j = json;
+    const list = j?.resp_result?.result?.products?.product ??
+        j?.aliexpress_affiliate_product_query_response?.resp_result?.result?.products?.product ??
+        j?.products ?? [];
+    const out = [];
+    for (const p of Array.isArray(list) ? list : []) {
+        const price = num(p.target_sale_price ?? p.target_app_sale_price ?? p.sale_price);
+        const url = p.product_detail_url || p.promotion_link;
+        if (price == null || !url)
+            continue;
+        out.push({
+            supplier: p.shop_name || "AliExpress",
+            unitPrice: price,
+            currency: (p.target_sale_price_currency || "USD").toUpperCase().slice(0, 3),
+            moq: 1,
+            country: "CN",
+            url: String(url).startsWith("http") ? url : `https:${url}`,
+            raw: { title: p.product_title, rating: p.evaluate_rate, productId: p.product_id },
+        });
+    }
+    return out;
+}
+const defaultHttpJson = async (url) => {
+    const res = await globalThis.fetch(url);
+    return res.json();
+};
+/**
+ * Dialecte scraper AliExpress (clé `aliexpress`). Sans `appKey`/`appSecret` → renvoie vide
+ * (le sourcing se rabat sur les autres connecteurs / le cache).
+ */
+export function aliexpressConnector(cfg = {}) {
+    const httpJson = cfg.httpJson ?? defaultHttpJson;
+    const ready = !!(cfg.appKey && cfg.appSecret);
+    return {
+        key: "aliexpress",
+        kind: "scraper",
+        hosts: ["aliexpress.com", "aliexpress.us"],
+        capabilities: { transport: "api", search: true, requiresAuth: true, ready, currency: cfg.targetCurrency ?? "USD", region: cfg.shipToCountry },
+        async search(query, opts) {
+            if (!ready)
+                return [];
+            const url = buildSignedUrl(cfg, "aliexpress.affiliate.product.query", {
+                keywords: query,
+                page_size: String(opts?.limit ?? 20),
+                page_no: "1",
+                target_currency: cfg.targetCurrency ?? "USD",
+                target_language: cfg.targetLanguage ?? "EN",
+                ...(cfg.shipToCountry ? { ship_to_country: cfg.shipToCountry } : {}),
+            });
+            try {
+                return mapProducts(await httpJson(url));
+            }
+            catch {
+                return [];
+            }
+        },
+        async scrape(url) {
+            if (!ready)
+                return null;
+            const id = url.match(/item\/(?:[^/]*?)?(\d{6,})\.html/)?.[1] || url.match(/(\d{8,})/)?.[1];
+            if (!id)
+                return null;
+            const api = buildSignedUrl(cfg, "aliexpress.affiliate.productdetail.get", {
+                product_ids: id,
+                target_currency: cfg.targetCurrency ?? "USD",
+                target_language: cfg.targetLanguage ?? "EN",
+            });
+            try {
+                return mapProducts(await httpJson(api))[0] ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/scrapers/generic.d.ts

@@ -0,0 +1,8 @@
+import type { Offer, ScraperDialect } from "../types.js";
+import { type HttpOpts } from "../http.js";
+/** Coercition « 1 250,50 € » / « $1,250.50 » → 1250.5 (null si introuvable). */
+export declare function parsePrice(s: unknown): number | null;
+/** Extrait une offre d'un HTML de page produit. Pur (cheerio), testable hors réseau. */
+export declare function parseOffer(html: string, url: string): Offer | null;
+/** Dialecte scraper générique (clé `generic`). Découverte non supportée (scrape direct). */
+export declare function genericScraper(http?: HttpOpts): ScraperDialect;

package/dist/scrapers/generic.js

@@ -0,0 +1,112 @@
+/**
+ * @mostajs/agora-sourcing — scraper générique « page produit → Offer » (cheerio).
+ * Heuristiques par ordre de fiabilité : JSON-LD (schema.org Product/Offer) → meta
+ * (og/product) → microdata itemprop → sélecteurs courants. Extraction de FAITS, 0 invention.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import * as cheerio from "cheerio";
+import { getText } from "../http.js";
+/** Coercition « 1 250,50 € » / « $1,250.50 » → 1250.5 (null si introuvable). */
+export function parsePrice(s) {
+    if (typeof s === "number" && Number.isFinite(s))
+        return s;
+    if (typeof s !== "string")
+        return null;
+    const m = s.replace(/\s/g, "").match(/-?\d[\d.,]*/);
+    if (!m)
+        return null;
+    let t = m[0];
+    // si virgule ET point : le dernier séparateur est le décimal
+    if (t.includes(",") && t.includes(".")) {
+        if (t.lastIndexOf(",") > t.lastIndexOf("."))
+            t = t.replace(/\./g, "").replace(",", ".");
+        else
+            t = t.replace(/,/g, "");
+    }
+    else if (t.includes(",")) {
+        // virgule seule : décimale si 1-2 chiffres après, sinon séparateur de milliers
+        t = /,\d{1,2}$/.test(t) ? t.replace(",", ".") : t.replace(/,/g, "");
+    }
+    const n = Number.parseFloat(t);
+    return Number.isFinite(n) ? n : null;
+}
+const CUR = { "€": "EUR", "$": "USD", "£": "GBP", "¥": "JPY" };
+function detectCurrency(s) {
+    if (!s)
+        return undefined;
+    const code = s.match(/\b(EUR|USD|GBP|JPY|CNY|CHF|CAD|AUD)\b/i);
+    if (code)
+        return code[1].toUpperCase();
+    for (const sym of Object.keys(CUR))
+        if (s.includes(sym))
+            return CUR[sym];
+    return undefined;
+}
+/** Extrait une offre d'un HTML de page produit. Pur (cheerio), testable hors réseau. */
+export function parseOffer(html, url) {
+    const $ = cheerio.load(html);
+    let price = null;
+    let currency;
+    let title;
+    // 1) JSON-LD schema.org
+    $('script[type="application/ld+json"]').each((_i, el) => {
+        if (price != null)
+            return;
+        try {
+            const data = JSON.parse($(el).contents().text());
+            const nodes = Array.isArray(data) ? data : [data, ...(data["@graph"] ?? [])];
+            for (const node of nodes) {
+                const offer = node?.offers && (Array.isArray(node.offers) ? node.offers[0] : node.offers);
+                if (offer?.price != null) {
+                    price = parsePrice(offer.price);
+                    currency = offer.priceCurrency || currency;
+                    title = title || node.name;
+                    break;
+                }
+            }
+        }
+        catch { /* JSON-LD invalide → ignore */ }
+    });
+    // 2) meta og/product
+    const meta = (sel) => $(`meta[property="${sel}"], meta[name="${sel}"]`).attr("content");
+    if (price == null) {
+        price = parsePrice(meta("product:price:amount") || meta("og:price:amount") || "");
+        currency = currency || meta("product:price:currency") || meta("og:price:currency") || undefined;
+    }
+    title = title || meta("og:title") || $("title").first().text().trim() || undefined;
+    const siteName = meta("og:site_name");
+    // 3) microdata itemprop
+    if (price == null) {
+        const ip = $('[itemprop="price"]').first();
+        price = parsePrice(ip.attr("content") || ip.text());
+        currency = currency || $('[itemprop="priceCurrency"]').first().attr("content") || undefined;
+    }
+    // 4) sélecteurs courants
+    if (price == null) {
+        const cand = $('[class*="price"], [data-price]').first();
+        price = parsePrice(cand.attr("data-price") || cand.text());
+        currency = currency || detectCurrency(cand.text());
+    }
+    if (price == null)
+        return null;
+    const supplier = (siteName || new URL(url).hostname.replace(/^www\./, "")).trim();
+    return {
+        supplier,
+        unitPrice: price,
+        currency: (currency || "USD").toUpperCase().slice(0, 3),
+        url,
+        raw: title ? { title } : undefined,
+    };
+}
+/** Dialecte scraper générique (clé `generic`). Découverte non supportée (scrape direct). */
+export function genericScraper(http = {}) {
+    return {
+        key: "generic",
+        kind: "scraper",
+        capabilities: { transport: "html", search: false, requiresAuth: false, ready: true },
+        async scrape(url) {
+            const html = await getText(url, http);
+            return parseOffer(html, url);
+        },
+    };
+}

package/dist/scrapers/site-profile.d.ts

@@ -0,0 +1,24 @@
+import type { Offer, ScraperDialect } from "../types.js";
+import { type HttpOpts } from "../http.js";
+/** Profil d'un site e-commerce : sélecteurs CSS + métadonnées de routage. */
+export interface SiteProfile {
+    key: string;
+    hosts: string[];
+    /** Sélecteur du prix (texte ou attribut content/data-price). */
+    price: string;
+    /** Sélecteur de la devise, OU code fixe (ex. "EUR"). */
+    currency?: string;
+    title?: string;
+    /** Nom fournisseur fixe (sinon hostname). */
+    supplier?: string;
+    country?: string;
+    /** Gabarit d'URL de recherche (liste) + sélecteur des liens produits. */
+    searchUrl?: (q: string) => string;
+    productLinks?: string;
+}
+/** Extraction par profil (pure, testable hors réseau). Repli générique si prix introuvable. */
+export declare function parseWithProfile(html: string, url: string, p: SiteProfile): Offer | null;
+/** Construit un dialecte scraper à partir d'un profil de site. */
+export declare function makeSiteScraper(p: SiteProfile, http?: HttpOpts): ScraperDialect;
+/** Profils e-commerce fournis (exemples génériques, extensibles par données). */
+export declare const BUILTIN_PROFILES: SiteProfile[];

package/dist/scrapers/site-profile.js

@@ -0,0 +1,68 @@
+/**
+ * @mostajs/agora-sourcing — scraper e-commerce piloté par PROFIL (data-driven).
+ * Ajouter une marketplace = des SÉLECTEURS (données), pas du code → forme dialectes.
+ * Repli sur le scraper générique (JSON-LD/meta) si un sélecteur manque.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import * as cheerio from "cheerio";
+import { getText } from "../http.js";
+import { parseOffer, parsePrice } from "./generic.js";
+const text = ($, sel) => {
+    if (!sel)
+        return undefined;
+    const el = $(sel).first();
+    return (el.attr("content") || el.attr("data-price") || el.text() || "").trim() || undefined;
+};
+/** Extraction par profil (pure, testable hors réseau). Repli générique si prix introuvable. */
+export function parseWithProfile(html, url, p) {
+    const $ = cheerio.load(html);
+    const price = parsePrice(text($, p.price));
+    if (price == null)
+        return parseOffer(html, url); // repli JSON-LD/meta
+    const rawCur = p.currency && /^[A-Z]{3}$/.test(p.currency) ? p.currency : text($, p.currency);
+    const currency = (rawCur?.match(/[A-Z]{3}/)?.[0]) || (text($, p.price)?.includes("€") ? "EUR" : "USD");
+    const supplier = p.supplier || new URL(url).hostname.replace(/^www\./, "");
+    const title = text($, p.title);
+    return { supplier, unitPrice: price, currency, country: p.country, url, raw: title ? { title } : undefined };
+}
+/** Construit un dialecte scraper à partir d'un profil de site. */
+export function makeSiteScraper(p, http = {}) {
+    return {
+        key: p.key,
+        kind: "scraper",
+        hosts: p.hosts,
+        capabilities: { transport: "html", search: !!(p.searchUrl && p.productLinks), requiresAuth: false, ready: true, currency: p.currency && /^[A-Z]{3}$/.test(p.currency) ? p.currency : undefined },
+        async scrape(url) {
+            const html = await getText(url, http);
+            return parseWithProfile(html, url, p);
+        },
+        ...(p.searchUrl && p.productLinks
+            ? {
+                async search(query, opts) {
+                    const html = await getText(p.searchUrl(query), http);
+                    const $ = cheerio.load(html);
+                    const links = [];
+                    const base = `https://${p.hosts[0] ?? ""}`;
+                    $(p.productLinks).each((_i, el) => {
+                        const href = $(el).attr("href");
+                        if (href) {
+                            try {
+                                links.push(new URL(href, base).toString());
+                            }
+                            catch { /* href invalide */ }
+                        }
+                        return links.length < (opts?.limit ?? 10);
+                    });
+                    const offers = await Promise.all(links.map((u) => this.scrape(u).catch(() => null)));
+                    return offers.filter((o) => o != null);
+                },
+            }
+            : {}),
+    };
+}
+/** Profils e-commerce fournis (exemples génériques, extensibles par données). */
+export const BUILTIN_PROFILES = [
+    // La plupart des marketplaces exposent JSON-LD → le scraper « generic » suffit souvent.
+    // Profil d'exemple pour un site sans JSON-LD (sélecteurs explicites) :
+    { key: "shopx", hosts: ["shopx.example"], price: ".product-price", title: ".product-name", supplier: "ShopX" },
+];

package/dist/tool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @mostajs/agora-sourcing — pont CHATBOT : outil `agora_sourcing` (forme ChatTool) que le copilote
+ * (`@mostajs/chatbot`) peut appeler comme CHEMIN DÉTERMINISTE (scraping + optimisation), alternative
+ * à la recherche web LLM. Renvoie des FAITS (prix vérifiables) + l'allocation optimale ; RFQ optionnelle.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+import type { HttpOpts } from "./http.js";
+import type { Offer, SolverPort, CachePort } from "./types.js";
+import { type RfqDeps } from "./rfq.js";
+export interface AgoraToolDeps {
+    http?: HttpOpts;
+    solver?: SolverPort;
+    cache?: CachePort;
+    cacheTtlMs?: number;
+    maxUrls?: number;
+    /** Clé de découverte du registre (ex. "llm" pour Claude, "ddg"). */
+    discoveryKey?: string;
+    /** Filtre de pertinence (défaut on) ; `false` ou seuil. */
+    relevance?: boolean | number;
+    /** Découverte/scrape injectables (tests) ; défaut = registre. */
+    discover?: (query: string) => Promise<string[]>;
+    scrape?: (url: string) => Promise<Offer | null>;
+    rfq?: RfqDeps;
+}
+/** Construit l'outil `agora_sourcing` (ChatTool) pour le copilote. */
+export declare function makeAgoraSourcingTool(deps?: AgoraToolDeps): {
+    name: string;
+    description: string;
+    schema: {
+        type: string;
+        properties: {
+            product: {
+                type: string;
+                description: string;
+            };
+            qty: {
+                type: string;
+                description: string;
+            };
+            budget: {
+                type: string;
+            };
+            maxSuppliers: {
+                type: string;
+            };
+            rfq: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    run(input: Record<string, unknown>): Promise<unknown>;
+};

package/dist/tool.js

@@ -0,0 +1,53 @@
+import { agoraSourceFromQuery } from "./index.js";
+import { sendAgoraRfqs } from "./rfq.js";
+const slim = (o) => ({ supplier: o.supplier, unitPrice: o.unitPrice, currency: o.currency, moq: o.moq, country: o.country, url: o.url });
+/** Construit l'outil `agora_sourcing` (ChatTool) pour le copilote. */
+export function makeAgoraSourcingTool(deps = {}) {
+    return {
+        name: "agora_sourcing",
+        description: "Source un produit sur le web de façon DÉTERMINISTE (scraping + optimisation d'achat). " +
+            "Renvoie des offres réelles (prix vérifiables avec lien source), le Top-N par prix, et " +
+            "l'ALLOCATION D'ACHAT OPTIMALE (combien commander chez qui, paliers B2B pris en compte). " +
+            "Préciser la quantité pour l'optimisation. Mettre rfq=true pour préparer des demandes de devis (brouillon).",
+        schema: {
+            type: "object",
+            properties: {
+                product: { type: "string", description: "produit à sourcer" },
+                qty: { type: "number", description: "quantité souhaitée (pour l'optimisation d'achat)" },
+                budget: { type: "number" },
+                maxSuppliers: { type: "number" },
+                rfq: { type: "boolean", description: "préparer des demandes de devis (brouillon)" },
+            },
+            required: ["product"],
+        },
+        async run(input) {
+            const product = String(input?.product ?? "").trim();
+            if (!product)
+                return { error: "produit manquant" };
+            const qty = Number(input?.qty) > 0 ? Number(input.qty) : 1;
+            const constraints = {
+                ...(Number(input?.budget) > 0 ? { budget: Number(input.budget) } : {}),
+                ...(Number(input?.maxSuppliers) > 0 ? { maxSuppliers: Number(input.maxSuppliers) } : {}),
+            };
+            const res = await agoraSourceFromQuery(product, {
+                qty, constraints, topN: 5,
+                http: deps.http, solver: deps.solver, cache: deps.cache, cacheTtlMs: deps.cacheTtlMs,
+                maxUrls: deps.maxUrls, discover: deps.discover, scrape: deps.scrape,
+                discoveryKey: deps.discoveryKey, relevance: deps.relevance,
+            });
+            const out = {
+                product, qty,
+                count: res.offers.length,
+                fromCache: !!res.fromCache,
+                topN: res.topN.map(slim),
+                allocation: res.allocation,
+                note: res.offers.length === 0 ? "aucune offre (sources indisponibles / sans clé API) — voir cache." : undefined,
+            };
+            if (input?.rfq === true && res.allocation.bySupplier.length) {
+                const retained = res.allocation.bySupplier.map((b) => res.offers.find((o) => o.url === b.url) ?? { supplier: b.supplier, unitPrice: b.unitPrice, currency: b.currency, url: b.url });
+                out.rfq = await sendAgoraRfqs(retained, product, deps.rfq);
+            }
+            return out;
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @mostajs/agora-sourcing — types du sourcing maison (collecte → optimisation → RFQ).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+/** Palier de prix dégressif B2B (remise sur volume, « all-units ») : prix unitaire si qté ≥ minQty. */
+export interface PriceTier {
+    minQty: number;
+    unitPrice: number;
+}
+/** Une offre — un FAIT collecté (scrappé), pas une supposition LLM. */
+export interface Offer {
+    supplier: string;
+    unitPrice: number;
+    currency: string;
+    /** Quantité minimale de commande. */
+    moq?: number;
+    /** Quantité disponible (= capacité pour l'optimisation). */
+    stock?: number;
+    /** Paliers de prix dégressifs (B2B : Alibaba/1688). Si présent, l'optimiseur choisit le bon palier. */
+    priceTiers?: PriceTier[];
+    /** Coût de livraison PAR UNITÉ (dans `currency`) — pour le coût rendu (landed cost). */
+    shippingCost?: number;
+    /** Délai d'approvisionnement estimé (jours) — pour le multi-objectif prix↔délai. */
+    leadTimeDays?: number;
+    country?: string;
+    url: string;
+    /** Données brutes d'origine (debug / traçabilité). */
+    raw?: unknown;
+}
+/** `fetch` injectable (DI) — par défaut le fetch global. */
+export type FetchFn = (url: string, init?: unknown) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface SearchOpts {
+    limit?: number;
+}
+/** Capacités déclarées d'un scraper (façon `SolverDialect.capabilities` de ro-pla / matrice ORM). */
+export interface ScraperCapabilities {
+    /** Mode d'accès : scraping HTML ou API officielle. */
+    transport: "html" | "api";
+    /** Sait découvrir par requête libre (`search`) ? */
+    search: boolean;
+    /** Nécessite des identifiants (clé .env) ? */
+    requiresAuth: boolean;
+    /** Identifiants présents / prêt à appeler ? */
+    ready: boolean;
+    /** Devise native des prix (ex. CNY) — pour la normalisation FX. */
+    currency?: string;
+    /** Région/pays par défaut. */
+    region?: string;
+}
+/** Un scraper = un dialecte (forme registre façon ORM). */
+export interface ScraperDialect {
+    key: string;
+    kind: "scraper";
+    /** Hôtes pris en charge (routage URL → scraper) ; absent = scraper générique. */
+    hosts?: string[];
+    /** Capacités déclarées (diagnostic / auto-sélection / « ready »). */
+    capabilities?: ScraperCapabilities;
+    /** Recherche par requête libre (si le site la supporte). */
+    search?(query: string, opts?: SearchOpts): Promise<Offer[]>;
+    /** Scrape une URL produit précise → une offre (ou null). */
+    scrape(url: string): Promise<Offer | null>;
+}
+/** Un moteur de découverte = un dialecte : requête libre → URLs candidates. */
+export interface DiscoveryDialect {
+    key: string;
+    kind: "discovery";
+    discover(query: string, opts?: SearchOpts): Promise<string[]>;
+}
+/** Contraintes d'achat (optimisation). */
+export interface OptimizeConstraints {
+    budget?: number;
+    maxSuppliers?: number;
+    allowedCountries?: string[];
+}
+/** Part d'achat affectée à un fournisseur. */
+export interface AllocationItem {
+    supplier: string;
+    qty: number;
+    unitPrice: number;
+    currency: string;
+    cost: number;
+    url: string;
+}
+/** Décision d'achat calculée (par ro-pla). */
+export interface Allocation {
+    bySupplier: AllocationItem[];
+    totalCost: number;
+    /** Quantité réellement couverte. */
+    filled: number;
+    status: "optimal" | "partial" | "infeasible";
+}
+/**
+ * Port solveur (DI) — compatible `@mostajs/ro-pla` : `solve(problem)` route par `problem.kind`.
+ * On n'importe PAS ro-pla ici (peer) ; l'app/le test injecte l'implémentation.
+ */
+export interface SolverPort {
+    solve(problem: {
+        kind: string;
+    } & Record<string, unknown>, opts?: unknown): unknown | Promise<unknown>;
+}
+/** Résultat d'un sourcing complet. */
+export interface SourcingResult {
+    offers: Offer[];
+    topN: Offer[];
+    allocation: Allocation;
+    /** Vrai si servi depuis le cache ORM (repli « dernier connu » ou hit frais). */
+    fromCache?: boolean;
+    /** Horodatage (ms) du résultat caché servi. */
+    cachedAt?: number;
+}
+/** Persistance des résultats (cache) — repli « au moins du disponible » sur nouvelle recherche. */
+export interface CachePort {
+    get(queryKey: string): Promise<{
+        result: SourcingResult;
+        at: number;
+    } | null>;
+    put(queryKey: string, result: SourcingResult): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * @mostajs/agora-sourcing — types du sourcing maison (collecte → optimisation → RFQ).
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+export {};

package/llms.txt

@@ -0,0 +1,37 @@
+# @mostajs/agora-sourcing — fiche LLM
+> Sourcing maison déterministe : SCRAPE les faits (cheerio + registre de scrapers façon ORM) → OPTIMISE l'achat (@mostajs/ro-pla) → RFQ (@mostajs/sourcing) ; le LLM ne fait que synthétiser.
+
+- Version: 0.0.1 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Chemin: mostajs/mosta-agora-sourcing · deps: cheerio, @mostajs/config ; peers: @mostajs/ro-pla (solveur), @mostajs/sourcing (RFQ), @mostajs/orm (cache, optionnel) ; puppeteer optionnel.
+
+## RÔLE
+Orchestre la chaîne « collecte → décision → RFQ » sans demander au LLM de chercher ni d'optimiser : un moteur de scraping déterministe (ex-AgoraScope-Studio) collecte les offres (prix, devise, MOQ, pays, lien), `@mostajs/ro-pla` calcule l'allocation d'achat exacte (min-cost-flow / MILP / hungarian), `@mostajs/sourcing` envoie les RFQ. Tout est injecté (DI) : scrapers, découverte, solveur, dispatchers, cache, lecteur d'env — agnostique et testable par stub. Stade proposition (0.0.1) : périmètre posé, moteur amorcé. NE fait pas la synthèse LLM elle-même ni la résolution RO (peer `ro-pla`).
+
+## EXPORTS
+- Orchestration: `registerBuiltins`, `registerApis`, `defaultSolver`, `agoraSourceFromUrls`, `agoraSourceFromQuery` ; types `AgoraSourceOpts`, `QuerySourceOpts`.
+- Registre (façon ORM): `registerScraper`, `getScraper`, `listScrapers`, `clearScrapers`, `activeScrapers`, `pickScraper`, `registerDiscovery`, `getDiscovery`, `listDiscovery`, `clearDiscovery`.
+- HTTP: `getText`, `isAllowedByRobots`, type `HttpOpts`.
+- Scrapers: `genericScraper`, `parseOffer`, `parsePrice` ; `makeSiteScraper`, `parseWithProfile`, `BUILTIN_PROFILES`, type `SiteProfile` ; `aliexpressConnector`, `signTop`, `buildSignedUrl`, `mapProducts`, types `AliexpressConfig`, `JsonFetch`.
+- Découverte: `ddgDiscovery`, `parseDdgResults` ; `makeLlmDiscovery`, `parseUrlList`, type `DiscoveryLlm`.
+- Optimisation: `optimizeOffers`, `optimizeSplitBuy`, `optimizeConstrained`, `optimizeTiered`, `optimizeAssignment`, `assignLinesToSuppliers`, `optimizeContinuous`, `topNByPrice`, types `AssignLine`, `LineAssignment`.
+- RFQ: `sendAgoraRfqs`, `toSourcingOffers`, types `RfqDeps`, `SourcingOffer`, `SendRfqs`.
+- Normalisation/pertinence: `normalizeOffers`, `landedUnit`, `convert`, types `FxRates`, `LandedOptions` ; `filterRelevant`, `relevanceScore`, `tokens`.
+- Config: `loadConfig`, `isEnabled`, `configuredApis`, `readerFromObject`, types `AgoraConfig`, `ApiCredential`, `EnvReader`.
+- Cache: `makeOrmCache`, `openFileCache`, `MemoryCache`, `AGORA_SEARCH_SCHEMA`.
+- Outil/types: `makeAgoraSourcingTool`, type `AgoraToolDeps` ; `export * from types` (`Offer`, `PriceTier`, `ScraperDialect`, `DiscoveryDialect`, `OptimizeConstraints`, `Allocation`, `SolverPort`, `CachePort`, `SourcingResult`, …).
+
+## API
+- `registerBuiltins(http?: HttpOpts): void` — enregistre scraper générique + profils e-commerce + découverte DDG.
+- `registerApis(cfg: AgoraConfig, deps?: { httpJson? }): string[]` — enregistre les connecteurs API dont les clés `.env` sont présentes ET actives ; renvoie les clés posées.
+- `defaultSolver(): Promise<SolverPort>` — charge paresseusement `@mostajs/ro-pla` (peer) au runtime.
+- `agoraSourceFromUrls(urls, opts: AgoraSourceOpts, scrape): Promise<SourcingResult>` — scrape chaque URL → filtre → `optimizeOffers` → `{ offers, topN, allocation }`. `AgoraSourceOpts = { qty, constraints?, topN?, solver?, filter? }`.
+- `agoraSourceFromQuery(query, opts: QuerySourceOpts): Promise<SourcingResult>` — pipeline complet avec persistance : (1) hit cache frais < `cacheTtlMs` ; (2) live découverte→scrape routé→optimisation, persiste si succès ; (3) repli sur dernier connu. `QuerySourceOpts` ajoute `http?, maxUrls?, queryKey?, cache?, cacheTtlMs?, discover?, discoveryKey?, scrape?, relevance?`.
+- `loadConfig(env?): AgoraConfig` — sans arg = cascade `@mostajs/config` ; objet plat ou `EnvReader` = tests.
+- `makeOrmCache(orm/conn)` / `openFileCache(...)` / `MemoryCache` — `CachePort { get, put }` ; schéma `AGORA_SEARCH_SCHEMA` (queryKey unique, payload `text`, at `number`).
+
+## PIÈGES
+- Cache ORM : le résultat est sérialisé dans `payload` de type **`text`** (JSON), pas un champ `'object'` (interdit en ORM → préférer `'text'`/`'json'`). Schéma `schemaStrategy: "update"`, upsert sur `queryKey`.
+- Peers non installés au build : `@mostajs/ro-pla` est importé **paresseusement** par `defaultSolver()` via specifier indirect ; sans lui, injecter un `SolverPort` (`opts.solver`) sinon échec runtime. `@mostajs/orm` est optionnel (cache).
+- `registerBuiltins()` (ou injection de `discover`/`scrape`) est requis avant `agoraSourceFromQuery` : sinon repli sur scraper générique / DDG seulement.
+- Env via `@mostajs/config` (cascade `.env` + `MOSTA_ENV`) : `AGORA_CURRENCY` est tronquée/majusculée sur 3 lettres ; `AGORA_SCRAPERS` vide ⇒ tous actifs (`isEnabled`). Un connecteur API sans `*_APP_KEY`+`*_APP_SECRET` n'est pas enregistré.
+- Conformité : respect `robots.txt`/CGU par défaut (`isAllowedByRobots`), rate-limit, UA identifié ; pas de contournement abusif.