NAME

Net::FriendFeed - Perl interface to FriendFeed.com API

SYNOPSIS

FriendFeed is a social feed agregator with a clean public REST-based API. This package allows easy access to FriendFeed from Perl.

Methods are named in accordance with the official Python package.

use Net::FriendFeed;

my $frf = Net::FriendFeed->new;
$frf->publish_message('Hello, world!');
...

GENERAL FUNCTIONS

new(\%opts)

This is a constructor for FriendFeed object. It takes an optional hashref parameter with auth credentials.

Example:

my $frf_anon = Net::FriendFeed->new;
my $frf = Net::FriendFeed->new({login => 'kkapp', remotekey => 'hfytr38'});

The remotekey is a kind of easily regeneratable password used only in API functions. A user can get his remotekey here: http://friendfeed.com/remotekey

Authentication is needed only to post or to read private feeds.

last_error()

Returns machine-readable code of the last error. You should consult this code if an API call returns undef.

This is a list of FriendFeed error codes: * bad-id-format - Bad format for UUID argument. * bad-url-format - Bad format for URL argument. * entry-not-found - Entry with the specified UUID was not found. * entry-required - Entry UUID argument is required. * forbidden - User does not have access to entry, room or other entity specified in the request. * image-format-not-supported - Unsupported image format. * internal-server-error - Internal error on FriendFeed server. * limit-exceeded - Request limit exceeded. * room-not-found - Room with specified name not found. * room-required - Room name argument is required. * title-required - Entry title argument is required. * unauthorized - The request requires authentication. * user-not-found - User with specified nickname not found. * user-required - User nickname argument is required. * error - Other unspecified error.

These error codes are generated inside Net::FriendFeed wrapper code: * need-auth - The request was not made because it requires authentication. * failed-req - The request was not made because of unknown reason.

Read/Write accessor for login name. You can either get current login or set it if you'd like to do it after calling new().

remotekey([$remotekey])

Read/Write accessor for remotekey. You can either get current remotekey or set it if you'd like to do it after calling new().

Remotekey is a special password valid only for use via API calls. A user can get his remotekey here: http://friendfeed.com/remotekey

validate()

Validates the current combination of login and remotekey.

list_services

Returns the list of all services supported by FriendFeed.

The returned JSON has the format:

* services[]
      o url - the official URL of the service, e.g., http://picasaweb.google.com/
      o iconUrl - the URL of the favicon for this service
      o id - the service's FriendFeed ID, e.g., "picasa"
      o name - the service's official name, e.g., "Picasa Web Albums"

FEED FUNCTIONS

A number of methods fetch arrays of data or "feeds" from FriendFeed. All feeds are available in four different formats. They are json, xml, atom and rss. JSON and XML formats are custom FriendFeed structures, while Atom and RSS are standard XML formats with all FriendFeed specific features represented as custom XML tags.

Net::FriendFeed adds one additional format called structure which means the feeds will be fetched as json and then deserialized into Perl structures using JSON.pm module. The format structure is set by default.

The feeds have the following structure (JSON-like notation is used):

* entries[]
      o id - the FriendFeed entry UUID, used to add comments/likes to the entry
      o title
      o link
      o published
      o updated
      o hidden - if true, this entry should be hidden based on the user's preferences
      o anonymous - if true, user will be present but should not be shown 
      o user{} - the user who shared this entry
            + id - the user's FriendFeed UUID
            + name - the user's full name
            + nickname - the user's FriendFeed nickname, used in FriendFeed URLs
            + profileUrl - the user's profile URL on FriendFeed
      o service{} - the service from which the entry came
            + id - the service's FriendFeed ID, e.g., "picasa"
            + name - the service's official name, e.g., "Picasa Web Albums"
            + iconUrl - the URL of the favicon for this service
            + profileUrl - the user's profile URL on this service
      o comments[]
            + date
            + id - the UUID of the comment
            + user{} - same structure as the user{} structure above
            + body - the textual body of the comment
            o via{}? - present if this comment came from an API client
                + name - the name of the API client, e.g., "fftogo"
                + url - the official URL of the API client, e.g., http://www.fftogo.com
      o likes[]
            + date
            + user{} - same structure as the user{} structure above
      o media[] - the videos/images associated with the entry
            + title? - the title of the media file
            + player? - the player for this media file (e.g., the YouTube.com URL with the embedded video)
            + thumbnails[] - the thumbnails for this media file
                  # url
                  # width
                  # height
            + content[] - the different versions of the media file
                  # url
                  # type - the MIME type of the media file
                  # width
                  # height
      o via{}? - present if this entry came from an API client
            + name - the name of the API client, e.g., "Alert Thingy"
            + url - the official URL of the API client, e.g., http://www.alertthingy.com/
      o room{}? - if the entry is in a room, the room the entry is in

            + id - the room's FriendFeed UUID
            + name - the room's display name
            + nickname - the room's FriendFeed nickname, used in FriendFeed URLs
            + url - the room's URL on FriendFeed

The simple XML format has the same structure as the JSON. The RSS and Atom formats use the standard RSS and Atom attributes for title, link, published, and updated, and include extension elements for all of the other meta-data.

Dates in JSON and dates in the FriendFeed extension elements in the Atom and RSS feeds are in RFC 3339 format in UTC. You can parse them with the strptime string "%Y-%m-%dT%H:%M:%SZ".

All feed-fetching methods support additional parameters:

service: only return entries from the service with the given ID, e.g., service=twitter
start: return entries starting with the given index, e.g., start=30
num: return num entries starting from start, e.g., num=10

They can be passed as key => value pairs after all the other arguments.

$frf->fetch_user_feed('kkapp', num => 50, service => 'twitter');

return_feeds_as($type)

Gets or sets the type of return feeds.

This can be one of qw/structure xml atom rss json/ and defaults to 'structure' which is a parsed Perl data structure. Other types are string scalars.

fetch_public_feed

Fetches the most recent 30 public entries published to FriendFeed.

fetch_user_feed($user)

Fetches the most recent entries from a user feed. If the user has a private feed, authentication is required.

fetch_user_comments_feed($user)

Returns the most recent entries the user has commented on, ordered by the date of that user's comments.

fetch_user_likes_feed($user)

Returns the most recent entries the user has "liked," ordered by the date of that user's "likes".

fetch_user_discussion_feed($user)

Returns the most recent entries the user has commented on or "liked".

fetch_multi_user_feed(\@users)

Returns the most recent entries from a list of users, specified by nickname:

If more than one nickname is specified, the feed most recent entries from all of the given users. If any one of the users has a private feed, authentication is required.

User nicknames should be passed as an arrayref.

$frf->fetch_multi_user_feed([qw/kkapp mihun/]);

fetch_room_feed($room)

Returns the most recent entries in the room with the given nickname.

If the room is private, authentication is required.

fetch_home_feed

Returns the entries the authenticated user would see on their FriendFeed homepage - all of their subscriptions and friend-of-a-friend entries.

Authentication is always required.

fetch_entry($uuid)

Fetches a single entry by its UUID. Needs authentication to read private entries.

search($query)

Executes a search over the entries in FriendFeed. If the request is authenticated, the default scope is over all of the entries in the authenticated user's Friends Feed. If the request is not authenticated, the default scope is over all public entries.

$frf->search('rambler service:twitter');

The query syntax is the same syntax as http://friendfeed.com/search/advanced. The query operators are:

who:: restricts the search to a specific user, e.g., who:bret
service:: restricts the search to a specific service ID, e.g., service:twitter

PUBLISHING FUNCTIONS

You can perform test calls from a web browser using the HTTP Basic Authentication built into your browser at http://friendfeed.com/static/html/apitest.html.

Requests to FriendFeed are rate limited, which, e.g., limits the number and size of thumbnails you can upload in a day. Normal uses should fall well within our rate limits. If you encounter HTTP 403 errors because of rate limits, and you think the limit is erroneous, please let us know in the developer forum.

publish_link($title, $link, $comment, [@images, [$imgN, $linkN]], $room, $via)

Share a link with a title, images and other possible options. Requires authentication.

All non-ASCII input data should be clean Perl Unicode (that is, decoded from any encoding). FriendFeed API is strictly UTF-8 so we unconditionally encode strings into UTF-8 via Encode::encode('UTF-8', $data) call.

Full signature looks like: $frf->publish_link($title, $link, $comment, [@images, [$imgN, $linkN]], $room, $via)

$title

Mandatory title of the shared item.

$links

URL to refer to. If absent, the shared link reduces to text.

$comment

Automatically add 1st comment to the item.

$images

This one is an arrayref of image items. Each image item is either an image PURL or a pair (taken as arrayrefs of two elements) of PURL => URL. PURL in the pair points to the image and URL is used as a href to follow when the user clicks on this very image. URL defaults to the main $link.

Each PURL may be either an (http|https|ftp) URL or a PATH to a local file in which case that file gets uploaded directly to FriendFeed.

$room

This is a room nickname to which the link should be published.

$via

This is an identifier of your software. It's ignored unless you register it with FriendFeed administration.

publish_message($msg)

Share a piece of text. The simplest form of FriendFeed sharing. Requires authentication.

This is actually a special case of publish_link with only $title set.

delete_entry($entry)

Delete an entry. The arguments are:

$entry: required - The FriendFeed UUID of the entry.

undelete_entry($entry)

Undelete a deleted entry. The arguments are:

$entry: required - The FriendFeed UUID of the entry.

hide_entry($entry)

Hides an entry for current user. The arguments are:

$entry: required - The FriendFeed UUID of the entry.

unhide_entry($entry)

Unhide a hidden entry. The arguments are:

$entry: required - The FriendFeed UUID of the entry.

COMMENT AND LIKE FUNCTIONS

add_comment($entry, $body, $via)

Add a comment on a FriendFeed entry. The arguments are:

$entry: required - The FriendFeed UUID of the entry to which this comment is attached.
$body: required - The textual body of the comment.
$via: This is an identifier of your software. It's ignored unless you register it with FriendFeed administration.

$frf->add_comment('550e8400-e29b-41d4-a716-446655440000', 'Testing the FriendFeed API', 'Microsoft Word');

edit_comment($entry, $body, $comment)

Edit an existing comment on a FriendFeed entry. The arguments are:

$entry: required - The FriendFeed UUID of the entry to which this comment is attached.
$body: required - The textual body of the comment.
$comment: The FriendFeed UUID of the comment to edit. If not given, the request will create a new comment.

delete_comment($entry, $comment)

Delete an existing comment. The arguments are:

$entry: required - The FriendFeed UUID of the entry to which this comment is attached.
$comment: required - The FriendFeed UUID of the comment to delete.

undelete_comment($entry, $comment)

Undelete a deleted comment. The arguments are:

$entry: required - The FriendFeed UUID of the entry to which this comment is attached.
$comment: required - The FriendFeed UUID of the comment to undelete.

add_like($entry)

Add a "Like" to a FriendFeed entry for the authenticated user.

$entry: required - The FriendFeed UUID of the entry to which this comment is attached

$frf->add_like("550e8400-e29b-41d4-a716-446655440000");

delete_like($entry)

Delete an existing "Like". The arguments are:

$entry: required - The FriendFeed UUID of the entry to which this comment is attached.

PROFILE FUNCTIONS

fetch_user_profile($user)

Returns list of all of the user's subscriptions (people) and services connected to their account.

The returned data has this structure:

* id - the user's FriendFeed UUID
* name - the user's full name
* nickname - the user's FriendFeed nickname, used in FriendFeed URLs
* profileUrl - the user's profile URL on FriendFeed
* services[] - the services connected to the user's account
      o id - the service's FriendFeed ID, e.g., "picasa"
      o name - the service's official name, e.g., "Picasa Web Albums"
      o url - the official URL of the service, e.g., http://picasaweb.google.com/
      o iconUrl - the URL of the favicon for this service
      o profileUrl? - the user's profile URL on this service, if any
      o username? - the user's username for this service, if any 
* subscriptions[] - the users this user is subscribed to
      o id
      o name
      o nickname
      o profileUrl 
* rooms[] - the rooms this user is a member of
      o id - the room's FriendFeed UUID
      o name - the room's display name
      o nickname - the room's FriendFeed nickname, used in FriendFeed URLs
      o url - the room's URL on FriendFeed

fetch_user_profiles(\@users)

Returns profiles for multiple users. The returned structure has one element profiles which is an array of profile structures described alongside fetch_user_profile method.

User nicknames should be passed as an arrayref.

AUTHOR

Alex Kapranoff, <kappa at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-friendfeed at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-FriendFeed. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc Net::FriendFeed

You can also look for information at:

RT: CPAN's request tracker

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

http://annocpan.org/dist/Net-FriendFeed
CPAN Ratings

http://cpanratings.perl.org/d/Net-FriendFeed
Search CPAN

http://search.cpan.org/dist/Net-FriendFeed

ACKNOWLEDGEMENTS

Mark Carey prompted to implement via for comments.

COPYRIGHT & LICENSE

This program is released under the following license: GPLv3

To install Net::FriendFeed, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::FriendFeed

CPAN shell

perl -MCPAN -e shell
install Net::FriendFeed

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

GENERAL FUNCTIONS

new(\%opts)

last_error()

login([$login])

remotekey([$remotekey])

validate()

list_services

FEED FUNCTIONS

return_feeds_as($type)

fetch_public_feed

fetch_user_feed($user)

fetch_user_comments_feed($user)

fetch_user_likes_feed($user)

fetch_user_discussion_feed($user)

fetch_multi_user_feed(\@users)

fetch_room_feed($room)

fetch_home_feed

fetch_entry($uuid)

search($query)

PUBLISHING FUNCTIONS

publish_link($title, $link, $comment, [@images, [$imgN, $linkN]], $room, $via)

publish_message($msg)

delete_entry($entry)

undelete_entry($entry)

hide_entry($entry)

unhide_entry($entry)

COMMENT AND LIKE FUNCTIONS

add_comment($entry, $body, $via)

edit_comment($entry, $body, $comment)

delete_comment($entry, $comment)

undelete_comment($entry, $comment)

add_like($entry)

delete_like($entry)

PROFILE FUNCTIONS

fetch_user_profile($user)

fetch_user_profiles(\@users)

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Module Install Instructions