Merge pull request #50 from kmck/kmck/tumblr.js-1.0.0

tumblr.js v1.0.0

.gitignore

@@ -1,9 +1,7 @@
-credentials.json
-.idea
 node_modules
-
-coverage.html
-lib-cov
-
+.DS_Store
+*.log
 *.swp
-*.swo
+*.bak
+credentials*.json
+coverage

.travis.yml

@@ -1,6 +1,8 @@
 notifications:
   email:
-    - john.crepezzi@gmail.com
+    - keith@tumblr.com
 language: node_js
-rvm:
-  - 0.8
+node_js:
+  - "5"
+  - "4"
+  - "0.12"

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-We want to make contributing to tumblr.js as easy and transparent as possible. If you run into problems, please open an issue. We also actively welcome pull requests.
+We want to make contributing to `tumblr.js` as easy and transparent as possible. If you run into problems, please open an issue. We also actively welcome pull requests.
 
 ## Pull Requests
 

LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2013 Tumblr, Inc.
+   Copyright 2013-2016 Tumblr, Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,14 +1,35 @@
 # tumblr.js
 
-[![Build Status](https://secure.travis-ci.org/tumblr/tumblr.js.png)](http://travis-ci.org/tumblr/tumblr.js)
+[![Build Status](https://travis-ci.org/tumblr/tumblr.js.svg?branch=master)](https://travis-ci.org/tumblr/tumblr.js)
 
-JavaScript client library for the
-[Tumblr API](http://www.tumblr.com/docs/en/api/v2) /
-npm: https://npmjs.org/package/tumblr.js
+The official JavaScript client library for the [Tumblr API](http://www.tumblr.com/docs/api/v2).
 
-## Create a Client
+## Installation
 
-``` javascript
+Install this package from [npm](https://www.npmjs.com/package/tumblr.js):
+
+    npm install --save tumblr.js
+
+## Usage
+
+### Authentication
+
+Different API methods use different kinds of authentication.
+
+Most of them require at least an API key, which will require you to [register an application](https://www.tumblr.com/oauth/apps). The **OAuth Consumer Key** is your API key.
+
+For methods that require a fully signed request, you'll need OAuth tokens as well, which you get from authenticating as a Tumblr user and allowing access to your API application. Here's the easy way to do it with our own account:
+
+1. Visit the [OAuth applications page](https://www.tumblr.com/oauth/apps)
+2. Click "Explore API" on the application you want to authorize
+3. Click the "Allow" button, which will take you to the [API console](https://api.tumblr.com/console)
+4. Click the "Show keys" button, which will show you the credentials you can use to make signed requests.
+
+If you're building an application of your own for users out in the world, you'll need to go through the 3-legged OAuth flow. See the [help docs](https://www.tumblr.com/docs/api/v2#auth) for more info.
+
+### In Node.js
+
+```js
 var tumblr = require('tumblr.js');
 var client = tumblr.createClient({
   consumer_key: '<consumer key>',
@@ -20,32 +41,34 @@ var client = tumblr.createClient({
 
 Or, if you prefer:
 
-``` javascript
+```js
 var tumblr = require('tumblr.js');
 var client = new tumblr.Client({
-	// ...
+  // ...
 });
 ```
 
+### In the Browser
+
+Due to CORS restrictions, you're going to have a really hard time using this library in the browser. Although GET endpoints on the Tumblr API support JSONP, this library is not intended for in-browser use. Sorry!
+
 ## Example
 
-``` javascript
+```js
 // Show user's blog names
-client.userInfo(function (err, data) {
-	data.user.blogs.forEach(function (blog) {
-		console.log(blog.name);
-	});
+client.userInfo(function(err, data) {
+  data.user.blogs.forEach(function(blog) {
+    console.log(blog.name);
+  });
 });
 ```
 
 ## Supported Methods
 
-Below is a list of available methods and their purpose.  Available options
-are documented on http://www.tumblr.com/docs/en/api/v2 and are specified as
-a JavaScript object, for example:
+Below is a list of available methods and their purpose. Available options are documented in the [API Docs](https://www.tumblr.com/docs/api/v2) and are specified as a JavaScript object.
 
-``` javascript
-client.posts('seejohnrun', { type: 'photo' }, function (err, resp) {
+```js
+client.blogPosts('staff', {type: 'photo'}, function(err, resp) {
   resp.posts; // use them for something
 });
 ```
@@ -54,121 +77,153 @@ In most cases, since options are optional (heh) they are also an optional
 argument, so there is no need to pass an empty object when supplying no options,
 like:
 
-``` javascript
-client.posts('seejohnrun', function (err, resp) {
+```js
+client.blogPosts('staff', function(err, resp) {
   resp.posts; // now we've got all kinds of posts
 });
 ```
 
-
 ### User Methods
 
-``` javascript
+```js
 // Get information about the authenticating user & their blogs
 client.userInfo(callback);
 
 // Get dashboard for authenticating user
-client.dashboard(options, callback);
-client.dashboard(callback);
+client.userDashboard(options, callback);
+client.userDashboard(callback);
 
 // Get likes for authenticating user
-client.likes(options, callback);
-client.likes(callback);
+client.userLikes(options, callback);
+client.userLikes(callback);
 
 // Get followings for authenticating user
-client.following(options, callback);
-client.following(callback);
+client.userFollowing(options, callback);
+client.userFollowing(callback);
 
 // Follow or unfollow a given blog
-client.follow(blogURL, callback);
-client.unfollow(blogURL, callback);
+client.followBlog(blogURL, callback);
+client.unfollowBlog(blogURL, callback);
 
 // Like or unlike a given post
-client.like(id, reblogKey, callback);
-client.unlike(id, reblogKey, callback);
+client.likePost(id, reblogKey, callback);
+client.unlikePost(id, reblogKey, callback);
 ```
 
 ### Blog Methods
 
-``` javascript
+```js
 // Get information about a given blog
 client.blogInfo(blogName, callback);
 
 // Get a list of posts for a blog (with optional filtering)
-client.posts(blogName, options, callback);
-client.posts(blogName, callback);
+client.blogPosts(blogName, options, callback);
+client.blogPosts(blogName, callback);
 
 // Get the avatar URL for a blog
-client.avatar(blogName, size, callback);
-client.avatar(blogName, callback);
+client.blogAvatar(blogName, size, callback);
+client.blogAvatar(blogName, callback);
 
 // Get the likes for a blog
 client.blogLikes(blogName, options, callback);
 client.blogLikes(blogName, callback);
 
 // Get the followers for a blog
-client.followers(blogName, options, callback);
-client.followers(blogName, callback);
+client.blogFollowers(blogName, options, callback);
+client.blogFollowers(blogName, callback);
 
 // Get the queue for a blog
-client.queue(blogName, options, callback);
-client.queue(blogName, callback);
+client.blogQueue(blogName, options, callback);
+client.blogQueue(blogName, callback);
 
 // Get the drafts for a blog
-client.drafts(blogName, options, callback);
-client.drafts(blogName, callback);
+client.blogDrafts(blogName, options, callback);
+client.blogDrafts(blogName, callback);
 
 // Get the submissions for a blog
-client.submissions(blogName, options, callback);
-client.submissions(blogName, callback);
+client.blogSubmissions(blogName, options, callback);
+client.blogSubmissions(blogName, callback);
 ```
 
 ### Post Methods
 
-``` javascript
+```js
 // Edit a given post
-client.edit(blogName, options, callback);
+client.editPost(blogName, options, callback);
 
 // Reblog a given post
-client.reblog(blogName, options, callback);
+client.reblogPost(blogName, options, callback);
 
 // Delete a given post
 client.deletePost(blogName, id, callback);
 
 // Convenience methods for creating post types
-client.photo(blogName, options, callback);
-client.quote(blogName, options, callback);
-client.text(blogName, options, callback);
-client.link(blogName, options, callback);
-client.chat(blogName, options, callback);
-client.audio(blogName, options, callback);
-client.video(blogName, options, callback);
+client.createTextPost(blogName, options, callback);
+client.createPhotoPost(blogName, options, callback);
+client.createQuotePost(blogName, options, callback);
+client.createLinkPost(blogName, options, callback);
+client.createChatPost(blogName, options, callback);
+client.createAudioPost(blogName, options, callback);
+client.createVideoPost(blogName, options, callback);
 ```
 
 ### Tagged Methods
 
-``` javascript
+```js
 // View posts tagged with a certain tag
-client.tagged(tag, options, callback);
-client.tagged(tag, callback);
+client.taggedPosts(tag, options, callback);
+client.taggedPosts(tag, callback);
 ```
 
----
+## Unsupported Methods
+
+You can make GET and POST requests to any endpoint directly. These methods are used internally by the methods listed above:
+
+```js
+// GET requests
+client.getRequest(apiPath, params, callback);
+
+// POST requests
+client.postRequest(apiPath, params, callback);
+```
 
-## Running tests
+In the unlikely event that we add a bunch of methods to the API docs and don't update this client, you can map new client methods to API endpoints. URL and query parameters are automatically turned into arguments to these methods. It's a little weird to explain, so just look at these examples:
+
+```js
+// GET methods
+client.addGetMethods({
+  // creates client.userInfo(params, callback)
+  userInfo: '/user/info',
+  // client.blogInfo(blogIdentifier, params, callback)
+  blogInfo: '/blog/:blogIdentifier/info',
+  // Creates client.taggedPosts(tag, params, callback)
+  taggedPosts: ['/tagged', ['tag']],
+});
 
-``` bash
-make # run tests
-make coverage # run coverage report
+// POST methods
+client.addPostMethods({
+  // client.deletePost(blogIdentifier, id, params, callback)
+  deletePost: ['/blog/:blogIdentifier/post/delete', ['id']],
+  // Creates client.likePost(tag, id, reblog_key, params, callback)
+  likePost: ['/user/like', ['id', 'reblog_key']],
+});
 ```
 
+---
+
+## Running Tests
+
+    npm test # linter and tests
+    gulp lint # linter
+    gulp test # just the tests
+
 # Copyright and license
 
-Copyright 2013 Tumblr, Inc.
+Copyright 2013-2016 Tumblr, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not
 use this work except in compliance with the License. You may obtain a copy of
-the License in the LICENSE file, or at:
+the License in the [LICENSE](LICENSE) file, or at:
 
 http://www.apache.org/licenses/LICENSE-2.0