node-sparky

Cisco Spark API for NodeJS (deprecated in favor of https://github.com/webex/webex-bot-node-framework)

Showing:

Popularity

Downloads/wk

159

GitHub Stars

17

Maintenance

Last Commit

3yrs ago

Contributors

4

Package

Dependencies

7

Size (min+gzip)

213.1KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

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

NameTypeDescription
optionsObject.<Options>Sparky options object

new Spark(options)

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

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

ParamTypeDescription
tokenStringSpark 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

ParamTypeDescription
contentIdStringSpark 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

ParamTypeDefaultDescription
filePathStringPath to file
[timeout]Integer15000Timeout 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

ParamTypeDescription
[eventSearch]ObjectSpark Event Search Object
[max]IntegerNumber 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

ParamTypeDescription
eventIdStringSpark 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

ParamTypeDescription
[orgId]StringThe organization ID to query (optional)
[max]IntegerNumber 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

ParamTypeDescription
licenseIdStringSpark 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

ParamTypeDescription
[membershipSearch]ObjectSpark Membership Search Object (optional)
[max]IntegerNumber 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

ParamTypeDescription
membershipIdStringSpark 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

ParamTypeDescription
roomIdStringSpark Room ID
personEmailStringEmail address of person to add
[isModerator]BooleanTrue if moderator

Example

spark.membershipAdd('Tm90aGluZyB0byBzZWUgaGVy', 'aperson@company.com')
  .then(membership => console.log(membership.id))
  .catch(err => console.error(err));

Example

const membershipObj = {
  personEmail: 'test@test.com',
  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

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

ParamTypeDescription
membershipIdStringSpark 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

ParamTypeDescription
messageSearchObjectSpark Message Search Object
[max]IntegerNumber 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

ParamTypeDescription
messageIdStringSpark 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

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

ParamTypeDescription
messageIdStringSpark 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

ParamTypeDescription
[max]IntegerNumber 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

ParamTypeDescription
orgIdStringSpark 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

ParamTypeDescription
[personSearch]ObjectSpark Person Search Object (optional)
[max]IntegerNumber 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

ParamTypeDescription
personIdStringSpark 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

ParamTypeDescription
personObject.<Person>Spark Person object

Example

let newPerson = {
  emails: ['aperson@company.com'],
  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

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

ParamTypeDescription
personIdStringSpark 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

ParamTypeDescription
[max]IntegerNumber 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

ParamTypeDescription
roleIdStringSpark 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

ParamTypeDescription
[roomSearch]Object.<RoomSearch>Spark Person Search Object (optional)
[max]IntegerNumber 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

ParamTypeDescription
roomIdStringSpark 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

ParamTypeDescription
titleStringTitle for a new Room
[teamId]StringTeam 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

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

ParamTypeDescription
roomIdStringSpark 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

ParamTypeDescription
[max]IntegerNumber 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

ParamTypeDescription
teamIdStringSpark 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

ParamTypeDescription
nameStringName 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

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

ParamTypeDescription
teamIdStringSpark 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

ParamTypeDescription
teamIdStringSpark Team Memebership ID
[max]IntegerNumber 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

ParamTypeDescription
membershipIdStringSpark 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

ParamTypeDescription
teamIdStringSpark Team Memebership ID
personEmailStringEmail address of person to add
isModeratorBooleanBoolean value to add as moderator

Example

spark.teamMembershipAdd('Tm90aGluZyB0byBzZWUgaGVy', 'aperson@company.com')
  .then(tm => console.log(tm.personEmail))
  .catch(err => console.error(err));

Example

const teamMembershipObj = {
  personEmail: 'test@test.com',
  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

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

ParamTypeDescription
membershipIdStringSpark 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

ParamTypeDescription
[webhookSearch]ObjectWebhook Search object
[max]IntegerNumber 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

ParamTypeDescription
webhookIdStringSpark 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

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

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

ParamTypeDescription
webhookIdStringSpark 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

ParamTypeDescription
secretStringValue of secret used when creating webhook
signatureStringValue of "X-Spark-Signature" from header
payloadString | ObjectThis 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

ParamTypeDescription
reqObjectrequest object
[res]Objectresponse object
[next]functionnext function

File : object

File Object

Kind: global namespace
Properties

NameTypeDescription
nameStringFile name
extStringFile extension
typeStringHeader [content-type] for file
binaryBufferFile contents as binary
base64StringFile contents as base64 encoded string

Event : object

Event Object

Kind: global namespace
Properties

NameTypeDescription
idStringEvent ID
resourceStringEvent resource
typeStringEvent type
actorIdStringPerson ID that triggered event
orgIdStringOrganzation ID that event occurred in
appIdStringApplication ID
createdStringDate Event created (ISO 8601)
dataObjectEvent data object

License : object

License Object

Kind: global namespace
Properties

NameTypeDescription
idStringLicense ID
nameStringLicense name
totalUnitsIntegerTotal units of license available
consumedUnitsIntegerNumber of license units consumed

Membership : object

Membership Object

Kind: global namespace
Properties

NameTypeDescription
idStringMembership ID
roomIdStringRoom ID
personIdStringPerson ID
personEmailStringPerson Email
isModeratorBooleanMembership is a moderator
isMonitorBooleanMembership is a monitor
createdStringDate Membership created (ISO 8601)

Message : object

Message Object

Kind: global namespace
Properties

NameTypeDescription
idStringMessage ID
roomIdStringRoom ID
roomTypeStringRoom Type
toPersonIdStringPerson ID
toPersonEmailStringPerson Email
textStringMessage text
markdownStringMessage markdown
filesArray.<String>Array of File URLs
personIdStringPerson ID
personEmailStringPerson Email
createdStringDate Message created (ISO 8601)
mentionedPeopleArray.StringPerson IDs of those mentioned in Message

Organization : object

Organization Object

Kind: global namespace
Properties

NameTypeDescription
idStringOrganization ID
displayNameStringOrganization name
createdStringDate Organization created (ISO 8601)

Person : object

Person Object

Kind: global namespace
Properties

NameTypeDescription
idStringPerson ID
emailsArray.StringArray of email addresses
displayNameStringDisplay name
firstNameStringFirst name
lastNameStringLast name
avatarStringAvatar URL
orgIdStringOrganization ID
rolesArray.StringArray of assigned Role IDs
licensesArray.StringArray of assigned License IDs
createdStringDate created (ISO 8601)

Role : object

Role Object

Kind: global namespace
Properties

NameTypeDescription
idStringRole ID
nameStringRole name

Room : object

Room Object

Kind: global namespace
Properties

NameTypeDescription
idStringRoom ID
titleStringRoom Title
typeStringRoom Type
isLockedBooleanRoom Moderated/Locked
teamIdStringTeam ID
lastActivityStringLast Activity in Room (ISO 8601)
creatorIdStringperson ID of Room creator (ISO 8601)
createdStringRoom Created (ISO 8601)

Team : object

Team Object

Kind: global namespace
Properties

NameTypeDescription
idStringMessage ID
nameStringTeam name
createdStringDate Team created (ISO 8601)

TeamMembership : object

Team Membership Object

Kind: global namespace
Properties

NameTypeDescription
idStringMembership ID
teamIdStringTeam ID
personIdStringPerson ID
personEmailStringPerson Email
isModeratorBooleanMembership is a moderator
createdStringDate Membership created (ISO 8601)

Webhook : object

Webhook Object

Kind: global namespace
Properties

NameTypeDescription
idStringWebhook ID
nameStringWebhook name
targetUrlStringWebhook target URL
resourceStringWebhook resource
eventStringWebhook event
filterStringWebhook filter
createdStringDate 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

ParamTypeDescription
filePathStringAbsolute 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

ParamTypeDescription
dirPathStringAbsolute 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

ParamTypeDescription
tokenStringCisco Spark Token

Validator.isEmail(email) ⇒ Boolean

Validate String is Email.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
emailStringEmail address string

Validator.isEmails(emails) ⇒ Boolean

Validate Emails in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
emailsArrayArray of Email address string

Validator.isUrl(url) ⇒ Boolean

Validate String is URL.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
urlStringURL String

Validator.isFilePath(path) ⇒ Boolean

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

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
pathStringString to test

Validator.isOptions(options) ⇒ Boolean

Validate Options object

Kind: static method of Validator
Returns: Boolean - result

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

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

ParamTypeDescription
eventEventEvent object

Validator.isEvents(events) ⇒ Boolean

Validate Spark Event Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
eventsArrayArray of Event objects

Validator.isEventSearch(searchObj) ⇒ Boolean

Validate Spark Event Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjEventSearchEventSearch object

Validator.isLicense(license) ⇒ Boolean

Validate Spark License Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
licenseLicenseLicense object

Validator.isLicenses(licenses) ⇒ Boolean

Validate Spark License Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
licensesArrayArray of License objects

Validator.isLicenseSearch(searchObj) ⇒ Boolean

Validate Spark License Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjLicenseSearchLicenseSearch object

Validator.isMembership(membership) ⇒ Boolean

Validate Spark Membership Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
membershipMembershipMembership object

Validator.isMemberships(memberships) ⇒ Boolean

Validate Spark Membership Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
membershipsArrayArray of Membership objects

Validator.isMembershipSearch(searchObj) ⇒ Boolean

Validate Spark Membership Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjMembershipSearchMembershipSearch object

Validator.isMessage(message) ⇒ Boolean

Validate Spark Message Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
messageMessageMessage object

Validator.isMessages(messages) ⇒ Boolean

Validate Spark Message Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
messagesArrayArray of Message objects

Validator.isMessageSearch(searchObj) ⇒ Boolean

Validate Spark Message Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjMessageSearchMessageSearch object

Validator.isOrganization(organization) ⇒ Boolean

Validate Spark Organization Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
organizationOrganizationOrganization object

Validator.isOrganizations(organizations) ⇒ Boolean

Validate Spark Organizations Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
organizationsArrayArray of Organization objects

Validator.isPerson(person) ⇒ Boolean

Validate Spark Person Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
personPersonPerson object

Validator.isPeople(people) ⇒ Boolean

Validate Spark Person Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
peopleArrayArray of Person objects

Validator.isPersonSearch(searchObj) ⇒ Boolean

Validate Spark Person Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjPersonSearchPerson Search object

Validator.isRole(role) ⇒ Boolean

Validate Spark Role Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
roleRoleRole object

Validator.isRoles(roles) ⇒ Boolean

Validate Spark Role Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
rolesArrayArray of Role objects

Validator.isRoom(room) ⇒ Boolean

Validate Spark Room Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
roomRoomRoom Object

Validator.isRooms(rooms) ⇒ Boolean

Validate Spark Room Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
roomsArrayArray of Room objects

Validator.isRoomSearch(searchObj) ⇒ Boolean

Validate Spark Room Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjRoomSearchRoomSearch object

Validator.isTeam(team) ⇒ Boolean

Validate Spark Team Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
teamTeamTeam object

Validator.isTeams(teams) ⇒ Boolean

Validate Spark Team Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
teamsArrayArray of Team objects

Validator.isTeamMembership(teamMembership) ⇒ Boolean

Validate Spark Team Membership Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
teamMembershipTeamMembershipTeamMembership object

Validator.isTeamMemberships(teamMemberships) ⇒ Boolean

Validate Spark Team Membership Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
teamMembershipsArrayArray of TeamMembership objects

Validator.isTeamMembershipSearch(searchObj) ⇒ Boolean

Validate Spark Team Memebership Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjTeamMembershipSearchTeamMembership object

Validator.isWebhook(webhook) ⇒ Boolean

Validate Spark Webhook Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
webhookWebhookWebhook object

Validator.isWebhooks(webhooks) ⇒ Boolean

Validate Spark Webhook Objects in Array.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
webhooksArrayArray of Webhook objects

Validator.isWebhookSearch(searchObj) ⇒ Boolean

Validate Spark Webhook Search Object.

Kind: static method of Validator
Returns: Boolean - result

ParamTypeDescription
searchObjWebhookSearchTeamMembership object

"memberships"

Webhook membership event

Kind: event emitted
Properties

NameTypeDescription
eventStringTriggered event (created, updated, deleted)
membershipObject.<Membership>Membership Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"messages"

Webhook messages event

Kind: event emitted
Properties

NameTypeDescription
eventStringTriggered event (created, deleted)
messageObject.<Message>Message Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"rooms"

Webhook rooms event

Kind: event emitted
Properties

NameTypeDescription
eventStringTriggered event (created, updated)
roomObject.<Room>Room Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"memberships-created"

Webhook Memberships Created event

Kind: event emitted
Properties

NameTypeDescription
membershipObject.<Membership>Membership Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"memberships-updated"

Webhook Memberships Updated event

Kind: event emitted
Properties

NameTypeDescription
membershipObject.<Membership>Membership Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"memberships-deleted"

Webhook Memberships Deleted event

Kind: event emitted
Properties

NameTypeDescription
membershipObject.<Membership>Membership Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"messages-created"

Webhook Messages Created event

Kind: event emitted
Properties

NameTypeDescription
messageObject.<Message>Message Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"messages-deleted"

Webhook Messages Deleted event

Kind: event emitted
Properties

NameTypeDescription
messageObject.<Message>Message Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"rooms-created"

Webhook Rooms Created event

Kind: event emitted
Properties

NameTypeDescription
messageObject.<Room>Room Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"rooms-updated"

Webhook Rooms Updated event

Kind: event emitted
Properties

NameTypeDescription
messageObject.<Room>Room Object found in Webhook
reqBodyObject.<RequestBody>Full Webhook Body Object

"request"

Webhook request event

Kind: event emitted
Properties

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial