akismet-api
    TypeScript icon, indicating that this package has built-in type declarations

    5.3.0 • Public • Published

    Akismet-api

    Build Status Download Count License

    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: 'not.a.spammer@gmail.com',
      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.

    Install

    npm i akismet-api

    DownloadsWeekly Downloads

    2,467

    Version

    5.3.0

    License

    MIT

    Unpacked Size

    74.4 kB

    Total Files

    20

    Last publish

    Collaborators

    • chrisfosterelli