snoowrap

Class: LiveThread

LiveThread

A class representing a live reddit thread

new LiveThread()

For the most part, reddit distributes the content of live threads via websocket, rather than through the REST API. As such, snoowrap assigns each fetched LiveThread object a stream property, which takes the form of an EventEmitter. To listen for new thread updates, simply add listeners to that emitter.

The following events can be emitted:

  • update: Occurs when a new update has been posted in this thread. Emits a LiveUpdate object containing information about the new update.
  • activity: Occurs periodically when the viewer count for this thread changes.
  • settings: Occurs when the thread's settings change. Emits an object containing the new settings.
  • delete: Occurs when an update has been deleted. Emits the ID of the deleted update.
  • strike: Occurs when an update has been striken (marked incorrect and crossed out). Emits the ID of the striken update.
  • embeds_ready: Occurs when embedded media is now available for a previously-posted update.
  • complete: Occurs when this LiveThread has been marked as complete, and no more updates will be sent.

(Note: These event types are mapped directly from reddit's categorization of the updates. The descriptions above are paraphrased from reddit's descriptions here.)

As an example, this would log all new livethread updates to the console:

someLivethread.stream.on('update', data => {
  console.log(data.body);
});
Example
// Get a livethread with the given ID
r.getLivethread('whrdxo8dg9n0')

Extends

Methods

addUpdate(body)

Adds a new update to this thread.

Parameters:
Name Type Description
body string

The body of the new update
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').addUpdate('Breaking: Someone is reading the snoowrap documentation \\o/')

strikeUpdate(options)

Strikes (marks incorrect and crosses out) the given update.

Parameters:
Name Type Description
options object
Properties
Name Type Description
id string

The ID of the update that should be striked.
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').strikeUpdate({id: 'LiveUpdate_edc34446-faf0-11e5-a1b4-0e858bca33cd'})

deleteUpdate(options)

Deletes an update from this LiveThread.

Parameters:
Name Type Description
options object
Properties
Name Type Description
id string

The ID of the LiveUpdate that should be deleted
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').deleteUpdate({id: 'LiveUpdate_edc34446-faf0-11e5-a1b4-0e858bca33cd'})

getContributors()

Gets a list of this LiveThread's contributors

Returns:

An Array containing RedditUsers

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').getContributors().then(console.log)
// => [
//  RedditUser { permissions: ['edit'], name: 'not_an_aardvark', id: 't2_k83md' },
//  RedditUser { permissions: ['all'], id: 't2_u3l80', name: 'snoowrap_testing' }
// ]

inviteContributor(options)

Invites a contributor to this LiveThread.

Parameters:
Name Type Description
options object
Properties
Name Type Description
name string

The name of the user who should be invited
permissions Array

The permissions that the invited user should receive. This should be an Array containing some combination of 'update', 'edit', 'manage'. To invite a contributor with full permissions, omit this property.
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').inviteContributor({name: 'actually_an_aardvark', permissions: ['update']})

revokeContributorInvite(options)

Revokes an invitation for the given user to become a contributor on this LiveThread.

Parameters:
Name Type Description
options object
Properties
Name Type Description
name string

The username of the account whose invitation should be revoked
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').revokeContributorInvite({name: 'actually_an_aardvark'});

acceptContributorInvite()

Accepts a pending contributor invitation on this LiveThread.

Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').acceptContributorInvite()

leaveContributor()

Abdicates contributor status on this LiveThread.

Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').leaveContributor()

removeContributor(options)

Removes the given user from contributor status on this LiveThread.

Parameters:
Name Type Description
options object
Properties
Name Type Description
name string

The username of the account who should be removed
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').removeContributor({name: 'actually_an_aardvark'})

setContributorPermissions(options)

Sets the permissions of the given contributor.

Parameters:
Name Type Description
options object
Properties
Name Type Description
name string

The name of the user whose permissions should be changed
permissions Array

The updated permissions that the user should have. This should be an Array containing some combination of 'update', 'edit', 'manage'. To give the contributor with full permissions, omit this property.
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').setContributorPermissions({name: 'actually_an_aardvark', permissions: ['edit']})

editSettings(options)

Edits the settings on this LiveThread.

Parameters:
Name Type Description
options object
Properties
Name Type Argument Description
title string

The title of the thread
description string <optional>

A descriptions of the thread. 120 characters max
resources string <optional>

Information and useful links related to the thread.
nsfw boolean

Determines whether the thread is Not Safe For Work
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').editSettings({title: 'My livethread', description: 'an updated description'})

closeThread()

Permanently closes this thread, preventing any more updates from being added.

Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').closeThread()

report(options)

Reports this LiveThread for breaking reddit's rules.

Parameters:
Name Type Description
options object
Properties
Name Type Description
reason string

The reason for the report. One of spam, vote-manipulation, personal-information, sexualizing-minors, site-breaking
Returns:

A Promise that fulfills with this LiveThread when the request is complete

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').report({reason: 'Breaking a rule blah blah blah'})

getRecentUpdates( [options])

Gets a Listing containing past updates to this LiveThread.

Parameters:
Name Type Argument Description
options object <optional>

Options for the resulting Listing
Returns:

A Listing containing LiveUpdates

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').getRecentUpdates().then(console.log)
// => Listing [
//  LiveUpdate { ... },
//  LiveUpdate { ... },
//  ...
// ]

getDiscussions( [options])

Gets a list of reddit submissions linking to this LiveThread.

Parameters:
Name Type Argument Description
options object <optional>

Options for the resulting Listing
Returns:

A Listing containing Submissions

Type
Promise
Example
r.getLivethread('whrdxo8dg9n0').getDiscussions().then(console.log)
// => Listing [
//  Submission { ... },
//  Submission { ... },
//  ...
// ]

closeStream()

Stops listening for new updates on this LiveThread.

To avoid memory leaks that can result from open sockets, it's recommended that you call this method when you're finished listening for updates on this LiveThread.

This should not be confused with LiveThread#closeThread, which marks the thread as "closed" on reddit.

Returns:

undefined

Example
var myThread = r.getLivethread('whrdxo8dg9n0');
myThread.stream.on('update', content => {
  console.log(content);
  myThread.closeStream();
})

fetch()

Fetches this content from reddit.

This will not mutate the original content object; all Promise properties will remain as Promises after the content has been fetched. However, the information on this object will be cached, so it may become out-of-date with the content on reddit. To clear the cache and fetch this object from reddit again, use refresh().

If snoowrap is running in an environment that supports ES2015 Proxies (e.g. Chrome 49+), then fetch() will get automatically called when an unknown property is accessed on an unfetched content object.

Inherited From:
Overrides:
Returns:

A version of this object with all of its fetched properties from reddit. This will not mutate the object. Once an object has been fetched once, its properties will be cached, so they might end up out-of-date if this function is called again. To refresh an object, use refresh().

Type
Promise
Example
r.getUser('not_an_aardvark').fetch().then(userInfo => {
  console.log(userInfo.name); // 'not_an_aardvark'
  console.log(userInfo.created_utc); // 1419104352
});

r.getComment('d1xchqn').fetch().then(comment => comment.body).then(console.log)
// => 'This is a little too interesting for my liking'

// In environments that support ES2015 Proxies, the above line is equivalent to:
r.getComment('d1xchqn').body.then(console.log);
// => 'This is a little too interesting for my liking'

refresh()

Refreshes this content.

Inherited From:
Overrides:
Returns:

A newly-fetched version of this content

Type
Promise
Example
var someComment = r.getComment('cmfkyus');
var initialCommentBody = some_comment.fetch().then(comment => comment.body);

setTimeout(() => {
  someComment.refresh().then(refreshedComment => {
    if (initialCommentBody.value() !== refreshedComment.body) {
      console.log('This comment has changed since 10 seconds ago.');
    }
  });
}, 10000);

toJSON()

Returns a stringifyable version of this object.

It is usually not necessary to call this method directly; simply running JSON.stringify(some_object) will strip the private properties anyway.

Inherited From:
Overrides:
Returns:

A version of this object with all the private properties stripped

Type
object
Example
var user = r.getUser('not_an_aardvark');
JSON.stringify(user) // => '{"name":"not_an_aardvark"}'