node-sparky

Cisco Spark API for Node JS

This is a Cisco Spark API Library for Node JS. This project aims to simplify interaction with the Spark API while transparently handling more complex operations such as pagination, webhook creation, and webhook authentication. If you have a question, feature request, or have found a bug, please open an issue.

Quick Start

const Spark = require('node-sparky');

const spark = new Spark({ token: '<token>' });

spark.roomsGet(10)
  .then(rooms => rooms.forEach(room => console.log(room.title)))
  .catch(err => console.error(err));

Features

Rate limiting headers inspected to adjust request rates based on Cisco Spark API. These are automatically re-queued and sent after the retry-after timer expires.
File processor for retrieving attachments from room.
Returns promises that comply with A+ standards..
Handles pagination transparently. (Receive unlimited records)
Support for authenticated HMAC-SHA1 webhooks

Using node-sparky as a Node JS Package

This module can be installed via NPM:

npm install node-sparky --save

Using node-sparky webhook event parser in an Express App

const Spark = require('node-sparky');
const express = require('express');
const bodyParser = require('body-parser');
const when = require('when');

const spark = new Spark({
  token: '<my token>',
  webhookSecret: 'somesecr3t',
});

const port = parseInt(process.env.PORT || '3000', 10);

// add events
spark.on('messages-created', msg => console.log(`${msg.personEmail} said: ${msg.text}`));

const app = express();
app.use(bodyParser.json());

// add route for path that is listening for web hooks
app.post('/webhook', spark.webhookListen());

// start express server
app.listen(port, function() {
  // get exisiting webhooks
  spark.webhooksGet()
    // remove all existing webhooks
    .then(webhooks => when.map(webhooks, webhook => spark.webhookRemove(webhook.id)))
    // create spark webhook directed back to the externally accessible
    // express route defined above.
    .then(() => spark.webhookAdd({
      name: 'my webhook',
      targetUrl: 'https://example.com/webhook',
      resource: 'all',
      event: 'all',
    });
  console.log(`Listening on port ${port}`);
});

Using node-sparky in the Browser

You can use node-sparky on the client side browser as well. Simply include <script src="browser/node-sparky.js"></script> in your page and you can use node-sparky just as you can with with node-js.

<head>
    <title>test</title>
    <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
    <script src="browser/node-sparky.js"></script>
</head>

<body>
    <h1>Test</h1>
    <div id="messageId"></div>

    <script>
        $(document).ready(function() {
            var spark = new Sparky({
                token: '<my token>'
            });

            var message = {
                roomId: '<room id>',
                text: 'Hello world!'
            };

            spark.messageSend(message)
                .then(function(res) {
                    $('#messageId').html(res.id);
                })
                .catch(function(err) {
                    console.log(err);
                });
        });
    </script>
</body>

</html>

Note: The above is a simple example. It is not recommended to include the token in anything client accessible. This would ideally be part of a broader application that makes use of oauth2 to cross authenticate the user to Spark to grab their token through a Spark integration should you use node-sparky in the browser side JS.

Contributing

Build

The README.md and browser/node-sparky.* files are auto-generated from the files in /lib and /docs. To regenerate these run:

npm run build

Test

Tests require a user token and will not fully run using a bot token. It is assumed that the user token has Org Admin permissions. If not, certain tests WILL fail. The tests can be run via:

git clone https://github.com/flint-bot/sparky
cd sparky
npm install
SPARKY_API_TOKEN=someUserTokenHere npm test

Support this Project

Find this project useful? Help suppport the continued development by submitting issues, feature requests, or code. Alternatively, you can...

Reference

Classes

<dl> <dt><a href="#Spark">Spark</a></dt> <dd></dd> </dl>

Objects

<dl> <dt><a href="#File">File</a> : <code>object</code></dt> <dd>File Object </dd> <dt><a href="#Event">Event</a> : <code>object</code></dt> <dd>Event Object </dd> <dt><a href="#License">License</a> : <code>object</code></dt> <dd>License Object </dd> <dt><a href="#Membership">Membership</a> : <code>object</code></dt> <dd>Membership Object </dd> <dt><a href="#Message">Message</a> : <code>object</code></dt> <dd>Message Object </dd> <dt><a href="#Organization">Organization</a> : <code>object</code></dt> <dd>Organization Object </dd> <dt><a href="#Person">Person</a> : <code>object</code></dt> <dd>Person Object </dd> <dt><a href="#Role">Role</a> : <code>object</code></dt> <dd>Role Object </dd> <dt><a href="#Room">Room</a> : <code>object</code></dt> <dd>Room Object </dd> <dt><a href="#Team">Team</a> : <code>object</code></dt> <dd>Team Object </dd> <dt><a href="#TeamMembership">TeamMembership</a> : <code>object</code></dt> <dd>Team Membership Object </dd> <dt><a href="#Webhook">Webhook</a> : <code>object</code></dt> <dd>Webhook Object </dd> <dt><a href="#Validator">Validator</a> : <code>object</code></dt> <dd>Spark Object Validation </dd> </dl>

Events

<dl> <dt><a href="#event_memberships">"memberships"</a></dt> <dd>Webhook membership event </dd> <dt><a href="#event_messages">"messages"</a></dt> <dd>Webhook messages event </dd> <dt><a href="#event_rooms">"rooms"</a></dt> <dd>Webhook rooms event </dd> <dt><a href="#event_memberships-created">"memberships-created"</a></dt> <dd>Webhook Memberships Created event </dd> <dt><a href="#event_memberships-updated">"memberships-updated"</a></dt> <dd>Webhook Memberships Updated event </dd> <dt><a href="#event_memberships-deleted">"memberships-deleted"</a></dt> <dd>Webhook Memberships Deleted event </dd> <dt><a href="#event_messages-created">"messages-created"</a></dt> <dd>Webhook Messages Created event </dd> <dt><a href="#event_messages-deleted">"messages-deleted"</a></dt> <dd>Webhook Messages Deleted event </dd> <dt><a href="#event_rooms-created">"rooms-created"</a></dt> <dd>Webhook Rooms Created event </dd> <dt><a href="#event_rooms-updated">"rooms-updated"</a></dt> <dd>Webhook Rooms Updated event </dd> <dt><a href="#event_request">"request"</a></dt> <dd>Webhook request event </dd> </dl>

Spark

Kind: global class
Properties

| Name | Type | Description | | --- | --- | --- | | options | <code>Object.<Options></code> | Sparky options object |

Spark
- new Spark(options)
- instance
 - .setToken(token) ⇒ <code>Promise.String</code>
- static

Sparky

Install / Use

README