snoowrap

Snoowrap uses an internal method snoowrap#_populate to transform raw JSON responses from Reddit into rich, typed JavaScript objects (e.g., Comment, Submission, RedditUser, Subreddit). This process replaces raw data representations with specialized snoowrap objects that provide a more intuitive API for interacting with Reddit content.

For example, a JSON response containing author and subreddit information is automatically populated into a Comment object where author and subreddit are themselves instances of RedditUser and Subreddit respectively.

// Input JSON from Reddit
{
    "kind": "t1",
    "data": {
        "author": "not_an_aardvark",
        "approved_by": "not_an_aardvark",
        "subreddit": "AskReddit",
    }
}

// Resulting snoowrap object
Comment {
  author: RedditUser {name: 'not_an_aardvark'},
  approved_by: RedditUser {name: 'not_an_aardvark'},
  subreddit: Subreddit {display_name: 'AskReddit'}
}

snoowrap uses lazy objects and ES6 Proxy to provide a highly consistent and fluent API. Most property accessors and method calls return Bluebird Promises.

Fluent Syntax and Chaining

You can chain actions together for a clean, readable syntax. For example, when creating a post, you can chain methods like .sticky(), .distinguish(), and .assignFlair().

Lazy Loading

Accessing a property like .author.name on a submission doesn't immediately fetch the data; it returns a Promise that resolves to the value. You can chain multiple API calls together in a single expression.

ES6 Proxy Support

In environments supporting ES6 Proxies (Node 6+, Chrome 49+, Firefox 18+), you can access nested properties directly. In older environments (like Node 4/5 without the --harmony_proxies flag), you must use the .fetch() method to resolve the object before accessing properties.

// With Proxy support (cleaner)
r.getSubmission('47v7tm').comments[0].upvote();

// Without Proxy support (heavier)
r.getSubmission('47v7tm').fetch().then(submission => {
  return submission.comments[0].upvote();
});

To contribute to snoowrap or run its test suite locally, follow these steps:

1. Clone and Install:

   git clone https://github.com/not-an-aardvark/snoowrap.git
   cd snoowrap/
   npm install

2. Configure OAuth Credentials: Since tests run live on Reddit, you must create an oauth_info.json file in the project root. You can use reddit-oauth-helper to generate these credentials.

   oauth_info.json structure:

   {
     "client_id": "put_your_client_id_here",
     "client_secret": "put_your_client_secret_here",
     "refresh_token": "put_your_refresh_token_here",
     "user_agent": "put_a_descriptive_useragent_string_here",
     "username": "put a username here",
     "password": "put a password here",
     "redirect_uri": "put the redirect URI here",
     "installed_app_client_id": "put_your_installed_app_client_id_here"
   }

3. Run Tests:

   npm test

   Note: Some tests (like retrieving private messages) may fail with a 403 error if your account lacks permission.

git clone https://github.com/not-an-aardvark/snoowrap.git
cd snoowrap/
npm install
# Create oauth_info.json then:
npm test

To use snoowrap, you must create a new instance with OAuth credentials. It is recommended to use environment variables or a separate config file rather than hardcoding credentials.

Using OAuth Refresh Token (Recommended)

Pass userAgent, clientId, clientSecret, and refreshToken to the constructor.

Using Username and Password (Script-type apps)

Pass userAgent, clientId, clientSecret, username, and password to the constructor.

const snoowrap = require('snoowrap');

// OAuth Refresh Token method
const r = new snoowrap({
  userAgent: 'put your user-agent string here',
  clientId: 'put your client id here',
  clientSecret: 'put your client secret here',
  refreshToken: 'put your refresh token here'
});

// Username/Password method
const otherRequester = new snoowrap({
  userAgent: 'put your user-agent string here',
  clientId: 'put your client id here',
  clientSecret: 'put your client secret here',
  username: 'put your username here',
  password: 'put your password here'
});

Below are common patterns for interacting with the Reddit API using snoowrap:

• Submitting a link: r.getSubreddit('name').submitLink({title, url})
• Getting hot posts: r.getHot() returns a collection you can iterate over.
• Expanding comments: r.getSubmission('id').expandReplies({limit, depth})
• Moderation: Use methods like .remove(), .banUser(), and .approve() on items retrieved from the modqueue.
• Wiki pages: r.getSubreddit('name').getWikiPage('page_name').content_md

// Submitting a link
r.getSubreddit('gifs').submitLink({
  title: 'Mt. Cameramanjaro',
  url: 'https://i.imgur.com/n5iOc72.gifv'
});

// Printing hot post titles
r.getHot().map(post => post.title).then(console.log);

// Automating moderation
r.getSubreddit('some_subreddit_name').getModqueue({limit: 100}).filter(someRemovalCondition).forEach(flaggedItem => {
  flaggedItem.remove();
  flaggedItem.subreddit.banUser(flaggedItem.author);
});

// Creating a stickied thread with flair
r.getSubreddit('some_subreddit_name')
  .submitSelfpost({title: 'Daily thread', text: 'Discuss things here'})
  .sticky()
  .distinguish()
  .approve()
  .assignFlair({text: 'Daily Thread flair text', css_class: 'daily-thread'})
  .reply('This is a comment that appears on that daily thread');

The snoowrap base class provides helper methods for common HTTP verbs to facilitate custom requests. These methods are wrappers around request-promise and accept standard request options.

Available helpers include:

• _get({uri, ...options})
• _post({uri, form, ...options})
• _put({uri, ...options})
• _delete({uri, ...options})

By default, request_handler.js configures these requests with the following options:

• auth: Bearer token using the user's access token.
• headers: Includes the user's user-agent.
• baseUrl: Defaults to https://oauth.reddit.com.
• qs: Includes {raw_json: 1} to prevent Reddit from escaping HTML characters.
• timeout: Uses the user's specified timeout.

// r is an instance of the snoowrap class

// Send a GET request to a specific endpoint
r._get({uri: 'r/snoowrap/about/moderators'})

// Send a POST request with form data
r._post({uri: 'api/remove', form: {id: 't3_2np694'}})