@pipedream/voilanorbert 0.0.2 → 0.0.3

package/README.md

@@ -1,20 +1,11 @@
 # Overview
 
-VoilaNorbert is the easiest way to find the most accurate email addresses and
-contact info in a few seconds. Thanks to its powerful API, you can quickly
-access information and create custom applications to help you get the data you
-need and make the best use of that information.
+VoilaNorbert is a potent tool for finding and verifying email addresses. With its API, you can automate processes like enriching leads with verified contact information, streamlining your email outreach, and maintaining the health of your email lists. The API's main features include searching for email addresses based on names and domains, verifying email deliverability, and managing your contacts. When used within Pipedream, you can leverage these capabilities to create workflows that respond to events, integrate with other services, and process data in real time.
 
-The VoilaNorbert API can help you with many tasks, including:
+# Example Use Cases
 
-- Building contact pages and customer lists
-- Generating personalized lead reports
-- Creating targeted campaigns for customers and prospects
-- Improving customer segmentation and list management
-- Validating customer contact information
-- Enhancing customer data for use in marketing
-- Automating lead verification processes
-- Integrating email address data into customer relationship management (CRM)
-  systems
-- Identifying customer contacts from web interactions
-- Enhancing existing customer contact databases with additional details
+- **Lead Enrichment Workflow**: Triggered by a new entry on a Google Sheet (containing names and companies), this workflow uses VoilaNorbert to find corresponding email addresses, verifies them to ensure deliverability, and then updates the Google Sheet with the new data. This automation keeps your lead database fresh and actionable.
+
+- **Email Verification on Signup**: When a new user signs up through a website form, VoilaNorbert is employed to verify the email address provided. If verified, the user's information is added to a CRM like Salesforce, and a welcome email is sent via SendGrid. This process ensures that you're capturing genuine leads without manual vetting.
+
+- **Periodic Email List Cleaning**: A scheduled workflow runs monthly, fetching email addresses from an email marketing platform like Mailchimp. It uses VoilaNorbert to verify and clean the list, removing invalid emails automatically. The cleaned list is then re-uploaded to Mailchimp, optimizing your email campaign's deliverability and engagement rates.

package/actions/common/base.mjs

@@ -0,0 +1,15 @@
+import voilanorbert from "../../voilanorbert.app.mjs";
+
+export default {
+  type: "action",
+  props: {
+    voilanorbert,
+  },
+  async run({ $ }) {
+    const response = await this.processEvent({
+      $,
+    });
+
+    $.export("$summary", this.getSummary(response));
+  },
+};

package/actions/find-contact/find-contact.mjs

@@ -0,0 +1,32 @@
+import common from "../common/base.mjs";
+
+export default {
+  ...common,
+  key: "voilanorbert-find-contact",
+  name: "Find Contact",
+  description: "This action returns a specific contact. The object email is either null when the email is not found, or contains an object with at least email (the email string) and the score. [See the docs here](https://api.voilanorbert.com/2018-01-08/#contacts-get-1)",
+  version: "0.0.2",
+  type: "action",
+  props: {
+    ...common.props,
+    contactId: {
+      propDefinition: [
+        common.props.voilanorbert,
+        "contactId",
+      ],
+    },
+  },
+  methods: {
+    async processEvent() {
+      const { contactId } = this;
+      return this.voilanorbert.getContact({
+        contactId,
+      });
+    },
+    getSummary({
+      name, email,
+    }) {
+      return `Contact '${name ?? email.email}' Successfully fetched!`;
+    },
+  },
+};

package/actions/start-contact-search/start-contact-search.mjs

@@ -0,0 +1,88 @@
+import common from "../common/base.mjs";
+import { ConfigurationError } from "@pipedream/platform";
+
+export default {
+  ...common,
+  key: "voilanorbert-start-contact-search",
+  name: "Start Contact Search",
+  description: `Search emails are based on the full name plus the domain or company name.
+  When your account does not have sufficient credits an HTTP status code of 402 is returned.
+  Also, take into consideration that we check the domain for its validity. So even if you provide a correct name+domain set, we may return a HTTP status code of 400 for the domain if we can't locate it.
+  [See the docs here](https://api.voilanorbert.com/2018-01-08/#search-endpoint-post)`,
+  version: "0.0.2",
+  type: "action",
+  props: {
+    ...common.props,
+    name: {
+      propDefinition: [
+        common.props.voilanorbert,
+        "name",
+      ],
+    },
+    domain: {
+      propDefinition: [
+        common.props.voilanorbert,
+        "domain",
+      ],
+      optional: true,
+    },
+    company: {
+      propDefinition: [
+        common.props.voilanorbert,
+        "company",
+      ],
+      optional: true,
+    },
+    listId: {
+      propDefinition: [
+        common.props.voilanorbert,
+        "listId",
+      ],
+      optional: true,
+    },
+    webhookUrl: {
+      type: "string",
+      label: "Webhook URL",
+      description: "The URL to send the webhook to. Required for Pipedream Connect. If not specified, the workflow will be suspended until verification results are returned.",
+      optional: true,
+    },
+  },
+  methods: {
+    async processEvent({ $ }) {
+      if (!this.domain && !this.company) {
+        throw new ConfigurationError("Either domain or company is required.");
+      }
+
+      const { resume_url } = this.webhookUrl
+        ? {
+          resume_url: this.webhookUrl,
+        }
+        : $.flow
+          ? $.flow.suspend()
+          : {
+            resume_url: undefined,
+          };
+      if (!resume_url) {
+        throw new ConfigurationError("Webhook URL is required for Pipedream Connect.");
+      }
+
+      const {
+        name,
+        domain,
+        company,
+        listId,
+      } = this;
+
+      return this.voilanorbert.startContactSearch({
+        name,
+        domain,
+        company,
+        webhook: resume_url,
+        list_id: listId,
+      });
+    },
+    getSummary() {
+      return "Contact Search Successfully fetched!";
+    },
+  },
+};

package/actions/verifiy-email/verifiy-email.mjs

@@ -0,0 +1,52 @@
+import common from "../common/base.mjs";
+import { ConfigurationError } from "@pipedream/platform";
+
+export default {
+  ...common,
+  key: "voilanorbert-verifiy-email",
+  name: "Verify Email",
+  description: `Verifies the given list of emails.
+  In case your account does not have a sufficient Verify API balance the service will try to auto refill the balance by charging using the billing details of the account. If it fails to charge, an HTTP status code of 402 will be returned.
+  [See the docs here](https://api.voilanorbert.com/2018-01-08/#verify-endpoint-post)`,
+  version: "0.0.2",
+  type: "action",
+  props: {
+    ...common.props,
+    emails: {
+      propDefinition: [
+        common.props.voilanorbert,
+        "emails",
+      ],
+    },
+    webhookUrl: {
+      type: "string",
+      label: "Webhook URL",
+      description: "The URL to send the webhook to. Required for Pipedream Connect. If not specified, the workflow will be suspended until verification results are returned.",
+      optional: true,
+    },
+  },
+  methods: {
+    async processEvent({ $ }) {
+      const { resume_url } = this.webhookUrl
+        ? {
+          resume_url: this.webhookUrl,
+        }
+        : $.flow
+          ? $.flow.suspend()
+          : {
+            resume_url: undefined,
+          };
+      if (!resume_url) {
+        throw new ConfigurationError("Webhook URL is required for Pipedream Connect.");
+      }
+
+      return this.voilanorbert.verifyEmails({
+        emails: this.emails.toString(),
+        webhook: resume_url,
+      });
+    },
+    getSummary() {
+      return "Emails Successfully sent for verification!";
+    },
+  },
+};

package/common/utils.mjs

@@ -0,0 +1,8 @@
+export const objectToString = (data) => {
+  return Object.keys(data).reduce((prev, key) => {
+    if (data[key] === undefined) return prev;
+    return `${prev
+      ? `${prev}&`
+      : ""}${key}=${data[key]}`;
+  }, "");
+};

package/package.json

@@ -1,21 +1,18 @@
 {
   "name": "@pipedream/voilanorbert",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Pipedream VoilaNorbert Components",
-  "main": "dist/app/voilanorbert.app.mjs",
+  "main": "voilanorbert.app.mjs",
   "keywords": [
     "pipedream",
     "voilanorbert"
   ],
-  "files": [
-    "dist"
-  ],
   "homepage": "https://pipedream.com/apps/voilanorbert",
   "author": "Pipedream <support@pipedream.com> (https://pipedream.com/)",
-  "dependencies": {
-    "@pipedream/platform": "^1.1.1"
-  },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@pipedream/platform": "^3.1.0"
   }
 }

package/voilanorbert.app.mjs

@@ -0,0 +1,124 @@
+import { axios } from "@pipedream/platform";
+import { objectToString } from "./common/utils.mjs";
+
+export default {
+  type: "app",
+  app: "voilanorbert",
+  propDefinitions: {
+    contactId: {
+      type: "integer",
+      label: "Contact Id",
+      description: "The contact's id.",
+      async options({ page }) {
+        const { result } = await this.getContacts(page + 1);
+
+        return result?.map(({
+          name, email, id,
+        }) => ({
+          label: `${name} - ${email?.email}`,
+          value: id,
+        })) ?? [];
+      },
+    },
+    name: {
+      type: "string",
+      label: "Name",
+      description: "Full name of the person to search.",
+    },
+    domain: {
+      type: "string",
+      label: "Domain",
+      description: "The domain of the company. (Either `domain` or `company` is required).",
+    },
+    company: {
+      type: "string",
+      label: "Company",
+      description: "The name of the company. (Either `domain` or `company` is required).",
+    },
+    emails: {
+      type: "string[]",
+      label: "Emails",
+      description: "A list of emails",
+    },
+    listId: {
+      type: "integer",
+      label: "List ID",
+      description: "A List ID the contact will affected to.",
+      async options() {
+        const { result } = await this.getLists();
+
+        return result.map(({
+          name: label, id: value,
+        }) => ({
+          label,
+          value,
+        }));
+      },
+    },
+  },
+  methods: {
+    _accessToken() {
+      return this.$auth.api_key;
+    },
+    _auth() {
+      return {
+        username: "",
+        password: this._accessToken(),
+      };
+    },
+    _apiUrl() {
+      return "https://api.voilanorbert.com/2018-01-08";
+    },
+    async _makeRequest({
+      $ = this, path, ...options
+    }) {
+      const config = {
+        url: `${this._apiUrl()}/${path}`,
+        ...options,
+        auth: this._auth(),
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+        },
+      };
+      return axios($, config);
+    },
+    async getContacts(page) {
+      try {
+        return await this._makeRequest({
+          path: "contacts/",
+          params: {
+            page,
+          },
+        });
+      } catch (e) {
+        return [];
+      }
+    },
+    async getContact({ contactId }) {
+      return await this._makeRequest({
+        path: `contacts/${contactId}`,
+      });
+    },
+    async getLists() {
+      return await this._makeRequest({
+        path: "lists/",
+      });
+    },
+    async startContactSearch(data) {
+      const bodyFormData = objectToString(data);
+      return await this._makeRequest({
+        method: "POST",
+        path: "search/name",
+        data: bodyFormData,
+      });
+    },
+    async verifyEmails(data) {
+      const bodyFormData = objectToString(data);
+      return await this._makeRequest({
+        method: "POST",
+        path: "verifier/upload",
+        data: bodyFormData,
+      });
+    },
+  },
+};