NAME

Net::Defensio - Perl interface for Defensio.com antispam services.

VERSION

Version 0.01

DESCRIPTION

This module provides a simple interface for using the Defensio.com antispam service.

SYNOPSIS

    use Net::Defensio;
    my $defensio = Net::Defensio->new( api_key => '...' );
    my $response = $defensio->audit_comment(
        owner_url => 'http://example.com/',
        ...
    );
    if ($response && $response->success) {
        if ($response->spam) {
            print "Comment is spam: " . $response->spaminess . "\n";
        }
        else {
            print "Comment is ham!\n";
        }
    } else {
        print "Error with request: "
            . $response ? $response->message : $defensio->errstr;
    }

METHODS

Net::Defensio->new( %params )

Constructs a new Net::Defension instance. Acceptable parameters:

• api_key

  The API key provided by defensio.com. This is a required parameter.

• host

  The defensio.com API hostname to use (default is 'api.defensio.com').

• protocol

  The protocol name to use for the request (default is 'http').

• agent

  The user agent string to use for API requests (default is 'Perl-Net-Defensio/VERSION').

• user_agent

  A LWP::UserAgent object to use for API requests. If not supplied, one will be created.

• api_version

  The API version number to use for requests (this currently defaults to '1.1').

• format

  The format to request for the response from Defensio (defaults to 'yaml').

• service_type

  Denotes the type of service being requested (currently supported are: "app" (i.e. use of Defensio within an application) and "blog" (i.e. use of Defensio to support a blogging platform). The default value is 'app', but you should override this if your application is a blogging application.

$defensio->validate_key( %params )

Issues a 'validate-key' API request. The parameters for this request are (all of these parameters are required for this request):

• owner_url

  The URL of the site owner using the service.

The response object returned will have these members assigned:

• status

  Indicates whether or not the action could be processed ('success' or 'fail').

• message

  A message provided by the action if applicable.

• api_version

  The version of the API used to process the request.

Returns a Net::Defensio::Response object. If successful, the response object's 'success' method will be true. Otherwise, you can check for the error message with the response object's 'message' method.

$defensio->announce_article( %params )

Issues an 'announce-article' API request. The parameters for this request are (all of these parameters are required for this request):

• owner_url

  The URL of the site owner using the service.

• article_author

  The name of the author of the article.

• article_author_email

  The email address of the person posting the article.

• article_title

  The title of the article.

• article_content

  The content of the blog posting itself.

• permalink

  The permalink of the article just posted.

The response object returned will have these members assigned:

• status

  Indicates whether or not the action could be processed ('success' or 'fail').

• message

  A message provided by the action if applicable.

• api_version

  The version of the API used to process the request.

Notes: This request is important in the accuracy of the Defensio filtering engine. Defensio expects this request to be issued upon initial publication of an article. It should not be issued for private or otherwise unpublished articles. It should also not be re-issued with edits to the article.

$defensio->audit_comment( %params )

Issues an 'audit-comment' API request. The parameters for this request are:

• owner-url

  The URL of the site owner using the service.

• user-ip

  The IP address of whomever is posting the comment.

• article-date

  The date the original blog article was posted (should be in this format: yyyy/mm/dd).

• comment-author

  The name of the author of the comment.

• comment-type

  The type of the comment being posted to the blog (acceptable values are 'comment', 'trackback', 'pingback', 'other').

• comment-content

  (optional) The actual content of the comment (strongly recommended to be included where ever possible).

• comment-author-email

  (optional) The email address of the person posting the comment.

• comment-author-url

  (optional) The URL of the person posting the comment.

• permalink

  (optional) The permalink of the blog post to which the comment is being posted.

• referrer

  (optional) The URL of the site that brought commenter to this page.

• user-logged-in

  (optional) Whether or not the user posting the comment is logged into the blogging platform (either 'true' or 'false').

• trusted-user

  (optional) Whether or not the user is an administrator, moderator or editor of this blog; the client should pass true only if blogging platform can guarantee that the user has been authenticated and has a role of responsibility on this blog (either 'true' or 'false').

• test-force

  (optional and FOR TESTING PURPOSES ONLY) Use this parameter to force the outcome of audit-comment. Optionally affix (with a comma) a desired spaminess return value (in the range 0 to 1).

The response object returned will have these members assigned:

• status

  Indicates whether or not the action could be processed ('success' or 'fail').

• message

  A message provided by the action if applicable.

• api_version

  The version of the API used to process the request.

• signature

  A message signature that uniquely identifies the comment in the Defensio system. This signature should be stored by the client for retraining purposes.

• spam

  A boolean value indicating whether Defensio believes the comment to be spam ('true' or 'false').

• spaminess

  A value indicating the relative likelihood of the comment being spam. This value should be stored by the client for use in building convenient spam sorting user-interfaces (a float between 0 and 1, e.g. 0.9893)

$defensio->report_false_negatives( %params )

Issues an 'report-false-negatives' API request. The parameters for this request are:

• owner-url

  The URL of the site owner using the service.

• signatures

  List of signatures (may contain a single entry) of the comments to be submitted for retraining. Note that a signature for each comment was originally provided by Defensio's audit-comment action. For multiple signatures, use a comma as a delimiter.

The response object returned will have these members assigned:

• status

  Indicates whether or not the action could be processed ('success' or 'fail').

• message

  A message provided by the action if applicable.

• api_version

  The version of the API used to process the request.

$defensio->report_false_positives( %params )

Issues an 'report-false-positives' API request. The parameters for this request are:

• owner-url

  The URL of the site owner using the service.

• signatures

  List of signatures (may contain a single entry) of the comments to be submitted for retraining. Note that a signature for each comment was originally provided by Defensio's audit-comment action. For multiple signatures, use a comma as a delimiter.

The response object returned will have these members assigned:

• status

  Indicates whether or not the action could be processed ('success' or 'fail').

• message

  A message provided by the action if applicable.

• api_version

  The version of the API used to process the request.

$defensio->get_stats( %params )

Issues an 'get-stats' API request. The parameters for this request are:

• owner-url: The URL of the site owner using the service.

The response object returned will have these members assigned:

• status

  Indicates whether or not the action could be processed ('success' or 'fail').

• message

  A message provided by the action if applicable.

• api_version

  The version of the API used to process the request.

• accuracy

  Describes the percentage of comments correctly identified as spam/ham by Defensio on this blog (returns a float between 0 and 1, e.g. 0.9983).

• spam

  The number of spam comments caught by the filter.

• ham

  The number of ham (legitimate) comments accepted by the filter.

• false_positives

  The number of times a legitimate message was retrained from the spambox (i.e. "de-spammed" by the user).

• false_negatives

  The number of times a spam message was retrained from comments box (i.e. "de-legitimized" by the user).

• learning

  A boolean value indicating whether Defensio is still in its initial learning phase ('true' or 'false').

• learning_message

  More details on the reason(s) why Defensio is still in its initial learning phase.

COPYRIGHT & LICENSE

Copyright 2007 Brad Choate, all rights reserved.

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

cpanm Net::Defensio

perl -MCPAN -e shell
install Net::Defensio