Skip to content

flint-bot/sparky

Repository files navigation

node-sparky

NPM

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...

Buy me a Coffee!

Reference

Classes

Spark

Objects

File : object

File Object

Event : object

Event Object

License : object

License Object

Membership : object

Membership Object

Message : object

Message Object

Organization : object

Organization Object

Person : object

Person Object

Role : object

Role Object

Room : object

Room Object

Team : object

Team Object

TeamMembership : object

Team Membership Object

Webhook : object

Webhook Object

Validator : object

Spark Object Validation

Events

"memberships"

Webhook membership event

"messages"

Webhook messages event

"rooms"

Webhook rooms event

"memberships-created"

Webhook Memberships Created event

"memberships-updated"

Webhook Memberships Updated event

"memberships-deleted"

Webhook Memberships Deleted event

"messages-created"

Webhook Messages Created event

"messages-deleted"

Webhook Messages Deleted event

"rooms-created"

Webhook Rooms Created event

"rooms-updated"

Webhook Rooms Updated event

"request"

Webhook request event

Spark

Kind: global class
Properties

Name Type Description
options Object.<Options> Sparky options object

new Spark(options)

Creates a Spark API instance that is then attached to a Spark Account.

Param Type Description
options Object.<Options> Sparky options object

Example

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

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

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

spark.setToken(token) ⇒ Promise.String

Set/Reset API token used in a Sparky instance. Use this function when needing to change an expired Token. Returns a fullfiled promise if token is valid, else returns a rejected promise.

Kind: instance method of Spark
Returns: Promise.String - Token promise

Param Type Description
token String Spark API token

Example

spark.setToken('Tm90aGluZyB0byBzZWUgaGVyZS4uLiBNb3ZlIGFsb25nLi4u')
  .then(token => console.log(token))
  .catch(err => console.error(err));

Spark.contentGet(contentId) ⇒ Promise.<File>

Returns a File Object specified by Content ID or Content URL.

Kind: static method of Spark
Returns: Promise.<File> - File object

Param Type Description
contentId String Spark Content ID or URL

Example

spark.contentGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(file => console.log('File name: %s', file.name))
  .catch(err => console.error(err));

Spark.contentCreate(filePath, [timeout]) ⇒ Promise.<File>

Create File Object from local file path.

Kind: static method of Spark
Returns: Promise.<File> - File

Param Type Default Description
filePath String Path to file
[timeout] Integer 15000 Timeout in ms to read file (optional)

Example

spark.contentCreate('/some/local/file.png')
  .then(file => console.log(file.name))
  .catch(err => console.error(err));

Spark.eventsGet([eventSearch], [max]) ⇒ Promise.Array.<Event>

List events in your organization. Several query parameters are available to filter the response. Long result sets will be split into pages. Requires admin permissions in organization.

Kind: static method of Spark
Returns: Promise.Array.<Event> - Events Collection

Param Type Description
[eventSearch] Object Spark Event Search Object
[max] Integer Number of records to return (optional)

Example

spark.eventsGet({ resource: 'messages' }, 10)
  .then(events => events.forEach(event => console.log(event.data.text)))
  .catch(err => console.error(err));

Spark.eventGet(eventId) ⇒ Promise.<Event>

Return details of Spark Event by ID.

Kind: static method of Spark
Returns: Promise.<Event> - Spark Event object

Param Type Description
eventId String Spark Event ID

Example

spark.eventGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(event => console.log(event.data.text))
  .catch(err => console.error(err));

Spark.licensesGet([orgId], [max]) ⇒ Promise.Array.<License>

Returns all Spark Licenses for a given Organization ID. If no organization ID argument is passed, licenses are returned for the Organization that the authenticated account is in. If 'max' is not specifed, returns all. Alternativly, you can pass a licenses object instead of the orgId string.

Kind: static method of Spark
Returns: Promise.Array.<License> - Licenses Collection

Param Type Description
[orgId] String The organization ID to query (optional)
[max] Integer Number of records to return (optional)

Example

spark.licensesGet('Tm90aGluZyB0byBzZWUgaGVy', 10)
  .then(licenses => licenses.forEach(license => console.log(license.name)))
  .catch(err => console.error(err));

Example

const licenseSearchObj = {
  orgId: 'Tm90aGluZyB0byBzZWUgaGVy',
};
spark.licensesGet(licenseSearchObj, 10)
  .then(licenses => licenses.forEach(license => console.log(license.name)))
  .catch(err => console.error(err));

Spark.licenseGet(licenseId) ⇒ Promise.<License>

Returns a Spark License specified by License ID.

Kind: static method of Spark
Returns: Promise.<License> - License

Param Type Description
licenseId String Spark License ID

Example

spark.licenseGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(license => console.log(license.name))
  .catch(err => console.error(err));

Spark.membershipsGet([membershipSearch], [max]) ⇒ Promise.Array.<Membership>

Returns all Spark Memberships that the authenticated account is in. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Membership> - Array of Spark Membership objects

Param Type Description
[membershipSearch] Object Spark Membership Search Object (optional)
[max] Integer Number of records to return

Example

spark.membershipsGet({ roomId: 'Tm90aGluZyB0byBzZWUgaGVy' }, 10)
  .then(memberships => memberships.forEach(membership => console.log(membership.id)))
  .catch(err => console.error(err));

Spark.membershipGet(membershipId) ⇒ Promise.<Membership>

Returns Spark Membership by ID.

Kind: static method of Spark
Returns: Promise.<Membership> - Spark Membership object

Param Type Description
membershipId String Spark Membership ID

Example

spark.membershipGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(membership => console.log(membership.id))
  .catch(err => console.error(err));

Spark.membershipAdd(roomId, personEmail, [isModerator]) ⇒ Promise.<Membership>

Add new Spark Membership given Room ID, email address, and moderator status. Alternativly, you can pass a membership object as the only argument.

Kind: static method of Spark
Returns: Promise.<Membership> - Spark Membership object

Param Type Description
roomId String Spark Room ID
personEmail String Email address of person to add
[isModerator] Boolean True if moderator

Example

spark.membershipAdd('Tm90aGluZyB0byBzZWUgaGVy', '[email protected]')
  .then(membership => console.log(membership.id))
  .catch(err => console.error(err));

Example

const membershipObj = {
  personEmail: '[email protected]',
  roomId: 'Tm90aGluZyB0byBzZWUgaGVy',
  isModerator: true,
};
spark.membershipAdd(membershipObj)
  .then(membership => console.log(membership.id))
  .catch(err => console.error(err));

Spark.membershipUpdate(membership) ⇒ Promise.<Membership>

Update a Membership.

Kind: static method of Spark
Returns: Promise.<Membership> - Spark Membership object

Param Type Description
membership Object.<Membership> Spark Membership object

Example

spark.membershipGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then((membership) => {
    membership.isModerator = true;
    return spark.membershipUpdate(membership);
  )
  .then(membership => console.log(membership.isModerator))
  .catch(err => console.error(err));

Spark.membershipRemove(membershipId) ⇒ Promise

Remove Spark Membership by ID.

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
membershipId String Spark Membership ID

Example

spark.membershipRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Membership removed.'))
  .catch(err => console.error(err));

Spark.messagesGet(messageSearch, [max]) ⇒ Promise.Array.<Message>

Returns Spark Message Objects. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Message> - Array of Spark Message objects

Param Type Description
messageSearch Object Spark Message Search Object
[max] Integer Number of records to return (optional)

Example

spark.messagesGet({roomId: 'Tm90aGluZyB0byBzZWUgaGVy'}, 100)
  .then(messages => messages.forEach(message => console.log(message.text)))
  .catch(err => console.error(err));

Spark.messageGet(messageId) ⇒ Promise.<Message>

Return details of Spark Message by ID.

Kind: static method of Spark
Returns: Promise.<Message> - Spark Message object

Param Type Description
messageId String Spark Message ID

Example

spark.messageGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(message => console.log(message.text))
  .catch(err => console.error(err));

Spark.messageSend(message, [file]) ⇒ Promise.<Message>

Send Spark Message.

Kind: static method of Spark
Returns: Promise.<Message> - Spark Message object

Param Type Description
message Object.<MessageAdd> Spark Message Add Object
[file] Object.<File> File Object to add to message (optional)

Example

const newMessage = {
  roomId: 'Tm90aGluZyB0byBzZWUgaGVy',
  text: 'Hello World'
};

spark.contentCreate('/some/file/with.ext')
  .then(file => spark.messageSend(newMessage, file))
  .then(message => console.log(message.id))
  .catch(err => console.error(err));

Spark.messageRemove(messageId) ⇒ Promise

Remove Spark Message by ID.

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
messageId String Spark Message ID

Example

spark.messageRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Message removed.'))
  .catch(err => console.error(err));

Spark.organizationsGet([max]) ⇒ Promise.Array.<Organization>

Return all Spark Organizations that the authenticated account is in. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Organization> - Array of Spark Organization objects

Param Type Description
[max] Integer Number of records to return (optional)

Example

spark.organizationsGet(10)
  .then(organizations => organizations.forEach(organization => console.log(organization.id)))
  .catch(err => console.error(err));

Spark.organizationGet(orgId) ⇒ Promise.<Organization>

Return Spark Organization specified by License ID.

Kind: static method of Spark
Returns: Promise.<Organization> - Spark Organization object

Param Type Description
orgId String Spark Organization ID

Example

spark.organizationGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(organization => console.log(organization.id))
  .catch(err => console.error(err));

Spark.peopleGet([personSearch], [max]) ⇒ Promise.Array.<Person>

Returns Spark Person Objects. If no arguments are passed and if the authenticated account is part of an Organization and if authenticated account is assigned the Role of Organization Admin, returns all Spark Person objects from the Organizations that the user is in. Otherwise, the PersonSearch object should contain the key "id", "displayName", or "email" to query. If 'max' is not specifed, returns all matched Person Objects.

Kind: static method of Spark
Returns: Promise.Array.<Person> - Array of Spark Person objects

Param Type Description
[personSearch] Object Spark Person Search Object (optional)
[max] Integer Number of records to return (optional)

Example

spark.peopleGet({ displayName: 'John' }, 10)
  .then(people => people.forEach(person => console.log(person.displayName)))
  .catch(err => console.error(err));

Spark.personGet(personId) ⇒ Promise.<Person>

Returns a Spark Person Object specified by Person ID.

Kind: static method of Spark
Returns: Promise.<Person> - Spark Person object

Param Type Description
personId String Spark Person ID

Example

spark.personGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(person => console.log(person.displayName))
  .catch(err => console.error(err));

Spark.personMe() ⇒ Promise.<Person>

Return the Spark Person Object of the authenticated account.

Kind: static method of Spark
Returns: Promise.<Person> - Spark Person object
Example

spark.personMe()
  .then(person => console.log(person.displayName))
  .catch(err => console.error(err));

Spark.personAdd(person) ⇒ Promise.<Person>

Add new Person.

Kind: static method of Spark
Returns: Promise.<Person> - Spark Person object

Param Type Description
person Object.<Person> Spark Person object

Example

let newPerson = {
  emails: ['[email protected]'],
  displayName: 'Any Person',
  firstName: 'Any',
  lastName: 'Person',
  avatar: 'http://lorempixel.com/400/400/',
  orgId: 'Tm90aGluZyB0byBzZWUgaGVy',
  roles: ['Tm90aGluZyB0byBzZWUgaGVy'],
  licenses: ['Tm90aGluZyB0byBzZWUgaGVy']
};

spark.personAdd(newPerson)
  .then(person => console.log(person.displayName))
  .catch(err => console.error(err));

Spark.personUpdate(person) ⇒ Promise.<Person>

Update a Person.

Kind: static method of Spark
Returns: Promise.<Person> - Spark Person object

Param Type Description
person Object.<Person> Spark Person object

Example

spark.personGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then((person) => {
    person.displayName = 'Another Person';
    return spark.personUpdate(person);
  })
  .then(person => console.log(person.displayName))
  .catch(err => console.error(err));

Spark.personRemove(personId) ⇒ Promise

Remove Spark Person by ID.

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
personId String Spark Person ID

Example

spark.personRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Person removed.'))
  .catch(err => console.error(err));

Spark.rolesGet([max]) ⇒ Promise.Array.<Role>

Returns all Spark Roles that the authenticated account is in. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Role> - Array of Spark Role object

Param Type Description
[max] Integer Number of records to return (optional)

Example

spark.rolesGet(10)
  .then(roles => roles.forEach(role => console.log(role.name)))
  .catch(err => console.error(err));

Spark.roleGet(roleId) ⇒ Promise.<Role>

Returns details for a Spark Role pecified by Role ID.

Kind: static method of Spark
Returns: Promise.<Role> - Spark Role object

Param Type Description
roleId String Spark Role ID

Example

spark.roleGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(role => console.log(role.name))
  .catch(err => console.error(err));

Spark.roomsGet([roomSearch], [max]) ⇒ Promise.Array.<Room>

Returns Spark Room Objects. If roomSearch argument is not passed, returns all Spark Rooms that the authenticated account is in. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Room> - Array of Spark Room objects

Param Type Description
[roomSearch] Object.<RoomSearch> Spark Person Search Object (optional)
[max] Integer Number of records to return (optional)

Example

spark.roomsGet({ type: 'group' }, 10)
  .then(rooms => rooms.forEach(room => console.log(room.title)))
  .catch(err => console.error(err));

Spark.roomGet(roomId) ⇒ Promise.<Room>

Returns a Spark Room Object specified by Room ID.

Kind: static method of Spark
Returns: Promise.<Room> - Spark Room object

Param Type Description
roomId String Spark Room ID

Example

spark.roomGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(room => console.log(room.title))
  .catch(err => console.error(err));

Spark.roomAdd(title, [teamId]) ⇒ Promise.<Room>

Add new Spark Room.

Kind: static method of Spark
Returns: Promise.<Room> - Spark Room object

Param Type Description
title String Title for a new Room
[teamId] String Team ID (optional)

Example

spark.roomAdd('myroom')
  .then(room => console.log(room.title))
  .catch(err => console.error(err));

Spark.roomUpdate(room) ⇒ Promise.<Room>

Update a Spark Room.

Kind: static method of Spark
Returns: Promise.<Room> - Spark Room object

Param Type Description
room Object.<Room> Spark Room object

Example

spark.roomGet(Tm90aGluZyB0byBzZWUgaGVy)
  .then((room) => {
    room.title = 'Another Title';
    return spark.roomUpdate(room);
  )
  .then(room => console.log(room.title))
  .catch(err => console.error(err));

Spark.roomRemove(roomId) ⇒ Promise

Remove Spark Room by ID.

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
roomId String Spark Room ID

Example

spark.roomRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Room removed.'))
  .catch(err => console.error(err));

Spark.teamsGet([max]) ⇒ Promise.Array.<Team>

Return all Spark Teams that the authenticated account is in. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Team> - Teams Collection

Param Type Description
[max] Integer Number of records to return (optional)

Example

spark.teamsGet(10)
  .then(teams => teams.forEach(team => console.log(team.name)))
  .catch(err => console.error(err));

Spark.teamGet(teamId) ⇒ Promise.<Team>

Returns a Spark Team Object specified by Team ID.

Kind: static method of Spark
Returns: Promise.<Team> - Team

Param Type Description
teamId String Spark Team ID

Example

spark.teamGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(team => console.log(team.name))
  .catch(err => console.error(err));

Spark.teamAdd(name) ⇒ Promise.<Team>

Add new Spark Team.

Kind: static method of Spark
Returns: Promise.<Team> - Team

Param Type Description
name String Name for new Team

Example

spark.teamAdd('myteam')
  .then(team => console.log(team.name))
  .catch(err => console.error(err));

Spark.teamUpdate(team) ⇒ Promise.<Team>

Update a Team.

Kind: static method of Spark
Returns: Promise.<Team> - Team

Param Type Description
team Object.<Team> Spark Team Object

Example

spark.teamGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then((team) => {
    team.name = 'Another Team';
    return spark.teamUpdate(team);
  })
  .then(team => console.log(team.name))
  .catch(err => console.error(err));

Spark.teamRemove(teamId) ⇒ Promise

Remove Spark Team by ID.

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
teamId String Spark Team ID

Example

spark.teamRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Team removed.'))
  .catch(err => console.error(err));

Spark.teamMembershipsGet(teamId, [max]) ⇒ Promise.Array.<TeamMembership>

Return all Spark Team Memberships for a specific Team that the authenticated account is in. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<TeamMembership> - Array of Spark TeamMembership objects

Param Type Description
teamId String Spark Team Memebership ID
[max] Integer Number of records to return

Example

spark.teamMembershipsGet('Tm90aGluZyB0byBzZWUgaGVy', 100)
  .then(tms => tms.forEach(tm => console.log(tm.personEmail)))
  .catch(err => console.error(err));

Spark.teamMembershipGet(membershipId) ⇒ Promise.<TeamMembership>

Return Spark Team Membership specified by Membership ID.

Kind: static method of Spark
Returns: Promise.<TeamMembership> - Spark TeamMembership object

Param Type Description
membershipId String Spark Membership ID

Example

spark.membershipGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(tm => console.log(tm.personEmail))
  .catch(err => console.error(err));

Spark.teamMembershipAdd(teamId, personEmail, isModerator) ⇒ Promise.<TeamMembership>

Add new Spark Team Membership.

Kind: static method of Spark
Returns: Promise.<TeamMembership> - Spark TeamMembership object

Param Type Description
teamId String Spark Team Memebership ID
personEmail String Email address of person to add
isModerator Boolean Boolean value to add as moderator

Example

spark.teamMembershipAdd('Tm90aGluZyB0byBzZWUgaGVy', '[email protected]')
  .then(tm => console.log(tm.personEmail))
  .catch(err => console.error(err));

Example

const teamMembershipObj = {
  personEmail: '[email protected]',
  teamId: 'Tm90aGluZyB0byBzZWUgaGVy',
  isModerator: true,
};
spark.teamMembershipAdd(teamMembershipObj)
  .then(tm => console.log(tm.personEmail))
  .catch(err => console.error(err));

Spark.teamMembershipUpdate(teamMembership) ⇒ Promise.<TeamMembership>

Update a Team Membership.

Kind: static method of Spark
Returns: Promise.<TeamMembership> - Spark TeamMembership object

Param Type Description
teamMembership object.<TeamMembership> Spark TeamMembership object

Example

spark.teamMembershipGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then((tm) => {
    tm.isModerator = true;
    return spark.teamMembershipUpdate(tm);
  )
  .then(tm => console.log(tm.isModerator))
  .catch(err => console.error(err));

Spark.teamMembershipRemove(membershipId) ⇒ Promise

Remove Spark Team Membership by ID..

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
membershipId String Spark Team Membership ID

Example

spark.teamMembershipRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Team Membership removed.'))
  .catch(err => console.error(err));

Spark.webhooksGet([webhookSearch], [max]) ⇒ Promise.Array.<Webhook>

Returns all webhooks for authenticated account with optional search criteria to filter results. If 'max' is not specifed, returns all.

Kind: static method of Spark
Returns: Promise.Array.<Webhook> - Array of Spark Webhook objects

Param Type Description
[webhookSearch] Object Webhook Search object
[max] Integer Number of records to return

Example

spark.webhooksGet(10)
  .then(webhooks => webhooks.forEach(webhook => console.log(webhook.name)))
  .catch(err => console.error(err));

Example

spark.webhooksGet({ name: 'My Awesome Webhook' }, 10)
  .then(webhooks => webhooks.forEach(webhook => console.log(webhook.name)))
  .catch(err => console.error(err));

Spark.webhookGet(webhookId) ⇒ Promise.<Webhook>

Returns details of Spark Webhook Object specified by Webhook ID.

Kind: static method of Spark
Returns: Promise.<Webhook> - Spark Webhook object

Param Type Description
webhookId String Spark Webhook ID

Example

spark.webhookGet('Tm90aGluZyB0byBzZWUgaGVy')
  .then(webhook => console.log(webhook.name))
  .catch(err => console.error(err));

Spark.webhookAdd(webhookObj) ⇒ Promise.<Webhook>

Add new Webhook.

Kind: static method of Spark
Returns: Promise.<Webhook> - Spark Webhook object

Param Type Description
webhookObj Object.<Webhook> Spark Webhook object

Example

const newWebhook = {
  name: 'my webhook',
  targetUrl: 'https://example.com/webhook',
  resource: 'memberships',
  event: 'created',
  filter: 'roomId=Tm90aGluZyB0byBzZWUgaGVy'
};

spark.webhookAdd(newWebhook)
  .then(webhook => console.log(webhook.name))
  .catch(err => console.error(err));

Spark.webhookUpdate(webhookObj) ⇒ Promise.<Webhook>

Update a Webhook.

Kind: static method of Spark
Returns: Promise.<Webhook> - Spark Webhook Object

Param Type Description
webhookObj Object.<Webhook> Spark Webhook Object

Example

spark.webhookGet(Tm90aGluZyB0byBzZWUgaGVy)
  .then((webhook) => {
    webhook.name = 'Another Webhook';
    return spark.webhookUpdate(webhook);
  })
  .then(webhook => console.log(webhook.name))
  .catch(err => console.error(err));

Spark.webhookRemove(webhookId) ⇒ Promise

Remove Spark Webhook by ID.

Kind: static method of Spark
Returns: Promise - Fulfilled promise

Param Type Description
webhookId String Spark Webhook ID.

Example

spark.webhookRemove('Tm90aGluZyB0byBzZWUgaGVy')
  .then(() => console.log('Webhook removed.'))
  .catch(err => console.error(err));

Spark.webhookAuth(secret, signature, payload) ⇒ Promise.String | Object

Authenticate X-Spark-Signature HMAC-SHA1 Hash.

Kind: static method of Spark
Returns: Promise.String | Object - payload

Param Type Description
secret String Value of secret used when creating webhook
signature String Value of "X-Spark-Signature" from header
payload String | Object This can either be the json object or a string representation of the webhook's body json payload

Example

const sig = req.headers['x-spark-signature'];
const secret = 'mySecret';

spark.webhookAuth(secret, sig, req.body)
  .then(() => console.log('Webhook is valid');
  .catch(err => console.error(err));

Spark.webhookListen() ⇒ webhookHandler

Process request from connect, express, or resitify routes. Returns function that accepts req, res, and next arguments.

Kind: static method of Spark
Returns: webhookHandler - function
Example

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}`);
});

webhookListen~webhookHandler(req, [res], [next]) ⇒ Null

Function returned by spark.webhookListen()

Kind: inner method of webhookListen
Returns: Null - null value

Param Type Description
req Object request object
[res] Object response object
[next] function next function

File : object

File Object

Kind: global namespace
Properties

Name Type Description
name String File name
ext String File extension
type String Header [content-type] for file
binary Buffer File contents as binary
base64 String File contents as base64 encoded string

Event : object

Event Object

Kind: global namespace
Properties

Name Type Description
id String Event ID
resource String Event resource
type String Event type
actorId String Person ID that triggered event
orgId String Organzation ID that event occurred in
appId String Application ID
created String Date Event created (ISO 8601)
data Object Event data object

License : object

License Object

Kind: global namespace
Properties

Name Type Description
id String License ID
name String License name
totalUnits Integer Total units of license available
consumedUnits Integer Number of license units consumed

Membership : object

Membership Object

Kind: global namespace
Properties

Name Type Description
id String Membership ID
roomId String Room ID
personId String Person ID
personEmail String Person Email
isModerator Boolean Membership is a moderator
isMonitor Boolean Membership is a monitor
created String Date Membership created (ISO 8601)

Message : object

Message Object

Kind: global namespace
Properties

Name Type Description
id String Message ID
roomId String Room ID
roomType String Room Type
toPersonId String Person ID
toPersonEmail String Person Email
text String Message text
markdown String Message markdown
files Array.<String> Array of File URLs
personId String Person ID
personEmail String Person Email
created String Date Message created (ISO 8601)
mentionedPeople Array.String Person IDs of those mentioned in Message

Organization : object

Organization Object

Kind: global namespace
Properties

Name Type Description
id String Organization ID
displayName String Organization name
created String Date Organization created (ISO 8601)

Person : object

Person Object

Kind: global namespace
Properties

Name Type Description
id String Person ID
emails Array.String Array of email addresses
displayName String Display name
firstName String First name
lastName String Last name
avatar String Avatar URL
orgId String Organization ID
roles Array.String Array of assigned Role IDs
licenses Array.String Array of assigned License IDs
created String Date created (ISO 8601)

Role : object

Role Object

Kind: global namespace
Properties

Name Type Description
id String Role ID
name String Role name

Room : object

Room Object

Kind: global namespace
Properties

Name Type Description
id String Room ID
title String Room Title
type String Room Type
isLocked Boolean Room Moderated/Locked
teamId String Team ID
lastActivity String Last Activity in Room (ISO 8601)
creatorId String person ID of Room creator (ISO 8601)
created String Room Created (ISO 8601)

Team : object

Team Object

Kind: global namespace
Properties

Name Type Description
id String Message ID
name String Team name
created String Date Team created (ISO 8601)

TeamMembership : object

Team Membership Object

Kind: global namespace
Properties

Name Type Description
id String Membership ID
teamId String Team ID
personId String Person ID
personEmail String Person Email
isModerator Boolean Membership is a moderator
created String Date Membership created (ISO 8601)

Webhook : object

Webhook Object

Kind: global namespace
Properties

Name Type Description
id String Webhook ID
name String Webhook name
targetUrl String Webhook target URL
resource String Webhook resource
event String Webhook event
filter String Webhook filter
created String Date Webhook created (ISO 8601)

Validator : object

Spark Object Validation

Kind: global namespace

Validator.isFile(filePath) ⇒ Promise.String

Validate filePath resolves to existing file. Returns fulfilled Promise with filePath if valid, else returns rejected Promise if not valid.

Kind: static method of Validator
Returns: Promise.String - Absolute path to file

Param Type Description
filePath String Absolute path to file

Validator.isDir(dirPath) ⇒ Promise.String

Validate filePath resolves to existing dir. Returns fulfilled Promise with dirPath if valid, else returns rejected Promise if not valid.

Kind: static method of Validator
Returns: Promise.String - Absolute path to a directory

Param Type Description
dirPath String Absolute path to a directory

Validator.isToken(token) ⇒ Promise.String

Validate Spark Token is valid by sending request to API to determine if authorized. Returns fulfilled Promise with token if valid, else returns rejected Promise if not valid.

Kind: static method of Validator
Returns: Promise.String - Cisco Spark Token

Param Type Description
token String Cisco Spark Token

Validator.isEmail(email) ⇒ Boolean

Validate String is Email.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
email String Email address string

Validator.isEmails(emails) ⇒ Boolean

Validate Emails in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
emails Array Array of Email address string

Validator.isUrl(url) ⇒ Boolean

Validate String is URL.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
url String URL String

Validator.isFilePath(path) ⇒ Boolean

Validate String is File path and not a URL/URI.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
path String String to test

Validator.isOptions(options) ⇒ Boolean

Validate Options object

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
options Object.<Options> Validate that object passed includes all valid options for sparky constructor

Validator.isFile(file) ⇒ Boolean

Validate File object

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
file Object.<File> Validate that object passed includes all valid options required in a file object

Validator.isEvent(event) ⇒ Boolean

Validate Spark Event Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
event Event Event object

Validator.isEvents(events) ⇒ Boolean

Validate Spark Event Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
events Array Array of Event objects

Validator.isEventSearch(searchObj) ⇒ Boolean

Validate Spark Event Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj EventSearch EventSearch object

Validator.isLicense(license) ⇒ Boolean

Validate Spark License Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
license License License object

Validator.isLicenses(licenses) ⇒ Boolean

Validate Spark License Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
licenses Array Array of License objects

Validator.isLicenseSearch(searchObj) ⇒ Boolean

Validate Spark License Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj LicenseSearch LicenseSearch object

Validator.isMembership(membership) ⇒ Boolean

Validate Spark Membership Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
membership Membership Membership object

Validator.isMemberships(memberships) ⇒ Boolean

Validate Spark Membership Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
memberships Array Array of Membership objects

Validator.isMembershipSearch(searchObj) ⇒ Boolean

Validate Spark Membership Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj MembershipSearch MembershipSearch object

Validator.isMessage(message) ⇒ Boolean

Validate Spark Message Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
message Message Message object

Validator.isMessages(messages) ⇒ Boolean

Validate Spark Message Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
messages Array Array of Message objects

Validator.isMessageSearch(searchObj) ⇒ Boolean

Validate Spark Message Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj MessageSearch MessageSearch object

Validator.isOrganization(organization) ⇒ Boolean

Validate Spark Organization Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
organization Organization Organization object

Validator.isOrganizations(organizations) ⇒ Boolean

Validate Spark Organizations Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
organizations Array Array of Organization objects

Validator.isPerson(person) ⇒ Boolean

Validate Spark Person Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
person Person Person object

Validator.isPeople(people) ⇒ Boolean

Validate Spark Person Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
people Array Array of Person objects

Validator.isPersonSearch(searchObj) ⇒ Boolean

Validate Spark Person Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj PersonSearch Person Search object

Validator.isRole(role) ⇒ Boolean

Validate Spark Role Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
role Role Role object

Validator.isRoles(roles) ⇒ Boolean

Validate Spark Role Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
roles Array Array of Role objects

Validator.isRoom(room) ⇒ Boolean

Validate Spark Room Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
room Room Room Object

Validator.isRooms(rooms) ⇒ Boolean

Validate Spark Room Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
rooms Array Array of Room objects

Validator.isRoomSearch(searchObj) ⇒ Boolean

Validate Spark Room Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj RoomSearch RoomSearch object

Validator.isTeam(team) ⇒ Boolean

Validate Spark Team Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
team Team Team object

Validator.isTeams(teams) ⇒ Boolean

Validate Spark Team Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
teams Array Array of Team objects

Validator.isTeamMembership(teamMembership) ⇒ Boolean

Validate Spark Team Membership Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
teamMembership TeamMembership TeamMembership object

Validator.isTeamMemberships(teamMemberships) ⇒ Boolean

Validate Spark Team Membership Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
teamMemberships Array Array of TeamMembership objects

Validator.isTeamMembershipSearch(searchObj) ⇒ Boolean

Validate Spark Team Memebership Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj TeamMembershipSearch TeamMembership object

Validator.isWebhook(webhook) ⇒ Boolean

Validate Spark Webhook Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
webhook Webhook Webhook object

Validator.isWebhooks(webhooks) ⇒ Boolean

Validate Spark Webhook Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
webhooks Array Array of Webhook objects

Validator.isWebhookSearch(searchObj) ⇒ Boolean

Validate Spark Webhook Search Object.

Kind: static method of Validator
Returns: Boolean - result

Param Type Description
searchObj WebhookSearch TeamMembership object

"memberships"

Webhook membership event

Kind: event emitted
Properties

Name Type Description
event String Triggered event (created, updated, deleted)
membership Object.<Membership> Membership Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"messages"

Webhook messages event

Kind: event emitted
Properties

Name Type Description
event String Triggered event (created, deleted)
message Object.<Message> Message Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"rooms"

Webhook rooms event

Kind: event emitted
Properties

Name Type Description
event String Triggered event (created, updated)
room Object.<Room> Room Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"memberships-created"

Webhook Memberships Created event

Kind: event emitted
Properties

Name Type Description
membership Object.<Membership> Membership Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"memberships-updated"

Webhook Memberships Updated event

Kind: event emitted
Properties

Name Type Description
membership Object.<Membership> Membership Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"memberships-deleted"

Webhook Memberships Deleted event

Kind: event emitted
Properties

Name Type Description
membership Object.<Membership> Membership Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"messages-created"

Webhook Messages Created event

Kind: event emitted
Properties

Name Type Description
message Object.<Message> Message Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"messages-deleted"

Webhook Messages Deleted event

Kind: event emitted
Properties

Name Type Description
message Object.<Message> Message Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"rooms-created"

Webhook Rooms Created event

Kind: event emitted
Properties

Name Type Description
message Object.<Room> Room Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"rooms-updated"

Webhook Rooms Updated event

Kind: event emitted
Properties

Name Type Description
message Object.<Room> Room Object found in Webhook
reqBody Object.<RequestBody> Full Webhook Body Object

"request"

Webhook request event

Kind: event emitted
Properties

Name Type Description
reqBody Object.<RequestBody> Full Webhook Body Object

License

The MIT License (MIT)

Copyright (c) 2016-2018

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.