Class Session

Extends Resource.
Session Resource
Defined in: session.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Session(spire, data) Represents a session in the spire api.

Field Summary
Field Attributes	Field Name and Description
	data Actual data from the spire.io api.
	spire Reference to spire object.

Method Summary
Method Attributes	Method Name and Description
	account(cb) Gets the account resource.
	account$(cb) Gets the account resource.
	applicationByName(applicationName, cb) Gets an application by name.
	applications(cb) Gets the applications collection.
	applications$(cb) Gets the applications collection.
	channelByName(channelName, cb) Gets a channel by name.
	channels(cb) Gets the channels collection.
	channels$(cb) Gets the channels collection.
	createApplication(name, cb) Creates an application.
	createChannel(name, limit, cb) Creates a channel.
	createSubscription(options, cb) Creates a subscription to any number of channels.
	findOrCreateChannel(name, limit, cb) Find or creates a channel
	findOrCreateSubscription(Subscription, channelOrChannels, cb) Gets a subscription to the given channels.
	get(cb) Gets the Session resource.
	publish(channelName, message, cb) Publish to a channel.
	resetAccount(cb) Resets the account resource.
	subscribe(channelOrChannels, options, listener, cb) Creates an new subscription to a channel or channels, and adds a listener.
	subscriptionByName(subscriptionName, cb) Gets a subscription by name.
	subscriptions(cb) Gets the subscriptions collection.
	subscriptions$(cb) Gets the subscriptions collection.

Methods borrowed from class Resource:: authorization, capabilities, capability, getIfCapable, mediaType, request, schema, update, url

Class Detail

Session(spire, data)

Represents a session in the spire api.

Sessions contain other resources, like channels and subscriptions. These can be accessed in the session.resources object.

One important resource inside session is the account resource session.account, which is only given to sessions authenticated with an email and password. The account resource is documented in its own class.

Session objects maintain lists of channels and subscriptions. If you call the session.channels or session.subscriptions methods, you will get back cached data if it exists. Use the $ cache-bypass methods: session.channels$ and session.subscriptions$ to get fresh data from the api.

Parameters:
{object} spire: Spire object
{object} data: Session data from the spire api

Field Detail

data

Actual data from the spire.io api.

spire

Reference to spire object.

Method Detail

account(cb)

Gets the account resource. Only available to sessions that are authenticated with an email and password. Returns a value from the cache, if one if available.

session.account(function (err, account) {
  if (!err) {
    // `account` is account resource.
  }
});

Parameters:
{function (err|account)} cb: Callback

account$(cb)

Gets the account resource. Only available to sessions that are authenticated with an email and password. Always gets a fresh value from the api.

session.account$(function (err, account) {
  if (!err) {
    // `account` is account resource.
  }
});

Parameters:
{function (err|account)} cb: Callback

applicationByName(applicationName, cb)

Gets an application by name. Returns an Application resource Always gets a fresh value from the api.

session.applicationByName('name_of_application', function (err, application) {
  if (!err) {
    // `application` now contains an application object
  }
});

Parameters:
{String} applicationName: Name of application
{function (err|application)} cb: Callback

applications(cb)

Gets the applications collection. Returns a hash of Application resources. Returns a value from the cache, if one if available.

session.applications(function (err, applications) {
  if (!err) {
    // `applications` is a hash of all the account's applications
  }
});

Parameters:
{function (err|applications)} cb: Callback

applications$(cb)

Gets the applications collection. Returns a hash of Application resources. Always gets a fresh value from the api.

session.applications$(function (err, applications) {
  if (!err) {
    // `applications` is a hash of all the account's applications
  }
});

Parameters:
{function (err|applications)} cb: Callback

channelByName(channelName, cb)

Gets a channel by name. Returns a Channel resource Always gets a fresh value from the api.

session.channelByName('name_of_channel', function (err, channel) {
  if (!err) {
    // `channel` now contains a channel object
  }
});

Parameters:
{String} channelName: Name of channel
{function (err|channel)} cb: Callback

channels(cb)

Gets the channels collection. Returns a hash of Channel resources. Returns a value from the cache, if one if available.

session.channels(function (err, channels) {
  if (!err) {
    // `channels` is a hash of all the account's channels
  }
});

Parameters:
{function (err|channels)} cb: Callback

channels$(cb)

Gets the channels collection. Returns a hash of Channel resources. Always gets a fresh value from the api.

session.channels$(function (err, channels) {
  if (!err) {
    // `channels` is a hash of all the account's channels
  }
});

Parameters:
{function (err|channels)} cb: Callback

createApplication(name, cb)

Creates an application. Returns an application resource. Errors if an application with the specified name exists.

session.createApplication('name_of_application', function (err, application) {
  if (!err) {
    // `application` now contains a application object
  }
});

Parameters:
{string} name: Application name
{function (err|application)} cb: Callback

createChannel(name, limit, cb)

Creates a channel. Returns a Channel resource. Errors if a channel with the specified name exists.

session.createChannel('foo', function (err, channel) {
  if (!err) {
    // `channel` is the channel named "foo".
  }
});

Parameters:
{string} name: Channel name
{number} limit Optional: Number of messages to keep in channel
{function (err|channel)} cb: Callback

createSubscription(options, cb)

Creates a subscription to any number of channels. Returns a Subscription resource. Errors if a subscription with the specified name exists.

session.findOrCreateSubscription({
  name: 'my-sub',
  channelNames: ['foo', 'bar']
},
function (err, subscription) {
  if (!err) {
    // `subscription` is the new subscription
  }
});

Parameters:
{object} options: Options
{string} options.name: Subscription name
{array} options.channelNames: Channel names to subscribe to
{array} options.channelUrls: Channel urls to subscribe to
{number} options.expiration: Subscription expiration (ms)
{function (err|subscription)} cb: Callback

findOrCreateChannel(name, limit, cb)

Find or creates a channel

session.findOrCreateChannel('foo', function (err, channel) {
  if (!err) {
    // `channel` is the channel named "foo".
  }
});

Parameters:
{string} name: Channel name to get or create
{number} limit Optional: Number of messages to keep in channel
{function(err|channel)} cb: Callback

findOrCreateSubscription(Subscription, channelOrChannels, cb)

Gets a subscription to the given channels. Creates the channels and the subscription if necessary.

session.findOrCreateSubscription('mySubscription', ['foo', 'bar'], function (err, subscription) {
  if (!err) {
    // `subscription` is a subscription named 'mySubscription', listening on channels named 'foo' and 'bar'.
  }
});

Parameters:
{string} Subscription: name
{array or string} channelOrChannels: Either a single channel name, or an array of channel names to subscribe to
{function (err|subscription)} cb: Callback

get(cb)

Gets the Session resource.

Parameters:
{function (err|session)} cb: Callback

publish(channelName, message, cb)

Publish to a channel. Creates the channel if necessary.

session.publish('my_channel', 'my message', function (err, message) {
  if (!err) {
    //  Message sent successfully
  }
});

Parameters:
{string} channelName: Channel name
{object|string} message: Message
{function (err|message)} cb: Callback

resetAccount(cb)

Resets the account resource. Only available to sessions that are authenticated with an email and password. *

session.resetAccount(function (err, session) {
  if (!err) {
    // `session` is session with new account resource.
  }
});

Parameters:
{function (err|session)} cb: Callback

subscribe(channelOrChannels, options, listener, cb)

Creates an new subscription to a channel or channels, and adds a listener.

session.subscribe('myChannel', options, function (messages) {
  // `messages` is array of messages sent to the channel
}, function (err) {
  // `err` will be non-null if there was a problem creating the subscription.
});

By default this will get all events from the beginning of time.
If you only want messages created from this point forward, pass { last: 'now' } in the options:

session.subscribe('myChannel', options, function (messages) {
  // `messages` is array of messages sent to the channel
}, function (err) {
  // `err` will be non-null if there was a problem creating the subscription.
});

Parameters:
{array or string} channelOrChannels: Either a single channel name, or an array of channel names to subscribe to
{object} options Optional: Options to pass to the listener
{function (messages)} listener: Listener that will get called with each batch of messages
{function (err|subscription)} cb Optional: Callback

subscriptionByName(subscriptionName, cb)

Gets a subscription by name. Returns a Subscription resource Always gets a fresh value from the api.

session.subscriptionByName('name_of_subscription', function (err, subscription) {
  if (!err) {
    // `subscription` now contains a subscription object
  }
});

Parameters:
{String} subscriptionName: Name of subscription
{function (err|subscription)} cb: Callback

subscriptions(cb)

Gets the subscriptions collection. Returns a hash of Subscription resources. Returns a value from the cache, if one if available.

session.subscriptions(function (err, subscriptions) {
  if (!err) {
    // `subscriptions` is a hash of all the account's subscriptions
  }
});

Parameters:
{function (err|channels)} cb: Callback

subscriptions$(cb)

Gets the subscriptions collection. Returns a hash of Subscription resources. Always gets a fresh value from the api.

session.subscriptions$(function (err, subscriptions) {
  if (!err) {
    // `subscriptions` is a hash of all the account's subscriptions
  }
});

Parameters:
{function (err|subscriptions)} cb: Callback

Classes

Class Session