Permalink
Browse files

Completed documentation for docco

  • Loading branch information...
1 parent a2be8ff commit f79defe2c3a756efa7be2e9a021508f9a0c3077c @andreareginato andreareginato committed Jan 22, 2013
Showing with 154 additions and 82 deletions.
  1. +3 −0 .gitignore
  2. +4 −48 README.md
  3. +10 −9 lib/client/access-token.js
  4. +4 −5 lib/client/auth-code.js
  5. +4 −4 lib/client/password.js
  6. +129 −16 lib/simple-oauth2.js
View
@@ -17,3 +17,6 @@ node_modules
# Procfile env
*.env
+
+# Docs
+docs/
View
@@ -21,15 +21,8 @@ Install the client library using git:
$ npm install
-## Documentation
-
-* [Simple Oauth2 Docs](git://andreareginato.github.com/simple-oauth2)
-
-
## Getting started
-### Get the Access Token
-
```javascript
var credentials = { client: { id: 'client-id', secret: 'client-secret', site: 'https://example.org' } };
var OAuth2 = require('simple-oauth2')(credentials);
@@ -45,51 +38,14 @@ OAuth2.AuthCode.getToken(params, function(error, result) {
})
```
-### Refresh the Access Token
-
-```javascript
-
-token = OAuth2.AccessToken.create(json_token);
-if (token.expired()) {
- token.refresh(function(error, refreshedToken) { token = refreshedToken; })
-}
-```
+## Documentation
-### Authorization Grants
Currently the Authorization Code and Resource Owner Password Credentials grant types
-have helper strategy classes that simplify client use. They are available via the #authCode
-and #password methods respectively.
-
-```javascript
-// Authorization code flow
-var uri = OAuth2.AuthCode.authorizeURL({ redirect_uri: 'http://localhost:3000/callback');
-var token = OAuth2.AuthCode.getToken({ code: 'authorization-code', redirectURI: 'http://localhost:3000/callback' }, callback);
+have helper strategy classes that simplify client use. They are available respectively
+via #AuthCode and #Password.
+Check out the complete [Simple Oauth2 Documentation](git://andreareginato.github.com/simple-oauth2)
-// Password credentials flow
-var token = OAuth2.Password.getToken({ username: 'username', 'password': 'password' }, callback);
-```
-
-If the functions fails an error object is passed as first argument to the callback.
-The body response object is always the last argument.
-
-
-## Errors
-
-Exceptions are raised when a 4xx or 5xx status code is returned.
-
-```javascript
-OAtuh2.HTTPError
-```
-
-Through the error message attribute you can access the JSON representation
-based on HTTP `status` and error `message`.
-
-```javascript
-OAuth2.AuthCode.getToken(function(error, token) {
- if (error) { console.log(error.message); }
-});
-```
## Contributing
@@ -1,15 +1,15 @@
//
-// Access Token class
+// ### Wrapper for the Access Token object
//
module.exports = function(config) {
var core = require('./../core')(config);
require('date-utils');
- // Returns the OAuth2.AccessToken instance.
+ //
+ // ### Creates an OAuth2.AccessToken instance.
//
// * `token` - An object containing the token object returned from the OAuth2 server.
- // maintain state between the request and the callback.
//
function create(token) {
this.token = token;
@@ -19,21 +19,22 @@ module.exports = function(config) {
//
- // Returns true if the token is expired, false otherwise.
+ // ### Check if the access token is expired or not.
//
- function expired() {
+ function expired() {
return (Date.compare(this.token.expires_at, new Date) == -1) ? false : true
}
//
- // Refresh the access token
+ // ### Refresh the access token
//
// * `callback` - The callback function returning the results.
- // An error object is passed as first argument and the result as last.
+ // An error object is passed as first argument and the new access
+ // token as last.
//
- function refresh(callback) {
- var params = { grant_type: 'refresh_token', refresh_token: this.token.refresh_token };
+ function refresh(callback) {
+ var params = { grant_type: 'refresh_token', refresh_token: this.token.refresh_token };
core.api('POST', config.tokenPath, params, callback);
}
@@ -1,13 +1,12 @@
//
-// Authorization Code flow implementation
+// ### Authorization Code flow implementation
//
module.exports = function(config) {
var core = require('./../core')(config),
qs = require('querystring');
- // Returns the OAuth2 authorization URI where the user decides to
- // grant or deny the resources' access.
+ // ### Redirect the user to the authorization page
//
// * `params.redirectURI` - A String that represents the registered application URI where the
// user is redirected after authorization.
@@ -23,9 +22,9 @@ module.exports = function(config) {
}
//
- // Returns the Access Token object.
+ // ### Returns the Access Token object.
//
- // * `params.code` - Authorization code (from the authorization step).
+ // * `params.code` - Authorization code (from previous step).
// * `params.redirectURI` - A String that represents the callback uri.
// * `callback` - The callback function returning the results.
// An error object is passed as first argument and the result as last.
@@ -1,15 +1,15 @@
//
-// Password credentials flow implementation
+// ### Password credentials flow implementation
//
module.exports = function(config) {
var core = require('./../core')(config);
//
- // Returns the Access Token object.
+ // ### Returns the Access Token object.
//
- // * `params.username` - Authorization code (from the authorization step).
- // * `params.password` - A String that represents the callback uri.
+ // * `params.username` - A string that represents the registered username.
+ // * `params.password` - A string that represents the registered password.
// * `params.scope` - A String that represents the application privileges.
// * `callback` - The callback function returning the results.
// An error object is passed as first argument and the result as last.
View
@@ -1,6 +1,123 @@
//
-// A NodeJS module for interfacing with OAuth2. It accepts
-// an object with the following valid params.
+// **Node.js client library for [OAuth2](http://oauth.net/2/)**
+//
+// **[Github repository](https://github.com/andreareginato/simple-oauth2)**
+//
+// OAuth2 lets users grant the access to the desired resources to third party applications,
+// giving them the possibility to enable and disable those accesses whenever they want.
+//
+// Simple OAuth2 supports the following flows.
+//
+// * Authorization Code Flow (for apps with servers that can store persistent information).
+// * Password Credentials (when previous flow can't be used or during development).
+//
+// ### Authorization Code flow implementation
+//
+// The Authorization Code flow is made up from two parts. At first your application asks to
+// the user the permission to access their data. If the user approves Lelylan sends to the
+// client an authorization code. In the second part, the client POST the authorization code
+// along with its client secret to the Lelylan in order to get the access token.
+// [Learn more about](auth-code.html).
+//
+//
+// // Set the client credentials
+// var credentials = { client: {
+// id: '<client-id>',
+// secret: '<client-secret>',
+// site: 'https://example.org'
+// }};
+//
+// // Initialize the OAuth2 Library
+// var OAuth2 = require('simple-oauth2')(credentials);
+//
+// // Authorization OAuth2 URI
+// var authorization_uri = OAuth2.AuthCode.authorizeURL({
+// redirect_uri: 'http://localhost:3000/callback'
+// });
+//
+// // Redirect example using Express
+// // See http://expressjs.com/api.html#res.redirect
+// res.redirect(authorization_uri);
+//
+// // Get the access token object.
+// // The authorization code is given from the previous step.
+// var token;
+// OAuth2.AuthCode.getToken({
+// code: 'authorization-code',
+// redirectURI: 'http://localhost:3000/callback'
+// }, function(error, result) { token = result });
+//
+// // Create the access token wrapper
+// var token = OAuth2.AccessToken.create(json_token);
+//
+// // Check if the token is expired. If expired it is refreshed.
+// if (token.expired()) {
+// token.refresh(function(error, result) {
+// token = result;
+// })
+// }
+//
+//
+// ### Password Credentials Flow
+//
+// This flow is suitable when the resource owner has a trust relationship with the
+// client, such as its computer operating system or a highly privileged application.
+// Use this flow only when other flows are not viable or when you need a fast way to
+// test your application. [Learn more about](password.html).
+//
+//
+// // Get the access token object.
+// var token;
+// OAuth2.Password.getToken({
+// username: 'username',
+// password: 'password' 
+// }, function(error, result) { token = result });
+//
+//
+// ### Access Token object
+//
+// When a token expires we need to refresh it. Simple OAuth2 offers the
+// AccessToken class that add a couple of useful methods to refresh the
+// access token when it is expired. [Learn more about](access-token.html).
+//
+//
+// // Get the access token object.
+// var token;
+// OAuth2.AuthCode.getToken({
+// code: 'authorization-code',
+// redirectURI: 'http://localhost:3000/callback'
+// }, function(error, result) { token = result });
+//
+// // Create the access token wrapper
+// var token = OAuth2.AccessToken.create(json_token);
+//
+// // Check if the token is expired. If expired it is refreshed.
+// if (token.expired()) {
+// token.refresh(function(error, result) {
+// token = result;
+// })
+// }
+//
+//
+// ### Errors
+//
+// Exceptions are raised when a 4xx or 5xx status code is returned.
+//
+// OAtuh2.HTTPError
+//
+// Through the error message attribute you can access the JSON representation
+// based on HTTP `status` and error `message`.
+//
+// OAuth2.AuthCode.getToken(function(error, token) {
+// if (error) { console.log(error.message); }
+// });
+// // => { "status": "401", "message": "Unauthorized" }
+//
+
+//
+// ### Configurations
+//
+// Simple OAuth2 accepts an object with the following valid params.
//
// * `client.id` - Required registered Client ID.
// * `client.secret` - Required registered Client secret.
@@ -10,36 +127,32 @@
// * `tokenPath` - Access token path for the OAuth2 server.
// Simple Oauth2 uses `/oauth/token` as default.
//
+//
var appConfig = require('./config');
-
-// Configuration merge
-function mergeDefaults(o1, o2) {
- for (var p in o2) {
- try { if (typeof o2[p] == 'object') { o1[p] = mergeDefaults(o1[p], o2[p]); } else if (typeof o1[p] == 'undefined') { o1[p] = o2[p]; } }
- catch(e) { o1[p] = o2[p]; }
- }
- return o1;
-}
-
-
-// Export the client we'll use to make requests
module.exports = function(config) {
- // Base configuration
function configure(config) {
config = config || {};
mergeDefaults(config, appConfig);
-
return config;
}
config = configure(config);
var core = require('./core')(config);
+ function mergeDefaults(o1, o2) {
+ for (var p in o2) {
+ try { if (typeof o2[p] == 'object') { o1[p] = mergeDefaults(o1[p], o2[p]); } else if (typeof o1[p] == 'undefined') { o1[p] = o2[p]; } }
+ catch(e) { o1[p] = o2[p]; }
+ }
+ return o1;
+ }
+
return {
'AuthCode': require('./client/auth-code')(config),
'Password': require('./client/password')(config),
'AccessToken': require('./client/access-token')(config)
}
};
+

0 comments on commit f79defe

Please sign in to comment.