Aperçu

BlunxAI transforme votre base de données en un collaborateur agentique : vos utilisateurs posent des questions en langage naturel et reçoivent des réponses, des graphiques, des tableaux et des insights automatiques — directement dans votre application.

Le principe

BlunxAI n'est pas une plateforme externe vers laquelle vous exporteriez vos données : c'est un SDK que vous embarquez dans votre infrastructure. Le SQL est exécuté localement, en lecture seule, et le système multi-agents est piloté par le serveur Blunx (le point d'entrée cloud /api/v1/*).

Architecture

Ce que vous devez retenir

• Lecture seule stricte : seuls des SELECT / WITH sont exécutés, à plusieurs niveaux de garde-fous (voir Sécurité).
• Backend-agnostique : le Web SDK n'attend qu'un contrat REST /api/blunx/*. Les packages Laravel et Node.js l'implémentent aujourd'hui ; les SDK Django, Go, Spring Boot suivront sans rien changer côté front.
• Un serveur, plusieurs clés : le SDK backend s'authentifie auprès du serveur Blunx avec une clé d'application (X-Blunx-Key) et une clé LLM (X-Blunx-LLM-Key).
• Votre BDD, vos règles : MySQL, MariaDB, PostgreSQL, SQLite et SQL Server sont pris en charge ; vous contrôlez les accès par rôle (RBAC).

Démarrage rapide

Installez Blunx dans votre application en ~10 minutes. Choisissez votre backend (Laravel ou Node.js) : le schéma est identique, seul le SDK change. Chaque étape est minimale — les détails sont dans les guides.

Ce que vous allez faire : 1 · récupérer vos clés → 2 · installer le SDK → 3 · configurer le .env → 4 · connecter Blunx et exclure les tables sensibles → 5 · générer le schéma de votre base → 6 · intégrer l'interface (Web SDK) dans vos pages. Une fois en place, Blunx transforme les questions de vos utilisateurs en SQL en lecture seule sur votre base : il ne modifie jamais vos données.

Prérequis

1 · Récupérer vos clés

Regroupez ces 4 informations — vous en aurez besoin à l'étape 3 :

composer require blunx/ai
php artisan vendor:publish --tag=blunx-config

BLUNX_API_KEY=blunx_app_live_xxxxxxxxxxxx
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
BLUNX_LLM_ENDPOINT=https://api.openai.com/v1
BLUNX_LLM_MODEL=gpt-4o

// Déjà exclus par défaut : migrations, failed_jobs, cache, jobs, sessions,
// password_reset_tokens, personal_access_tokens… + toutes les tables blunx_*
'excluded_tables' => [
    'admin_logs', 'notifications', 'settings', 'audit_trail',   // ▶ vos tables
],

php artisan blunx:init    # scanne la base → storage/app/blunx_schema.json
php artisan blunx:setup   # verrouille le schéma + crée les 8 tables

public function getUserRoleName(): ?string
{
    return $this->role->name ?? null;
}

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx-loader.min.js"
        data-container="#blunx"
        data-view="auto"></script>

npm install blunx-ai

BLUNX_API_KEY=blunx_app_live_xxxxxxxxxxxx
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
BLUNX_LLM_ENDPOINT=https://api.openai.com/v1
BLUNX_LLM_MODEL=gpt-4o
# Votre base (ADAPTEZ) — mysql://user:motdepasse@hote:port/base
BLUNX_DB_URL=mysql://root:secret@127.0.0.1:3306/ma_base

const { Blunx, blunxExpress } = require('blunx-ai');   // 1. import

// 2. Runtime Blunx — clés (BLUNX_API_KEY, BLUNX_LLM_*) et base (BLUNX_DB_URL)
//    lues dans le .env. Les 2 hooks ci-dessous sont OBLIGATOIRES :
const blunx = Blunx.init({
  getUserRole: (userId) => null,   // TODO : retournez le libellé du rôle (ex. 'admin')
  getUser: (userId) => null,       // TODO : retournez { name, email } ou null
});

// 3. Montez le routeur Blunx APRÈS votre middleware d'authentification
//    (celui-ci doit avoir rempli req.user avant)
app.use('/api/blunx', blunxExpress(blunx));

getUserRole: (userId) => users[userId]?.role ?? null,
getUser: (userId) => {
  const u = users[userId];
  return u ? { name: u.name, email: u.email } : null;
},

const express = require('express');                   // framework HTTP
const { Blunx, blunxExpress } = require('blunx-ai');   // SDK Blunx

const app = express();
app.use(express.json());   // lit le body JSON

// ── Utilisateurs de démo (ADAPTEZ : venez de votre table users) ──
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// ── Authentification (ADAPTEZ : Passport, JWT, session…) ──
// Blunx renvoie 401 si req.user est absent : votre middleware d'auth
// doit s'exécuter AVANT le routeur Blunx et remplir req.user.
app.use((req, res, next) => {
  req.user = USERS[1];   // démo : l'utilisateur 1 est connecté
  next();
});

// ── Runtime Blunx (clés + BDD lues dans le .env) ──
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// ── Routeur Blunx monté APRÈS l'auth ──
app.use('/api/blunx', blunxExpress(blunx));

// ── Démarrage ──
app.listen(3000, () => console.log('Blunx prêt sur http://localhost:3000'));

cp node_modules/blunx-ai/config/blunx.config.ts ./config/blunx.config.ts
cp node_modules/blunx-ai/config/blunx-access.config.ts ./config/blunx-access.config.ts

import blunxConfig from './config/blunx.config';            // ta copie éditée
import blunxAccessConfig from './config/blunx-access.config'; // tes règles RBAC

const blunx = Blunx.init({
  ...blunxConfig,             // serverUrl, apiKey, llm, currency, locale…
  access: blunxAccessConfig,  // règles RBAC
  // hooks identiques à ceux du Cas A / B ci-dessus (USERS) :
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

export default {
  // Tables internes blunx_* déjà ignorées par défaut.
  // ▶ Ajoutez vos tables techniques / sensibles à ne pas scanner :
  excludedTables: ['migrations', 'sessions', 'log_errors', 'admin_logs', 'notifications'],
};

npx blunx-ai init    # scanne la base → storage/app/blunx_schema.json
npx blunx-ai setup   # verrouille le schéma + crée les 8 tables

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx-loader.min.js"
        data-container="#blunx"
        data-view="auto"></script>

Vérifier que tout fonctionne

Connectez-vous avec un utilisateur de votre application et ouvrez la page. Posez une question (ex. « Quel est le nombre total de clients ? ») : le cockpit affiche le pipeline puis le résultat.

Compatibilité

Les versions et environnements pris en charge, par brique de l'intégration. Les SDK backend : Laravel et Node.js sont disponibles, les autres suivent.

Bases de données

Blunx fonctionne avec la connexion de votre application et exécute le SQL en lecture seule. Les bases suivantes sont prises en charge par le SDK Laravel et par le serveur Blunx :

Backend (SDK serveur)

Front-end (Web SDK @blunx/web-sdk)

Fournisseurs LLM

Le driver openai est un adaptateur compatible OpenAI : il fonctionne avec la quasi-totalité des fournisseurs propriétaires ET open-source. Voir Fournisseurs LLM pour le détail.

Navigateurs & environnements

Backend Laravel

Le package blunx/ai sert le contrat /api/blunx/* attendu par le Web SDK, exécute le SQL en lecture seule sur votre base et proxie vers le serveur Blunx. Prérequis : Laravel 9 à 12 (testé sous 12), PHP 8.1+.

Installation

composer require blunx/ai
php artisan vendor:publish --tag=blunx-config

• Provider en auto-discovery — aucune déclaration manuelle.
• Aucune migration à publier : les 8 tables Blunx sont créées par blunx:setup.

Configuration

Deux fichiers publiés dans config/ : blunx.php (lu depuis vos variables BLUNX_*) et blunx_access.php (règles RBAC). La référence complète des variables est dans Configuration.

public function getUserRoleName(): ?string
{
    return $this->role->name ?? null;
}

Commandes artisan

Workflow : blunx:init → (optionnel) blunx:edit → blunx:setup. Relancez blunx:edit après chaque évolution de votre base.

Tables créées

Toutes ont un id auto-incrémenté + un uuid unique (routes liées par uuid) :

Authentification & routes

Toutes les routes /api/blunx/* sont dans le groupe de middleware blunx = session + auth (utilisateur connecté exigé, sans CSRF) + throttle:60,1. Rien à configurer : une requête non authentifiée est bloquée par le framework (401/redirection).

File d'attente & insights

• GenerateWidgetInsightJob : ShouldQueue, tries=5, timeout=200 — exécute le widget, génère le rapport PDF et l'email.
• BlunxInsightMail : email coloré selon la sévérité, PDF en pièce jointe.
• Planification : toutes les heures pour les réglages « dus » ; un nouveau réglage est exécuté immédiatement.
• Échec après retries (ex. appel serveur en erreur) : le job n'avance pas vers le prochain créneau — il re-tente dans 30 min (next_run_at = maintenant + 30 min, last_run_at inchangé tant que le job n'a pas abouti).
• En local : php artisan queue:work --once (ou QUEUE_CONNECTION=sync en dev).

Backend Node.js

Le package blunx-ai sert le contrat /api/blunx/* attendu par le Web SDK, exécute le SQL en lecture seule sur votre base et proxie vers le serveur Blunx. Prérequis : Node.js 18+, framework agnostique (Express, Fastify, Koa, NestJS ou HTTP natif).

Installation

npm install blunx-ai

• Le .env est chargé automatiquement (dotenv) — aucune publication de config obligatoire.
• Aucune migration à publier : les 8 tables Blunx sont créées par blunx-ai setup.

Initialisation

Créez le runtime Blunx une seule fois avec vos hooks d'authentification. La priorité de configuration : option de Blunx.init() > variable BLUNX_* > défaut (voir Configuration).

La connexion à votre base se fournit de 3 façons (du plus simple au plus intégré) :

const { Blunx } = require('blunx-ai');

// Clés (BLUNX_API_KEY, BLUNX_LLM_*) et base (BLUNX_DB_URL) lues dans le .env.
// Exemple de résolution des utilisateurs (ADAPTEZ : venez de votre base) :
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

const blunx = Blunx.init({
  // Résout le rôle de l'utilisateur (RBAC) — équivaut getUserRoleName() de Laravel
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  // Résout {name, email} pour /api/blunx/user — équivaut Auth::user() de Laravel
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

Option (avancé) — publier et charger les fichiers de config

Vous n'en avez pas besoin pour démarrer : le .env suffit. Cette option ne remplace pas l'initialisation ci-dessus — elle change seulement la source de la configuration. Utilisez-la si vous voulez versionner vos réglages et vos règles RBAC dans des fichiers TypeScript plutôt que dans le .env. Copiez les 2 templates (aucune dépendance), éditez-les, puis chargez-les dans Blunx.init() :

cp node_modules/blunx-ai/config/blunx.config.ts ./config/blunx.config.ts
cp node_modules/blunx-ai/config/blunx-access.config.ts ./config/blunx-access.config.ts

import blunxConfig from './config/blunx.config';            // ta copie éditée
import blunxAccessConfig from './config/blunx-access.config'; // tes règles RBAC

const blunx = Blunx.init({
  ...blunxConfig,             // serverUrl, apiKey, llm, currency, locale…
  access: blunxAccessConfig,  // règles RBAC
  // hooks identiques à ci-dessus (USERS) :
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

La base se passe par BLUNX_DB_URL (.env) ou l'option database. Détail des règles RBAC dans Configuration.

Commandes (CLI blunx-ai)

Workflow : blunx-ai init → (optionnel) blunx-ai edit → blunx-ai setup. La CLI construit sa propre connexion depuis le .env (BLUNX_DB_URL ou BLUNX_DB_*) — lancez-la depuis la racine de votre projet.

Tables créées

Identiques au package Laravel : blunx_conversations, blunx_messages, blunx_feedbacks, blunx_dashboards, blunx_dashboard_widgets, blunx_insights, blunx_widget_insight_settings, blunx_cache (toutes avec id + uuid unique).

Authentification & routes

Le package protège lui-même les routes : sans utilisateur authentifié (req.user / ctx.state.user absent), il renvoie 401 {"message":"Unauthenticated."} — équivalent du middleware auth du groupe blunx de Laravel. Aucun garde requireAuth à ajouter.

const express = require('express');
const { Blunx, blunxExpress } = require('blunx-ai');

const app = express();
app.use(express.json());

// Utilisateurs de démo (ADAPTEZ : venez de votre base)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// 1. Authentification : votre middleware d'auth (Passport, JWT, session…)
//    remplit req.user. Exemple de démo :
app.use((req, res, next) => {
  req.user = USERS[1];
  next();
});

const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// 2. Blunx monté APRÈS : il vérifie req.user et renvoie 401 s'il est absent
app.use('/api/blunx', blunxExpress(blunx));

app.listen(3000);

Blunx lit req.user.id (filtrage user_id), req.user.name/email (endpoint /user) et optionnellement req.user.getUserRoleName() (sinon votre hook getUserRole est appelé). Autres adaptateurs : blunxFastify, blunxKoa, createBlunxNestController, blunxNodeHttp.

Planification des insights

• Scheduler (node-cron) : toutes les heures, trouve les réglages « dus » et exécute GenerateWidgetInsightJob. Activé par défaut (enableScheduler: true), désactivable via Blunx.init({ enableScheduler: false }).
• npx blunx-ai run-insights : exécution manuelle immédiate.
• Échec après retries (ex. appel serveur en erreur) : le job n'avance pas vers le prochain créneau — il re-tente dans 30 min (next_run_at = maintenant + 30 min, last_run_at inchangé tant que le job n'a pas abouti).
• sendInsightMail (nodemailer) : email coloré selon la sévérité, PDF en pièce jointe (généré par InsightPdfGenerator — rendu 100 % JS, aucun navigateur).

Exemples complets par framework

Chaque exemple est un fichier complet et copiable : utilisateurs de démo, authentification, runtime et démarrage. Remplacez les blocs marqués ADAPTEZ (base, auth, rôles) par vos vraies données. Clés + BDD dans le .env.

const express = require('express');                   // framework HTTP
const { Blunx, blunxExpress } = require('blunx-ai');   // SDK Blunx

const app = express();
app.use(express.json());   // lit le body JSON

// ── Utilisateurs de démo (ADAPTEZ : venez de votre table users) ──
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// ── Authentification (ADAPTEZ : Passport, JWT, session…) ──
app.use((req, res, next) => {
  req.user = USERS[1];   // démo : l'utilisateur 1 est connecté
  next();
});

// ── Runtime Blunx (clés + BDD depuis le .env) ──
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// ── Routeur Blunx monté APRÈS l'auth ──
app.use('/api/blunx', blunxExpress(blunx));

app.listen(3000, () => console.log('Blunx prêt sur http://localhost:3000'));

const fastify = require('fastify');
const { Blunx, blunxFastify } = require('blunx-ai');

const app = fastify();

// Utilisateurs de démo (ADAPTEZ)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// Authentification (ADAPTEZ) : remplit req.user avant le routeur Blunx
app.addHook('onRequest', (req, reply, done) => {
  req.user = USERS[1];
  done();
});

// Runtime Blunx (clés + BDD depuis le .env)
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// Montage du routeur Blunx
blunxFastify(app, blunx);

app.listen({ port: 3000 }).then(() => console.log('Blunx prêt sur http://localhost:3000'));

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');   // requis : lit le body JSON
const { Blunx, blunxKoa } = require('blunx-ai');

const app = new Koa();
app.use(bodyParser());

// Utilisateurs de démo (ADAPTEZ)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// Authentification (ADAPTEZ) : remplit ctx.state.user avant le routeur Blunx
app.use(async (ctx, next) => {
  ctx.state.user = USERS[1];
  await next();
});

// Runtime Blunx (clés + BDD depuis le .env)
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// Montage du routeur Blunx
app.use(blunxKoa(blunx));

app.listen(3000, () => console.log('Blunx prêt sur http://localhost:3000'));

import { Module } from '@nestjs/common';
import { Blunx, createBlunxNestController } from 'blunx-ai';

// Utilisateurs de démo (ADAPTEZ)
const USERS: Record<number, any> = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// Runtime Blunx (clés + BDD depuis le .env)
const blunx = Blunx.init({
  getUserRole: (userId: any) => USERS[userId]?.role ?? null,
  getUser: (userId: any) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

// Contrôleur Blunx (votre guard d'auth Nest doit remplir req.user — ADAPTEZ)
const BlunxController = createBlunxNestController(blunx);

@Module({ controllers: [BlunxController] })
export class BlunxModule {}

const http = require('http');
const { Blunx, blunxNodeHttp } = require('blunx-ai');

// Utilisateurs de démo (ADAPTEZ)
const USERS = {
  1: { name: 'Amir',  email: 'amir@x.com',  role: 'admin'   },
  2: { name: 'Sarah', email: 'sarah@x.com', role: 'vendeur' },
};

// Runtime Blunx (clés + BDD depuis le .env)
const blunx = Blunx.init({
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

http.createServer((req, res) => {
  // Authentification (ADAPTEZ) : remplit req.user avant le routeur Blunx
  req.user = USERS[1];

  if (blunxNodeHttp(blunx, req, res)) return;   // requête gérée par Blunx
  res.writeHead(404).end();
}).listen(3000, () => console.log('Blunx prêt sur http://localhost:3000'));

Web SDK

Le Web SDK (@blunx/web-sdk) est une application front autonome et embarquable : cockpit de chat + canvas, dashboards et insights. Il se monte dans un simple conteneur DOM. L'intégration est identique quel que soit votre backend (Laravel, Node.js…).

Formats de distribution

Intégration par framework

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx-loader.min.js"
        data-container="#blunx"
        data-view="auto"></script>

<div id="blunx" style="height:100vh;"></div>
<script src="https://cdn.jsdelivr.net/npm/@blunx/web-sdk/dist/blunx.min.js"></script>
<script>
  Blunx.init({ container: '#blunx', view: 'auto' })
    .then(function (info) { console.log('[Blunx] prêt', info); })
    .catch(function (err) { console.error('[Blunx] échec', err); });
</script>

npm install @blunx/web-sdk

import { useEffect } from 'react';
import { init, destroy, navigate } from '@blunx/web-sdk';

export default function App() {
    useEffect(() => {
        let mounted = true;

        init({
            container: '#blunx',
            apiBaseUrl: '', // cross-origin — vide en même origine
            view: 'auto',
            onReady: (info) => console.log('[React] Blunx prêt', info),
            onError: (err) => console.error('[React] Blunx erreur', err),
        })
            .then((info) => { if (mounted) console.log('[React] monté', info); })
            .catch((err) => console.error('[React] init échouée', err));

        return () => { mounted = false; destroy(); }; // démontage (StrictMode-safe)
    }, []);

    return (
        <div className="host">
            <header className="host-top">
                <strong>React hôte</strong>
                <span>SDK monté dans <code>#blunx</code></span>
            </header>
            <div id="blunx" className="blunx-zone" />
        </div>
    );
}

'use client';

import { useEffect, useRef } from 'react';

export default function Home() {
    const apiRef = useRef(null);

    useEffect(() => {
        let mounted = true;

        import('@blunx/web-sdk')
            .then(({ init, destroy, navigate }) => {
                apiRef.current = { destroy, navigate };
                return init({
                    container: '#blunx',
                    apiBaseUrl: '', // cross-origin — vide en même origine
                    view: 'auto',
                    onReady: (info) => console.log('[Next] Blunx prêt', info),
                    onError: (err) => console.error('[Next] Blunx erreur', err),
                });
            })
            .then((info) => { if (mounted) console.log('[Next] monté', info); })
            .catch((err) => console.error('[Next] init échouée', err));

        return () => { mounted = false; apiRef.current?.destroy?.(); };
    }, []);

    return (
        <main className="host">
            <header className="host-top">
                <strong>Next.js hôte</strong>
                <span>SDK importé dynamiquement (SSR-safe)</span>
            </header>
            <div id="blunx" className="blunx-zone" />
        </main>
    );
}

npm install @blunx/web-sdk

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { init, destroy, navigate } from '@blunx/web-sdk';

onMounted(async () => {
    try {
        const info = await init({
            container: '#blunx',
            apiBaseUrl: '', // cross-origin — vide en même origine
            view: 'auto',
            onReady: (i) => console.log('[Vue] Blunx prêt', i),
            onError: (e) => console.error('[Vue] Blunx erreur', e),
        });
        console.log('[Vue] monté', info);
    } catch (e) {
        console.error('[Vue] init échouée', e);
    }
});

onUnmounted(() => {
    destroy(); // démonte le SDK quand le composant est retiré
});
</script>

<template>
    <div class="host">
        <header class="host-top">
            <strong>Vue 3 hôte</strong>
            <span>SDK monté dans <code>#blunx</code></span>
        </header>
        <div id="blunx" class="blunx-zone" />
    </div>
</template>

import { Component, OnInit, OnDestroy } from '@angular/core';
import { init, destroy, navigate } from '@blunx/web-sdk';

@Component({
    selector: 'app-root',
    standalone: true,
    template: `
        <div class="host">
            <header class="host-top">
                <strong>Angular hôte</strong>
                <span>SDK monté dans <code>#blunx</code></span>
            </header>
            <div id="blunx" class="blunx-zone"></div>
        </div>
    `,
})
export class AppComponent implements OnInit, OnDestroy {
    async ngOnInit(): Promise<void> {
        try {
            const info = await init({
                container: '#blunx',
                apiBaseUrl: '', // cross-origin — vide en même origine
                view: 'auto',
                onReady: (i) => console.log('[Angular] Blunx prêt', i),
                onError: (e) => console.error('[Angular] Blunx erreur', e),
            });
            console.log('[Angular] monté', info);
        } catch (e) {
            console.error('[Angular] init échouée', e);
        }
    }

    ngOnDestroy(): void {
        destroy(); // démonte le SDK quand le composant est détruit
    }

}

<script>
    import { onMount, onDestroy } from 'svelte';
    import { init, destroy, navigate } from '@blunx/web-sdk';

    onMount(async () => {
        try {
            const info = await init({
                container: '#blunx',
                apiBaseUrl: '', // cross-origin — vide en même origine
                view: 'auto',
                onReady: (i) => console.log('[Svelte] Blunx prêt', i),
                onError: (e) => console.error('[Svelte] Blunx erreur', e),
            });
            console.log('[Svelte] monté', info);
        } catch (e) {
            console.error('[Svelte] init échouée', e);
        }
    });

    onDestroy(() => {
        destroy(); // démonte le SDK quand le composant est détruit
    });
</script>

<div class="host">
    <header class="host-top">
        <strong>Svelte hôte</strong>
        <span>SDK monté dans <code>#blunx</code></span>
    </header>
    <div id="blunx" class="blunx-zone"></div>
</div>

API publique & options

import { init, destroy, navigate, version } from '@blunx/web-sdk';

init(options)  // → Promise<{ view: 'cockpit'|'dashboard', version }>
destroy()      // démonte et nettoie le listener hashchange + le contenu du conteneur
navigate(path) // navigation interne, ex. navigate('/dashboard/abc-123') → '#/dashboard/abc-123'
version        // string, ex. "0.1.0"

Via script-tag, les options se passent en attributs data-* : data-container, data-api-base-url, data-view, data-dashboard-uuid.

Pièges & bonnes pratiques

Configuration

Cette page est la référence complète : toutes les variables d'environnement, toutes les options de Blunx.init() et les règles d'accès RBAC. Dans la majorité des cas, le .env suffit.

Les 3 façons de configurer

Variables d'environnement

Colonne Alternative : clé blunx.* (Laravel) / option init() (Node).

Les tables exclues du scan (excluded_tables en Laravel, excludedTables en Node) et les règles RBAC (access) n'ont pas de variable d'env : elles se passent par option/fichier (voir les sections ci-dessous).

Blunx.init() — toutes les options (Node.js)

Référence complète de ce que vous pouvez passer à Blunx.init(). Priorité : option > variable d'env > défaut. Le template TypeScript config/blunx.config.ts (exporté, sans dépendance) utilise ces clés en camelCase ; les clés snake_case (server_url, api_key, db_url…) sont aussi acceptées (miroir de config/blunx.php).

Charger les fichiers de config (Node.js)

Exemple complet : on publie config/blunx.config.ts + config/blunx-access.config.ts (templates TypeScript, aucune dépendance), on les charge, et on ajoute la base + les hooks :

import blunxConfig from './config/blunx.config';            // ta copie éditée
import blunxAccessConfig from './config/blunx-access.config'; // tes règles RBAC

const blunx = Blunx.init({
  ...blunxConfig,          // serverUrl, apiKey, llm, currency, locale…
  access: blunxAccessConfig,  // règles RBAC
  // BDD : via BLUNX_DB_URL dans le .env (recommandé), ou :
  // database: { client: 'mysql2', connection: { host, user, password, database } },
  getUserRole: (userId) => USERS[userId]?.role ?? null,
  getUser: (userId) => {
    const u = USERS[userId];
    return u ? { name: u.name, email: u.email } : null;
  },
});

Règles d'accès RBAC (access)

Approche NÉGATIVE : on définit ce que l'utilisateur N'A PAS le droit de voir. En Laravel : config/blunx_access.php. En Node : option access de Blunx.init() (fichier config/blunx-access.config.ts). Aucune variable d'env.

Trois niveaux de restriction par rôle :

Exemple complet (fichier config/blunx-access.config.ts) :

export default {
  "vendeur": {
    "forbidden_tables": ["salaires", "comptabilite"],
    "forbidden_columns": {
      "users": ["salaire", "numero_secu", "adresse_complete"],
      "*": ["mot_de_passe", "token_api"]
    },
    "row_level": {
      "orders":   { "column": "user_id", "value": "USER_ID" },
      "products": { "column": "vendor_id", "value": "USER_ID" }
    }
  },
  "admin":   { "forbidden_tables": [], "forbidden_columns": [], "row_level": {} },
  "default": { "forbidden_tables": ["users"], "forbidden_columns": {}, "row_level": {} },
  "enabled": true
}

• USER_ID : placeholder remplacé par l'ID de l'utilisateur connecté.
• Le SDK fusionne default + les règles du rôle (fusion récursive, comme array_replace_recursive).
• Si aucun rôle n'est résolu → null → erreur SSE Access rules not resolved.
• enabled : active/désactive tout le système de permissions.

Tables exclues du scan (excluded_tables / excludedTables)

À la génération du schéma (blunx:init / npx blunx-ai init), Blunx scanne toutes les tables de votre base et les rend interrogeables par l'assistant. Listez ici les tables techniques, sensibles ou sans intérêt qui ne doivent jamais apparaître dans le schéma. Aucune variable d'env : la liste se déclare par fichier/option.

'excluded_tables' => [
    // Déjà exclus par défaut : migrations, failed_jobs, cache, jobs, sessions,
    // password_reset_tokens, personal_access_tokens… + les tables internes blunx_*
    'admin_logs', 'notifications', 'settings', 'audit_trail',   // ▶ vos tables
],

export default {
  // ...
  // Tables internes blunx_* déjà ignorées par défaut.
  // ▶ Ajoutez vos tables techniques / sensibles à ne pas scanner :
  excludedTables: ['migrations', 'sessions', 'log_errors', 'admin_logs', 'notifications'],
};

Un .env complet prêt à copier

# --- Serveur Blunx ---
BLUNX_SERVER_URL=https://blunxai.com
# Timeout (s) de chaque requête vers le Hub — 600 (10 min) par défaut ; 0 = aucun
BLUNX_REQUEST_TIMEOUT=600
BLUNX_API_KEY=blunx_app_live_xxxxxxxxxxxx

# --- Fournisseur LLM (OpenAI dans cet exemple) ---
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=https://api.openai.com/v1
BLUNX_LLM_MODEL=gpt-4o
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

# --- Base de données ---
BLUNX_DB_CONNECTION=mysql
# BLUNX_DB_URL=postgres://user:pass@host:5432/db?sslmode=require   # alternative : URL de connexion (DSN)
# BLUNX_READONLY_DB_USERNAME=blunx_readonly   # optionnel (voir modes de connexion)
# BLUNX_READONLY_DB_PASSWORD=secret
# BLUNX_PGSQL_SCHEMA=public                    # PostgreSQL uniquement

# --- Affichage & langue ---
BLUNX_CURRENCY_CODE=EUR
BLUNX_CURRENCY_SYMBOL=€
BLUNX_CURRENCY_LOCALE=fr_FR
BLUNX_LOCALE=fr

Les 3 modes de connexion à la base de données

Blunx exécute le SQL sur votre base. Trois notions complémentaires — à ne pas confondre :

Contrat API

Deux familles d'endpoints : le Web SDK ne connaît que les endpoints locaux /api/blunx/* servis par votre SDK backend ; celui-ci proxie vers le serveur Blunx /api/v1/*.

Endpoints locaux (/api/blunx/*)

Session + auth, sans CSRF, throttle 60:1. Réponses enveloppées dans { "data": … }, sauf /user (objet direct).

Endpoints du serveur Blunx (/api/v1/*)

Middlewares : ValidateBlunxKey (X-Blunx-Key) puis RequireLLMConfig (X-Blunx-LLM-Key + bloc llm dans le body).

En-têtes communs

X-Blunx-Key: blunx_app_live_xxxxxxx      # clé d'application (requis)
X-Blunx-LLM-Key: sk-xxxxxxxxxxxxxxxx     # clé du fournisseur LLM (requis)
Content-Type: application/json
Accept: text/event-stream | application/json

Payload de base

Chaque appel au serveur Blunx transporte la connexion BDD et la configuration LLM. Les clés passent par les en-têtes, jamais dans le body (pas de fuite dans les logs).

{
  "db_connection": "mysql",
  "locale": "fr",
  "currency": { "code": "XOF", "symbol": "FCFA", "locale": "fr_FR" },
  "llm": {
    "driver": "openai",
    "endpoint": "https://api.openai.com/v1",
    "model": "gpt-4o",
    "supports_json_format": true
  }
}

Chat — POST /api/v1/chat/queries

Requête :

{
  "question": "Quel est le chiffre d'affaires par région ?",
  "conversation_history": [ { "role": "user", "content": "…" } ],
  "access_rules": { "forbidden_tables": [], "forbidden_columns": [], "row_level": [] },
  "schema": "… schéma complet en JSON string (ou schema_id) …",
  "schema_id": "uuid-optionnel",
  "db_connection": "mysql",
  "locale": "fr",
  "currency": { "code": "XOF", "symbol": "FCFA", "locale": "fr_FR" },
  "llm": { "driver": "openai", "endpoint": "…", "model": "…", "supports_json_format": true }
}

Réponse SSE — événement result :

{
  "needs_data": true,
  "needs_clarification": false,
  "normalized_question": "…",
  "intent": "…",
  "queries": [ { "sql": "SELECT …", "ui_hint": "chart", "chart_type": "bar" } ],
  "warnings": [],
  "filtered_schema_id": "uuid"
}

Cas terminaux : needs_clarification (+ clarification_question), needs_data=false, access_denied (+ message, forbidden_info).

Chat — validate & synthesize

Validate : {normalized_question, intent, execution_results, filtered_schema_id, access_rules, locale, db_connection, llm} → {queries[], warnings[]} (SQL corrigés).

Synthesize : {normalized_question, execution_results, conversation_history, needs_data, locale, currency, llm} → réponse structurée :

{
  "title": "Chiffre d'affaires par région",
  "layout": [
    { "type": "paragraph", "content": "… HTML Bootstrap 5 …" },
    { "type": "chart", "chart_type": "bar", "title": "…", "label_column": "…",
      "data_columns": ["…"], "comment": "…", "sql_query": "…" },
    { "type": "table", "title": "…", "comment": "…", "sql_query": "…" }
  ],
  "Resume": "… résumé markdown …"
}

Si needs_data=false : { "Resume": "…", "is_conversational": true }.

Insights, schéma & références

• Analyze : {widget_title, sql_query, current_meta, previous_meta?, metric_weights?, locale, currency, llm} → {type, severity, message, meta}.
• Report : {insight_result, current_meta, previous_meta?, last_insight?, widget_title, dashboard_name, report_frequency, locale, currency, llm} → {html}.
• Schema enrich : {columns, locale, llm} → {columns} avec descriptions.
• Reference generate : {widget_sql, widget_title?, numeric_columns[], access_rules?, db_connection, locale, llm} → {queries}.

Flux SSE — événements

event: step
data: {"step":1,"status":"running","duration":1}

event: result
data: { …resultat… }

event: done
data: {"result":{ "title":"…", "Resume":"…", "layout":[…] }, "message_uuid":"…"}

event: error
data: {"message":"…"}

Sécurité & accès

Blunx applique une défense en profondeur sur plusieurs niveaux pour garantir que vos données ne sont jamais modifiées ni exposées au-delà de ce que vous autorisez.

1. Lecture seule stricte (SqlGuard)

Chaque requête SQL est validée localement avant exécution. Les règles sont multiples :

• La requête doit commencer par SELECT ou WITH (CTE).
• Mots-clés dangereux interdits : INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, GRANT, REVOKE, EXEC, VACUUM, LOCK, COPY, etc.
• Fonctions dangereuses interdites : pg_sleep, pg_read_file, lo_import, dblink, pg_execute_server_program, set_config, etc.
• SELECT … INTO interdit.
• Un sanitize() retire les littéraux chaîne et les commentaires avant analyse (évite les faux positifs sur les valeurs).

invalid statement type: INSERT (only SELECT allowed)
forbidden keyword found: DROP
forbidden function call found: pg_sleep
SELECT ... INTO is forbidden ...

Même si une requête était altérée entre la génération et l'exécution, l'agent d'exécution (DataExecutorAgent) re-valide et saute toute requête non-SELECT.

2. Connexion BDD en lecture seule dédiée

C'est le verrou de sécurité principal. Si BLUNX_READONLY_DB_USERNAME est renseigné, le package crée une connexion blunx_readonly (même driver/hôte/base, identifiants dédiés) utilisée pour toutes les exécutions. En base, accordez à ce rôle uniquement GRANT SELECT, USAGE :

-- MySQL
CREATE USER 'blunx_readonly'@'%' IDENTIFIED BY 'mot_de_passe_fort';
GRANT SELECT ON votre_base.* TO 'blunx_readonly'@'%';

-- PostgreSQL
CREATE ROLE blunx_readonly LOGIN PASSWORD 'mot_de_passe_fort';
GRANT CONNECT ON DATABASE votre_base TO blunx_readonly;
GRANT USAGE ON SCHEMA public TO blunx_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO blunx_readonly;

3. Règles d'accès par rôle (RBAC)

Le fichier config/blunx_access.php définit, par rôle, les tables et colonnes interdites et le filtrage par ligne. Voir la section Configuration pour la syntaxe complète. Le rôle provient de getUserRoleName() sur votre modèle User.

• Tables interdites : jamais scannées ni exposées au LLM.
• Colonnes interdites : masquées (motif '*' = toutes les tables).
• Filtrage par ligne : le placeholder USER_ID est remplacé par l'ID de l'utilisateur connecté (ex. un vendeur ne voit que orders.user_id = lui-même).

4. Authentification

En cross-origin, le backend doit accepter credentials: include (Access-Control-Allow-Credentials + origine explicite, pas *) et les en-têtes Accept, Content-Type, X-Requested-With (préflight CORS).

5. Autres protections

• Rate limiting : 60 requêtes/min/IP sur le groupe local /api/blunx/* (throttle Laravel ; en Node, ajoutez votre rate limiter, ex. express-rate-limit), sauf webhook Stripe (non concerné ici).
• Validation SQL : double vérification (client + serveur), une requête non-SELECT n'est jamais exécutée.
• Schéma PostgreSQL : le scan ne touche que le schéma configuré (BLUNX_PGSQL_SCHEMA), jamais les autres.
• CSRF : le groupe blunx reproduit web sans CSRF (l'auth par session suffit pour cette API AJAX).

Fournisseurs LLM

Choisissez votre fournisseur via le driver et l'endpoint. L'adaptateur openai est « compatible OpenAI » : il fonctionne avec la quasi-totalité des fournisseurs, propriétaires comme open-source.

Tableau des fournisseurs

Configurer un fournisseur

Exemple : DeepSeek (API compatible OpenAI)

BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=https://api.deepseek.com/v1
BLUNX_LLM_MODEL=deepseek-chat
BLUNX_LLM_API_KEY=sk-xxxxxxxxxxxx
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

Exemple : Ollama en local (zéro dépendance cloud)

BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=http://localhost:11434/v1
BLUNX_LLM_MODEL=llama3.1
BLUNX_LLM_API_KEY=ollama          # valeur non utilisée, peut rester vide
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

Exemple : Groq

BLUNX_LLM_DRIVER=openai
BLUNX_LLM_ENDPOINT=https://api.groq.com/openai/v1
BLUNX_LLM_MODEL=llama-3.3-70b-versatile
BLUNX_LLM_API_KEY=gsk_xxxxxxxxxxxx
BLUNX_LLM_SUPPORTS_JSON_FORMAT=true

Détail des drivers

supports_json_format

Indique si le modèle gère le mode response_format: json_object. Les modèles modernes (GPT-4o, DeepSeek, Groq…) le supportent (true) ; certains modèles locaux plus anciens non. Si le modèle ne le supporte pas, mettez false pour que le pipeline demande le JSON en langage naturel plutôt qu'en mode structuré.

Erreurs & dépannage

Organisé par niveau : serveur Blunx (HTTP), backend (Laravel / Node), SSE et Web SDK. Cherchez d'abord le code HTTP, puis le niveau concerné.

1 · Codes HTTP du serveur Blunx

Communs aux deux backends — renvoyés par le hub /api/v1/* :

2 · Backend

Les deux SDK lèvent une exception avec un message humain (le message du serveur prime s'il existe) :

401 => "Invalid or expired API key"
402 => "Billing inactive. Please check your subscription."
403 => "Application suspended. Contact support."
429 => "Quota exceeded. Please wait before retrying."
422 => "LLM configuration missing. Check your settings."
default => "AI service error. Please try again later."

try {
  await blunx.api.someCall();
} catch (e) {
  if (e instanceof BlunxError) {
    console.error(e.statusCode, e.message); // ex. 401 "Invalid or expired API key"
  }
}

3 · Erreurs SSE

• Événement error : {message, code, fields, plan, limit, used}.
• HTTP ≥ 400 : extraction de message / error / detail.
• Erreur réseau : cURL error: … (PHP) / fetch failed (Node).
• SCHEMA_NOT_FOUND : retry automatique sans schema_id.

4 · Erreurs du Web SDK

5 · Erreurs fréquentes à l'intégration

Versions & mises à jour

Politique de versioning du Web SDK et mise à jour du SDK backend.

Politique de versioning

Le Web SDK suit le versioning sémantique (MAJEUR.MINEUR.CORRECTIF) :

• Correctif : bugfix sans rupture (aucune action requise).
• Mineur : nouvelle fonctionnalité rétro-compatible.
• Majeur : rupture (API publique, contrat REST, navigation).

Mises à jour du Web SDK

Changelog du Web SDK

Package Laravel

• Mettez à jour avec composer update blunx/ai.
• Vérifiez la version : composer show blunx/ai.
• Après mise à jour majeure, revérifiez config/blunx.php publié (le fichier publié n'est pas écrasé automatiquement).

Support

Un problème non résolu par cette documentation ? L'équipe Blunx vous répond sous 24 h.

Licence : MIT — © 2026 BlunxAI. Package Laravel : blunx/ai · Web SDK : @blunx/web-sdk.