Akismet-api

Full Nodejs bindings to the Akismet (https://akismet.com) spam detection service.

Features:

Promise and callback support
Supports all active versions of node (4 to 10)
Supports all Akismet API features
Uses a modern HTTP client
Complete test suite
No coffeescript

Upgrading to 4.0? You likely don't need to change anything, but check out the changelog.

Installing

npm install akismet-api

Creating the Client

The blog and key values are required by Akismet. There are a set of other avaliable default options visible in the source, but you likely will not need to change those.

var akismet = require('akismet-api');
var client = akismet.client({
  key  : 'myKey',                   // Required!
  blog : 'https://myblog.com'       // Required!
});

Promises and Callbacks

All of the function methods below support both promises and callbacks! The returned promises use the Bluebird promise library. The following documentation primarily uses the callback version, but to return a promise simply don't provide a callback. Here is an example of the promise version of the verifyKey() function:

client.verifyKey()
.then(function(valid) {
  if (valid) console.log('Valid key!');
  else console.log('Invalid key!');
})
.catch(function(err) {
  console.log('Check failed: ' + err.message);
}):

Verifying your Key

It's a good idea to verify your key before use. If your key returns as invalid, the error field will contain the debug help message returned by Akismet.

client.verifyKey(function(err, valid) {
  if (err) console.log('Error:', err.message);
  if (valid) console.log('Valid key!');
  else console.log('Invalid key!');
});

Checking for Spam

The user_ip, user_agent, and referrer are required options. All other options are optional, but will provide you with better spam detection accuracy.

client.checkSpam({
  user_ip : '123.123.123.123',              // Required!
  user_agent : 'MyUserAgent 1.0 Webkit',    // Required!
  referrer : 'https://google.com',          // Required!
  permalink : 'https://myblog.com/myPost',
  comment_type : 'comment',
  comment_author : 'John Smith',
  comment_author_email : 'john.smith@gmail.com',
  comment_author_url : 'https://johnsblog.com',
  comment_content : 'Very nice blog! Check out mine!',
  is_test : true // Default value is false
}, function(err, spam) {
  if (err) console.log ('Error!');
  if (spam) {
    console.log('OMG Spam!');
  } else {
    console.log('Totally not spam');
  }
});

Submitting False Negatives

If Akismet reports something as not-spam, but it turns out to be spam anyways, we can report this to Akismet via this API call.

client.submitSpam({
  user_ip : '123.123.123.123',              // Required!
  user_agent : 'MyUserAgent 1.0 Webkit',    // Required!
  referrer : 'https://google.com',          // Required!
  permalink : 'https://myblog.com/myPost',
  comment_type : 'comment',
  comment_author : 'John Smith',
  comment_author_email : 'john.smith@gmail.com',
  comment_author_url : 'https://johnsblog.com',
  comment_content : 'Very nice blog! Check out mine!',
  is_test : true // Default value is false
}, function(err) {
  if (!err) {
    console.log('Spam reported!');
  }
});

Submitting False Positives

If Akismet reports something as spam, but it turns out to not be spam anyways, we can report this to Akismet via this API call.

client.submitHam({
  user_ip : '123.123.123.123',              // Required!
  user_agent : 'MyUserAgent 1.0 Webkit',    // Required!
  referrer : 'https://google.com',          // Required!
  permalink : 'https://myblog.com/myPost',
  comment_type : 'comment',
  comment_author : 'John Smith',
  comment_author_email : 'john.smith@gmail.com',
  comment_author_url : 'https://johnsblog.com',
  comment_content : 'Very nice blog! Check out mine!',
  is_test : true // Default value is false
}, function(err) {
  if (!err) {
    console.log('Non-spam reported!');
  }
});

Testing

cd node_modules/akismet-api
npm test

Credits

Author and maintainer is Chris Foster. Development was sponsored by Two Story Robot.

License

Released under the MIT license.

See LICENSE.txt for more information.

lkbr / akismet-api