snoowrap

Class: VoteableContent

VoteableContent

A set of mixin functions that apply to Submissions and Comments.

new VoteableContent()

Extends

Methods

upvote()

Upvotes this Comment or Submission.

Note: votes must be cast by humans. That is, API clients proxying a human's action one-for-one are OK, but bots deciding how to vote on content or amplifying a human's vote are not. See the reddit rules for more details on what constitutes vote cheating. (This guideline is quoted from the official reddit API documentation page.)

Returns:

A Promise that fulfills with this Comment/Submission when the request is complete

Type
Promise
Example
r.getSubmission('4e62ml').upvote()

downvote()

Downvotes this Comment or Submission.

Note: votes must be cast by humans. That is, API clients proxying a human's action one-for-one are OK, but bots deciding how to vote on content or amplifying a human's vote are not. See the reddit rules for more details on what constitutes vote cheating. (This guideline is quoted from the official reddit API documentation page.)

Returns:

A Promise that fulfills with this Comment/Submission when the request is complete.

Type
Promise
Example
r.getSubmission('4e62ml').downvote()

unvote()

Removes any existing vote on this Comment or Submission.

Note: votes must be cast by humans. That is, API clients proxying a human's action one-for-one are OK, but bots deciding how to vote on content or amplifying a human's vote are not. See the reddit rules for more details on what constitutes vote cheating. (This guideline is quoted from the official reddit API documentation page.)

Returns:

A Promise that fulfills with this Comment/Submission when the request is complete.

Type
Promise
Example
r.getSubmission('4e62ml').unvote()

save()

Saves this Comment or Submission (i.e. adds it to the list at reddit.com/saved)

Returns:

A Promise that fulfills when the request is complete

Type
Promise
Example
r.getSubmission('4e62ml').save()

unsave()

Unsaves this item

Returns:

A Promise that fulfills when the request is complete

Type
Promise
Example
r.getSubmission('4e62ml').unsave()

distinguish(options)

Distinguishes this Comment or Submission with a sigil.

Note: This function will only work if the requester is the author of this Comment/Submission.

Parameters:
Name Type Description
options object
Properties
Name Type Argument Default Description
status boolean | string <optional>
 true

Determines how the item should be distinguished. true (default) signifies that the item should be moderator-distinguished, and false signifies that the item should not be distinguished. Passing a string (e.g. admin) will cause the item to get distinguished with that string, if possible.
sticky boolean <optional>
 false

Determines whether this item should be stickied in addition to being distinguished. (This only applies to comments; to sticky a submission, use Submission#sticky instead.)
Returns:

A Promise that fulfills when the request is complete.

Type
Promise
Example
r.getComment('d1xclfo').distinguish({status: true, sticky: true})

undistinguish()

Undistinguishes this Comment or Submission. Alias for distinguish({status: false})

Returns:

A Promise that fulfills when the request is complete.

Type
Promise
Example
r.getSubmission('4e62ml').undistinguish()

edit(updatedText)

Edits this Comment or Submission.

Parameters:
Name Type Description
updatedText string

The updated markdown text to use
Returns:

A Promise that fulfills when this request is complete.

Type
Promise
Example
r.getComment('coip909').edit('Blah blah blah this is new updated text')

gild()

Gives reddit gold to the author of this Comment or Submission.

Returns:

A Promise that fullfills with this Comment/Submission when this request is complete

Type
Promise
Example
r.getComment('coip909').gild()

enableInboxReplies()

Enables inbox replies on this Comment or Submission

Returns:

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

Type
Promise
Example
r.getComment('coip909').enableInboxReplies()

disableInboxReplies()

Disables inbox replies on this Comment or Submission

Returns:

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

Type
Promise
Example
r.getComment('coip909').disableInboxReplies()

expandReplies( [options])

Expands the reply Listings on this Comment/Submission.

This is useful in cases where one wants to enumerate all comments on a thread, even the ones that are initially hidden when viewing it (e.g. long comment chains).

This function accepts two optional parameters options.limit and options.depth. options.limit sets an upper bound for the branching factor of the resulting replies tree, i.e. the number of comments that are fetched in reply to any given item. options.depth sets an upper bound for the depth of the resulting replies tree (where a depth of 0 signifies that no replies should be fetched at all).

Note that regardless of the limit and depth parameters used, any reply that appeared in the original reply tree will appear in the expanded reply tree. In certain cases, the depth of the resulting tree may also be larger than options.depth, if the reddit API returns more of a comment tree than needed.

These parameters should primarily be used to keep the request count low; if a precise limit and depth are needed, it is recommended to manually verify the comments in the tree afterwards.

Both parameters default to Infinity if omitted, i.e. the resulting tree contains every single comment available. It should be noted that depending on the size and depth of the thread, fetching every single comment can use up a significant number of ratelimited requests. (To give an intuitive estimate, consider how many clicks would be needed to view all the comments on the thread using the HTML site.)

Parameters:
Name Type Argument Default Description
options object <optional>
 {}
Properties
Name Type Argument Default Description
limit number <optional>
 Infinity

An upper-bound for the branching factor of the resulting tree of replies
depth number <optional>
 Infinity

An upper-bound for the depth of the resulting tree of replies
Returns:

A Promise that fulfills with a new version of this object that has an expanded reply tree. The original object is not modified

Type
Promise
Example
r.getSubmission('4fuq26').expandReplies().then(console.log)
// => (a very large comment tree containing every viewable comment on this thread)

delete()

Deletes this Comment or Submission

Returns:

A Promise that fulfills with this Comment/Submission when this request is complete

Type
Promise
Example
r.getComment('coip909').delete()

remove(options)

Removes this Comment, Submission or PrivateMessage from public listings.

This requires the authenticated user to be a moderator of the subreddit with the posts permission.

Parameters:
Name Type Description
options object
Properties
Name Type Argument Default Description
spam boolean <optional>
 false

Determines whether this should be marked as spam
Inherited From:
Returns:

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

Type
Promise
Example
r.getComment('c08pp5z').remove({spam: true})

approve()

Approves this Comment, Submission, or PrivateMessage, re-adding it to public listings if it had been removed

Inherited From:
Returns:

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

Type
Promise
Example
r.getComment('c08pp5z').approve()

report( [options])

Reports this content anonymously to subreddit moderators (for Comments and Submissions) or to the reddit admins (for PrivateMessages)

Parameters:
Name Type Argument Description
options object <optional>
Properties
Name Type Argument Description
reason string <optional>

The reason for the report
Inherited From:
Returns:

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

Type
Promise
Example
r.getComment('c08pp5z').report({reason: 'Breaking the subreddit rules'})

ignoreReports()

Ignores reports on this Comment, Submission, or PrivateMessage

Inherited From:
Returns:

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

Type
Promise
Example
r.getComment('c08pp5z').ignoreReports()

unignoreReports()

Unignores reports on this Comment, Submission, or PrivateMessages

Inherited From:
Returns:

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

Type
Promise
Example
r.getComment('c08pp5z').unignoreReports()

reply(text)

Submits a new reply to this object. (This takes the form of a new Comment if this object is a Submission/Comment, or a new PrivateMessage if this object is a PrivateMessage.)

Parameters:
Name Type Description
text string

The content of the reply, in raw markdown text
Inherited From:
Returns:

A Promise that fulfills with the newly-created reply

Type
Promise
Example
r.getSubmission('4e60m3').reply('This was an interesting post. Thanks.');

blockAuthor()

Blocks the author of this content.

Note: In order for this function to have an effect, this item must be in the authenticated account's inbox or modmail somewhere. The reddit API gives no outward indication of whether this condition is satisfied, so the returned Promise will fulfill even if this is not the case.

Inherited From:
Returns:

A Promise that fulfills with this message after the request is complete

Type
Promise
Example
r.getInbox({limit: 1}).then(messages =>
  messages[0].blockAuthor();
);

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:
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:
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:
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"}'