NAME
    Etherpad::API - Access Etherpad Lite API easily

SYNOPSIS
      use Etherpad::API;
      my $ec = Etherpad::API->new({
        url      => "http://pad.example.com",
        apikey   => "teirnausetsraunieti",
        user     => "apiuser",
        password => "apipassword"
      });

      $ec->create_pad('new_pad_name');

DESCRIPTION
    This is a client for the Etherpad Lite HTTP API.

USAGE
  new
     Usage     : my $ec = Etherpad::API->new({ url => "http://pad.example.com", apikey => "secretapikey" });
     Purpose   : Constructor
     Returns   : An Etherpad::API object
     Argument  : An mandatory hash reference, containing at least two keys:
                    url      : mandatory, the epl URL (trailing slashes will be removed)
                    apikey   : mandatory, the epl API key
                    user     : optional, the user for epl authentication
                    password : optional, the passowrd for epl authentication

  apikey
     Usage     : $ec->apikey();
     Purpose   : Get the apikey
     Returns   : The apikey

  url
     Usage     : $ec->url();
     Purpose   : Get the epl URL
     Returns   : The epl URL

  Groups
    Pads can belong to a group. The padID of grouppads is starting with a
    groupID like g.asdfasdfasdfasdf$test

   create_group
     Usage     : $ec->create_group();
     Purpose   : Creates a new group
     Returns   : The new group ID

   create_group_if_not_exists_for
     Usage     : $ec->create_group_if_not_exists_for('myGroupId');
     Purpose   : This functions helps you to map your application group ids to epl group ids
     Returns   : The epl group id
     Argument  : Your application group id

   delete_group
     Usage     : $ec->delete_group('groupId');
     Purpose   : Deletes a group
     Returns   : 1 if it succeeds
     Argument  : The id of the group you want to delete

   list_pads
     Usage     : $ec->list_pads('groupId');
     Purpose   : Returns all pads of this group
     Returns   : An array or an array reference (depending on the context) which contains the pad ids
     Argument  : The id of the group from which you want the pads

   create_group_pad
     Usage     : $ec->create_group_pad('groupID', 'padName' [, 'text'])
     Purpose   : Creates a new pad in this group
     Returns   : 1 if it succeeds
     Argument  : The group id, the pad name, optionally takes the pad's initial text

   list_all_groups
     Usage     : $ec->list_all_groups()
     Purpose   : Lists all existing groups
     Returns   : An array or an array reference (depending on the context) which contains the groups ids

  Author
    These authors are bound to the attributes the users choose (color and
    name).

   create_author
     Usage     : $ec->create_author(['name'])
     Purpose   : Creates a new author
     Returns   : The new author ID
     Argument  : Optionally takes a string as argument : the new author's name

   create_author_if_not_exists_for
     Usage     : $ec->create_author_if_not_exists_for(authorMapper [, name])
     Purpose   : This functions helps you to map your application author ids to epl author ids
     Returns   : The epl author ID
     Argument  : Your application author ID (mandatory) and optionally the epl author name

   list_pads_of_author
     Usage     : $ec->list_pads_of_author('authorID')
     Purpose   : Returns an array of all pads this author contributed to
     Returns   : An array or an array reference depending on the context, containing the pads names
     Argument  : An epl author ID

   get_author_name
     Usage     : $ec->get_author_name('authorID')
     Purpose   : Returns the Author Name of the author
     Returns   : The author name
     Argument  : The epl author ID

  Session
    Sessions can be created between a group and an author. This allows an
    author to access more than one group. The sessionID will be set as a
    cookie to the client and is valid until a certain date. The session
    cookie can also contain multiple comma-seperated sessionIDs, allowing a
    user to edit pads in different groups at the same time. Only users with
    a valid session for this group, can access group pads. You can create a
    session after you authenticated the user at your web application, to
    give them access to the pads. You should save the sessionID of this
    session and delete it after the user logged out.

   create_session
     Usage     : $ec->create_session('groupID', 'authorID', 'validUntil')
     Purpose   : Creates a new session. validUntil is an unix timestamp in seconds
     Returns   : The epl session ID
     Argument  : An epl group ID, an epl author ID and an valid unix timestamp (the session validity end date)

   delete_session
     Usage     : $ec->delete_session('sessionID')
     Purpose   : Deletes a session
     Returns   : 1 if it succeeds
     Argument  : An epl session ID

   get_session_info
     Usage     : $ec->get_session_info('sessionID')
     Purpose   : Returns informations about a session
     Returns   : An hash reference, containing 3 keys : authorID, groupID and validUntil
     Argument  : An epl session ID

   list_sessions_of_group
     Usage     : $ec->list_sessions_of_group('groupID')
     Purpose   : Returns all sessions of a group
     Returns   : Returns a hash reference, which keys are sessions ID and values are sessions infos (see get_session_info)
     Argument  : An epl group ID

   list_sessions_of_author
     Usage     : $ec->list_sessions_of_author('authorID')
     Purpose   : Returns all sessions of an author
     Returns   : Returns a hash reference, which keys are sessions ID and values are sessions infos (see get_session_info)
     Argument  : An epl group ID

  Pad Content
    Pad content can be updated and retrieved through the API.

   get_text
     Usage     : $ec->get_text('padID', ['rev'])
     Purpose   : Returns the text of a pad
     Returns   : A string, containing the text of the pad
     Argument  : Takes a pad ID (mandatory) and optionally a revision number

   set_text
     Usage     : $ec->set_text('padID', 'text')
     Purpose   : Sets the text of a pad
     Returns   : 1 if it succeeds
     Argument  : Takes a pad ID and the text you want to set (both mandatory)

   get_html
     Usage     : $ec->get_html('padID', ['rev'])
     Purpose   : Returns the text of a pad formatted as html
     Returns   : A string, containing the text of the pad formatted as html
     Argument  : Takes a pad ID (mandatory) and optionally a revision number

  Chat
   get_chat_history
     Usage     : $ec->get_chat_history('padID' [, start, end])
     Purpose   : Returns
                  - a part of the chat history, when start and end are given
                  - the whole chat history, when no extra parameters are given
     Returns   : An array or an array reference, depending of the context, containing hash references with 4 keys :
                  - text     => text of the message
                  - userId   => epl user id
                  - time     => unix timestamp of the message
                  - userName => epl user name
     Argument  : Takes a pad ID (mandatory) and optionally the start and the end numbers of the messages you want.
                 The start number can't be higher than or equal to the current chatHead. The first chat message is number 0.
                 If you specify a start but not an end, all messages will be returned.

   get_chat_head
     Usage     : $ec->get_chat_head('padID')
     Purpose   : Returns the chatHead (last number of the last chat-message) of the pad
     Returns   : The last chat-message number. -1 if there is no chat message
     Argument  : A pad ID

  Pad
    Group pads are normal pads, but with the name schema GROUPID$PADNAME. A
    security manager controls access of them and its forbidden for normal
    pads to include a $ in the name.

   create_pad
     Usage     : $ec->create_pad('padID' [, 'text'])
     Purpose   : Creates a new (non-group) pad. Note that if you need to create a group Pad, you should call create_group_pad.
     Returns   : 1 if it succeeds
     Argument  : Takes a pad ID (mandatory) and optionally a text to fill the pad

   get_revisions_count
     Usage     : $ec->get_revisions_count('padID')
     Purpose   : Returns the number of revisions of this pad
     Returns   : The number of revisions
     Argument  : A pad ID

   get_users_count
     Usage     : $ec->get_users_count('padID')
     Purpose   : Returns the number of user that are currently editing this pad
     Returns   : The number of users
     Argument  : A pad ID

   pad_users
     Usage     : $ec->pad_users('padID')
     Purpose   : Returns the list of users that are currently editing this pad
     Returns   : An array or an array reference, depending of the context, containing hash references with 3 keys : colorId, name and timestamp
     Argument  : A pad ID

   delete_pad
     Usage     : $ec->delete_pad('padID')
     Purpose   : Deletes a pad
     Returns   : 1 if it succeeds
     Argument  : A pad ID

   get_read_only_id
     Usage     : $ec->get_read_only_id('padID')
     Purpose   : Returns the read only link of a pad
     Returns   : A string
     Argument  : A pad ID

   set_public_status
     Usage     : $ec->set_public_status('padID', 'publicStatus')
     Purpose   : Sets a boolean for the public status of a pad
     Returns   : 1 if it succeeds
     Argument  : A pad ID and the public status you want to set : 1 or 0

   get_public_status
     Usage     : $ec->get_public_status('padID')
     Purpose   : Return true of false
     Returns   : 1 or 0
     Argument  : A pad ID

   set_password
     Usage     : $ec->set_password('padID', 'password')
     Purpose   : Returns ok or a error message
     Returns   : 1 if it succeeds
     Argument  : A pad ID and a password

   is_password_protected
     Usage     : $ec->is_password_protected('padID')
     Purpose   : Returns true or false
     Returns   : 1 or 0
     Argument  : A pad ID

   list_authors_of_pad
     Usage     : $ec->list_authors_of_pad('padID')
     Purpose   : Returns an array of authors who contributed to this pad
     Returns   : An array or an array reference depending on the context, containing the epl authors IDs
     Argument  : A pad ID

   list_names_of_authors_of_pad
     Usage     : $ec->list_names_authors_of_pad('padID')
     Returns   : Returns an array of the names of the authors who contributed to this pad in list context
                 Returns an array reference in scalar context
     Argument  : The pad name

   get_last_edited
     Usage     : $ec->get_last_edited('padID')
     Purpose   : Returns the timestamp of the last revision of the pad
     Returns   : A unix timestamp
     Argument  : A pad ID

   send_clients_message
     Usage     : $ec->send_clients_message('padID', 'msg')
     Purpose   : Sends a custom message of type msg to the pad
     Returns   : 1 if it succeeds
     Argument  : A pad ID and the message you want to send

  check_token
     Usage     : $ec->check_token()
     Purpose   : Returns ok when the current api token is valid
     Returns   : 1 if the token is valid, 0 otherwise

  Pads
   list_all_pads
     Usage     : $ec->list_all_pads()
     Purpose   : Lists all pads on this epl instance
     Returns   : An array or an array reference depending on the context, containing the pads names

INSTALL

  perl Makefile.PL
  make
  make test
  make install

If you are on a windows box you should use 'nmake' rather than 'make'.

BUGS and SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Etherpad::API

    Bugs and feature requests will be tracked at RT:

        http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Etherpad-API
        bug-etherpad-api at rt.cpan.org

    The latest source code can be browsed and fetched at:

        https://github.com/ldidry/etherpad-api
        git clone git://github.com/ldidry/etherpad-api.git

    You can also look for information at:

        RT: CPAN's request tracker

        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Etherpad-API
        AnnoCPAN: Annotated CPAN documentation

        http://annocpan.org/dist/Etherpad-API
        CPAN Ratings

        http://cpanratings.perl.org/d/Etherpad-API
        Search CPAN

        http://search.cpan.org/dist/Etherpad-API

AUTHOR
        Luc DIDRY
        CPAN ID: LDIDRY
        ldidry@cpan.org
        http://www.fiat-tux.fr/

COPYRIGHT
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

SEE ALSO
    perl(1).

