alerts-api — API wrapper for Donation Alerts written in NodeJS with promises support
![npm](https://img.shields.io/npm/dw/alerts-api)
There was no library so I did it myself. Fuck Mail.ru and their developers.
Feature matrix:
✅ Latest donations with pagination
✅ Retreiving user profile information
✅ Recursive searching through donations messages
✅ Custom alerts (reusable)
✅ Refreshing tokens
✅ Access token generation
✅ OAuth link generation
❌ Merchandise API
❌ Centrifugo & Polls updates
Installation
$ npm i alerts-api
OR
$ yarn add alerts-api
Usage
const AlertsAPI = require('alerts-api')
import AlertsAPI from 'alerts-api'
const donationAlerts = new AlertsAPI({ access_token: '' })
async function getUserPictureURL() {
let user = await donationAlerts.getUser()
console.log(user.avatar)
}
getUserPictureURL()
API reference
Constructor config object
Constructor accepts exactly 1 argument: config object
{
access_token: 'def502...e8d',
version: 1
}
All methods
-
STATIC ASYNC generateOauthLink(config)
-
STATIC ASYNC getAccessToken(config)
- Exchanges authorization code on access token needed for every API request
- Method accepts exactly 1 argument: config object
- Config object example:
-
{
clientID: 690,
clientSecret: '7N...RDY',
redirectURI: 'https://example.com/',
code: 'def502...e8d',
}
- Returned object example:
-
{
token_type: 'Bearer',
expires_in: 61235,
access_token: 'RDY...7N',
refreshToken: 'd50...bc'
}
-
ASYNC refreshToken(config)
- Refreshes access token to prevent expiring by exchanging refresh_token
- Method accepts exactly 1 argument: config object
- DO NOT CHANGE SCOPES! USE EXACTLY THE SAME SCOPES YOU USED FOR OBTAINING AUTHORZATION CODE!!!
- Config object example:
-
{
clientID: 690,
clientSecret: 'd50...bc',
refreshToken: 'https://example.com/',
scopes: ['oauth-user-show'],
}
- Returned object example:
-
{
token_type: 'Bearer',
expires_in: 61235,
access_token: 'RDY...7N',
refreshToken: 'd50...bc'
}
-
ASYNC getUser()
- Method returns user information (endpoint: https://www.donationalerts.com/api/vXXX/user/oauth)
- Returned object example:
-
{
data: {
id: 918237,
code: 'vityaschel',
name: 'VityaSchel',
avatar: 'https://static-cdn.jtvnw.net/user-default-pictures-uv/41780b5a-def8-11e9-94d9-784f43822e80-profile_image-300x300.png',
email: 'vityaschel@utidteam.com',
language: 'en_US',
socket_connection_token: 'sfysjdhgaskduqhtwldiqdguaskdajsd'
}
}
-
ASYNC getDonations(page, raw)
- Method returns latest donations (endpoint: https://www.donationalerts.com/api/v1/alerts/donations)
- page is optional; defaults to 1; must be a number;
- raw is optional; defaults to false; must be a boolean;
- use raw = true if you want to get raw response from donation alerts api
- returns an object; below is an example of it
- data will always be array
- use .next() and .prev() functions to fetch new pages (use with await/.then)
- if there is no next/previous page, no function will be in response
- Returned object example:
-
{
data: [
id: 123456,
name: 'donation',
username: 'user name',
recipient_name: 'your name',
message: 'most valuable in donations',
message_type: 'text',
payin_system: { title: 'Bank card RUB' },
amount: 24,
currency: 'RUB',
is_shown: 1,
amount_in_user_currency: 24,
created_at: '2019-01-17 17:17:09',
shown_at: null
],
page: 1
next: Function,
prev: Function
}
-
ASYNC searchWithinMessage(term, pageLimit, caseSensetive)
- Method searching through every donation and returns the ones with term included() in message field
- pageLimit is optional; defaults to 0 (no limit)
- caseSensetive is optional; defaults to true!!
- Returned object example:
-
[
id: 123456,
name: 'donation',
username: 'donator`s name',
recipient_name: 'your name',
message: 'most valuable in donations',
message_type: 'text',
payin_system: { title: 'Bank card RUB' },
amount: 24,
currency: 'RUB',
is_shown: 1,
amount_in_user_currency: 24,
created_at: '2019-01-17 17:17:09',
shown_at: null
]
-
ASYNC sendCustomAlert(alert)
-
class CustomAlert inside AlertsAPI class
- Use it for sendCustomAlert method (see above)
- Constructor accepts exactly 1 argument: object
- external_id is generated automatically from 0 up to Number.MAX_SAFE_INTEGER
-
{
header: 'Text',
message: 'Text',
is_shown: 1,
image_url: 'https://example.com/image.png',
sound_url: 'https://example.com/sound.mp3'
}
- Example of creation instance:
-
let myAlert = new AlertsAPI.CustomAlert({ header: 'My Alert', message: 'Hello world!' })
More examples
Contribution
Please maintain this repository please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please please 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏 🙏
PRs are welcome, email me (vityaschel@utidteam.com) if you want to maintain this repository.