Generic application to handle https://ejabberd-saas.com/ Remote Data API calls

==========
 djabberd
==========

For each specific tasks a handler function must be implemented.

Install
-------
::

   pip install djabberd

Quick start
-----------

1. Include the django-ejabberd URLconf in your project urls.py like this::
::

   url(r'', include('djabberd.urls'),

::

   # For Django==1.8
   url(r'', include('djabberd.urls'), namespace='djabberd')

2. Setup the handler in your Django settings::
::

    DJABBERD_API_HANDLERS='your.module.path'

Based on ejabberd-saas's documentation those endpoints are required(01-Feb-2016):

1. User management:

   1. Authentication ('/auth')
   2. User exists ('/user')

2. Roster management:

   1. Retrieve user roster ('/roster')

3. Archive:

   1. Store ('/archive')
   2. Get ('/archive')

There must be one function for each endpoint that should be implemented like this:

* user_authentication(username, password):

  - Returns `True` if authentication is valid
  - Returns `False` if authentication is *not* valid

* user_exists(username):

  - Returns `True` if user exists
  - Returns `False` if not(or if it is not active)

* retrieve_user_roster(username):

  - Returns the roster in JSON format
  - Returns `False` if user does not exist

* archive_store(payload)

  - Returns `True` if message has been stored
  - Returns a string containing an error message if message has *not* been stored

* archive_get(username[, peer, after, before, limit, chat_type])

  - Returns the message history in JSON format
  - Returns `False` in any other case

Formats
-------

* retrieve_user_roster::

   {"roster": [
       {"username": "CONTACT", 
        "subscription": "both", 
        "nick": "NICK"}, 
        ...
     ]}

* archive_store::

     {"username": "USERNAME1",
      "peer": "USERNAME2",
      "xml": "MESSAGE_STANZA",
      "body": "TEXT",
      "timestamp": "TIMESTAMP",
      "direction": "DIRECTION"}

* archive_get::

     {"archive": [{"username": "USERNAME1", 
                   "peer": "USERNAME2", 
                   "xml": "MESAGE_STANZA", 
                   "body": "TEXT", 
                   "timestamp": "TIMESTAMP", 
                   "direction": "DIRECTION"}, ...]
                   "count" : MESSAGES_NUMBER
     }


Considerations
--------------

Based on ejabberd-saas's documentation:

- If XMPP JID is "userid@xmppdomain", just pass "userid"
- If XMPP JID of USER is "userid@xmppdomain", just pass "xmppdomain"
- If an exception is raised from your handler it would be treated as a server error
- Return HTTP 200 for the successful case
- Return HTTP 401 if authentication fails
- Return HTTP 401 if it's not the successful case
- Return HTTP 500 for server errors, this is the Django's default behavior

Running Tests
=============
::

   python setup.py develop
   python runtests.py [tests.<tests_module>[.<TestClass>[.<test_method>]]]
