The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
=head1 NAME

REST::Google::Apps::Provisioning - A Perl library to Google's RESTful Apps
Provisioning API

=head1 SYNOPSIS

  use REST::Google::Apps::Provisioning

  $google = REST::Google::Apps::Provisioning->new(
      domain   => 'company.com',
      username => 'admin',
      password => 'g00gl34pp5!'
  );

  $user->{'jsmith'} = $google->getUser( username => 'jsmith' );

=head1 DESCRIPTION

REST::Google::Apps::Provisioning provides a Perl interface to Google's
RESTful Apps API.

=head1 CONSTRUCTOR

=head2 new ( DOMAIN, USERNAME, PASSWORD )

Creates a new B<REST::Google::Apps::Provisioning> object.  A domain parameter
is required.

Supplying authentication information to the constructor is optional, but needs
to happen either here or with a call to the B<authenticate> method.

B<Example>

  $google = REST::Google::Apps::Provisioning->new(
      domain   => 'company.com',
      username => 'admin',
      password => 'g00gl34pp5!'
  );

=head1 METHODS

=head2 authenticate ( USERNAME, PASSWORD )

Authenticate a session.

B<Example>

  $google->authenticate(
      username => 'admin',
      password => 'g00gl34pp5!'
  )
  || die "Could not authenticate";

=head2 createUser ( USERNAME, GIVENNAME, FAMILYNAME, PASSWORD, PASSWORDHASHFUNCTION, ADMIN )

Create a new user.

The following parameters are required:

=over 4

=item username

The username associated with the account being created.

=item givenName

The user's given (first) name.

=item familyName

The user's family (last) name.

=item password

The user's password.

=back

The following parameters are optional:

=over 4

=item passwordHashFunction

The format of the value in the B<password> attribute.  Currently, the only
valid values for this parameter are "SHA-1" and "MD5".

=item admin

Can be 'true' or 'false', representing whether or not the user should be
granted administrator access.

=back

B<Example>

  $user->{'jsmith'} = $google->createUser(
      username   => 'jsmith',
      givenName  => 'Joseph',
      familyName => 'Smith',
      password   => 'j5m1thp455w0rd!'
  )
  || die "Could not create user";

=head2 deleteUser ( USERNAME )

Delete a user.

B<Example>

  delete $user->{'jsmith'} if $google->deleteUser( username => 'jsmith' );

=head2 renameUser ( USERNAME, NEWNAME )

Rename a user.

B<Example>

  $google->renameUser(
      username => 'jsmith',
      newname  => 'josephsmith'
  )
  || die "Could not rename user";

=head2 updateUser ( USERNAME, ATTR )

Update a user's attributes.  See the B<createUser> function for a list of
valid attributes.

B<Example>

  $google->updateUser(
      username => 'jsmith',
      givenName => 'Joey'
  )
  || die "Could not update user";

=head2 getUser ( USER )

Retrieve a hash containing a user's account information.

B<Example>

  $user->{'jsmith'} = $google->getUser( username => 'jsmith' );

B<Hash>

Using the above example, the returned hash is:

  'jsmith' => {
      'admin' => 'false',
      'ipWhitelisted' => 'false',
      'suspended' => 'false',
      'limit' => '7168',
      'username' => 'jsmith`',
      'changePasswordAtNextLogin' => 'false',
      'givenName' => 'Joseph',
      'familyName' => 'Smith',
      'agreedToTerms' => 'false'
  }

=head2 getAllUsers

Retrieve a list of all users.

B<Example>

  $users = $google->getAllUsers();

=head2 createGroup ( GROUP, DESCRIPTION, PERMISSION )

Create a new group.

The following parameters are required:

=over 4

=item group

The group name.

=back

The following parameters are optional:

=over 4

=item description

A longer description of the group.

=item permission

The permission level of the group.  Valid values are:

=over 4

=item owner

Owners of the group.

=item member

Members of the group.

=item domain

Any user who belongs to the same domain as the group.

=item anyone

Any user.

=back

=back

B<Example>

  $google->createGroup(
      group => 'finance',
      description => 'Finance Department'
  )
  || die "Could not create group";

=head2 deleteGroup ( GROUP )

Delete a group.

B<Example>

  delete $group->{'finance'} if $google->deleteGroup( group => 'finance' );

=head2 updateGroup ( GROUP, ... )

Not yet implemented.

=head2 getGroup ( GROUP )

Retrieve a hash containing group information.

B<Example>

  $group->{'finance'} = $google->getGroup( group => 'finance' );

B<Hash>

Using the above example, the returned hash is:

  'finance' => {
      'emailPermission' => 'Anyone',
      'groupId' => 'finance@company.com',
      'updated' => '2009-09-16T21:05:15.697Z',
      'groupName' => 'finance',
      'description' => 'Finance Department'
  }

=head2 getAllGroups

Retrieve a list of all groups.

B<Example>

  $groups = $google->getAllGroups();

=head2 addGroupMember ( GROUP, MEMBER )

Add a member to a group.

B<Example>

  $google->addGroupMember(
      group  => 'finance',
      member => 'jsmith'
  )
  || die "Could not add group member";

=head2 deleteGroupMember ( GROUP, MEMBER )

Remove a member from a group.

B<Example>

  $google->deleteGroupMember(
      group  => 'finance',
      member => 'jsmith'
  )
  || die "Could not delete group member";

=head2 getGroupMembers ( GROUP )

Retrieve a list of group members.

B<Example>

  $group->{'finance'}->{'members'} = $google->getGroupMembers( group => 'finance' );

B<Hash>

Using the above example, the returned hash is:

  'members' => {
      'jsmith' => {
          'memberType' => 'User',
          'directMember' => 'true',
          'memberId' => 'jsmith@company.com'
      },
      'sschneid' => {
          'memberType' => 'User',
          'directMember' => 'true',
          'memberId' => 'sschneid@company.com'
      }
  }

=head2 addGroupOwner ( GROUP, OWNER )

Add an owner to a group.

B<Example>

  $google->addGroupOwner(
      group => 'finance',
      owner => 'jsmith'
  )
  || die "Could not add group owner";

=head2 deleteGroupOwner ( GROUP, OWNER )

Remove an owner from a group.

B<Example>

  $google->deleteGroupOwner(
      group => 'finance',
      owner => 'jsmith'
  )
  || die "Could not delete group owner";

=head2 getGroupOwner ( GROUP, OWNER )

Not yet implemented.

=head2 getGroupOwners ( GROUP )

Retrieve a list of group owners.

B<Example>

  $group->{'finance'}->{'owners'} = $google->getGroupOwners( group => 'finance' );

B<Hash>

Using the above example, the returned hash is:

  'owners' => {
      'jsmith' => {
          'email' => 'jsmith@company.com',
          'type' => 'User'
      },
      'sschneid' => {
          'email' => 'sschneid@company.com',
          'type' => 'User'
      }
  }

=head2 createNickname ( USERNAME, NICKNAME )

Create a nickname (e-mail alias).

B<Example>

  $google->createNickname(
      username => 'jsmith',
      nickname => 'joe'
  )
  || die "Could not create nickname";

=head2 deleteNickname ( NICKNAME )

Delete a nickname (e-mail alias).

B<Example>

  $google->deleteNickname( nickname => 'joe' );

=head2 getNickname ( NICKNAME )

Retrieve a nickname.

B<Example>

  $nickname->{'frank'} = $google->getNickname( nickname => 'frank' );

B<Hash>

Using the above example, the returned hash is:

  'frank' => {
      'name' => 'frank',
      'username' => 'jsmith'
  }

=head2 getUserNicknames ( USERNAME )

Retrieve a list of a user's nicknames.

B<Example>

  $user->{'jsmith'}->{'nicknames'} = $google->getUserNicknames( username => 'jsmith' );

=head2 getAllNicknames

Retrieve a list of all nicknames.

=head1 AUTHOR

Scott Schneider <sschneid@gmail.com>

=cut