Skip to content

Latest commit

 

History

History
168 lines (131 loc) · 4.73 KB

callbacks.md

File metadata and controls

168 lines (131 loc) · 4.73 KB
Raw

Akismet-api

Build Status Dependency Status Download Count License

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

Features:

  • API support for async/await, promises, and callbacks
  • Supports all active versions of node (8 to 13)
  • Supports all Akismet API features
  • Complete set of unit and integration tests
  • Idiomatic JS parameters (with backward compatability)
  • Trusted by many projects (like Coral!)

Upgrading to 5.0? The docs have changed a fair bit but everything is backward compatible on supported node versions, so you likely don't need to change anything! Check out the changelog.

These docs below are with callback usage, but if you prefer another API you can also use this library with ES6 async/await or with promises!

Installing

$ npm install --save akismet-api

Creating the Client

Your blog URL and API key are required by Akismet and are all you will need to get started! For a full list of available client parameters and alternative constructors, check out the client documentation.

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

Verifying your Key

It's a good idea to verify your key before use.

client.verifyKey(function(err, isValid) {
  if (err) return console.error('Error:', err.message);

  if (isValid) console.log('Valid key!');
  else console.log('Invalid key!');
});

Creating a Comment

A comment, at the bare minimum, must have the commenter's IP and user agent. You can provide more than that for better accuracy and doing so is strongly recommended. The following is a basic example, but see our documentation on the comment data structure for a complete list of fields you can provide.

var comment = {
  ip: '123.123.123.123',
  useragent: 'CommentorsAgent 1.0 WebKit',
  content: 'Very nice blog! Check out mine!',
  email: '[email protected]',
  name: 'John Doe'
};

Checking for Spam

Once you have a comment, we can check it! This tells you if it is spam or not. If Akismet cannot be reached or returns an error, checkSpam will throw an exception.

client.checkSpam(comment, function(err, isSpam) {
  if (err) return console.error('Error:', err.message);

  if (isSpam) 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 to help improve their accuracy in the future.

client.submitSpam(comment, function(err) {
  if (err) return console.error('Error:', err.message);
  console.log('Spam reported!');
});

Submitting False Positives

If Akismet reports something as spam, but it turns out to not be spam, we can report this to Akismet too.

client.submitHam(comment, function(err) {
  if (err) return console.error('Error:', err.message);
  console.log('Non-spam reported!');
});

Testing

If you are running integration tests on your app with Akismet, you should set isTest: true in your comments! That way, your testing data won't affect Akismet.

To run the library's tests, just use npm test. To also run the optional integration tests, include a valid Akismet API key in the AKISMET_KEY environment variable.

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.