FluxChat SDK

# npm · pnpm · yarn
npm install @fluxchat_sdk/sdk
pnpm add @fluxchat_sdk/sdk
yarn add @fluxchat_sdk/sdk

import { FluxChat } from '@fluxchat_sdk/sdk';

const fluxchat = new FluxChat({ apiKey: process.env.FLUXCHAT_API_KEY });

const { reply } = await fluxchat.ask({
  message: 'What is the status of my order?',
  context: 'Order #1234 — shipped on June 3rd.',   // v2: injected as priority truth
});

<script src="https://unpkg.com/@fluxchat_sdk/sdk/dist/widget.global.js"></script>
<script>
  FluxChatWidget.init({
    apiKey: 'fc_prod_xxx',
    autoContext: true,   // captures page title, URL and visible text automatically
    autoCrawl: true,     // indexes this page in your KB on first load
  });
</script>

const { reply } = await fluxchat.ask({
  message: userQuestion,
  context: `Plan: ${user.plan}. Open tickets: ${tickets.length}.`,
});

{
  "title": "Bengali Chicken Curry",
  "content": "Chicken curry from Bengal. Ingredients: 4 chicken breasts…",
  "category": "recipe",
  "keywords": ["chicken", "curry", "bengal", "spices"]
}

import { init } from '@fluxchat_sdk/sdk/widget';

const widget = init({
  apiKey: 'fc_prod_xxx',
  clientName: 'Acme Bank',
  assistantName: 'Léa',
  primaryColor: '#5b6ef0',
  autoEnvDetect: true,  // DEV badge on localhost, prod badge in production
  autoContext: true,    // captures page context automatically
  autoCrawl: true,      // indexes pages in your KB silently
});
// widget.open() · widget.toggleTheme() · widget.destroy()

import { init } from '@fluxchat_sdk/sdk/widget';

init({
  apiKey: 'fc_prod_xxx',
  greeting: 'Bonjour ! Comment puis-je vous aider ?',
  quickReplies: [
    'Quelles sont vos horaires ?',
    'Comment vous contacter ?',
    'Voir les tarifs',
    'Suivre ma commande',
  ],
});

init({ apiKey: 'fc_prod_xxx', mode: 'floating', position: 'right' });

<div id="support" style="height: 600px; max-width: 460px"></div>

<script src="https://unpkg.com/@fluxchat_sdk/sdk/dist/widget.global.js"></script>
<script>
  FluxChatWidget.init({ apiKey: 'fc_prod_xxx', mode: 'inline', target: '#support' });
</script>

fc_dev_xxx   → development (relaxed rate limits, verbose logs)
fc_prod_xxx  → production (full enforcement)

POST /api/v2/organizations/:orgId/api-keys/provision
// returns { dev: { key: 'fc_dev_xxx' }, prod: { key: 'fc_prod_xxx' } }

init({
  apiKey: 'fc_dev_xxx',     // fc_dev_ prefix → dev mode
  autoEnvDetect: true,      // default — can be set to false to disable
});

// Basic — string or object, both work
window.fluxchatContext = "User: Marie, Plan: Pro, Cart: 2 items";

// Recommended — structured object (auto-serialised to JSON)
window.fluxchatContext = {
  user: { name: "Marie", email: "marie@example.com", plan: "Pro" },
  cart: [{ id: 1, name: "T-shirt", qty: 2, price: 29.99 }],
};

// Merging sections (e.g. set user at root, add billing on billing page)
window.fluxchatContext = {
  ...window.fluxchatContext,
  billing: { plan: "Enterprise", messages_used: 255, messages_limit: 500000 },
};

// Root authenticated layout — runs once after login
useEffect(() => {
  if (!user) return;
  window.fluxchatContext = {
    user: {
      name: user.displayName,
      email: user.email,
      role: user.role,
      phone: user.phone,
      location: user.location,
    },
    org: { name: currentOrg.name },
  };
}, [user, currentOrg]);

// Billing page — adds quota data on top, removes on unmount
useEffect(() => {
  window.fluxchatContext = {
    ...window.fluxchatContext,
    billing: { plan: "Enterprise", messages_used: 255, messages_limit: 500000 },
  };
  return () => {
    const c = { ...window.fluxchatContext };
    delete c.billing;
    window.fluxchatContext = c;
  };
}, [subscription, usage]);

const fluxchat = new FluxChat({
  apiKey: 'fc_prod_xxx',
  organizationId: 'org-uuid', // only needed for knowledge & config
});

const res = await fluxchat.ask({ message, context, conversationId });
const info = await fluxchat.testKey();

await fluxchat.config.update({
  assistantName: 'Léa',
  tone: 'chaleureux et concis',
  styleRules: 'Tutoie le client, évite le jargon.',
  captureTrainingData: false,
});

const current = await fluxchat.config.get();

await fluxchat.config.update({ strictMode: true });

await fluxchat.knowledge.create({ title: 'Horaires', content: 'Lun–Ven 9h–18h.' });
await fluxchat.knowledge.update(id, { content: 'Lun–Ven 8h–19h.' });
await fluxchat.knowledge.remove(id);
const all = await fluxchat.knowledge.list(); // JWT

// Single page
await fluxchat.knowledge.crawl({ url: 'https://acme.com/faq' });

// From a sitemap (up to 20 pages)
await fluxchat.knowledge.crawl({
  url: 'https://acme.com/sitemap.xml',
  isSitemap: true,
  maxPages: 20,
});

fluxchat kb crawl --url https://acme.com/faq
fluxchat kb crawl --url https://acme.com/sitemap.xml --sitemap --max-pages 20

init({ apiKey: 'fc_prod_xxx', autoCrawl: true });

export FLUXCHAT_API_KEY="fc_prod_xxx"
fluxchat test
fluxchat ask "Bonjour !" --context "Client VIP"
fluxchat kb create --title "FAQ" --content "…"

# v2 — crawl a URL or sitemap
fluxchat kb crawl --url https://acme.com/faq
fluxchat kb crawl --url https://acme.com/sitemap.xml --sitemap --max-pages 20

curl -X POST /api/v2/organizations/$ORG_ID/api-keys/provision \
  -H "Authorization: Bearer $ADMIN_JWT"

POST https://dev-api.fluxchat-corp.com/api/v2/public/bot/pages
Content-Type: application/json
X-API-Key: fc_prod_f45868df738ddbec537c6c929570f1dad830fb0ca0cd5f82652e9eb7db4ede16

{
  "url": "https://test.example.com/about",
  "title": "About FluxTest",
  "content": "FluxTest is a fictional company founded in 2099 by Zara Kowalski. Our slogan is: code never lies, only humans do."
}

HTTP/1.1 204 No Content

POST https://dev-api.fluxchat-corp.com/api/v2/public/bot/ask
Content-Type: application/json
X-API-Key: fc_prod_f45868df738ddbec537c6c929570f1dad830fb0ca0cd5f82652e9eb7db4ede16

{
  "message": "Who founded FluxTest and what is their slogan?"
}

{
  "success": true,
  "data": {
    "reply": "FluxTest was founded in 2099 by Zara Kowalski. Their slogan is: code never lies, only humans do.",
    "conversationId": "",
    "confidence": 1
  }
}

// Message 1 — introduce something
POST /public/bot/ask
{ "message": "My name is Zara.", "sessionId": "test-session-001" }
→ bot: "Nice to meet you, Zara!"

// Message 2 — same sessionId — test context retention
POST /public/bot/ask
{ "message": "What is my name?", "sessionId": "test-session-001" }
→ bot: "Your name is Zara."   ← PASS

// Message 2 — NO sessionId — test that context is correctly absent
POST /public/bot/ask
{ "message": "What is my name?", "sessionId": "test-session-002" }
→ bot: "I don't have your name."   ← PASS (different session, no context)

400 Bad Request   → missing required field (url, title, or content is empty)
401 Unauthorized  → API key header missing or malformed
403 Forbidden     → API key is valid but lacks bot:write scope (use the sandbox key above — it has all scopes)
413               → content exceeds 6000 chars — truncate before sending
204 but bot doesn't answer → content was received but extraction is still running — wait 10s and retry
204 but entry missing from KB → content was too short or had no extractable facts (min ~50 words recommended)

POST /public/bot/ask
Content-Type: application/json
X-API-Key: fc_prod_your_key

{
  "message": "What are your opening hours?",
  "context": "User: Alice, Plan: Pro",    // optional — highest priority
  "sessionId": "sess_abc123",             // optional — stateful Redis session
  "conversationId": ""                    // optional — omit for stateless
}

// Success response (every endpoint follows this envelope)
{
  "success": true,
  "data": {
    "reply": "We are open Mon–Fri 9am–6pm.",
    "conversationId": "conv-uuid",        // empty string if stateless
    "intent": null,
    "confidence": 1
  },
  "timestamp": "2026-06-11T00:00:00.000Z"
}

// Error response
{
  "success": false,
  "statusCode": 403,
  "message": "API key missing required scope(s): bot:write",
  "timestamp": "2026-06-11T00:00:00.000Z"
}

// Verify API key
GET /public/bot/test
X-API-Key: fc_prod_your_key
→ { "data": { "organizationId": "uuid", "scopes": ["bot:write"] } }

// Passive page capture (no bot:write needed)
POST /public/bot/pages
{ "url": "https://app.com/about", "title": "About", "content": "…max 6000 chars…" }
→ 204 No Content

// KB article — requires bot:write scope
POST   /bot/knowledge          { title, content, category, keywords }
PATCH  /bot/knowledge/:id      { content: "updated" }
DELETE /bot/knowledge/:id      → 204

// Admin (JWT required)
GET    /bot/knowledge           list all articles
GET    /bot/knowledge/:id       get one article
GET    /bot/config              get persona config
PATCH  /bot/config              { assistantName, tone, styleRules, strictMode }

fluxchat-sdk/               ← root = official JS/TS SDK (published to npm)
├── src/
├── dist/
├── package.json
├── README.md
│
├── sdk/                    ← community SDKs live here
│   ├── python/             ← your contribution goes here
│   │   ├── README.md       # install + quickstart for Python
│   │   ├── src/
│   │   ├── tests/
│   │   └── pyproject.toml
│   │
│   ├── flutter/
│   │   ├── README.md
│   │   ├── lib/
│   │   ├── test/
│   │   └── pubspec.yaml
│   │
│   ├── go/
│   │   ├── README.md
│   │   ├── fluxchat.go
│   │   ├── fluxchat_test.go
│   │   └── go.mod
│   │
│   └── <your-stack>/       ← same pattern for every other language
│       ├── README.md
│       ├── src/
│       ├── tests/
│       └── <package config>

✓ ask — successful response parsing
✓ ask — stateless (no conversationId → empty string returned)
✓ testKey — parse organizationId + scopes
✓ knowledge.create — create + parse response
✓ knowledge.list — list parsing
✓ knowledge.delete — 204 handling
✓ Network error (connection refused) → FluxChatNetworkError
✓ 401 Unauthorized → FluxChatApiError(401)
✓ 403 Forbidden (missing scope) → FluxChatApiError(403)

import httpx
from dataclasses import dataclass

BASE_URL = "https://dev-api.fluxchat-corp.com/api/v2"

@dataclass
class AskResponse:
    reply: str
    conversation_id: str

class FluxChatApiError(Exception):
    def __init__(self, status: int, message: str):
        self.status = status
        super().__init__(f"FluxChat API {status}: {message}")

class FluxChat:
    def __init__(self, api_key: str, base_url: str = BASE_URL):
        self._headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
        self.base_url = base_url.rstrip("/")

    def ask(self, message: str, *, context: str | None = None,
            conversation_id: str | None = None) -> AskResponse:
        payload: dict = {"message": message}
        if context:     payload["context"] = context
        if conversation_id: payload["conversationId"] = conversation_id
        with httpx.Client() as c:
            r = c.post(f"{self.base_url}/public/bot/ask",
                       json=payload, headers=self._headers)
        if not r.is_success:
            raise FluxChatApiError(r.status_code, r.text)
        data = r.json()["data"]
        return AskResponse(reply=data["reply"],
                           conversation_id=data.get("conversationId", ""))

    def capture_page(self, url: str, title: str, content: str) -> None:
        with httpx.Client() as c:
            c.post(f"{self.base_url}/public/bot/pages",
                   json={"url": url, "title": title, "content": content[:6000]},
                   headers=self._headers)

package fluxchat

import (
    "bytes"; "encoding/json"; "fmt"; "net/http"
)

const defaultBaseURL = "https://dev-api.fluxchat-corp.com/api/v2"

type Client struct { apiKey, baseURL string; http *http.Client }

type AskOptions struct {
    Message        string `json:"message"`
    Context        string `json:"context,omitempty"`
    ConversationID string `json:"conversationId,omitempty"`
}
type AskResponse struct {
    Reply          string `json:"reply"`
    ConversationID string `json:"conversationId"`
}

func New(apiKey string) *Client {
    return &Client{apiKey: apiKey, baseURL: defaultBaseURL, http: &http.Client{}}
}

func (c *Client) Ask(opts AskOptions) (*AskResponse, error) {
    body, _ := json.Marshal(opts)
    req, _ := http.NewRequest("POST", c.baseURL+"/public/bot/ask", bytes.NewReader(body))
    req.Header.Set("X-API-Key", c.apiKey)
    req.Header.Set("Content-Type", "application/json")
    resp, err := c.http.Do(req)
    if err != nil { return nil, fmt.Errorf("network: %w", err) }
    defer resp.Body.Close()
    if resp.StatusCode >= 400 { return nil, fmt.Errorf("api error %d", resp.StatusCode) }
    var env struct{ Data AskResponse `json:"data"` }
    json.NewDecoder(resp.Body).Decode(&env)
    return &env.Data, nil
}

import 'dart:convert';
import 'package:http/http.dart' as http;

class FluxChat {
  final String apiKey;
  final String baseUrl;
  FluxChat({required this.apiKey,
            this.baseUrl = 'https://dev-api.fluxchat-corp.com/api/v2'});

  Future<Map<String, dynamic>> ask(String message,
      {String? context, String? conversationId}) async {
    final body = <String, dynamic>{'message': message};
    if (context != null) body['context'] = context;
    if (conversationId != null) body['conversationId'] = conversationId;
    final r = await http.post(
      Uri.parse('$baseUrl/public/bot/ask'),
      headers: {'X-API-Key': apiKey, 'Content-Type': 'application/json'},
      body: jsonEncode(body),
    );
    if (r.statusCode >= 400) throw Exception('FluxChat ${r.statusCode}: ${r.body}');
    final data = jsonDecode(r.body)['data'];
    return {'reply': data['reply'], 'conversationId': data['conversationId'] ?? ''};
  }

  Future<void> capturePage(String url, String title, String content) =>
    http.post(Uri.parse('$baseUrl/public/bot/pages'),
      headers: {'X-API-Key': apiKey, 'Content-Type': 'application/json'},
      body: jsonEncode({'url': url, 'title': title,
                        'content': content.substring(0, content.length.clamp(0, 6000))}));
}

# 1. Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/fluxchat-sdk.git
cd fluxchat-sdk

# 2. Create your branch (sdk/<language> for new SDKs)
git checkout -b sdk/python

# 3. Create sdk/python/ with:
#    - README.md (install + quickstart)
#    - src/       (your implementation)
#    - tests/     (required test coverage — see above)
#    - pyproject.toml / go.mod / pubspec.yaml / etc.

# 4. Push and open a PR against main
git push origin sdk/python
# → open PR at github.com/benflux-company/fluxchat-sdk

User message → POST /public/bot/ask
        │
        ▼
1. Authenticate X-API-Key → resolve organizationId + org config (strictMode, persona)
        │
        ▼
2. Upsert per-request context into bot_session_page (BEFORE stateless check)
        │
        ▼
3. Stateless check: no conversationId → skip DB load, reply won't be persisted
        │
        ▼
4. Build knowledge context
   a. ILIKE search in bot_knowledge  (permanent KB articles)
   b. ILIKE search in bot_session_page  (passively captured pages)
        │
        ▼
5. Intent detection (pattern match) → if matched, call org API/DB for live data
        │
        ▼
6. Build system prompt
   = persona (name, tone, style rules)
   + anti-hallucination rule (conditional on strictMode)
   + KB context (step 4a)
   + session page context (step 4b)
   + live action data (step 5)  ← highest priority
   + per-request context (from SDK)
        │
        ▼
7. FluxChat AI call
        │
        ▼
8. Return { reply, conversationId }   ← conversationId is "" if stateless

// Flutter — call when a new screen loads
@override
void initState() {
  super.initState();
  FluxChat.capturePage(
    url: 'app://my-app/${widget.routeName}',
    title: widget.title,
    content: extractVisibleText(),   // serialize the screen's visible text
  );
}

// React Native — call on screen focus
useEffect(() => {
  fluxchat.capturePage({
    url: `app://my-app/${route.name}`,
    title: route.params?.title ?? route.name,
    content: extractScreenText(),
  });
}, [route]);

Priority order when building the context string:
1. window.fluxchatContext (or platform equivalent) — user, org, any runtime data
2. data-fluxchat="…" attributes on DOM / screen elements
3. Screen title + current URL / route
4. Visible text from the main content area (first message only, max 3000 chars)

Rules:
- Set persistent data (user, org) once at app root, not per screen
- Always MERGE page-specific data — never overwrite the full object
- Clean up page-specific keys on screen unmount
- DOM / screen scraping only on first message — subsequent messages use context only

git clone https://github.com/benflux-company/fluxchat-sdk
cd fluxchat-sdk && npm install
npm run build   # tsup → ESM + CJS + types + CLI + IIFE widget
npm test        # vitest
npm run typecheck

src/
├── index.ts            # main SDK entry (FluxChatClient, errors)
├── client.ts           # HTTP client
├── knowledge.ts        # KB CRUD
├── config.ts           # persona config
├── cli/
│   └── index.ts        # CLI commands (ask, test, kb, config)
└── widget/
    ├── widget.ts        # embeddable widget — DOM, SPA capture, autocorrect
    ├── types.ts         # WidgetOptions, WidgetInstance interfaces
    └── styles.ts        # CSS-in-JS widget styles