feat: Add tooling, docs, examples etc. (#1)

* Update a lot of stuff * Add docs * Make build work * Add example * Add files in package.json * Add github files * Add README * Update README * Update syntax * Remove test * Update README * Update README * Update docs * Update syntax * Update readme * Update README * Bigger image * Image below * Update README * Update LICENSE * Remove license headers * Docs * Update docs
reacherhq · Jul 12, 2020 · f231392 · f231392
1 parent 1c0444a
commit f231392
Show file tree

Hide file tree

Showing 28 changed files with 3,919 additions and 661 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -0,0 +1,2 @@
+.eslintrc.js
+**/lib/*
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -0,0 +1 @@
+module.exports = require('@amaurymartiny/eslintrc');
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: amaurymartiny
+custom: https://www.paypal.me/amaurymartiny/10
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
@@ -0,0 +1,13 @@
+name: pr
+
+on: [pull_request]
+
+jobs:
+    lint:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+            - name: Run yarn lint
+              run: |
+                  yarn install
+                  yarn lint
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Built
+lib
+
+# Dependency directories
+node_modules/
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+.yarn-integrity
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "backend"]
+	path = backend
+	url = https://github.com/reacherhq/backend
diff --git a/.prettierrc.js b/.prettierrc.js
@@ -0,0 +1 @@
+module.exports = require('@amaurymartiny/eslintrc/prettierrc');
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -0,0 +1,109 @@
+<br /><br />
+
+<h1 align="center">@reacherhq/api</h1>
+<h4 align="center">Check if an email address exists without sending any email.</h4>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@reacherhq/api">
+    <img alt="npm" src="https://img.shields.io/npm/v/@reacherhq/api.svg" />
+  </a>
+  <a href="https://github.com/reacherhq/reacher-js/actions">
+    <img alt="Github Actions" src="https://github.com/reacherhq/reacher-js/workflows/pr/badge.svg" />
+  </a>
+  <a href="https://opensource.org/licenses/Apache-2.0">
+    <img alt="Apache-2.0" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" />
+  </a>
+  <a href="https://david-dm.org/reacherhq/reacher-js">
+    <img alt="david-dm" src="https://img.shields.io/david/reacherhq/reacher-js.svg" />
+  </a>
+</p>
+
+<br /><br />
+
+## What is it?
+
+This tool allows you to check if an email address exists without sending any email.
+
+It is a thin TypeScript wrapper around the [Reacher Email Verification API](https://reacher.email). Reacher is a 100% open-source SaaS, written in Rust. It's also free for personal use, and the API token in `@reacherhq/api` is optional, but in this case the requests will be rate-limited.
+
+## Usage
+
+Install the package:
+
+```bash
+yarn add @reacherhq/api # Or npm install @reacherhq/api
+```
+
+Then open up a JavaScript file and use:
+
+```typescript
+import { checkEmail } from '@reacherhq/api';
+
+checkEmail({ to_email: '[email protected]' }).then(console.log); // Output will be the JSON described below.
+```
+
+## 📚 [See Full Documentation](https://github.com/reacherhq/reacher-js/blob/master/docs/modules/_src_index_.md#functions-1)
+
+## What Does Reacher Check?
+
+| Included? | Feature                                       | Description                                                                                                                     | JSON field               |
+| --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| ✅        | **Email reachability**                        | How confident are we in sending an email to this address? Can be one of `safe`, `risky`, `invalid` or `unknown`.                | `is_reachable`           |
+| ✅        | **Syntax validation**                         | Is the address syntactically valid?                                                                                             | `syntax.is_valid_syntax` |
+| ✅        | **DNS records validation**                    | Does the domain of the email address have valid MX DNS records?                                                                 | `mx.accepts_mail`        |
+| ✅        | **Disposable email address (DEA) validation** | Is the address provided by a known [disposable email address](https://en.wikipedia.org/wiki/Disposable_email_address) provider? | `misc.is_disposable`     |
+| ✅        | **SMTP server validation**                    | Can the mail exchanger of the email address domain be contacted successfully?                                                   | `smtp.can_connect_smtp`  |
+| ✅        | **Email deliverability**                      | Is an email sent to this address deliverable?                                                                                   | `smtp.is_deliverable`    |
+| ✅        | **Mailbox disabled**                          | Has this email address been disabled by the email provider?                                                                     | `smtp.is_disabled`       |
+| ✅        | **Full inbox**                                | Is the inbox of this mailbox full?                                                                                              | `smtp.has_full_inbox`    |
+| ✅        | **Catch-all address**                         | Is this email address a [catch-all](https://debounce.io/blog/help/what-is-a-catch-all-or-accept-all/) address?                  | `smtp.is_catch_all`      |
+| ✅        | **Role account validation**                   | Is the email address a well-known role account?                                                                                 | `misc.is_role_account`   |
+
+## JSON Output
+
+The output will be a JSON with the below format, the fields should be self-explanatory. For `[email protected]` (note that it is disabled by Gmail), here's the exact output:
+
+```json
+{
+	"input": "[email protected]",
+	"is_reachable": "invalid",
+	"misc": {
+		"is_disposable": false,
+		"is_role_account": false
+	},
+	"mx": {
+		"accepts_mail": true,
+		"records": [
+			"alt3.gmail-smtp-in.l.google.com.",
+			"gmail-smtp-in.l.google.com.",
+			"alt1.gmail-smtp-in.l.google.com.",
+			"alt4.gmail-smtp-in.l.google.com.",
+			"alt2.gmail-smtp-in.l.google.com."
+		]
+	},
+	"smtp": {
+		"can_connect_smtp": true,
+		"has_full_inbox": false,
+		"is_catch_all": false,
+		"is_deliverable": false,
+		"is_disabled": true
+	},
+	"syntax": {
+		"domain": "gmail.com",
+		"is_valid_syntax": true,
+		"username": "someone"
+	}
+}
+```
+
+You can also take a look at the [OpenAPIv3 specification](https://reacher.email/docs#operation/post-check-email) of this JSON object.
+
+## License
+
+The source code is available under the Apache-2.0 license. See the [LICENSE](./LICENSE) file for more info.
+
+## 🌯 Sponsor me a Falafel Wrap
+
+I don't drink coffee, but consider sponsoring me with a wrap from my favorite Falafel dealer! 👉 [See which one.](https://github.com/sponsors/amaurymartiny/)
+
+[![Sponsor](https://img.shields.io/badge/Github%20Sponsors-%E2%9D%A4%EF%B8%8F-white)](https://github.com/sponsors/amaurymartiny/)
diff --git a/backend b/backend
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,113 @@
+[@reacherhq/api](README.md) › [Globals](globals.md)
+
+# @reacherhq/api
+
+<br /><br />
+
+<h1 align="center">@reacherhq/api</h1>
+<h4 align="center">Check if an email address exists without sending any email.</h4>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@reacherhq/api">
+    <img alt="npm" src="https://img.shields.io/npm/v/@reacherhq/api.svg" />
+  </a>
+  <a href="https://github.com/reacherhq/reacher-js/actions">
+    <img alt="Github Actions" src="https://github.com/reacherhq/reacher-js/workflows/pr/badge.svg" />
+  </a>
+  <a href="https://opensource.org/licenses/Apache-2.0">
+    <img alt="Apache-2.0" src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" />
+  </a>
+  <a href="https://david-dm.org/reacherhq/reacher-js">
+    <img alt="david-dm" src="https://img.shields.io/david/reacherhq/reacher-js.svg" />
+  </a>
+</p>
+
+<br /><br />
+
+## What is it?
+
+This tool allows you to check if an email address exists without sending any email.
+
+It is a thin TypeScript wrapper around the [Reacher Email Verification API](https://reacher.email). Reacher is a 100% open-source SaaS, written in Rust. It's also free for personal use, and the API token in `@reacherhq/api` is optional, but in this case the requests will be rate-limited.
+
+## Usage
+
+Install the package:
+
+```bash
+yarn add @reacherhq/api # Or npm install @reacherhq/api
+```
+
+Then open up a JavaScript file and use:
+
+```typescript
+import { checkEmail } from '@reacherhq/api';
+
+checkEmail({ to_email: '[email protected]' }).then(console.log); // Output will be the JSON described below.
+```
+
+## 📚 [See Full Documentation](https://github.com/reacherhq/reacher-js/blob/master/docs/modules/_src_index_.md#functions-1)
+
+## What Does Reacher Check?
+
+| Included? | Feature                                       | Description                                                                                                                     | JSON field               |
+| --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| ✅        | **Email reachability**                        | How confident are we in sending an email to this address? Can be one of `safe`, `risky`, `invalid` or `unknown`.                | `is_reachable`           |
+| ✅        | **Syntax validation**                         | Is the address syntactically valid?                                                                                             | `syntax.is_valid_syntax` |
+| ✅        | **DNS records validation**                    | Does the domain of the email address have valid MX DNS records?                                                                 | `mx.accepts_mail`        |
+| ✅        | **Disposable email address (DEA) validation** | Is the address provided by a known [disposable email address](https://en.wikipedia.org/wiki/Disposable_email_address) provider? | `misc.is_disposable`     |
+| ✅        | **SMTP server validation**                    | Can the mail exchanger of the email address domain be contacted successfully?                                                   | `smtp.can_connect_smtp`  |
+| ✅        | **Email deliverability**                      | Is an email sent to this address deliverable?                                                                                   | `smtp.is_deliverable`    |
+| ✅        | **Mailbox disabled**                          | Has this email address been disabled by the email provider?                                                                     | `smtp.is_disabled`       |
+| ✅        | **Full inbox**                                | Is the inbox of this mailbox full?                                                                                              | `smtp.has_full_inbox`    |
+| ✅        | **Catch-all address**                         | Is this email address a [catch-all](https://debounce.io/blog/help/what-is-a-catch-all-or-accept-all/) address?                  | `smtp.is_catch_all`      |
+| ✅        | **Role account validation**                   | Is the email address a well-known role account?                                                                                 | `misc.is_role_account`   |
+
+## JSON Output
+
+The output will be a JSON with the below format, the fields should be self-explanatory. For `[email protected]` (note that it is disabled by Gmail), here's the exact output:
+
+```json
+{
+	"input": "[email protected]",
+	"is_reachable": "invalid",
+	"misc": {
+		"is_disposable": false,
+		"is_role_account": false
+	},
+	"mx": {
+		"accepts_mail": true,
+		"records": [
+			"alt3.gmail-smtp-in.l.google.com.",
+			"gmail-smtp-in.l.google.com.",
+			"alt1.gmail-smtp-in.l.google.com.",
+			"alt4.gmail-smtp-in.l.google.com.",
+			"alt2.gmail-smtp-in.l.google.com."
+		]
+	},
+	"smtp": {
+		"can_connect_smtp": true,
+		"has_full_inbox": false,
+		"is_catch_all": false,
+		"is_deliverable": false,
+		"is_disabled": true
+	},
+	"syntax": {
+		"domain": "gmail.com",
+		"is_valid_syntax": true,
+		"username": "someone"
+	}
+}
+```
+
+You can also take a look at the [OpenAPIv3 specification](https://reacher.email/docs#operation/post-check-email) of this JSON object.
+
+## License
+
+The source code is available under the Apache-2.0 license. See the [LICENSE](./LICENSE) file for more info.
+
+## 🌯 Sponsor me a Falafel Wrap
+
+I don't drink coffee, but consider sponsoring me with a wrap from my favorite Falafel dealer! 👉 [See which one.](https://github.com/sponsors/amaurymartiny/)
+
+[![Sponsor](https://img.shields.io/badge/Github%20Sponsors-%E2%9D%A4%EF%B8%8F-white)](https://github.com/sponsors/amaurymartiny/)
diff --git a/docs/globals.md b/docs/globals.md
@@ -0,0 +1,10 @@
+[@reacherhq/api](README.md) › [Globals](globals.md)
+
+# @reacherhq/api
+
+## Index
+
+### Modules
+
+* ["src/index"](modules/_src_index_.md)
+* ["src/types"](modules/_src_types_.md)
diff --git a/docs/interfaces/_src_index_.checkemailinput.md b/docs/interfaces/_src_index_.checkemailinput.md
@@ -0,0 +1,53 @@
+[@reacherhq/api](../README.md) › [Globals](../globals.md) › ["src/index"](../modules/_src_index_.md) › [CheckEmailInput](_src_index_.checkemailinput.md)
+
+# Interface: CheckEmailInput
+
+## Hierarchy
+
+* object
+
+  ↳ **CheckEmailInput**
+
+## Index
+
+### Properties
+
+* [from_email](_src_index_.checkemailinput.md#optional-from_email)
+* [hello_name](_src_index_.checkemailinput.md#optional-hello_name)
+* [to_email](_src_index_.checkemailinput.md#to_email)
+
+## Properties
+
+### `Optional` from_email
+
+• **from_email**? : *undefined | string*
+
+*Inherited from [__type](_src_types_.components.md#__type).[from_email](_src_types_.components.md#optional-from_email)*
+
+*Defined in [src/types.ts:129](https://github.com/reacherhq/reacher-js/blob/527ae93/src/types.ts#L129)*
+
+In the SMTP connection, the FROM email address.
+
+___
+
+### `Optional` hello_name
+
+• **hello_name**? : *undefined | string*
+
+*Inherited from [__type](_src_types_.components.md#__type).[hello_name](_src_types_.components.md#optional-hello_name)*
+
+*Defined in [src/types.ts:137](https://github.com/reacherhq/reacher-js/blob/527ae93/src/types.ts#L137)*
+
+In the SMTP connection, the EHLO hostname.
+
+___
+
+###  to_email
+
+• **to_email**: *string*
+
+*Inherited from [__type](_src_types_.components.md#__type).[to_email](_src_types_.components.md#to_email)*
+
+*Defined in [src/types.ts:133](https://github.com/reacherhq/reacher-js/blob/527ae93/src/types.ts#L133)*
+
+The email address to check.