view release on metacpan or  search on metacpan

lib/Echo/StreamServer/Users.pm  view on Meta::CPAN

package Echo::StreamServer::Users;

use 5.008008;
use strict;
use warnings;

use Echo::StreamServer::Client;
our @ISA = ( 'Echo::StreamServer::Client' );

use Echo::StreamServer::Core;
$Echo::StreamServer::Core::DEBUG=0;

our $VERSION = '0.01';

# ======================================================================
# JSON.pm calls TO_JSON() method on the blessed hash.
#
# NOTE: The convert_blessed flag must be set (false by default).
#	my $json = JSON->new->convert_blessed;
# ======================================================================
use JSON;
my $json = JSON->new->convert_blessed;

our @USER_SUBJECTS = ( 'roles', 'state', 'markers', 'poco' );

sub get {
	my ($self, $identity_url, $raise_not_found) = @_;

	my %params = (
		'identityURL' => $identity_url,
	);

	my $json_hash_ref;
	eval {
		$json_hash_ref = send_request($self->{'account'}, 'users/get', \%params);
	};
        # Re-raise not_found StreamServer error.
        if ($@) {
                if ((not defined($raise_not_found)) and ($@ =~ m/\[not_found\]/)) {
                        # not_found OK
                }
                else {
                        die($@);
                }
        }
	return $json_hash_ref;
}

sub update {
	my ($self, $identity_url, $subject, $content) = @_;

	unless (grep(m/^$subject$/, @USER_SUBJECTS)) {
		die("Users API must update a valid subject (" . join(', ', @USER_SUBJECTS) . "), not '$subject'");
	}

	# Convert content to a JSON document.
	my %params = (
		'identityURL' => $identity_url,
		'subject' => $subject,
		'content' => $json->encode($content),
	);

	my $json_hash_ref = send_request($self->{'account'}, 'users/update', \%params, 'post');
	return $json_hash_ref;
}

sub whoami {
	my ($self, $session_id) = @_;

	my %params = (
		'appkey' => $self->{'account'}->{'appkey'},
		'sessionID' => $session_id,
	);

	my $json_hash_ref = send_request($self->{'account'}, 'users/whoami', \%params);
	return $json_hash_ref;
}

1;
__END__

=head1 NAME

Echo::StreamServer::Users - Users API

=head1 SYNOPSIS

  use Echo::StreamServer::Account;
  use Echo::StreamServer::Users;

  my $acct = new Echo::StreamServer::Account($appkey, $secret);
  my $client = new Echo::StreamServer::Users($acct);

  my $user_ref = $client->get("http://users.example.com/poco/sam");

=head1 DESCRIPTION

The Users API is Echo::StreamServer::Users and requires an Echo::StreamServer::Account.

Echo Users API is designed for providing interface for working with user identities along with core permission information.

The core data element of this API is a User Account Record. The user account is created automatically when the user logs in for the first time. 

The user account contains one or more identities (E.g. Twitter, Facebook, Acme Widgets) which are represented by identity URLs. A URL is considered to be a valid identity URL if it is either well-known (recognized by Social Graph Node Mapper) or is a...

User Accounts are stored in a namespace - essentially each namespace is a different user database.

One can think of user accounts as boxes where business cards (identities) are put. When a new user gets logged in to the system, a new box is allocated and the user's business cards (identities) are placed into it. Echo allows to add multiple identit...