refactor(debounce): extract debounce connector to individual pkg

.changeset/witty-ducks-hammer.md

@@ -0,0 +1,7 @@
+---
+"@gouvfr-lasuite/proconnect.debounce": minor
+---
+
+♻️ Prélèvement d'un partie du connecteur Debounce
+
+Dans le cadres la suggestion d'email sur PCF, une partie du connecteur Debounce est maintenant dans le package `@gouvfr-lasuite/proconnect.debounce`.

Dockerfile

@@ -11,6 +11,7 @@ RUN --mount=type=bind,source=package.json,target=package.json \
   --mount=type=bind,source=package-lock.json,target=package-lock.json \
   --mount=type=bind,source=packages/core/package.json,target=packages/core/package.json \
   --mount=type=bind,source=packages/crisp/package.json,target=packages/crisp/package.json \
+  --mount=type=bind,source=packages/debounce/package.json,target=packages/debounce/package.json \
   --mount=type=bind,source=packages/email/package.json,target=packages/email/package.json \
   --mount=type=bind,source=packages/identite/package.json,target=packages/identite/package.json \
   --mount=type=bind,source=packages/insee/package.json,target=packages/insee/package.json \
@@ -23,6 +24,7 @@ RUN --mount=type=bind,source=package.json,target=package.json \
   --mount=type=bind,source=package-lock.json,target=package-lock.json \
   --mount=type=bind,source=packages/core/package.json,target=packages/core/package.json \
   --mount=type=bind,source=packages/crisp/package.json,target=packages/crisp/package.json \
+  --mount=type=bind,source=packages/debounce/package.json,target=packages/debounce/package.json \
   --mount=type=bind,source=packages/email/package.json,target=packages/email/package.json \
   --mount=type=bind,source=packages/identite/package.json,target=packages/identite/package.json \
   --mount=type=bind,source=packages/insee/package.json,target=packages/insee/package.json \

package.json

@@ -10,9 +10,10 @@
   "main": "src/index.js",
   "workspaces": [
     "packages/core",
+    "packages/crisp",
+    "packages/debounce",
     "packages/email",
     "packages/insee",
-    "packages/crisp",
     "packages/identite"
   ],
   "scripts": {
@@ -53,6 +54,7 @@
   },
   "dependencies": {
     "@gouvfr-lasuite/proconnect.core": "workspace:*",
+    "@gouvfr-lasuite/proconnect.debounce": "workspace:*",
     "@gouvfr-lasuite/proconnect.crisp": "workspace:*",
     "@gouvfr-lasuite/proconnect.email": "workspace:*",
     "@gouvfr-lasuite/proconnect.identite": "workspace:*",

packages/debounce/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Direction Interministérielle du Numérique - Gouvernement Français
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/debounce/README.md

@@ -0,0 +1,25 @@
+# 📦 @gouvfr-lasuite/proconnect.debounce
+
+> ⚡ Typed Debounce API for ProConnect
+
+## ⚙️ Installation
+
+```bash
+npm install @gouvfr-lasuite/proconnect.debounce
+```
+
+## 📖 Usage
+
+### [Single Validation](https://developers.debounce.io/reference/single-validation)
+
+```ts
+import { singleValidationFactory } from "@gouvfr-lasuite/proconnect.debounce/api";
+
+const singleValidation = singleValidationFactory(DEBOUNCE_API_KEY);
+
+const response = await singleValidation("[email protected]");
+```
+
+## 📖 License
+
+[MIT](./LICENSE.md)

packages/debounce/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@gouvfr-lasuite/proconnect.debounce",
+  "version": "0.3.2",
+  "homepage": "https://github.com/numerique-gouv/moncomptepro/tree/master/packages/debounce#readme",
+  "bugs": "https://github.com/numerique-gouv/moncomptepro/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/numerique-gouv/moncomptepro.git",
+    "directory": "packages/debounce"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {},
+  "exports": {
+    "./api": {
+      "require": "./dist/api/index.cjs",
+      "import": "./dist/api/index.js",
+      "types": "./dist/api/index.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "api": [
+        "./dist/api/index.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "pkgroll --tsconfig=tsconfig.lib.json",
+    "check": "npm run build -- --noEmit",
+    "dev": "npm run build -- --watch --preserveWatchOutput",
+    "test": "mocha"
+  },
+  "mocha": {
+    "reporter": "spec",
+    "require": [
+      "tsx"
+    ],
+    "spec": "src/**/*.test.ts"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@tsconfig/node22": "^22.0.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.10.2",
+    "chai": "^5.1.2",
+    "mocha": "^11.0.1",
+    "pkgroll": "^2.6.1",
+    "tsx": "^4.19.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

packages/debounce/src/api/index.ts

@@ -0,0 +1,3 @@
+//
+
+export * from "./single-validation.js";

packages/debounce/src/api/single-validation.test.ts

@@ -0,0 +1,32 @@
+//
+
+import { expect } from "chai";
+import { before, describe } from "mocha";
+import { singleValidationFactory } from "./single-validation.js";
+
+//
+
+const { DEBOUNCE_API_KEY } = process.env;
+const singleValidation = singleValidationFactory(DEBOUNCE_API_KEY ?? "");
+
+//
+
+describe("singleValidationFactory", () => {
+  before(function () {
+    if (!DEBOUNCE_API_KEY) this.skip();
+  });
+
+  it("should return a valid response", async function () {
+    const response = await singleValidation("[email protected]");
+    expect(response).includes({
+      email: "[email protected]",
+      code: "3",
+      role: "true",
+      free_email: "true",
+      result: "Invalid",
+      reason: "Disposable, Role",
+      send_transactional: "0",
+      did_you_mean: "[email protected]",
+    });
+  });
+});

packages/debounce/src/api/single-validation.ts

@@ -0,0 +1,34 @@
+//
+
+import type { DebounceSuccessResponse } from "#src/types/index.js";
+import axios, { type AxiosRequestConfig, type AxiosResponse } from "axios";
+
+//
+
+/**
+ * Perform a single email validation request.
+ *
+ * @see https://developers.debounce.io/reference/single-validation#response-parameters
+ * @param apiKey the debounce.io API key
+ * @param config the Axios request config
+ * @returns Debounce Single Validation response
+ */
+export function singleValidationFactory(
+  apiKey: string,
+  config?: AxiosRequestConfig,
+) {
+  return async function singleValidation(email: string) {
+    const {
+      data: { debounce },
+    }: AxiosResponse<DebounceSuccessResponse> = await axios({
+      method: "get",
+      url: `https://api.debounce.io/v1/?email=${email}&api=${apiKey}`,
+      headers: {
+        accept: "application/json",
+      },
+      ...config,
+    });
+
+    return debounce;
+  };
+}

packages/debounce/src/types/index.ts

@@ -0,0 +1,48 @@
+//
+
+/**
+ * @see https://developers.debounce.io/reference/responses#error-response
+ */
+
+export interface DebounceErrorResponse {
+  debounce: {
+    error: string;
+    code: "0";
+  };
+  success: "0";
+}
+
+/**
+ * @see https://developers.debounce.io/reference/responses#success-response
+ */
+export interface DebounceSuccessResponse {
+  debounce: {
+    // The email address you are requesting to validate.
+    // ex: '[email protected]'
+    email: string;
+    // DeBounce validation response code.
+    // ex: '6'
+    code: string;
+    // Is the email role-based or not. Role emails such as "sales@", "webmaster@" etc. are not suitable for sending marketing emails to.
+    // ['true', 'false']
+    role: string;
+    // Is the email from a free email provider - like Gmail - or not.
+    // ['true', 'false']
+    free_email: string;
+    // The final result of the validation process. This response will help to determine whether you should send marketing emails to a recipient or not.
+    // ['Invalid', 'Risky', 'Safe to Send', 'Unknown']
+    result: string;
+    // The reason why the result is given.
+    // ex: 'Bounce, Role'
+    reason: string;
+    // Is it suggested that you send transactional emails to the recipient or not (0: no, 1: yes). Generally, it is suggested to send transactional emails to Valid, Accept-all, and Unknown emails.
+    // ['0', '1']
+    send_transactional: string;
+    // If you use a misspelled email address like someemail@gmial.com, the validation engine tries to suggest you the corrected email address.
+    // ex: '[email protected]', ''
+    did_you_mean: string;
+  };
+
+  success: "1";
+  balance: `${number}`;
+}

packages/debounce/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "src",
+    "types": ["node"],
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "verbatimModuleSyntax": true,
+    "paths": {
+      "#src/*": ["./src/*"]
+    }
+  },
+  "extends": "@tsconfig/node22/tsconfig.json",
+  "references": []
+}

packages/debounce/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "exclude": ["src/**/*.test.ts"],
+  "extends": "./tsconfig.json",
+  "include": ["src"]
+}

src/config/env.zod.ts

@@ -14,7 +14,7 @@ export const connectorEnvSchema = z.object({
   CRISP_WEBSITE_ID: z.string().default(""),
   CRISP_MODERATION_TAG: zCoerceArray(z.string()).default("identite,moderation"),
   DATABASE_URL: z.string().url(),
-  DEBOUNCE_API_KEY: z.string().optional(),
+  DEBOUNCE_API_KEY: z.string().default(""),
   INSEE_CONSUMER_KEY: z.string(),
   INSEE_CONSUMER_SECRET: z.string(),
   REDIS_URL: z.string().url().default("redis://:@127.0.0.1:6379"),