diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 891c350..4625a31 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -19,27 +19,3 @@ jobs: env: AKISMET_API_KEY: ${{secrets.AKISMET_API_KEY}} NODE_ENV: test - deploy: - needs: test - runs-on: ubuntu-latest - steps: - - name: Fetch sources - uses: actions/checkout@v4 - - name: Set up Node.js - uses: actions/setup-node@v4 - with: - cache: npm - node-version: 22 - - name: Set up Python - uses: actions/setup-python@v5 - with: - cache: pip - python-version: 3.12 - - name: Install dependencies - run: | - npm ci - pip install --requirement=etc/requirements.txt - - name: Deploy documentation - run: | - npx gulp doc - mkdocs gh-deploy --config-file=etc/mkdocs.yaml --force diff --git a/.gitignore b/.gitignore index 6f85d2b..4b8c587 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,8 @@ /**/.DS_Store /.idea/ -/docs/api/ /etc/http-client.private.env.json /lib/ /node_modules/ /npm-debug.log /var/ -/www/ +/wiki/ diff --git a/README.md b/README.md index c1aa9f0..adc2d28 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,11 @@ Prevent comment spam using [Akismet](https://akismet.com) service, in [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript). ## Documentation -- [User guide](https://docs.belin.io/akismet.js) -- [API reference](https://docs.belin.io/akismet.js/api) +- [User guide](https://github.com/cedx/akismet.js/wiki) +- [Examples](https://github.com/cedx/akismet.js/tree/main/example) ## Development - [Git repository](https://github.com/cedx/akismet.js) -- [npm package](https://www.npmjs.com/package/@cedx/akismet) - [Submit an issue](https://github.com/cedx/akismet.js/issues) ## License diff --git a/docs/favicon.ico b/docs/favicon.ico deleted file mode 100644 index 4e9b4c6..0000000 Binary files a/docs/favicon.ico and /dev/null differ diff --git a/docs/favicon.svg b/docs/favicon.svg deleted file mode 100644 index d77226c..0000000 --- a/docs/favicon.svg +++ /dev/null @@ -1 +0,0 @@ -JS-avatar \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 7ba99d3..0000000 --- a/docs/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Akismet for JS -Used by millions of websites, [Akismet](https://akismet.com) filters out hundreds of millions of spam comments from the Web every day. -Add Akismet to your [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) applications so you don't have to worry about spam again. - -!!! warning - The Akismet service requires an API key. - If you are not already registered, [sign up for an Akismet account](https://akismet.com/developers). - -## Quick start -Install the latest version of **Akismet for JS** with [npm](https://getcomposer.org) package manager: - -```shell -npm install @cedx/akismet -``` - -For detailed instructions, see the [installation guide](installation.md). - -## Usage -There are three different types of calls to [Akismet](https://akismet.com): - -1. [Key verification](usage/verify_key.md) will verify whether a valid API key is being used. This is especially useful if you will have multiple users with their own Akismet subscriptions using your application. -2. [Comment check](usage/check_comment.md) is used to ask Akismet whether a given post, comment, profile, etc. is spam. -3. [Submit spam](usage/submit_spam.md) and [submit ham](usage/submit_ham.md) are follow-ups to let Akismet know when it got something wrong (missed spam and false positives). These are very important, and you shouldn't develop using the Akismet API without a facility to include reporting missed spam and false positives. - -Before integrating this library into your application, you should [test your API calls](testing.md) to ensure a proper usage. diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 73eca83..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,28 +0,0 @@ -# Installation - -## Requirements -Before installing **Akismet for JS**, you need to make sure you have [Node.js](https://nodejs.org) -and [npm](https://www.npmjs.com), the Node.js package manager, up and running. - -You can verify if you're already good to go with the following command: - -```shell -node --version -# v22.0.0 -``` - -## Installing with npm package manager - -### 1. Install it -From a command prompt, run: - -```shell -npm install @cedx/akismet -``` - -### 2. Import it -Now in your [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) code, you can use: - -```js -import * as akismet from "@cedx/akismet"; -``` diff --git a/docs/styles.css b/docs/styles.css deleted file mode 100644 index ff5dd9a..0000000 --- a/docs/styles.css +++ /dev/null @@ -1,4 +0,0 @@ -body { - --md-code-font-family: ui-monospace, monospace; - --md-text-font-family: ui-sans-serif, sans-serif; -} diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index d54d30d..0000000 --- a/docs/testing.md +++ /dev/null @@ -1,74 +0,0 @@ -# Testing -When you will integrate this library with your own application, you will of course need to test it. -Often we see developers get ahead of themselves, making a few trivial API calls with minimal values -and drawing the wrong conclusions about Akismet's accuracy. - -## Simulate a positive result (spam) -Make a [comment check](usage/check_comment.md) API call with the `Author.name` set to `"viagra-test-123"` -or `Author.email` set to `"akismet-guaranteed-spam@example.com"`. Populate all other required fields with typical values. - -The Akismet API will always return a `CheckResult.spam` response to a valid request with one of those values. -If you receive anything else, something is wrong in your client, data, or communications. - -```js -import console from "node:console"; -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -const comment = new Comment({ - content: "A user comment.", - author: new Author({ - ipAddress: "127.0.0.1", - name: "viagra-test-123", - userAgent: "Mozilla/5.0" - }) -}); - -const blog = new Blog({url: "https://www.yourblog.com"}) -const result = await new Client("123YourAPIKey", blog).checkComment(comment); -console.log(`It should be "CheckResult.spam": ${result}`); -``` - -## Simulate a negative result (ham) -Make a [comment check](usage/check_comment.md) API call with the `Author.role` set to `"administrator"` -and all other required fields populated with typical values. - -The Akismet API will always return a `CheckResult.ham` response. Any other response indicates a data or communication problem. - -```js -import console from "node:console"; -import {Author, AuthorRole, Blog, Client, Comment} from "@cedx/akismet"; - -const comment = new Comment({ - content: "A user comment.", - author: new Author({ - ipAddress: "127.0.0.1", - role: AuthorRole.administrator, - userAgent: "Mozilla/5.0" - }) -}); - -const blog = new Blog({url: "https://www.yourblog.com"}) -const result = await new Client("123YourAPIKey", blog).checkComment(comment); -console.log(`It should be "CheckResult.ham": ${result}`); -``` - -## Automated testing -Enable the `Client.isTest` option in your tests. - -That will tell Akismet not to change its behaviour based on those API calls: they will have no training effect. -That means your tests will be somewhat repeatable, in the sense that one test won't influence subsequent calls. - -```js -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -const blog = new Blog({url: "https://www.yourblog.com"}); -const client = new Client("123YourAPIKey", blog, {isTest: true}); - -const comment = new Comment({ - content: "A user comment.", - author: new Author({ipAddress: "127.0.0.1", userAgent: "Mozilla/5.0"}) -}); - -// It should not influence subsequent calls. -client.checkComment(comment); -``` diff --git a/docs/usage/check_comment.md b/docs/usage/check_comment.md deleted file mode 100644 index 8d3a99a..0000000 --- a/docs/usage/check_comment.md +++ /dev/null @@ -1,72 +0,0 @@ -# Comment check -This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content -and then returns a thumbs up or thumbs down. **Performance can drop dramatically if you choose to exclude data points.** -The more data you send Akismet about each comment, the greater the accuracy. We recommend erring on the side of including too much data. - -```ts -Client.checkComment(comment: Comment): Promise -``` - -It is important to [test Akismet](../testing.md) with a significant amount of real, live data in order to draw any conclusions on accuracy. -Akismet works by comparing content to genuine spam activity happening **right now** (and this is based on more than just the content itself), -so artificially generating spam comments is not a viable approach. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/comment-check) for more information. - -## Parameters - -### **comment**: Comment -The `Comment` providing the user's message to be checked. - -## Return value -A `Promise` that resolves with a `CheckResult` value indicating whether the given `Comment` is ham, spam or pervasive spam. - -!!! tip - A comment classified as pervasive spam can be safely discarded. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Author, Blog, CheckResult, Client, Comment, CommentType} from "@cedx/akismet"; - -try { - const author = new Author({ - email: "john.doe@domain.com", - ipAddress: "192.168.123.456", - name: "John Doe", - role: "guest", - userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Edg/126.0.0.0" - }); - - const comment = new Comment({ - author, - date: new Date, - content: "A user comment.", - referrer: "https://github.com/cedx/akismet.js", - type: CommentType.contactForm - }); - - const blog = new Blog({ - charset: "UTF-8", - languages: ["fr"], - url: "https://www.yourblog.com" - }); - - const result = await new Client("123YourAPIKey", blog).checkComment(comment); - console.log(result == CheckResult.ham ? "The comment is ham." : "The comment is spam."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` - -See the [API reference](../api/) for detailed information about the `Author` and `Comment` classes, and their properties. diff --git a/docs/usage/submit_ham.md b/docs/usage/submit_ham.md deleted file mode 100644 index 00c61de..0000000 --- a/docs/usage/submit_ham.md +++ /dev/null @@ -1,57 +0,0 @@ -# Submit ham -This call is intended for the submission of false positives - items that were incorrectly classified as spam by Akismet. -It takes identical arguments as [comment check](check_comment.md) and [submit spam](submit_spam.md). - -```ts -Client.submitHam(comment: Comment): Promise -``` - -Remember that, as explained in the [submit spam](submit_spam.md) documentation, you should ensure -that any values you're passing here match up with the original and corresponding [comment check](check_comment.md) call. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/submit-ham-false-positives) for more information. - -## Parameters - -### **comment**: Comment -The user's `Comment` to be submitted, incorrectly classified as spam. - -!!! note - Ideally, it should be the same object as the one passed to the original [comment check](check_comment.md) API call. - -## Return value -A `Promise` that resolves when the given `Comment` has been submitted. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -try { - const blog = new Blog({url: "https://www.yourblog.com"}); - const client = new Client("123YourAPIKey", blog); - - const comment = new Comment({ - content: "I'm testing out the Service API.", - author: new Author({ - ipAddress: "192.168.123.456", - userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Edg/126.0.0.0" - }) - }); - - await client.submitHam(comment); - console.log("The comment was successfully submitted as ham."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` diff --git a/docs/usage/submit_spam.md b/docs/usage/submit_spam.md deleted file mode 100644 index 233badb..0000000 --- a/docs/usage/submit_spam.md +++ /dev/null @@ -1,59 +0,0 @@ -# Submit spam -This call is for submitting comments that weren't marked as spam but should have been. - -```ts -Client.submitSpam(comment: Comment): Promise -``` - -It is very important that the values you submit with this call match those of your [comment check](check_comment.md) calls as closely as possible. -In order to learn from its mistakes, Akismet needs to match your missed spam and false positive reports -to the original [comment check](check_comment.md) API calls made when the content was first posted. While it is normal for less information -to be available for [submit spam](submit_spam.md) and [submit ham](submit_ham.md) calls (most comment systems and forums will not store all metadata), -you should ensure that the values that you do send match those of the original content. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/submit-spam-missed-spam) for more information. - -## Parameters - -### **comment**: Comment -The user's `Comment` to be submitted, incorrectly classified as ham. - -!!! note - Ideally, it should be the same object as the one passed to the original [comment check](check_comment.md) API call. - -## Return value -A `Promise` that resolves when the given `Comment` has been submitted. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -try { - const blog = new Blog({url: "https://www.yourblog.com"}); - const client = new Client("123YourAPIKey", blog); - - const comment = new Comment({ - content: "Spam!", - author: new Author({ - ipAddress: "192.168.123.456", - userAgent: "Spam Bot/6.6.6" - }) - }); - - await client.submitSpam(comment); - console.log("The comment was successfully submitted as spam."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` diff --git a/docs/usage/verify_key.md b/docs/usage/verify_key.md deleted file mode 100644 index c1f14b5..0000000 --- a/docs/usage/verify_key.md +++ /dev/null @@ -1,46 +0,0 @@ -# Key verification -Key verification authenticates your API key before calling the [comment check](check_comment.md), -[submit spam](submit_spam.md) or [submit ham](submit_ham.md) methods. - -```ts -Client.verifyKey(): Promise -``` - -This is the first call that you should make to Akismet and is especially useful -if you will have multiple users with their own Akismet subscriptions using your application. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/key-verification) for more information. - -## Parameters -None. - -## Return value -A `Promise` that resolves with a boolean value indicating whether the client's API key is valid. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Blog, Client} from "@cedx/akismet"; - -try { - const blog = new Blog({url: "https://www.yourblog.com"}); - const client = new Client("123YourAPIKey", blog); - - const isValid = await client.verifyKey(); - console.log(isValid ? "The API key is valid." : "The API key is invalid."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` - -See the [API reference](../api/) for detailed information about the `Client` and `Blog` classes, and their properties and methods. diff --git a/etc/mkdocs.yaml b/etc/mkdocs.yaml deleted file mode 100644 index d86d42a..0000000 --- a/etc/mkdocs.yaml +++ /dev/null @@ -1,66 +0,0 @@ -site_name: Akismet for JS -site_url: https://docs.belin.io/akismet.js -site_author: Cédric Belin - cedric@belin.io -site_description: > - Prevent comment spam using the Akismet service, in JavaScript. - Add Akismet to your JavaScript applications so you don't have to worry about spam again. - -docs_dir: ../docs -site_dir: ../www -use_directory_urls: false - -edit_uri: edit/main/docs/ -repo_name: cedx/akismet.js -repo_url: https://github.com/cedx/akismet.js - -copyright: Copyright © Cédric Belin -extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/cedx - name: GitHub - - icon: fontawesome/brands/linkedin - link: https://linkedin.com/in/cedxbelin - name: LinkedIn - - icon: fontawesome/brands/mastodon - link: https://mastodon.social/@cedx - name: Mastodon - -extra_css: - - styles.css - -markdown_extensions: - - admonition - - pymdownx.superfences - -nav: - - Home: index.md - - Installation: installation.md - - Usage: - - Key verification: usage/verify_key.md - - Comment check: usage/check_comment.md - - Submit spam: usage/submit_spam.md - - Submit ham: usage/submit_ham.md - - Related topics: - - API reference: api/ - - Testing: testing.md - - See also: - - Changelog: changelog.md - - License: license.md - -theme: - favicon: favicon.svg - features: - - content.code.copy - - content.tooltips - - navigation.footer - - navigation.instant - - navigation.instant.progress - - navigation.sections - - search.suggest - font: false - logo: favicon.svg - name: material - palette: - accent: yellow - primary: yellow diff --git a/etc/requirements.txt b/etc/requirements.txt deleted file mode 100644 index 4c8f017..0000000 --- a/etc/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mkdocs-material diff --git a/etc/typedoc.js b/etc/typedoc.js deleted file mode 100644 index 5468111..0000000 --- a/etc/typedoc.js +++ /dev/null @@ -1,10 +0,0 @@ -export default { - entryPoints: ["../src/index.js"], - excludePrivate: true, - gitRevision: "main", - hideGenerator: true, - name: "Akismet for JS", - out: "../docs/api", - readme: "none", - tsconfig: "../src/tsconfig.json" -}; diff --git a/gulpfile.js b/gulpfile.js index e0d7cfd..a2aa8b1 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -1,4 +1,4 @@ -import {cp, readFile, writeFile} from "node:fs/promises"; +import {readFile, writeFile} from "node:fs/promises"; import {env} from "node:process"; import {deleteAsync} from "del"; import {$} from "execa"; @@ -17,12 +17,6 @@ export function clean() { return deleteAsync(["lib", "var/**/*", "www"]); } -// Builds the documentation. -export async function doc() { - for (const file of ["CHANGELOG.md", "LICENSE.md"]) await cp(file, `docs/${file.toLowerCase()}`); - return $`typedoc --options etc/typedoc.js`; -} - // Performs the static analysis of source code. export async function lint() { await $`tsc --project tsconfig.json`; @@ -35,12 +29,6 @@ export async function publish() { for (const action of [["tag"], ["push", "origin"]]) await $`git ${action} v${pkg.version}`; } -// Starts the development server. -export async function serve() { - await doc(); - return $({stdio: "inherit"})`mkdocs serve --config-file=etc/mkdocs.yaml`; -} - // Runs the test suite. export function test() { env.NODE_ENV = "test"; diff --git a/package.json b/package.json index cfc67bd..3f722fd 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "bugs": "https://github.com/cedx/akismet.js/issues", "description": "Prevent comment spam using the Akismet service.", - "homepage": "https://docs.belin.io/akismet.js", + "homepage": "https://github.com/cedx/akismet.js", "license": "MIT", "name": "@cedx/akismet", "repository": "cedx/akismet.js",