/ 
Net-Stitcho-0.02
/ Net::Stitcho

NAME

Net::Stitcho - Client module for the Stitcho.com API

VERSION

Version 0.01

SYNOPSIS

use Net::Stitcho;

my $api = Net::Stitcho->new({
  id  => 1,          # your partner id
  key => '3246327a', # the secrect signing key
});

my $uri = $api->send_uri({
  email   => 'melo@cpan.org',       # Recipient address
  message => 'Yuppi!',              # Message to send
  url     => 'http://stitcho.com/', # Jump to this URL on click
  icon    => 1,                     # ID of the icon to use
});

my $error = $api->send({
  # same arguments as send_uri()
  # this version uses LWP::UserAgent to actually call the API
});

DESCRITION

The module provides access to the Stitcho.com notification service using the provided HTTP-based API.

You need to get an partner account at the site. After you have your API secret key, you can start to use this module.

You can use this module in two ways:

  • to generate the proper URIs to use with the API;

  • to call the API;

The first option is best if you have a way to do the HTTP GET request yourself. For example, if you are using AnyEvent or POE, you can use their Async HTTP client to call the API using the URI calculated by this module.

METHODS

new

Creates a new API object. Accepts a hashref of parameters. Valid keys are:

id

Partner ID provided by Stitcho.com.

key

Secret signing key provided by Stitcho.com.

Returns a API object.

send_uri

Constructs the URI to use to send a notification to a user.

Accepts a hashref of parameters. Valid keys are:

email

Email address of recipient.

title

Title of the notification.

message

Message text.

url

If the message is clicked, the users browser will open with this URL.

icon (optional)

Numeric ID of the icon to use.

Returns the complete URI to use to call the Send API. Use your prefered HTTP client to do the actual call.

send

Sends a notification to a user.

Accepts the same parameters as the send_uri() method.

After creating a proper URL, uses LWP::UserAgent to call the API.

If successful, returns no error (undef).

If not, returns the HTTP code of the operation. As of October 2008, the documented HTTP codes are:

202

The call was formatted correctly, but the user was not connected, so the notification was not sent.

400

The request was incorrectly formatted.

If you get this error code, report it as a bug to the author of this module.

401

The signature was invalid. Check the id and key parameters to your call to new().

500

An unanticipated error occurred, and the problem most likely lies with Stitcho, not your software. Retry in a minute or so.

EXPORT

This module does not export any symbols.

AUTHOR

Pedro Melo, <melo at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-stitcho at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Stitcho. 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::Stitcho

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Pedro Melo.

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

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 222:

Non-ASCII character seen before =encoding in 'notification'. Assuming UTF-8

Around line 225:

Expected text after =item, not a number

Around line 232:

Expected text after =item, not a number

Around line 238:

Expected text after =item, not a number