Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oauth-io/oauth-js
OAuth that just works ! This is the JavaScript SDK for OAuth.io
https://github.com/oauth-io/oauth-js
Last synced: 4 months ago
JSON representation
OAuth that just works ! This is the JavaScript SDK for OAuth.io
- Host: GitHub
- URL: https://github.com/oauth-io/oauth-js
- Owner: oauth-io
- Created: 2013-06-14T21:17:22.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2017-12-31T04:24:28.000Z (about 7 years ago)
- Last Synced: 2024-10-08T05:23:36.028Z (5 months ago)
- Language: CoffeeScript
- Homepage: https://oauth.io
- Size: 2.86 MB
- Stars: 796
- Watchers: 33
- Forks: 197
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
OAuth.io JavaScript SDK
=======================
This is the JavaScript SDK for [OAuth.io](https://oauth.io). OAuth.io allows you to integrate **100+ providers** really easily in your web app, without worrying about each provider's OAuth specific implementation.
Installation
============
Getting the SDK
---------------
To get the SDK, you can :
- download the zip file from this repository
- get it via Bower or npm (for browserify)
**Zip file**
Just copy the dist/oauth.js or dist/oauth.min.js to your project.
**Bower**
```sh
$ bower install oauthio-web
```
**npm for browserify**
```sh
$ npm install oauthio-web
```
Integrating in your project
---------------------------
In the `` of your HTML, include OAuth.js
``
In your Javascript, add this line to initialize OAuth.js
`OAuth.initialize('your_app_public_key');`
Usage
=====
To connect your user using facebook, 2 methods:
Popup mode
----------
```javascript
//Using popup (option 1)
OAuth.popup('facebook')
.done(function(result) {
//use result.access_token in your API request
//or use result.get|post|put|del|patch|me methods (see below)
})
.fail(function (err) {
//handle error with err
});
```
Redirection mode
----------------
```javascript
//Using redirection (option 2)
OAuth.redirect('facebook', "callback/url");
```
In callback url :
```javascript
OAuth.callback('facebook')
.done(function(result) {
//use result.access_token in your API request
//or use result.get|post|put|del|patch|me methods (see below)
})
.fail(function (err) {
//handle error with err
});
```
Making requests
---------------
You can make requests to the provider's API manually with the access token you got from the `popup` or `callback` methods, or use the request methods stored in the `result` object.
**GET Request**
To make a GET request, you have to call the `result.get` method like this :
```javascript
//Let's say the /me endpoint on the provider API returns a JSON object
//with the field "name" containing the name "John Doe"
OAuth.popup(provider)
.done(function(result) {
result.get('/me')
.done(function (response) {
//this will display "John Doe" in the console
console.log(response.name);
})
.fail(function (err) {
//handle error with err
});
})
.fail(function (err) {
//handle error with err
});
```
**POST Request**
To make a POST request, you have to call the `result.post` method like this :
```javascript
//Let's say the /message endpoint on the provider waits for
//a POST request containing the fields "user_id" and "content"
//and returns the field "id" containing the id of the sent message
OAuth.popup(provider)
.done(function(result) {
result.post('/message', {
data: {
user_id: 93,
content: 'Hello Mr. 93 !'
}
})
.done(function (response) {
//this will display the id of the message in the console
console.log(response.id);
})
.fail(function (err) {
//handle error with err
});
})
.fail(function (err) {
//handle error with err
});
```
**PUT Request**
To make a PUT request, you have to call the `result.post` method like this :
```javascript
//Let's say the /profile endpoint on the provider waits for
//a PUT request to update the authenticated user's profile
//containing the field "name" and returns the field "name"
//containing the new name
OAuth.popup(provider)
.done(function(result) {
result.put('/message', {
data: {
name: "John Williams Doe III"
}
})
.done(function (response) {
//this will display the new name in the console
console.log(response.name);
})
.fail(function (err) {
//handle error with err
});
})
.fail(function (err) {
//handle error with err
});
```
**PATCH Request**
To make a PATCH request, you have to call the `result.patch` method like this :
```javascript
//Let's say the /profile endpoint on the provider waits for
//a PATCH request to update the authenticated user's profile
//containing the field "name" and returns the field "name"
//containing the new name
OAuth.popup(provider)
.done(function(result) {
result.patch('/message', {
data: {
name: "John Williams Doe III"
}
})
.done(function (response) {
//this will display the new name in the console
console.log(response.name);
})
.fail(function (err) {
//handle error with err
});
})
.fail(function (err) {
//handle error with err
});
```
**DELETE Request**
To make a DELETE request, you have to call the `result.del` method like this :
```javascript
//Let's say the /picture?id=picture_id endpoint on the provider waits for
//a DELETE request to delete a picture with the id "84"
//and returns true or false depending on the user's rights on the picture
OAuth.popup(provider)
.done(function(result) {
result.del('/picture?id=84')
.done(function (response) {
//this will display true if the user was authorized to delete
//the picture
console.log(response);
})
.fail(function (err) {
//handle error with err
});
})
.fail(function (err) {
//handle error with err
});
```
**Me() Request**
The `me()` request is an OAuth.io feature that allows you, when the provider is supported, to retrieve a unified object describing the authenticated user. That can be very useful when you need to login a user via several providers, but don't want to handle a different response each time.
To use the `me()` feature, do like the following (the example works for Facebook, Github, Twitter and many other providers in this case) :
```javascript
//provider can be 'facebook', 'twitter', 'github', or any supported
//provider that contain the fields 'firstname' and 'lastname'
//or an equivalent (e.g. "FirstName" or "first-name")
var provider = 'facebook';
OAuth.popup(provider)
.done(function(result) {
result.me()
.done(function (response) {
console.log('Firstname: ', response.firstname);
console.log('Lastname: ', response.lastname);
})
.fail(function (err) {
//handle error with err
});
})
.fail(function (err) {
//handle error with err
});
```
*Filtering the results*
You can filter the results of the `me()` method by passing an array of fields you need :
```javascript
//...
result.me(['firstname', 'lastname', 'email'/*, ...*/])
//...
```
Contributing
============
You are welcome to fork and make pull requests. We will be happy to review them and include them in the code if they bring nice improvements :)
Testing the SDK
===============
To test the SDK, you first need to install the npm modules `jasmine-node` and `istanbul` (to get the tests coverage) :
```sh
$ sudo npm install -g [email protected] istanbul
```
Then you can run the testsuite from the SDK root directory :
```sh
$ jasmine-node --verbose tests/unit/spec
```
Once you've installed `istanbul`, you can run the following command to get coverage information :
```sh
$ npm test
```
The coverage report is generated in the `coverage` folder. You can have a nice HTML render of the report in `coverage/lcof-report/index.html`
License
=======
This SDK is published under the Apache2 License.
More information in [oauth.io documentation](http://oauth.io/#/docs)