Akismet-api

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

Features:

• Typescript support
• API support for async/await, promises, and callbacks
• Supports all active versions of node (10 to 16)
• 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 ES6 async/await usage, but if you prefer another API you can also use this library with promises or with callbacks!

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.

import { AkismetClient } from 'akismet-api'

const key = 'myKey'
const blog = 'https://myblog.com'
const client = new AkismetClient({ key, blog })

Verifying your Key

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

try {
  const isValid = await client.verifyKey()

  if (isValid) console.log('Valid key!')
  else console.log('Invalid key!')
} catch (err) {
  console.error('Could not reach Akismet:', err.message)
}

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.

const 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.

try {
  const isSpam = await client.checkSpam(comment)

  if (isSpam) console.log('OMG Spam!')
  else console.log('Totally not spam')
} catch (err) {
  console.error('Something went wrong:', err.message)
}

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.

try {
  await client.submitSpam(comment)
  console.log('Spam reported!')
} catch (err) {
  console.error('Something went wrong:', err.message)
}

Submitting False Positives

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

try {
  await client.submitHam(comment)
  console.log('Non-spam reported!')
} catch (err) {
  console.error('Something went wrong:', err.message)
}

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.