botql 1.0.0 → 1.0.1

package/Bootstrap.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Bootstrap.js — ponto de entrada do BotQL.
+ *
+ * Lê um ficheiro .sql (com suporte a IMPORT), cria o interpreter, liga os
+ * connectors reais das plataformas usadas via CONNECT, corre ON START e
+ * fica pronto a receber mensagens.
+ *
+ * Uso:
+ *   node Bootstrap.js caminho/para/bot.sql
+ *
+ * Uso programático:
+ *   const { bootstrap } = require('./Bootstrap.js');
+ *   const bot = await bootstrap('bot.sql');
+ *   await bot.receiveMessage('+244900000000', 'quero comprar');
+ */
+
+const path = require('path');
+const { BotQLInterpreter } = require('./botql.js');
+const { ConnectorRegistry, attachConnectors } = require('./Connectors.js');
+const { SQLiteDatabase } = require('./Database.js');
+
+/**
+ * @param {string} sqlFilePath Caminho do ficheiro .sql principal do bot.
+ * @param {object} options
+ * @param {string} [options.dbPath] Caminho do ficheiro .sqlite. Sem isto,
+ *   usa MemoryDatabase (sem persistência), que é o omisso do interpreter.
+ * @param {string} [options.connectorsPath] Caminho alternativo para o JSON
+ *   de connectors. Por omissão usa o Connectors.json ao lado deste ficheiro.
+ * @param {boolean} [options.autoStart] Corre ON START automaticamente (omissão: true).
+ */
+async function bootstrap(sqlFilePath, options = {}) {
+    const interpreterOptions = {};
+    if (options.dbPath) {
+        interpreterOptions.db = new SQLiteDatabase(options.dbPath);
+    }
+
+    const bot = BotQLInterpreter.fromFile(sqlFilePath, interpreterOptions);
+
+    const registry = new ConnectorRegistry(
+        options.connectorsPath || path.join(__dirname, 'Connectors.json')
+    );
+    attachConnectors(bot, registry);
+
+    if (options.autoStart !== false) {
+        await bot.start();
+    }
+
+    return bot;
+}
+
+// Execução direta: node Bootstrap.js caminho/bot.sql
+if (require.main === module) {
+    const sqlFilePath = process.argv[2];
+    if (!sqlFilePath) {
+        console.error('Uso: node Bootstrap.js caminho/para/bot.sql');
+        process.exit(1);
+    }
+
+    bootstrap(sqlFilePath)
+        .then((bot) => {
+            console.log(`BotQL: bot "${bot.botName || '(sem nome)'}" iniciado.`);
+            if (!bot.running) {
+                console.log('Aviso: o ficheiro não tem "RUN BOT" — o bot foi carregado mas não marcado como em execução.');
+            }
+        })
+        .catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
+}
+
+module.exports = { bootstrap };

package/Connectors.json

@@ -0,0 +1,17 @@
+{
+    "TELEGRAM": "./connectors/telegram.js",
+    "WHATSAPP": "./connectors/whatsapp.js",
+    "DISCORD": "./connectors/discord.js",
+    "SLACK": "./connectors/slack.js",
+    "MESSENGER": "./connectors/messenger.js",
+    "INSTAGRAM": "./connectors/instagram.js",
+    "TWITTER": "./connectors/twitter.js",
+    "SMS": "./connectors/sms.js",
+    "EMAIL": "./connectors/email.js",
+    "WEBHOOK": "./connectors/webhook.js",
+    "VIBER": "./connectors/viber.js",
+    "LINE": "./connectors/line.js",
+    "WECHAT": "./connectors/wechat.js",
+    "MATRIX": "./connectors/matrix.js",
+    "GOOGLECHAT": "./connectors/googlechat.js"
+}

package/botql-mode.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * Modo BotQL para CodeMirror 5 (addon/mode/simple.js).
+ *
+ * Usa exatamente a mesma lista de keywords do Parser.js (KEYWORDS),
+ * para nunca desalinhar highlight vs. sintaxe real aceite pelo parser.
+ *
+ * Uso (depois de incluir codemirror.js, mode/sql/sql.js NÃO é necessário,
+ * e addon/mode/simple.js):
+ *
+ *   <script src="codemirror.js"></script>
+ *   <script src="addon/mode/simple.js"></script>
+ *   <script src="botql-mode.js"></script>
+ *
+ *   const editor = CodeMirror(document.body, {
+ *       mode: "botql",
+ *       theme: "default"
+ *   });
+ */
+
+// Mesma lista do Parser.js — SQL real (CREATE, INSERT, UPDATE, ...)
+// e BotQL (ON, WHEN, REPLY, ...) juntas, porque highlight não separa
+// os dois mundos: é uma linguagem só.
+const BOTQL_KEYWORDS = [
+    'CREATE', 'BOT', 'PLATFORM', 'CONNECT', 'TABLE', 'PREVENT', 'DEFAULT',
+    'ON', 'START', 'MESSAGE', 'FROM',
+    'WHEN', 'CONTAINS', 'OR', 'OTHERWISE',
+    'REPLY', 'TO', 'FORWARD', 'PARSE', 'SEND',
+    'INSERT', 'INTO', 'VALUES', 'UPDATE', 'SET', 'WHERE',
+    'IMPORT', 'RUN'
+];
+
+// Palavras especiais que merecem cor própria por serem "mágicas"
+// no interpreter (botql.js), não por serem sintaxe da gramática.
+const BOTQL_BUILTINS = ['Context', 'NOW', 'LAST_INSERT_ID'];
+
+// Variáveis implícitas do runtime (client, message, lastMsg, SIGNAL).
+const BOTQL_VARS = ['client', 'message', 'lastMsg', 'SIGNAL'];
+
+function defineBotQLMode(CodeMirror) {
+    const keywordRegex = new RegExp('^(?:' + BOTQL_KEYWORDS.join('|') + ')\\b');
+    const builtinRegex = new RegExp('^(?:' + BOTQL_BUILTINS.join('|') + ')\\b');
+    const varRegex = new RegExp('^(?:' + BOTQL_VARS.join('|') + ')\\b');
+
+    CodeMirror.defineSimpleMode('botql', {
+        start: [
+            { regex: /--.*/, token: 'comment' },
+            { regex: /"(?:[^"\\]|\\.)*"?/, token: 'string' },
+            { regex: /'(?:[^'\\]|\\.)*'?/, token: 'string' },
+            { regex: /\b\d+(?:\.\d+)?\b/, token: 'number' },
+            { regex: keywordRegex, token: 'keyword' },
+            { regex: builtinRegex, token: 'builtin' },
+            { regex: varRegex, token: 'variable-2' },
+            { regex: /[A-Za-z_]\w*(?=\s*\()/, token: 'variable-2' }, // chamadas: NOME(
+            { regex: /[{}]/, token: 'bracket' },
+            { regex: /[()]/, token: 'bracket' },
+            { regex: /[+=,.]/, token: 'operator' },
+            { regex: /[A-Za-z_]\w*/, token: 'variable' }
+        ],
+        meta: {
+            lineComment: '--'
+        }
+    });
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { defineBotQLMode, BOTQL_KEYWORDS, BOTQL_BUILTINS, BOTQL_VARS };
+}
+if (typeof window !== 'undefined' && window.CodeMirror) {
+    defineBotQLMode(window.CodeMirror);
+}

package/connectors/_shared.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * _shared.js — utilidades comuns aos connectors reais.
+ *
+ * A credencial de um CONNECT em BotQL é sempre uma única string
+ * (CONNECT SERVICO TIPO "credencial"). Quando a plataforma precisa de mais
+ * do que um valor (ex: WhatsApp precisa de token + phone_number_id),
+ * a credencial deve ser escrita como uma string JSON:
+ *
+ *   CONNECT WHATSAPP CLOUD_API "{\"token\":\"...\",\"phoneNumberId\":\"...\"}"
+ *
+ * parseCredential() trata os dois casos: JSON válido vira objeto,
+ * qualquer outra coisa fica disponível em { token: credential }.
+ */
+function parseCredential(credential) {
+    if (typeof credential !== 'string') return credential || {};
+    try {
+        const parsed = JSON.parse(credential);
+        if (parsed && typeof parsed === 'object') return parsed;
+        return { token: credential };
+    } catch {
+        return { token: credential };
+    }
+}
+
+// Wrapper fino sobre fetch: lança erro com o corpo da resposta quando o
+// pedido falha, para os erros aparecerem claros nos logs do bot.
+async function httpJson(url, options = {}) {
+    const res = await fetch(url, options);
+    const raw = await res.text();
+    let body;
+    try { body = raw ? JSON.parse(raw) : null; } catch { body = raw; }
+
+    if (!res.ok) {
+        const detail = typeof body === 'string' ? body : JSON.stringify(body);
+        throw new Error(`BotQL connector: pedido HTTP falhou (${res.status}): ${detail}`);
+    }
+    return body;
+}
+
+module.exports = { parseCredential, httpJson };

package/connectors/discord.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Discord — envia mensagem a um canal usando um bot token.
+ * CONNECT DISCORD BOT "bot-token-do-discord"
+ * O "target" em REPLY/FORWARD/SEND deve ser o ID do canal.
+ */
+module.exports = function discordConnector(credential) {
+    const { token } = parseCredential(credential);
+
+    return {
+        async send(channelId, text) {
+            return httpJson(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bot ${token}`
+                },
+                body: JSON.stringify({ content: text })
+            });
+        }
+    };
+};

package/connectors/email.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Email via SendGrid (sem dependências externas, só a API HTTP).
+ * CONNECT EMAIL SENDGRID "{\"apiKey\":\"...\",\"from\":\"bot@dominio.com\"}"
+ * O "target" deve ser o endereço de email destinatário.
+ */
+module.exports = function emailConnector(credential) {
+    const { apiKey, from } = parseCredential(credential);
+
+    return {
+        async send(to, text) {
+            return httpJson('https://api.sendgrid.com/v3/mail/send', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`
+                },
+                body: JSON.stringify({
+                    personalizations: [{ to: [{ email: to }] }],
+                    from: { email: from },
+                    subject: 'Mensagem do bot',
+                    content: [{ type: 'text/plain', value: text }]
+                })
+            });
+        }
+    };
+};

package/connectors/googlechat.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Google Chat — webhook de um espaço (Space). Não precisa de OAuth quando se
+ * usa o webhook do próprio espaço.
+ * CONNECT GOOGLECHAT WEBHOOK "https://chat.googleapis.com/v1/spaces/.../messages?key=...&token=..."
+ * O "target" é ignorado (o webhook já aponta a um espaço fixo).
+ */
+module.exports = function googleChatConnector(credential) {
+    const { token: url } = parseCredential(credential); // credencial simples = URL do webhook
+
+    return {
+        async send(_target, text) {
+            return httpJson(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ text })
+            });
+        }
+    };
+};

package/connectors/instagram.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Instagram Messaging API (conta profissional ligada a uma Página, via Graph API).
+ * CONNECT INSTAGRAM PAGE "{\"token\":\"...\",\"igUserId\":\"...\"}"
+ * O "target" deve ser o IGSID (Instagram-scoped id) do utilizador.
+ */
+module.exports = function instagramConnector(credential) {
+    const { token, igUserId } = parseCredential(credential);
+    const url = `https://graph.facebook.com/v20.0/${igUserId}/messages?access_token=${encodeURIComponent(token)}`;
+
+    return {
+        async send(igsid, text) {
+            return httpJson(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    recipient: { id: igsid },
+                    message: { text }
+                })
+            });
+        }
+    };
+};

package/connectors/line.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * LINE Messaging API.
+ * CONNECT LINE BOT "channel-access-token-do-line"
+ * O "target" deve ser o userId do LINE.
+ */
+module.exports = function lineConnector(credential) {
+    const { token } = parseCredential(credential);
+
+    return {
+        async send(userId, text) {
+            return httpJson('https://api.line.me/v2/bot/message/push', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`
+                },
+                body: JSON.stringify({
+                    to: userId,
+                    messages: [{ type: 'text', text }]
+                })
+            });
+        }
+    };
+};

package/connectors/matrix.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Matrix — envia mensagens de texto a uma sala usando um access token de bot.
+ * CONNECT MATRIX BOT "{\"homeserver\":\"https://matrix.org\",\"accessToken\":\"...\"}"
+ * O "target" deve ser o room ID (ex: "!sala:matrix.org").
+ */
+module.exports = function matrixConnector(credential) {
+    const { homeserver, accessToken } = parseCredential(credential);
+
+    return {
+        async send(roomId, text) {
+            const txnId = Date.now();
+            const url = `${homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/m.room.message/${txnId}`;
+            return httpJson(url, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${accessToken}`
+                },
+                body: JSON.stringify({ msgtype: 'm.text', body: text })
+            });
+        }
+    };
+};

package/connectors/messenger.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Facebook Messenger Send API.
+ * CONNECT MESSENGER PAGE "token-de-acesso-da-pagina"
+ * O "target" deve ser o PSID (page-scoped id) do utilizador.
+ */
+module.exports = function messengerConnector(credential) {
+    const { token } = parseCredential(credential);
+    const url = `https://graph.facebook.com/v20.0/me/messages?access_token=${encodeURIComponent(token)}`;
+
+    return {
+        async send(psid, text) {
+            return httpJson(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    recipient: { id: psid },
+                    message: { text }
+                })
+            });
+        }
+    };
+};

package/connectors/slack.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Slack Web API.
+ * CONNECT SLACK BOT "xoxb-token-do-bot"
+ * O "target" deve ser o ID do canal ou utilizador (ex: "C0123456").
+ */
+module.exports = function slackConnector(credential) {
+    const { token } = parseCredential(credential);
+
+    return {
+        async send(channel, text) {
+            return httpJson('https://slack.com/api/chat.postMessage', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`
+                },
+                body: JSON.stringify({ channel, text })
+            });
+        }
+    };
+};

package/connectors/sms.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * SMS via Twilio.
+ * CONNECT SMS TWILIO "{\"accountSid\":\"...\",\"authToken\":\"...\",\"from\":\"+244...\"}"
+ * O "target" deve ser o número de telefone destinatário, em formato E.164.
+ */
+module.exports = function smsConnector(credential) {
+    const { accountSid, authToken, from } = parseCredential(credential);
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`;
+    const auth = Buffer.from(`${accountSid}:${authToken}`).toString('base64');
+
+    return {
+        async send(to, text) {
+            const body = new URLSearchParams({ From: from, To: to, Body: text });
+            return httpJson(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Basic ${auth}`
+                },
+                body: body.toString()
+            });
+        }
+    };
+};

package/connectors/telegram.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Telegram Bot API.
+ * CONNECT TELEGRAM BOT "123456:ABC-token-do-bot"
+ */
+module.exports = function telegramConnector(credential) {
+    const { token } = parseCredential(credential);
+    const base = `https://api.telegram.org/bot${token}`;
+
+    return {
+        async send(chatId, text) {
+            return httpJson(`${base}/sendMessage`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ chat_id: chatId, text })
+            });
+        }
+    };
+};

package/connectors/twitter.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Twitter/X API v2 — Direct Messages.
+ * CONNECT TWITTER BEARER "bearer-token-com-permissao-dm"
+ * O "target" deve ser o ID numérico do utilizador destinatário.
+ */
+module.exports = function twitterConnector(credential) {
+    const { token } = parseCredential(credential);
+
+    return {
+        async send(userId, text) {
+            return httpJson('https://api.twitter.com/2/dm_conversations/with/' + userId + '/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`
+                },
+                body: JSON.stringify({ text })
+            });
+        }
+    };
+};

package/connectors/viber.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Viber REST API.
+ * CONNECT VIBER BOT "token-da-conta-viber"
+ * O "target" deve ser o "receiver" (id do utilizador Viber).
+ */
+module.exports = function viberConnector(credential) {
+    const { token } = parseCredential(credential);
+
+    return {
+        async send(receiver, text) {
+            return httpJson('https://chatapi.viber.com/pa/send_message', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Viber-Auth-Token': token
+                },
+                body: JSON.stringify({
+                    receiver,
+                    type: 'text',
+                    text
+                })
+            });
+        }
+    };
+};

package/connectors/webhook.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * Webhook genérico: entrega a mensagem a qualquer endpoint HTTP próprio.
+ * CONNECT WEBHOOK POST "https://meu-servidor.com/receber"
+ * ou, com autenticação:
+ * CONNECT WEBHOOK POST "{\"url\":\"https://...\",\"secret\":\"...\"}"
+ * O "target" é incluído no corpo do pedido, para o servidor decidir o destino.
+ */
+module.exports = function webhookConnector(credential) {
+    const parsed = parseCredential(credential);
+    const url = parsed.url || parsed.token; // token guarda a URL quando é string simples
+    const secret = parsed.secret;
+
+    return {
+        async send(target, text) {
+            const headers = { 'Content-Type': 'application/json' };
+            if (secret) headers['X-BotQL-Secret'] = secret;
+
+            return httpJson(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ target, text })
+            });
+        }
+    };
+};

package/connectors/wechat.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * WeChat (conta de serviço/oficial) — API de mensagens customer service.
+ * CONNECT WECHAT OFFICIAL "{\"accessToken\":\"...\"}"
+ * O "target" deve ser o OpenID do utilizador WeChat.
+ *
+ * Nota: o accessToken da WeChat expira periodicamente e normalmente exige
+ * um passo prévio de refresh (appId + appSecret -> token). Este connector
+ * assume que esse refresh já foi feito fora do bot e que recebe um token válido.
+ */
+module.exports = function wechatConnector(credential) {
+    const { accessToken } = parseCredential(credential);
+    const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${encodeURIComponent(accessToken)}`;
+
+    return {
+        async send(openId, text) {
+            return httpJson(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    touser: openId,
+                    msgtype: 'text',
+                    text: { content: text }
+                })
+            });
+        }
+    };
+};

package/connectors/whatsapp.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const { parseCredential, httpJson } = require('./_shared.js');
+
+/**
+ * WhatsApp Cloud API (Meta).
+ * CONNECT WHATSAPP CLOUD_API "{\"token\":\"...\",\"phoneNumberId\":\"...\"}"
+ */
+module.exports = function whatsappConnector(credential) {
+    const { token, phoneNumberId, apiVersion } = parseCredential(credential);
+    const version = apiVersion || 'v20.0';
+    const base = `https://graph.facebook.com/${version}/${phoneNumberId}`;
+
+    return {
+        async send(to, text) {
+            return httpJson(`${base}/messages`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`
+                },
+                body: JSON.stringify({
+                    messaging_product: 'whatsapp',
+                    to,
+                    type: 'text',
+                    text: { body: text }
+                })
+            });
+        }
+    };
+};

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "botql",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "BotQL is a simple, SQL-inspired rules language for creating bots without writing traditional code.",
   "main": "botql.js",
+  "browser": "botql.browser.js",
   "files": [
     "botql.js",
+    "botql.browser.js",
+    "botql-mode.js",
+    "Bootstrap.js",
     "Parser.js",
     "Database.js",
     "RAG.js",
     "FileSystem.js",
     "Connectors.js",
+    "Connectors.json",
+    "connectors/",
     "README.md",
     "LICENSE"
   ],
@@ -31,4 +37,4 @@
     "url": "https://github.com/adilson889/botql/issues"
   },
   "homepage": "https://github.com/adilson889/botql#readme"
-}
+}