Add IP Enrichment (#88)

* add ip enrichment api

* update packages

* update version

README.md

@@ -74,6 +74,15 @@ try {
   console.log(error);
 }
 
+// By Preview Enrichment
+try {
+  const response = await PDLJSClient.person.enrichmentPreview({ phone: '4155688415' });
+
+  console.log(response);
+} catch (error) {
+  console.log(error);
+}
+
 // By Bulk Enrichment
 const bulkEnrichmentRecords = {
   requests: [
@@ -276,6 +285,18 @@ try {
 }
 ```
 
+**Using IP Enrichment API**
+```js
+// Enrich an IP Address
+try {
+  const response = await PDLJSClient.ip({ ip: '72.212.42.169' });
+
+  console.log(response);
+} catch (error) {
+  console.log(error);
+}
+```
+
 **Using Sandbox APIs**
 ```js
 // By Enrichment
@@ -336,6 +357,7 @@ try {
 | API Endpoint | PDLJS Function |
 |-|-|
 | [Person Enrichment API](https://docs.peopledatalabs.com/docs/enrichment-api) | `PDLJS.person.enrichment({ ...params })` |
+| [Person Preview Enrichment API](https://docs.peopledatalabs.com/docs/preview-enrichment-api) | `PDLJS.person.enrichmentPreview({ ...params })` |
 | [Person Bulk Person Enrichment API](https://docs.peopledatalabs.com/docs/bulk-enrichment-api) | `PDLJS.person.bulk.enrichment({ ...records })` |
 | [Person Search API](https://docs.peopledatalabs.com/docs/search-api) | SQL: `PDLJS.person.search.sql({ ...params })` <br/> Elasticsearch: `PDLJS.person.search.elastic({ ...params })`|
 | [Person Retrieve API](https://docs.peopledatalabs.com/docs/person-retrieve-api) | `PDLJS.person.retrieve({ ...params })` |
@@ -357,6 +379,7 @@ try {
 | [School Cleaner API](https://docs.peopledatalabs.com/docs/cleaner-apis#schoolclean) | `PDLJS.school.cleaner({ ...params })` |
 | [Job Title Enrichment API](https://docs.peopledatalabs.com/docs/job-title-enrichment-api) | `PDLJS.jobTitle({ ...params })` |
 | [Skill Enrichment API](https://docs.peopledatalabs.com/docs/skill-enrichment-api) | `PDLJS.skill({ ...params })` |
+| [IP Enrichment API](https://docs.peopledatalabs.com/docs/ip-enrichment-api) | `PDLJS.ip({ ...params })` |
 
 **Sandbox Endpoints**
 | API Endpoint | PDLJS Function |

example/index.js

@@ -15,6 +15,12 @@ PDLJSClient.person.enrichment({ phone: '4155688415' }).then((data) => {
   console.log(error);
 });
 
+PDLJSClient.person.enrichmentPreview({ phone: '4155688415' }).then((data) => {
+  console.log(data);
+}).catch((error) => {
+  console.log(error);
+});
+
 PDLJSClient.person.identify({ phone: '4155688415' }).then((data) => {
   console.log(data);
 }).catch((error) => {
@@ -127,6 +133,12 @@ PDLJSClient.skill({ skill: 'c++' }).then((data) => {
   console.log(error);
 });
 
+PDLJSClient.ip({ ip: '72.212.42.169' }).then((data) => {
+  console.log(data);
+}).catch((error) => {
+  console.log(error);
+});
+
 // Sandbox APIs
 
 PDLJSClient.person.enrichment({ email: '[email protected]', sandbox: true }).then((data) => {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "peopledatalabs",
-  "version": "5.0.6",
+  "version": "5.1.0",
   "description": "JavaScript client with TypeScript support for the People Data Labs API",
   "type": "module",
   "main": "dist/index.cjs",
@@ -43,17 +43,17 @@
   },
   "homepage": "https://docs.peopledatalabs.com/docs/javascript-sdk",
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^6.1.0",
-    "@typescript-eslint/parser": "^6.1.0",
+    "@typescript-eslint/eslint-plugin": "^6.2.1",
+    "@typescript-eslint/parser": "^6.2.1",
     "chai": "^4.3.7",
     "dotenv": "^16.3.1",
-    "eslint": "^8.45.0",
+    "eslint": "^8.46.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^17.1.0",
-    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-import": "^2.28.0",
     "eslint-plugin-jsx-a11y": "^6.7.1",
-    "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react": "^7.33.1",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "eslint-plugin-unused-imports": "^3.0.0",

src/endpoints/ip/index.ts

@@ -0,0 +1,36 @@
+import axios from 'axios';
+
+import { check, errorHandler } from '../../errors';
+import { IPParams, IPResponse } from '../../types/ip-types';
+import { parseRateLimitingResponse } from '../../utils/api-utils';
+
+export default (
+  basePath: string,
+  apiKey: string,
+  params: IPParams,
+) => new Promise<IPResponse>((resolve, reject) => {
+  check(params, basePath, apiKey, null, 'ip').then(() => {
+    const headers = {
+      'Accept-Encoding': 'gzip',
+      'User-Agent': 'PDL-JS-SDK',
+    };
+
+    axios.get<IPResponse>(`${basePath}/ip/enrich`, {
+      params: {
+        api_key: apiKey,
+        ...params,
+      },
+      headers,
+    })
+      .then((response) => {
+        if (response?.data?.status === 200) {
+          resolve(parseRateLimitingResponse(response));
+        }
+      })
+      .catch((error) => {
+        reject(errorHandler(error));
+      });
+  }).catch((error) => {
+    reject(error);
+  });
+});

src/endpoints/skill/index.ts

@@ -1,4 +1,5 @@
 import axios from 'axios';
+
 import { check, errorHandler } from '../../errors';
 import { SkillParams, SkillResponse } from '../../types/skill-types';
 import { parseRateLimitingResponse } from '../../utils/api-utils';

src/errors.ts

@@ -2,6 +2,7 @@ import { AxiosError } from 'axios';
 
 import { AutoCompleteParams } from './types/autocomplete-types';
 import { ErrorEndpoint } from './types/error-types';
+import { IPParams } from './types/ip-types';
 import { JobTitleParams } from './types/jobTitle-types';
 import { RetrieveParams } from './types/retrieve-types';
 import { BaseSearchParams } from './types/search-types';
@@ -72,6 +73,15 @@ const check = (
     }
   }
 
+  if (endpoint === 'ip') {
+    const { ip } = params as IPParams;
+    if (!ip) {
+      error.message = 'Missing ip';
+      error.status = 400;
+      reject(error);
+    }
+  }
+
   if (!basePath) {
     error.message = 'Missing API Base Path';
     error.status = 400;

src/index.ts

@@ -1,4 +1,5 @@
 import { autocomplete, bulkEnrichment, bulkRetrieve, cleaner, enrichment, enrichmentPreview, identify, jobTitle, retrieve, search, skill } from './endpoints';
+import ip from './endpoints/ip';
 import { APISettings } from './types/api-types';
 import { AutoCompleteParams, AutoCompleteResponse } from './types/autocomplete-types';
 import { BulkPersonRetrieveParams, BulkPersonRetrieveResponse } from './types/bulk-retrieve-types';
@@ -15,6 +16,7 @@ import {
   PersonPreviewResponse,
 } from './types/enrichment-types';
 import { IdentifyParams, IdentifyResponse } from './types/identify-types';
+import { IPParams, IPResponse } from './types/ip-types';
 import { JobTitleParams, JobTitleResponse } from './types/jobTitle-types';
 import { RetrieveParams, RetrieveResponse } from './types/retrieve-types';
 import { CompanySearchParams, CompanySearchResponse, PersonSearchParams, PersonSearchResponse } from './types/search-types';
@@ -61,6 +63,8 @@ class PDLJS {
 
   public jobTitle: (params: JobTitleParams) => Promise<JobTitleResponse>;
 
+  public ip: (params: IPParams) => Promise<IPResponse>;
+
   constructor({
     apiKey,
     basePath,
@@ -108,6 +112,8 @@ class PDLJS {
     this.jobTitle = (params: JobTitleParams) => jobTitle(this.basePath, this.apiKey, params);
 
     this.skill = (params: SkillParams) => skill(this.basePath, this.apiKey, params);
+
+    this.ip = (params: IPParams) => ip(this.basePath, this.apiKey, params);
   }
 }
 
@@ -130,6 +136,8 @@ export type {
   CompanySearchResponse,
   IdentifyParams,
   IdentifyResponse,
+  IPParams,
+  IPResponse,
   JobTitleParams,
   JobTitleResponse,
   LocationCleanerParams,

src/types/error-types.ts

@@ -1 +1 @@
-export type ErrorEndpoint = 'enrichment' | 'autocomplete' | 'search' | 'identify' | 'bulk' | 'cleaner' | 'retrieve' | 'jobTitle' | 'skill';
+export type ErrorEndpoint = 'enrichment' | 'autocomplete' | 'search' | 'identify' | 'bulk' | 'cleaner' | 'retrieve' | 'jobTitle' | 'skill' | 'ip';

src/types/ip-types.ts

@@ -0,0 +1,68 @@
+import { BaseResponse } from './api-types';
+
+export interface IPParams {
+  ip: string;
+  return_ip_location?: boolean;
+  return_ip_metadata?: boolean;
+  return_person?: boolean;
+  pretty?: boolean;
+  titlecase?: boolean;
+}
+
+export interface IPResponse extends BaseResponse {
+  data?: {
+    ip?: {
+      address?: string,
+      metadata?: {
+        version?: 4 | 6,
+        mobile?: boolean,
+        hosting?: boolean,
+        proxy?: boolean,
+        tor?: boolean,
+        vpn?: boolean,
+        relay?: boolean,
+        service?: boolean,
+      },
+      location?: {
+        name?: string,
+        locality?: string,
+        region?: string,
+        metro?: string,
+        country?: string,
+        continent?: string,
+        postal_code?: string,
+        geo?: string,
+        timezone?: string,
+      },
+    },
+    company?: {
+      confidence?: 'very high' | 'high' | 'moderate' | 'low' | 'very low',
+      id?: string,
+      domain?: string,
+      name?: string,
+      location?: {
+        name?: string,
+        locality?: string,
+        region?: string,
+        metro?: string,
+        country?: string,
+        continent?: string,
+        street_address?: string,
+        address_line_2?: string,
+        postal_code?: string,
+        geo?: string,
+      },
+      size?: string,
+      industry?: string,
+      inferred_revenue?: string,
+      employee_count?: number,
+      tags?: Array<string>,
+    },
+    person?: {
+      confidence?: 'very high' | 'high' | 'moderate' | 'low' | 'very low',
+      job_title_sub_role?: string,
+      job_title_role?: string,
+      job_title_levels?: Array<string>,
+    },
+  }
+}

tests/index.test.js

@@ -80,6 +80,8 @@ const skill = { skill: 'c++' };
 
 const jobTitle = { jobTitle: 'software engineer' };
 
+const ip = { ip: '72.212.42.169' };
+
 describe('Person Enrichment', () => {
   it(`Should Return Person Record for ${phone}`, async () => {
     try {
@@ -104,6 +106,30 @@ describe('Person Enrichment', () => {
   });
 });
 
+describe('Person Preview Enrichment', () => {
+  it(`Should Return Person Preview Record for ${phone}`, async () => {
+    try {
+      const response = await PDLJSClient.person.enrichmentPreview({ phone });
+
+      expect(response.status).to.equal(200);
+      expect(response).to.be.a('object');
+    } catch (error) {
+      expect(error).to.be.a('object');
+    }
+  });
+
+  it('Should Error for Person Preview Enrichment', async () => {
+    try {
+      const response = await PDLJSClient.person.enrichmentPreview();
+
+      expect(response.status).to.equal(200);
+      expect(response).to.be.a('object');
+    } catch (error) {
+      expect(error).to.be.a('object');
+    }
+  });
+});
+
 describe('Person Bulk Enrichment', () => {
   it(`Should Return Person Records for ${JSON.stringify(records)}`, async () => {
     try {
@@ -456,6 +482,30 @@ describe('Job Title API', () => {
   });
 });
 
+describe('IP Enrichment API', () => {
+  it(`Should Return IP Records for ${JSON.stringify(ip)}`, async () => {
+    try {
+      const response = await PDLJSClient.ip(ip);
+
+      expect(response.status).to.equal(200);
+      expect(response).to.be.a('object');
+    } catch (error) {
+      expect(error).to.be.a('object');
+    }
+  });
+
+  it('Should Error for IP Enrichment', async () => {
+    try {
+      const response = await PDLJSClient.ip();
+
+      expect(response.status).to.equal(200);
+      expect(response).to.be.a('object');
+    } catch (error) {
+      expect(error).to.be.a('object');
+    }
+  });
+});
+
 describe('Sandbox APIs', () => {
   it('Should Return Sandbox Person Record for { email: \'[email protected]\' }', async () => {
     try {