icq-bot-node-node

<h1>icq-bot-node</h1> <blockquote>Node.js module for creating bots with ICQ New BotAPI</blockquote> <ul> <li><a href='#installation'>Installation</a></li> <li> <a href='#life'>Life</a> <ul> <li><a href='#creating'>Creating</a></li> <li><a href='#methods-and-properties'>Methods and properties</a></li> </ul> </li> <li> <a href='#waiting'>Waiting</a> <ul> <li><a href='#creating1'>Creating</a></li> <li><a href='#methods-and-properties-1'>Methods and properties</a></li> </ul> </li> <li><a href='#action'>Action</a></li> <li><a href='#conclusion'>Conclusion</a></li> </ul> So, recommend you to see <a href='https://icq.com/botapi'>ICQ New BotAPI documentation</a> before working with this module. There you'll see facilities of API, which realized here. Any additional features didn't add intend... <h2>Installation</h2> <pre><code>npm i icq-bot-node</code></pre> Some dependecies will be installed with icq-bot-node. Mainly, node-fetch and form-data for queries <h2>Life</h2> <h3>Creating</h3> Bot object is ICQLife class here <pre> <code> const {ICQLife} = require('icq-bot-node'); const TOKEN = '000.000000000.000000000:00000000'; //dont't forget about bot token, which you must get from ICQ New special service // const bot = new ICQLife(TOKEN); </code> </pre> ICQLife constructor gets only one argument - secret bot token. At once it run checking - you'l see in console this yellow-font message: <pre><code>Checking and finding information about this bot (/there will be token/)...</code></pre> If checking will be succesfull, console write green-font (what is surprisingly, german) message. Else, it wil be red-font message with error description, like: <pre><code>Bot checking error: Error response from ICQ. Description: invalid token. Token: (/there will be your invalid token/)</code></pre> Checking is asynchronously, so you can use two event-prototypes of ICQLife class: onCheckSuccess and onCheckFail: <pre> <code> const {ICQLife} = require('icq-bot-node'); const TOKEN = '000.000000000.000000000:00000000'; // const bot = new ICQLife(TOKEN); bot.onCheckSuccess = (bot) => { console.log(bot.me); //you'll know about property me further }; bot.onCheckFail = (bot) => { console.log(bot.me); }; </code> </pre> <blockquote>You can create several ICQLife with one token. They will be work in parallel</blockquote> <h3>Methods and properties</h3> ICQLife class give this properties and methods: <pre> <code> (ICQLife).token //bot secret token (only for reading; string) (ICQLife).me //bot information (only for reading; form after checking; object). You can see object, which stores in this property in <a href='https://icq.com/botapi/#/self/get_self_get'>there</a> (ICQLife).store //special user store (writable, defaultly - empty; object) (ICQLife).waitings //binded waitings (you'll know about ICQWaiting in appropriate section) (only for reading, defaultly - empty; array) (ICQLife).listen() //run event-listening of bot. It's asynchronously function and exist special ICQLife event onlisten (ICQLife).stopListen() //pause event-listening of bot. It's asynchronously function and exist special ICQLife event onStopListen (ICQLife).bindWaitings(/waitings array/) //bind one or more ICQWaiting classes to bot (you'll know about ICQWaiting in appropriate section). It's synchronously function, returned object with property waitingsLength, contained number of binded waitings (ICQLife).unbindWaitings(/waiting index or nothing/) //unbind one or all ICQWaiting classes out of bot. Unbind all binded waitings on calling without argument. It's synchronously function, returned object with property waitingsLength, contained number of binded waitings </code> </pre> <blockquote>Every function of this module returns object. If it isn't any information for returning, function can return empty object. If error happends, function necessarily return object with property error. Also red-font message with error description is written in console.</blockquote> <pre> <code> const result = bot.bindWaitings(waiting1, waiting2); //there is error - waiting isn't combined in array if (result.hasOwnProperty('error')) { console.log('Erorr'); } else bot.listen(); </code> </pre> <h2>Waiting</h2> <h3>Creating</h3> Bot begins listening for events with listen(). But work with gotten events ICQWaiting class <pre> <code> const {ICQLife, ICQWaiting} = require('icq-bot-node'); const TOKEN = '000.000000000.000000000:00000000'; // const waiting = new ICQWaiting('newMessage'); const bot = new ICQLife(TOKEN); bot.onCheckSuccess = (bot) => { bot.bindWaitings([waiting]); bot.listen(); }; </code> </pre> ICQWaiting constructor get one argument - waiting type. It matches event types in ICQ New BotAPI documentation (<a href='https://icq.com/botapi/#/events/get_events_get'>there</a>). Here is a list of this types: <pre> <code> 'newMessage' 'pinnedMessage' 'unpinnedMessage' 'newChatMembers' 'leftChatMembers' 'callbackQuery' </code> </pre> After binding with bot waitings are available in ICQLife property array waitings by index, given in order of binding: <pre> <code> const waiting1 = new ICQWaiting('newMessage'); const waiting2 = new ICQWaiting('editedMessage'); const waiting3 = new ICQWaiting('deletedMessage'); // let checking = bot.bindWaitings([waiting1, waiting2, waiting3]); if (!checking.hasOwnProperty('error')) { console.log(bot.waitings[0].type); //'newMessage' console.log(bot.waitings[1].type); //'editedMessage' console.log(bot.waitings[2].type); //'deletedMessage' }; </code> </pre> <h3>Methods and properties</h3> ICQWaiting class give this properties and methods: <pre> <code> (ICQWaiting).type //type of waiting (only for reading; string) (ICQWaiting).myBot //bot information (only for reading; form after binding waiting with any ICQLife; object). You can see object, which stores in this property <a href='https://icq.com/botapi/#/self/get_self_get'>there</a> (ICQWaiting).actions //binded actions (you'll know about ICQAction in appropriate section) (only for reading, defaultly - empty; array) (ICQWaiting).conditions //special conditions, which waiting uses for detecting right event source. It is object, consisted of three writable and defaultly empty array properties: chats (you can push id of chats, then this waiting will be ignore all events, gotten from other chats) ignoreChats (you can push id of chats, then this waiting will be ignore all events, gotten from this chats) typeChats (you can push type of chats, then this waiting will be ignore all events, gotten from chats of other type. There are three chat types: private, group and channel) When all properties of conditions empty, waiting react to all gotten events (ICQWaiting).stop() //pause waiting. It won't react to gotten events after this method calling (ICQWaiting).run() //run waiting, which was paused (ICQWaiting).bindActions(/actions array/) //bind one or more ICQAction classes to waiting (you'll know about ICQAction in appropriate section). It's synchronously function, returned object with property actionsLength, contained number of binded actions (ICQWaiting).unbindActions(/action index or nothing/) //unbind one or more ICQAction classes out of waiting (you'll know about ICQAction in appropriate section). Unbind all binded actions on calling without argument. It's synchronously function, returned object with property actionsLength, contained number of binded actions </code> </pre> <blockquote>After binding to ICQLife waiting copies in ICQLife property waitings and stores by his index there. If you change original ICQWaiting class it isn't affect on binded copy. Also changings of binded waitings are ignored by original ICQWaiting</blockquote> <pre> <code> const waiting = new ICQWaiting('pinMessage'); waiting.conditions.typeChats.push('private'); // const bot = new ICQLife(TOKEN); bot.onCheckSuccess = () => { bot.bindWaitings([waiting]); bot.waitings[0].conditions.typeChats = []; console.log(bot.waitings[0].conditions.typeChats); //[] console.log(waiting.conditions.typeChats); //['private'] // waitings.conditions.typeChats.push('channel'); console.log(bot.waitings[0].conditions.typeChats); //[] console.log(waiting.conditions.typeChats); //['private', 'channel'] }; </code> </pre> But waitings only wait for event getting and filter their. It is useless without binded actions <h2>Action</h2> Bot answers events with special actions. There are two types of it: user and built-in. User actions are simple desired asynchronous functions, binded with ICQWaiting. Built-in actions are calling of special method of ICQAction object <pre> <code> const {ICQLife, ICQWaiting, ICQAction} = require('icq-bot-node'); const TOKEN = '000.000000000.000000000:00000000'; // const action1 = async (bot, token, event, interResult) => { //this is user action ICQAction.act({ //this is built-in action actionType: 'sendText', text: 'Hello, world!', chatId: 'artem' }, token); let chance = Math.round(Math.random()); if (chance === 0) { return false; } else return true; }; const action2 = async (bot, token, event, interResult) => { //this is user action if (!interResult) { ICQAction.act({ //this is built-in action actionType: 'sendText', text: 'Unluck! I dont wont talk with you now...', chatId: 'artem' }, token); bot.waitings[0].conditions.chatsId = []; bot.waitings[0].conditions.ignoreChats.push('artem'); }; ICQAction.act({ //this is built-in action actionType: 'sendText', text: 'Luck! But you really play with fire...', chatId: 'artem' }, token); }; // const waiting = new ICQWaiting('newMessage'); waiting.conditions.chatsId.push('artem'); waiting.bindActions([action1, action2]); // const bot = new ICQLife(TOKEN); bot.onCheckSuccess = (bot) => { bot.bindWaitings([waiting]); bot.listen(); }; </code> </pre> <blockquote>User action get four arguments:</blockquote> first argument is ICQLife class second argument is token of this bot third argument is object with information about gotten event. You can see examples of object, which you can meet in this argument <a href='https://icq.com/botapi/#/events/get_events_get'>there</a> four argument is returned data of last done user action <blockquote>Built-in action activates with method act(), which has two arguments: object with type of action and data for action (you can see <a href='https://icq.com/botapi'>ICQ New BotAPI documentation</a> and know about properties need for action query) and token. There is a list of action types:</blockquote> <pre> <code> 'sendText' 'sendFile' 'sendVoice' 'editText' 'deleteMessages' 'sendActions' 'getChatInfo' //name of this type differs from original - you can find information about it in documentation section '/chats/getInfo' 'getFileInfo' //name of this type differs from original - you can find information about it in documentation section '/files/getInfo' 'getAdmins' 'getMembers' 'getBlockedUsers' 'getPendingUsers' 'blockUser' 'unclockUser' 'resolvePending' 'setTitle' 'setAbout' 'setRules' 'pinMessage' 'unpinMessage' 'answerCallbackQuery' </code> </pre> Set of properties, need for actions, equals to documentation, except sendFile and sendVoice. You can send uploaded file and write property 'fileId' or upload new file and send it. In second case you must write two properties instead of 'chatId': 'location' (local path to file) and 'fileName' (necessarilly with format) <blockquote>ICQAction.act() returns object, described in <a href='https://icq.com/botapi'>ICQ New BotAPI documentation</a></blockquote> <h2>Conclusion</h2> I know, I could explain badly for public. You can write questions here, in <a href='https://github.com/artomich/icq-bot-node/issues'>issues</a> or send it to me: <a href='mailto:artomich.work.1@gmail.com'>artomich.work.1@gmail.com</a>