Neophobe Plebeian Mumpsimus

    proovl

    1.1.0 • Public • Published

    proovl

    The unofficial library for Proovl SMS service which supports all API functionalities including HTTP hooks.

    npm version npm downloads dependencies license paypal

    Features Usage Video Example Getting Started Documentation Examples Credits License

    💬 Questions / Comments? Join our Discord server!

    Features

    • Easy and fast SMS sending via Proovl
    • SMS statuses checking
    • Balance checking
    • HTTP hooks via Express
    • Easy configuration.
    • And everything what Proovl's API offers!

    Usage

    $ npm i proovl --save
    
    const Proovl = require('proovl')
     
    const proovl = new Proovl('ACC_ID', 'ACC_TOKEN')
     
    proovl.balance().then(balance => {
      console.log('Account balance: ' + balance)
    }).catch(error => {
      console.error(error)
    })

    Video Example

    Soon

    Getting Started

    • Install Proovl via NPM, create a new index.js, require Proovl and create a new instance using your Proovl Account'suser and token:

    Note: If you don't know how to get these, just click here.

    const Proovl = require('proovl')
     
    const proovl = new Proovl('ACC_ID', 'ACC_TOKEN')
     
    proovl.balance().then(balance => {
      console.log('Account balance: ' + balance)
    }).catch(error => {
      console.error(error)
    })
    • Subscribe to incoming SMS:
    const Proovl = require('proovl')
     
    const proovl = new Proovl('ACC_ID', 'ACC_TOKEN')
     
    proovl.start()
     
    proovl.on('error', error => {
      console.error(error)
    })
     
    proovl.on('receive sms', data => {
      console.log(`
     
        New SMS!
     
        From: ${data.from}
        To: ${data.to}
        Text: ${data.text}
        ID: ${data.id}
     
      `)
    })
    • Set up webhooks and start the express server:
    proovl.start()
    • Start up your bot by running node:
    $ node index.js
    > Node-Proovl running on port 3000
    > Proovl Webhook running on localhost:3000/webhook
    
    • If you want to test your bot locally, install a localhost tunnel like ngrok and run it on your bot's port:
    $ ngrok http 3000
    

    Then use the provided HTTPS URL to config your webhook on Proovl's Dashboard. For example if the URL provided by ngrok is https://99b8d4c2.ngrok.io, use https://99b8d4c2.ngrok.io/webhook.

    Documentation

    Proovl Class

    new Proovl(userId, authToken, options)

    • accountId - the user ID
    • accountToken - the authentication token
    • options - Optional. An object containing zero or more of the following properties:
      • request - An instance of request which will be used by proovl for its HTTP requests. proovl will create its own if omitted.
      • timeout - The time in milliseconds that proovl will wait for HTTP requests to complete. Defaults to 50000 (50 seconds). Overrides any timeout option that was set on the passed-in request object.
      • userAgent - The user-agent value that proovl will use for its HTTP requests. Defaults to Mac OS X's user-agent. Overrides any headers['User-Agent'] option that was set on the passed-in request object.
      • localAddress - The local IP address that proovl will use for its HTTP requests. Overrides an localAddress option that was set on the passed-in request object.
      • webhook - Webhook URL path. Defaults to /webhook

    Creates a new Proovl instance. Instantiates the new express app and all required webhooks.

    If you want to specify a custom endpoint name for your webhook, you can do it with the webhook option.

    .start([ port ])

    Param Type Default Required
    port number 3000 N

    Starts the express server on the specified port. Defaults port to 3000.

    .close()

    Closes the express server (calls .close() on the server instance).

    .balance() [Promise]

    Param Type Default Required

    Returns account balance.

    .sendSms(options) [Promise]

    Parameters need to be object properties, not arguments

    Param Type Default Required
    route number 1 N
    from string Y
    to string Y
    text string Y

    Sends an SMS. Route should be a value beetwen 1 and 2. You can use static enum directly from Proovl class too: Proovl.ERoutes.Standard, Proovl.ERoutes.Economy From: The number you are sending SMS from. Without +, with country code, without any spaces. To: The number you are sending SMS to. Without +, with country code, without any spaces.

    .checkSms(options) [Promise]

    Parameters need to be object properties, not arguments

    Param Type Default Required
    id string Y
    phone string Y

    Returns object with id, status, price properties. Example:

    { id: '123', status: 'Sent', price: '-0.0123' }
    

    handleReports(data) and handleSms(data)

    These functions are just emitting events.


    Receive API

    Use these methods to subscribe your bot to SMS's and SMS's delivery statuses.

    .on(event, callback)

    Param Type Default Required
    event string Y
    callback function Y

    Subscribe to an event emitted by the proovl module, and execute a callback when those events are emitted. Available events are:

    Event Description
    error Emitted when there is an error while parsing HTTP hook request
    delivery reports SMS status changed
    receive sms You got a new SMS

    When these events ocurr, the specified callback will be invoked with 1 param: data (except for error: it will callback error param)

    Param Description
    data In receive sms: object containing from, to, text, id, token properties. In delivery reports: object containing token, id, status properties.
    error Error Object
    .on() examples:
    proovl.on('error', error => {
      console.error(error)
    })
     
    proovl.on('delivery reports', data => {
      console.log(`
     
        SMS Status Changed:
     
        New Status: ${data.status}
        ID: ${data.id}
     
      `)
    })
     
    proovl.on('receive sms', data => {
      console.log(`
     
        New SMS!
     
        From: ${data.from}
        To: ${data.to}
        Text: ${data.text}
        ID: ${data.id}
     
      `)
    })

    Bypassing Express

    You may only want to use proovl for the Proovl related config and the simple to use API features but handle routing from somewhere else.

    Or maybe you don't want to use express but a different HTTP server.

    Just do not start the express server and handle routing somehow.

    Examples

    Check the examples directory to see more demos of:

    • A balance checker
    • SMS sender, SMS status checker
    • How to use events

    To run the examples, make sure to complete the ACC_ID and ACC_TOKEN fields, and then cd into the examples folder and run the desired example with node. For example:

    $ cd examples
    $ node balance.js
    

    Credits

    Made with 🍺 by expl0it - @expl0it Credits to bootbot for letting me to copy this README.

    License

    MIT

    Install

    npm i proovl

    DownloadsWeekly Downloads

    4

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    17 kB

    Total Files

    7

    Last publish

    Collaborators

    • expl0it