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

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

Spark
- new Spark(options)
- instance
  - .setToken(token) ⇒ Promise.String
- static
  - .contentGet(contentId) ⇒ Promise.<File>
  - .contentCreate(filePath, [timeout]) ⇒ Promise.<File>
  - .eventsGet([eventSearch], [max]) ⇒ Promise.Array.<Event>
  - .eventGet(eventId) ⇒ Promise.<Event>
  - .licensesGet([orgId], [max]) ⇒ Promise.Array.<License>
  - .licenseGet(licenseId) ⇒ Promise.<License>
  - .membershipsGet([membershipSearch], [max]) ⇒ Promise.Array.<Membership>
  - .membershipGet(membershipId) ⇒ Promise.<Membership>
  - .membershipAdd(roomId, personEmail, [isModerator]) ⇒ Promise.<Membership>
  - .membershipUpdate(membership) ⇒ Promise.<Membership>
  - .membershipRemove(membershipId) ⇒ Promise
  - .messagesGet(messageSearch, [max]) ⇒ Promise.Array.<Message>
  - .messageGet(messageId) ⇒ Promise.<Message>
  - .messageSend(message, [file]) ⇒ Promise.<Message>
  - .messageRemove(messageId) ⇒ Promise
  - .organizationsGet([max]) ⇒ Promise.Array.<Organization>
  - .organizationGet(orgId) ⇒ Promise.<Organization>
  - .peopleGet([personSearch], [max]) ⇒ Promise.Array.<Person>
  - .personGet(personId) ⇒ Promise.<Person>
  - .personMe() ⇒ Promise.<Person>
  - .personAdd(person) ⇒ Promise.<Person>
  - .personUpdate(person) ⇒ Promise.<Person>
  - .personRemove(personId) ⇒ Promise
  - .rolesGet([max]) ⇒ Promise.Array.<Role>
  - .roleGet(roleId) ⇒ Promise.<Role>
  - .roomsGet([roomSearch], [max]) ⇒ Promise.Array.<Room>
  - .roomGet(roomId) ⇒ Promise.<Room>
  - .roomAdd(title, [teamId]) ⇒ Promise.<Room>
  - .roomUpdate(room) ⇒ Promise.<Room>
  - .roomRemove(roomId) ⇒ Promise
  - .teamsGet([max]) ⇒ Promise.Array.<Team>
  - .teamGet(teamId) ⇒ Promise.<Team>
  - .teamAdd(name) ⇒ Promise.<Team>
  - .teamUpdate(team) ⇒ Promise.<Team>
  - .teamRemove(teamId) ⇒ Promise
  - .teamMembershipsGet(teamId, [max]) ⇒ Promise.Array.<TeamMembership>
  - .teamMembershipGet(membershipId) ⇒ Promise.<TeamMembership>
  - .teamMembershipAdd(teamId, personEmail, isModerator) ⇒ Promise.<TeamMembership>
  - .teamMembershipUpdate(teamMembership) ⇒ Promise.<TeamMembership>
  - .teamMembershipRemove(membershipId) ⇒ Promise
  - .webhooksGet([webhookSearch], [max]) ⇒ Promise.Array.<Webhook>
  - .webhookGet(webhookId) ⇒ Promise.<Webhook>
  - .webhookAdd(webhookObj) ⇒ Promise.<Webhook>
  - .webhookUpdate(webhookObj) ⇒ Promise.<Webhook>
  - .webhookRemove(webhookId) ⇒ Promise
  - .webhookAuth(secret, signature, payload) ⇒ Promise.String | Object
  - .webhookListen() ⇒ webhookHandler
    - ~webhookHandler(req, [res], [next]) ⇒ Null

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 : object
- .isFile(filePath) ⇒ Promise.String
- .isDir(dirPath) ⇒ Promise.String
- .isToken(token) ⇒ Promise.String
- .isEmail(email) ⇒ Boolean
- .isEmails(emails) ⇒ Boolean
- .isUrl(url) ⇒ Boolean
- .isFilePath(path) ⇒ Boolean
- .isOptions(options) ⇒ Boolean
- .isFile(file) ⇒ Boolean
- .isEvent(event) ⇒ Boolean
- .isEvents(events) ⇒ Boolean
- .isEventSearch(searchObj) ⇒ Boolean
- .isLicense(license) ⇒ Boolean
- .isLicenses(licenses) ⇒ Boolean
- .isLicenseSearch(searchObj) ⇒ Boolean
- .isMembership(membership) ⇒ Boolean
- .isMemberships(memberships) ⇒ Boolean
- .isMembershipSearch(searchObj) ⇒ Boolean
- .isMessage(message) ⇒ Boolean
- .isMessages(messages) ⇒ Boolean
- .isMessageSearch(searchObj) ⇒ Boolean
- .isOrganization(organization) ⇒ Boolean
- .isOrganizations(organizations) ⇒ Boolean
- .isPerson(person) ⇒ Boolean
- .isPeople(people) ⇒ Boolean
- .isPersonSearch(searchObj) ⇒ Boolean
- .isRole(role) ⇒ Boolean
- .isRoles(roles) ⇒ Boolean
- .isRoom(room) ⇒ Boolean
- .isRooms(rooms) ⇒ Boolean
- .isRoomSearch(searchObj) ⇒ Boolean
- .isTeam(team) ⇒ Boolean
- .isTeams(teams) ⇒ Boolean
- .isTeamMembership(teamMembership) ⇒ Boolean
- .isTeamMemberships(teamMemberships) ⇒ Boolean
- .isTeamMembershipSearch(searchObj) ⇒ Boolean
- .isWebhook(webhook) ⇒ Boolean
- .isWebhooks(webhooks) ⇒ Boolean
- .isWebhookSearch(searchObj) ⇒ Boolean

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