Language library refactor

.coveragerc

@@ -2,4 +2,4 @@
 omit =
     */python?.?/*
     */site-packages/nose/*
-    tests.py
+    test/*

.gitignore

@@ -54,3 +54,7 @@ Icon
 
 ### Added by etg
 setenv
+
+### Added by ndm
+venv
+.idea

.travis.yml

@@ -1,9 +1,10 @@
 language: python
 python:
   - 2.6
+  - 2.7
 install:
   - pip install -r requirements.txt --use-mirrors
 script:
-  nosetests tests.py --with-coverage --cover-package=toopher
+  nosetests --with-coverage test
 after_success:
   coveralls

README.md

@@ -1,85 +1,104 @@
-#ToopherPython
+#ToopherPython [![Build Status](https://travis-ci.org/toopher/toopher-python.png?branch=master)](https://travis-ci.org/toopher/toopher-python)
 
-[![Build Status](https://travis-ci.org/toopher/toopher-python.png?branch=master)](https://travis-ci.org/toopher/toopher-python)
+ToopherPython is a Toopher API library that simplifies the task of interfacing with the Toopher API from Python code.
+  This project wrangles all the dependency libraries and handles the required OAuth and JSON functionality so you can
+  focus on just using the API.
 
-#### Introduction
-ToopherPython is a Toopher API library that simplifies the task of interfacing with the Toopher API from Python code.  This project wrangles all the required OAuth and JSON functionality so you can focus on just using the API.
+### Python Version
+* 3.6
 
-#### Learn the Toopher API
+### Documentation
 Make sure you visit [https://dev.toopher.com](https://dev.toopher.com) to get acquainted with the Toopher API fundamentals.  The documentation there will tell you the details about the operations this API wrapper library provides.
 
-#### OAuth Authentication
-First off, to access the Toopher API you'll need to sign up for an account at the [Toopher developers portal](https://dev.toopher.com) and create a "requester". When that process is complete, your requester is issued OAuth 1.0a credentials in the form of a consumer key and secret. Your key is used to identify your requester when Toopher interacts with your customers, and the secret is used to sign each request so that we know it is generated by you.  This library properly formats each request with your credentials automatically.
+## ToopherApi Workflow
 
-#### The Toopher Two-Step
-Interacting with the Toopher web service involves two steps: pairing, and authenticating.
-
-##### Pair
-Before you can enhance your website's actions with Toopher, your customers will need to pair their phone's Toopher app with your website.  To do this, they generate a unique, nonsensical "pairing phrase" from within the app on their phone.  You will need to prompt them for a pairing phrase as part of the Toopher enrollment process.  Once you have a pairing phrase, just send it to the Toopher web service and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
-
-##### Authenticate
-You have complete control over what actions you want to authenticate using Toopher (for example: logging in, changing account information, making a purchase, etc.).  Just send us the user's pairing ID, a name for the terminal they're using, and a description of the action they're trying to perform and we'll make sure they actually want it to happen.
-
-#### Librarified
-This library makes it super simple to do the Toopher two-step.  Check it out:
+### Step 1: Pair
+Before you can enhance your website's actions with Toopher, your customers will need to pair their mobile device's Toopher app with your website.  To do this, they generate a unique pairing phrase from within the app on their mobile device.  You will need to prompt them for a pairing phrase as part of the Toopher enrollment process.  Once you have a pairing phrase, just send it to the Toopher web service along with your requester credentials and we'll return a pairing ID that you can use whenever you want to authenticate an action for that user.
 
 ```python
 import toopher
 
 # Create an API object using your credentials
 api = toopher.ToopherApi("<your consumer key>", "<your consumer secret>")
 
-# Step 1 - Pair with their phone's Toopher app
-pairing_status = api.pair("pairing phrase", "username@yourservice.com")
+# Step 1 - Pair with their mobile device's Toopher app
+pairing = api.pair("username@yourservice.com", "pairing phrase")
+```
+
+### Step 2: Authenticate
+You have complete control over what actions you want to authenticate using Toopher (logging in, changing account
+information, making a purchase, etc.).  Just send us the username or pairing ID and we'll make sure they actually want it to happen
+. You can also choose to provide the following optional parameters: terminal name, requester specified ID and
+action name (*default: "Log in"*).
 
+```python
 # Step 2 - Authenticate a log in
-auth = api.authenticate(pairing_status.id, "my computer")
+authentication_request = api.authenticate("username@yourservice.com", "terminal name")
 
 # Once they've responded you can then check the status
-auth_status = api.get_authentication_status(auth.id)
-if (auth_status.pending == False and auth_status.granted == True):
+authentication_request.refresh_from_server()
+if not authentication_request.pending and authentication_request.granted:
 	# Success!
 ```
 
-#### Handling Errors
-If any request runs into an error a `ToopherApiError` will be thrown with more details on what went wrong.
+## ToopherIframe Workflow
 
-#### Zero-Storage usage option
-Requesters can choose to integrate the Toopher API in a way does not require storing any per-user data such as Pairing ID and Terminal ID - all of the storage
-is handled by the Toopher API Web Service, allowing your local database to remain unchanged.  If the Toopher API needs more data, it will `raise()` a specific
-error that allows your code to respond appropriately.
+### Step 1: Embed a request in an IFRAME
+1. Generate an authentication URL by providing a username.
+2. Display a webpage to your user that embeds this URL within an `<iframe>` element.
 
 ```python
-try:
-    # optimistically try to authenticate against Toopher API with username and a Terminal Identifier
-    # Terminal Identifer is typically a randomly generated secure browser cookie.  It does not
-    # need to be human-readable
-    auth = api.authenticate_by_user_name(user_name, requester_terminal_id)
-
-    # if you got here, everything is good!  poll the auth request status as described above
-    # there are four distinct errors ToopherAPI can return if it needs more data
-except UserDisabledError:
-    # you have marked this user as disabled in the Toopher API.
-except UserUnknownError:
-    # This user has not yet paired a mobile device with their account.  Pair them
-    # using api.pair() as described above, then re-try authentication
-except TerminalUnknownError:
-    # This user has not assigned a "Friendly Name" to this terminal identifier.
-    # Prompt them to enter a terminal name, then submit that "friendly name" to
-    # the Toopher API:
-    #   api.create_user_terminal(user_name, terminal_name, requester_terminal_id)
-    # Afterwards, re-try authentication
-except PairingDeactivatedError:
-    # this user does not have an active pairing,
-    # typically because they deleted the pairing.  You can prompt
-    # the user to re-pair with a new mobile device.
+import toopher
+
+# Create an API object using your credentials
+iframe_api = toopher.ToopherIframe("<your consumer key>", "<your consumer secret>")
+
+
+auth_iframe_url = iframe_api.get_authentication_url("username@yourservice.com");
+
+# Add an <iframe> element to your HTML:
+# <iframe id="toopher_iframe" src=auth_iframe_url />
 ```
 
-#### Dependencies
-This library uses the [Requests](http://docs.python-requests.org/en/latest/) library to handle OAuth signing and to make the web requests.  If you install using pip (or easy_install) they'll be installed automatically for you. 
+### Step 2: Validate the postback data
+
+The simplest way to validate the postback data is to call `is_authentication_granted` to check if the authentication request was granted.
 
-#### Try it out
-Check out `demo.py` for an example program that walks you through the whole process!  Just download the contents of this repo, make sure you have the dependencies listed above installed, and then run it like-a-this:
+```python
+# Retrieve the postback data as a string from POST parameter 'iframe_postback_data'
+postback_data = request.args['iframe_postback_data']
+
+# Returns boolean indicating if authentication request was granted by user
+authentication_request_granted = iframe_api.is_authentication_granted(postback_data)
+
+if authentication_request_granted:
+    # Success!
+```
+
+### Handling Errors
+If any request runs into an error a `ToopherApiError` will be thrown with more details on what went wrong.
+
+### Demo
+Check out `demo.py` for an example program that walks you through the whole process!  Just download the contents of
+this repo, make sure you have the dependencies installed, and run the command below:
+```shell
+$ python demo.py
+```
+
+## Contributing
+### Dependencies
+This library uses the [Requests](http://docs.python-requests.org/en/latest/) library and [OAuthLib](https://oauthlib.readthedocs.org/en/latest/index.html) to handle OAuth signing and make the web requests.
+
+Toopher uses [pip](https://pypi.python.org/pypi/pip) to install Python packages. To ensure all dependencies are up-to-date run:
 ```shell
-$ python ./demo.py
+$ pip install -r requirements.txt
 ```
+
+### Tests
+To run the tests using [nose](http://nose.readthedocs.org/en/latest/) enter:
+```shell
+$ nosetests test
+```
+
+## License
+ToopherPython is licensed under the MIT License. See LICENSE.txt for the full text.

assets/js/toopher-web.js

@@ -0,0 +1,43 @@
+(function(window, $){
+  var postToUrl = function (path, params, method){
+    method = method || 'POST';
+    var form = $('<form />').attr('method', method).attr('action', path);
+    for (var key in params){
+      if (params.hasOwnProperty(key)){
+        var hiddenField = $('<input />').attr('type', 'hidden').attr('name', key).attr('value', params[key]);
+        form.append(hiddenField);
+      }
+    }
+    $('body').append(form);
+    form.submit();
+  }
+
+  var handleMessage = function(e){
+    var msgData = JSON.parse(e.data);
+    if (msgData.status === 'toopher-api-complete'){
+      var iframe = $('#toopher_iframe');
+      var frameworkPostArgsJSON = iframe.attr('framework_post_args');
+      var frameworkPostArgs = {};
+      if(frameworkPostArgsJSON){
+        frameworkPostArgs = $.parseJSON(frameworkPostArgsJSON);
+      }
+      var postData = $.extend({}, msgData.payload, frameworkPostArgs);
+      var toopherData = {'toopher_iframe_data': $.param(postData)};
+
+      if(iframe.attr('use_ajax_postback')){
+      $.post(iframe.attr('toopher_postback'), toopherData)
+        .done(function(data){
+          data = $.parseJSON(data);
+        });
+      } else {
+        postToUrl(iframe.attr('toopher_postback'), toopherData, 'POST');
+      }
+    }
+  }
+
+  if (window.addEventListener) {
+    window.addEventListener('message', handleMessage, false);
+  } else {
+    window.attachEvent('onmessage', handleMessage);
+  }
+})(window, jQuery);