Job Posting: New job posting endpoint (#373)

* New job posting endpoint

* test fix

* test fix2

Author: Jbot29

README.md

@@ -298,6 +298,44 @@ try {
 }
 ```
 
+**Using Job Posting Search API**
+
+```js
+// By Search (Elasticsearch query)
+const esQuery = {
+  query: {
+    bool: {
+      must: [
+        { term: { title_role: 'engineering' } },
+        { term: { remote_work_policy: 'remote' } },
+      ],
+    },
+  },
+}
+
+try {
+  const response = await PDLJSClient.jobPosting.search({ ...esQuery, size: 10 });
+
+  console.log(response.total);
+} catch (error) {
+  console.log(error);
+}
+
+// By Search (field parameters)
+try {
+  const response = await PDLJSClient.jobPosting.search({
+    title_role: 'engineering',
+    remote_work_policy: 'remote',
+    is_active: true,
+    size: 10,
+  });
+
+  console.log(response.total);
+} catch (error) {
+  console.log(error);
+}
+```
+
 **Using IP Enrichment API**
 
 ```js
@@ -427,6 +465,11 @@ try {
 | [Company Bulk Enrichment API](https://docs.peopledatalabs.com/docs/bulk-company-enrichment-api) | `PDLJS.company.bulk.enrichment({ ...records })` |
 | [Company Search API](https://docs.peopledatalabs.com/docs/company-search-api) | SQL: `PDLJS.company.search.sql({ ...params })` <br/> Elasticsearch: `PDLJS.company.search.elastic({ ...params })`|
 
+**Job Posting Endpoints**
+| API Endpoint | PDLJS Function |
+|-|-|
+| [Job Posting Search API](https://docs.peopledatalabs.com/docs/job-posting-search-api) | `PDLJS.jobPosting.search({ ...params })` |
+
 **Supporting Endpoints**
 | API Endpoint | PDLJS Function |
 |-|-|

src/endpoints/index.ts

@@ -7,8 +7,9 @@ import cleaner from './cleaner/index.js';
 import enrichment from './enrichment/index.js';
 import enrichmentPreview from './enrichmentPreview/index.js';
 import identify from './identify/index.js';
+import jobPostingSearch from './jobPostingSearch/index.js';
 import jobTitle from './jobTitle/index.js';
 import retrieve from './retrieve/index.js';
 import search from './search/index.js';
 
-export { autocomplete, bulkCompanyEnrichment, bulkEnrichment, bulkRetrieve, changelog, cleaner, enrichment, enrichmentPreview, identify, jobTitle, retrieve, search };
+export { autocomplete, bulkCompanyEnrichment, bulkEnrichment, bulkRetrieve, changelog, cleaner, enrichment, enrichmentPreview, identify, jobPostingSearch, jobTitle, retrieve, search };

src/endpoints/jobPostingSearch/index.ts

@@ -0,0 +1,43 @@
+import axios from 'axios';
+
+import { check, errorHandler } from '../../errors.js';
+import { RequestOptions } from '../../types/api-types.js';
+import { JobPostingSearchParams, JobPostingSearchResponse } from '../../types/jobPosting-types.js';
+import { parseRateLimitingResponse } from '../../utils/api-utils.js';
+import SDK_VERSION from '../../utils/sdk-version.js';
+
+export default (
+  basePath: string,
+  apiKey: string,
+  params: JobPostingSearchParams,
+  options: RequestOptions = {},
+) => new Promise<JobPostingSearchResponse>((resolve, reject) => {
+  check(params, basePath, apiKey, null, 'jobPostingSearch').then(() => {
+    const body = {
+      size: 10,
+      pretty: false,
+      ...params,
+    };
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'Accept-Encoding': 'gzip',
+      'User-Agent': 'PDL-JS-SDK',
+      'SDK-Version': SDK_VERSION,
+      'X-Api-Key': apiKey,
+    };
+
+    axios.post<JobPostingSearchResponse>(`${basePath}/job_posting/search`, body, {
+      headers,
+      ...options,
+    }).then((response) => {
+      if (response?.data?.status === 200) {
+        resolve(parseRateLimitingResponse(response));
+      }
+    }).catch((error) => {
+      reject(errorHandler(error));
+    });
+  }).catch((error) => {
+    reject(error);
+  });
+});

src/errors.ts

@@ -4,6 +4,7 @@ import { AutoCompleteParams } from './types/autocomplete-types.js';
 import { ChangelogParams } from './types/changelog-types.js';
 import { ErrorEndpoint, PdlError } from './types/error-types.js';
 import { IPParams } from './types/ip-types.js';
+import { JobPostingQuerySearchParams, JobPostingSearchParams } from './types/jobPosting-types.js';
 import { JobTitleParams } from './types/jobTitle-types.js';
 import { RetrieveParams } from './types/retrieve-types.js';
 import { BaseSearchParams } from './types/search-types.js';
@@ -71,6 +72,22 @@ const check = (
     }
   }
 
+  if (endpoint === 'jobPostingSearch') {
+    const searchParams = params as JobPostingSearchParams | undefined;
+    if (!searchParams || Object.keys(searchParams).length === 0) {
+      error.message = 'Missing Params';
+      error.status = 400;
+      reject(error);
+    } else if (
+      'query' in searchParams
+      && typeof (searchParams as JobPostingQuerySearchParams).query !== 'object'
+    ) {
+      error.message = 'query must be an object';
+      error.status = 400;
+      reject(error);
+    }
+  }
+
   if (endpoint === 'jobTitle') {
     const { jobTitle } = params as JobTitleParams;
     if (!jobTitle) {

src/index.ts

@@ -1,4 +1,4 @@
-import { autocomplete, bulkCompanyEnrichment, bulkEnrichment, bulkRetrieve, changelog, cleaner, enrichment, enrichmentPreview, identify, jobTitle, retrieve, search } from './endpoints/index.js';
+import { autocomplete, bulkCompanyEnrichment, bulkEnrichment, bulkRetrieve, changelog, cleaner, enrichment, enrichmentPreview, identify, jobPostingSearch, jobTitle, retrieve, search } from './endpoints/index.js';
 import ip from './endpoints/ip/index.js';
 import { APISettings, RequestOptions } from './types/api-types.js';
 import { AutoCompleteParams, AutoCompleteResponse } from './types/autocomplete-types.js';
@@ -10,6 +10,7 @@ import { CompanyResponse, PersonResponse } from './types/common-types.js';
 import { CompanyEnrichmentParams, CompanyEnrichmentResponse, PersonEnrichmentParams, PersonEnrichmentPreviewParams, PersonEnrichmentPreviewResponse, PersonEnrichmentResponse, PersonPreviewResponse } from './types/enrichment-types.js';
 import { IdentifyParams, IdentifyResponse } from './types/identify-types.js';
 import { IPParams, IPResponse } from './types/ip-types.js';
+import { JobPostingSearchParams, JobPostingSearchResponse } from './types/jobPosting-types.js';
 import { JobTitleParams, JobTitleResponse } from './types/jobTitle-types.js';
 import { RetrieveParams, RetrieveResponse } from './types/retrieve-types.js';
 import { CompanySearchParams, CompanySearchResponse, PersonSearchParams, PersonSearchResponse } from './types/search-types.js';
@@ -57,6 +58,10 @@ class PDLJS {
 
   public jobTitle: (params: JobTitleParams, options?: RequestOptions) => Promise<JobTitleResponse>;
 
+  public jobPosting: {
+    search: (params: JobPostingSearchParams, options?: RequestOptions) => Promise<JobPostingSearchResponse>;
+  };
+
   public ip: (params: IPParams, options?: RequestOptions) => Promise<IPResponse>;
 
   constructor({
@@ -109,6 +114,10 @@ class PDLJS {
 
     this.jobTitle = (params: JobTitleParams, options) => jobTitle(this.basePath, this.apiKey, params, options);
 
+    this.jobPosting = {
+      search: (params, options) => jobPostingSearch(this.basePath, this.apiKey, params, options),
+    };
+
     this.ip = (params: IPParams, options) => ip(this.basePath, this.apiKey, params, options);
   }
 }
@@ -138,6 +147,8 @@ export type {
   IdentifyResponse,
   IPParams,
   IPResponse,
+  JobPostingSearchParams,
+  JobPostingSearchResponse,
   JobTitleParams,
   JobTitleResponse,
   LocationCleanerParams,

src/types/error-types.ts

@@ -1,6 +1,6 @@
 import { RateLimit } from './api-types.js';
 
-export type ErrorEndpoint = 'enrichment' | 'autocomplete' | 'changelog' | 'search' | 'identify' | 'bulk' | 'cleaner' | 'retrieve' | 'jobTitle' | 'ip';
+export type ErrorEndpoint = 'enrichment' | 'autocomplete' | 'changelog' | 'search' | 'identify' | 'bulk' | 'cleaner' | 'retrieve' | 'jobTitle' | 'jobPostingSearch' | 'ip';
 
 export type PdlError = {
   message: string;

src/types/jobPosting-types.ts

@@ -0,0 +1,57 @@
+import { BaseResponse } from './api-types.js';
+
+export type RemoteWorkPolicy = 'remote' | 'onsite';
+export type SalaryPeriod = 'year' | 'month' | 'week' | 'day' | 'hour';
+
+interface JobPostingSearchCommon {
+  pretty?: boolean;
+  scroll_token?: string;
+  size?: number;
+}
+
+export interface JobPostingQuerySearchParams extends JobPostingSearchCommon {
+  query: object;
+}
+
+export interface JobPostingParamSearchParams extends JobPostingSearchCommon {
+  id?: string;
+  first_seen_min?: string;
+  first_seen_max?: string;
+  deactivated_date_min?: string;
+  deactivated_date_max?: string;
+  title?: string;
+  title_class?: string;
+  title_role?: string;
+  title_sub_role?: string;
+  title_levels?: string;
+  company_id?: string;
+  company_name?: string;
+  company_industry?: string;
+  company_industry_v2?: string;
+  company_website?: string;
+  company_profile?: string;
+  location?: string;
+  description?: string;
+  salary_range_min?: number;
+  salary_range_max?: number;
+  salary_currency?: string;
+  salary_period?: SalaryPeriod;
+  remote_work_policy?: RemoteWorkPolicy;
+  inferred_skills?: string;
+  last_verified_min?: string;
+  last_verified_max?: string;
+  is_active?: boolean;
+}
+
+export type JobPostingSearchParams = JobPostingQuerySearchParams | JobPostingParamSearchParams;
+
+export interface JobPostingResponse {
+  id?: string | null;
+  [key: string]: unknown;
+}
+
+export interface JobPostingSearchResponse extends BaseResponse {
+  data: Array<JobPostingResponse>;
+  scroll_token?: string;
+  total: number;
+}

tests/index.test.ts

@@ -550,6 +550,64 @@ describe('Job Title API', () => {
   });
 });
 
+describe('Job Posting Search API', () => {
+  const jobPostingElastic = {
+    query: {
+      bool: {
+        must: [
+          { term: { title_role: 'engineering' } },
+        ],
+      },
+    },
+  };
+
+  it(`Should Return Job Posting Records for ${JSON.stringify(jobPostingElastic)}`, async () => {
+    try {
+      const response = await PDLJSClient.jobPosting.search({ ...jobPostingElastic, size: 10 });
+
+      expect(response.status).to.equal(200);
+      expect(response).to.be.a('object');
+    } catch (error) {
+      expect(error).to.equal(null);
+    }
+  }).timeout(10000);
+
+  it('Should Return Job Posting Records by field params', async () => {
+    try {
+      const response = await PDLJSClient.jobPosting.search({
+        title_role: 'engineering',
+        remote_work_policy: 'remote',
+        size: 10,
+      });
+
+      expect(response.status).to.equal(200);
+      expect(response).to.be.a('object');
+    } catch (error) {
+      expect(error).to.equal(null);
+    }
+  }).timeout(10000);
+
+  it('Should Error for Job Posting Search with no params', async () => {
+    try {
+      const response = await PDLJSClient.jobPosting.search();
+
+      expect(response).to.equal(null);
+    } catch (error) {
+      expect(error).to.be.a('object');
+    }
+  });
+
+  it('Should Error for Job Posting Search with empty params', async () => {
+    try {
+      const response = await PDLJSClient.jobPosting.search({});
+
+      expect(response).to.equal(null);
+    } catch (error) {
+      expect(error).to.be.a('object');
+    }
+  });
+});
+
 describe('IP Enrichment API', () => {
   it(`Should Return IP Records for ${JSON.stringify(ip)}`, async () => {
     try {