botql 1.0.2 → 1.2.2

package/README.md

@@ -1,23 +1,194 @@
-# BotQL — Bot Query Language
+<h1 align="center">
+    <span style="background: linear-gradient(90deg, #6C5CE7, #00B894); -webkit-background-clip: text; -webkit-text-fill-color: transparent; font-weight: 900; font-size: 2.2em;">
+        BotQL: Bot Query Language
+    </span>
+</h1>
 
-[![npm version](https://img.shields.io/npm/v/botql.svg)](https://www.npmjs.com/package/botql)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/adilson889/botql/pulls)
-[![BotQL](https://img.shields.io/badge/BotQL-rules%20language-blue.svg)](https://github.com/adilson889/botql)
+<p align="center">
+    <a href="https://www.npmjs.com/package/botql">
+        <img src="https://img.shields.io/npm/v/botql.svg" alt="npm version">
+    </a>
+    <a href="https://opensource.org/licenses/MIT">
+        <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+    </a>
+    <a href="https://github.com/adilson889/botql/pulls">
+        <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
+    </a>
+    <a href="https://github.com/adilson889/botql">
+        <img src="https://img.shields.io/badge/BotQL-rules%20language-blue.svg" alt="BotQL">
+    </a>
+    <a href="https://github.com/sponsors/adilson889">
+        <img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-red.svg" alt="Sponsor">
+    </a>
+</p>
 
-**BotQL** é uma linguagem de regras simples, inspirada em SQL, para criar bots sem precisar de escrever código tradicional. Todos os comandos são escritos em **MAIÚSCULAS**, e blocos com mais de uma ação usam chaves `{ }`.
+<p align="justify">
+    <strong>BotQL</strong> is a simple, SQL-inspired rules language for creating bots without writing traditional code. All commands are written in <strong>UPPERCASE</strong>, and blocks with more than one action use curly braces <code>{ }</code>.
+</p>
 
-Vive no mesmo ficheiro `.sql`, com comandos reais de banco de dados — o bot age e persiste dados na mesma linguagem, sem sair do BotQL. O bot corre localmente, no computador ou servidor do próprio utilizador, e não em servidores geridos por terceiros.
+<p align="justify">
+    It lives in <code>.sql</code> files, with real database commands — the bot acts and persists data in the same language, without leaving BotQL. The bot runs locally, on the user's own computer or server, not on third-party managed servers.
+</p>
 
-Não precisas de saber programar para escrever BotQL; precisas apenas de saber o que queres que o teu bot faça.
+<p align="justify">
+    You don't need to know how to code to write BotQL; you just need to know what you want your bot to do.
+</p>
 
 ---
 
-## Documentação Completa
+## Getting Started
 
-Ver **[docs/GETSTARTED.md](docs/GETSTARTED.md)** para o guia completo.
+Want to learn the full syntax, see all commands, and understand how BotQL works? The complete guide walks you through everything from your first bot to advanced features like local knowledge retrieval and AI integration.
 
-## Instalação
+**[Read the full documentation →](docs/GETSTARTED.md)**
+
+---
+
+## Installation
+
+### Node.js
+
+For server-side applications, CLI tools, and any Node.js environment:
 
 ```bash
-npm install botql
+npm install botql
+```
+
+```javascript
+// bot.sql
+CREATE BOT "MyBot"
+ON MESSAGE {
+    WHEN CONTAINS "hello" REPLY "Hi!"
+}
+RUN BOT
+```
+
+```javascript
+const { createBot } = require('botql');
+
+const bot = await createBot('bot.sql');
+await bot.receiveMessage('+244900000000', 'hello');
+```
+
+`createBot(sqlFilePath, options)` is the standard entry point: it loads the `.sql` file, wires up any `CONNECT`-ed platforms, runs `ON START`, and hands you back a bot that's ready to receive messages.
+
+You can also run a bot straight from the command line:
+
+```bash
+node node_modules/botql/createBot.js bot.sql
+```
+
+### Browser (CDN)
+
+For websites, web apps, and in-browser editors — no build step required:
+
+```html
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/botql/botql.browser.js"></script>
+
+<!-- unpkg -->
+<script src="https://unpkg.com/botql/botql.browser.js"></script>
+```
+
+<p align="justify">
+    The browser bundle doesn't include <code>createBot()</code> (it depends on Node's <code>fs</code>/<code>path</code> to read <code>.sql</code> files and connectors). In the browser, use <code>BotQLInterpreter.fromSource(...)</code> directly with the source code as a string, and wire <code>onReply</code>/<code>onThinking</code>/etc yourself — see the JavaScript example below.
+</p>
+
+---
+
+## Usage
+
+### JavaScript — from a file (Node.js)
+
+```javascript
+const { createBot } = require('botql');
+
+const bot = await createBot('bot.sql', {
+    onReply: ({ text, client }) => console.log(client + ':', text),
+});
+
+await bot.receiveMessage('+244900000000', 'hello');
+```
+
+### JavaScript — from a source string (Node.js or browser)
+
+```javascript
+const { BotQLInterpreter } = require('botql');
+
+const bot = BotQLInterpreter.fromSource(`
+CREATE BOT "JSBot"
+ON MESSAGE {
+    WHEN CONTAINS "hello" REPLY "Hello!"
+}
+RUN BOT
+`);
+
+bot.onReply = ({ text }) => console.log(text);
+
+await bot.start();
+await bot.receiveMessage('+244900000000', 'hello');
+```
+
+### JSX (React)
+
+```jsx
+import { BotQLInterpreter } from 'botql';
+
+const bot = BotQLInterpreter.fromSource(`
+CREATE BOT "ReactBot"
+ON MESSAGE {
+    WHEN CONTAINS "hello" REPLY "Hello from React!"
+}
+RUN BOT
+`);
+
+bot.onReply = ({ text }) => console.log(text);
+
+await bot.start();
+```
+
+### TypeScript
+
+```typescript
+import { createBot } from 'botql';
+
+const bot = await createBot('bot.sql', {
+    onReply: ({ text }: { text: string }) => console.log(text),
+});
+
+await bot.receiveMessage('+244900000000', 'hello');
+```
+
+### PHP
+
+```php
+<?php
+$code = 'CREATE BOT "PHPBot" ON MESSAGE { WHEN CONTAINS "hello" REPLY "Hello!" } RUN BOT';
+$response = shell_exec('node -e "' . addslashes($code) . '"');
+echo $response;
+?>
+```
+
+### Python
+
+```python
+import subprocess
+
+code = 'CREATE BOT "PythonBot" ON MESSAGE { WHEN CONTAINS "hello" REPLY "Hello!" } RUN BOT'
+subprocess.run(['node', '-e', code])
+```
+
+---
+
+## Support
+
+If this project helped you, consider supporting:
+
+[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-Donate-pink.svg)](https://github.com/sponsors/adilson889)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg)](https://www.buymeacoffee.com/adilson889)
+
+---
+
+### License
+
+MIT © Adilson C. Rafael

package/Terminal.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+* Terminal.js — feedback visual de "a pensar" para quando o BotQL corre
+* num terminal Node.js puro (ex: bot ligado via Bootstrap.js, sem editor
+* nenhum por perto).
+
+*/
+
+const FRAMES = ['|', '/', '-', '\\'];
+const INTERVALO_MS = 100;
+
+function isNodeRuntime() {
+return typeof process !== 'undefined' && !!process.versions && !!process.versions.node;
+}
+
+function isInteractiveTerminal() {
+return isNodeRuntime() && !!process.stdout && !!process.stdout.isTTY;
+}
+
+/**
+* Liga um spinner de terminal ao onThinking do interpretador, e um
+* fallback de console.log a onReply/onForward/onSend — só para os que
+* ainda não tiverem sido definidos.
+*
+* @param {import('./botql.js').BotQLInterpreter} interpreter
+* @returns {() => void} função para desligar o spinner manualmente, se
+*   for preciso parar antes do bot terminar (raramente necessário).
+*/
+function attachTerminalUI(interpreter) {
+if (!isNodeRuntime()) {
+// Browser/WebView: quem trata da UI é o próprio editor.
+return () => {};
+}
+
+let timer = null;
+let ativo = false;
+
+function pararSpinner() {
+if (!ativo) return;
+ativo = false;
+if (timer) clearInterval(timer);
+if (isInteractiveTerminal()) {
+process.stdout.write('\r\x1b[K'); // limpa a linha do spinner
+}
+}
+
+if (!interpreter.onThinking) {
+interpreter.onThinking = ({ text }) => {
+const rotulo = text ? text + ' ' : '';
+
+if (!isInteractiveTerminal()) {
+// Não interativo (ex: saída redirecionada para ficheiro,
+// ou executado em CI): uma linha só, sem animação.
+console.log(rotulo.trim() || '...');
+return;
+}
+
+ativo = true;
+let frame = 0;
+timer = setInterval(() => {
+process.stdout.write('\r' + rotulo + FRAMES[frame]);
+frame = (frame + 1) % FRAMES.length;
+}, INTERVALO_MS);
+};
+}
+
+// Sem isto o spinner nunca pararia sozinho — onReply/onForward/onSend
+// são os eventos que sinalizam "o THINK/bloco terminou, já há resposta".
+const envolverEPararSpinner = (onEvent) => async (payload) => {
+pararSpinner();
+if (onEvent) await onEvent(payload);
+};
+
+if (!interpreter.onReply) {
+interpreter.onReply = envolverEPararSpinner(({ text }) => console.log(text));
+} else {
+interpreter.onReply = envolverEPararSpinner(interpreter.onReply);
+}
+
+if (!interpreter.onForward) {
+interpreter.onForward = envolverEPararSpinner(({ target }) => console.log(`(encaminhado para ${target})`));
+} else {
+interpreter.onForward = envolverEPararSpinner(interpreter.onForward);
+}
+
+if (!interpreter.onSend) {
+interpreter.onSend = envolverEPararSpinner(({ target, signal }) => console.log(`(enviado para ${target})`, signal));
+} else {
+interpreter.onSend = envolverEPararSpinner(interpreter.onSend);
+}
+
+return pararSpinner;
+}
+
+module.exports = { attachTerminalUI, isInteractiveTerminal, isNodeRuntime };