update job searching

Author: LordOfTheVillage

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedapi/node",
-  "version": "2.3.9",
+  "version": "2.3.10",
   "description": "Control your LinkedIn accounts and retrieve real-time data, all through this Node.js SDK.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/index.ts

@@ -986,6 +986,10 @@ class LinkedApi {
    * This method performs a job search on LinkedIn using the standard search interface.
    * You can filter by location, date posted, experience level, employment type, workplace type, and more.
    *
+   * LinkedIn serves either a classic or an AI-powered jobs search, and the two do not offer the
+   * same refinements. Pass `filter` for the classic one or `preferences` for the AI-powered one,
+   * never both.
+   *
    * @param params - Search parameters including keywords, filters, and pagination options
    * @returns Promise resolving to an object containing an array of job search results
    *
@@ -995,8 +999,8 @@ class LinkedApi {
    * ```typescript
    * const workflow = await linkedapi.searchJobs.execute({
    *   term: "product manager",
+   *   location: "San Francisco, California, United States",
    *   filter: {
-   *     location: "San Francisco, California, United States",
    *     experienceLevels: ["midSeniorLevel", "director"],
    *     workplaceTypes: ["remote", "hybrid"]
    *   },

src/types/actions/job.ts

@@ -36,6 +36,35 @@ export const JOB_WORKPLACE_TYPE = {
 } as const;
 export type TJobWorkplaceType = (typeof JOB_WORKPLACE_TYPE)[keyof typeof JOB_WORKPLACE_TYPE];
 
+/**
+ * Experience levels of LinkedIn's AI-powered jobs search.
+ * Not a subset of {@link JOB_EXPERIENCE_LEVEL}: `senior` corresponds to `midSeniorLevel`, `manager`
+ * has no classic equivalent, and `internship` / `associate` are absent here.
+ */
+export const JOB_PREFERENCE_EXPERIENCE_LEVEL = {
+  entryLevel: 'entryLevel',
+  senior: 'senior',
+  manager: 'manager',
+  director: 'director',
+  executive: 'executive',
+} as const;
+export type TJobPreferenceExperienceLevel =
+  (typeof JOB_PREFERENCE_EXPERIENCE_LEVEL)[keyof typeof JOB_PREFERENCE_EXPERIENCE_LEVEL];
+
+/**
+ * Employment types of LinkedIn's AI-powered jobs search.
+ * Same names as {@link JOB_EMPLOYMENT_TYPE}, minus `temporary` and `other`.
+ */
+export const JOB_PREFERENCE_EMPLOYMENT_TYPE = {
+  fullTime: 'fullTime',
+  partTime: 'partTime',
+  contract: 'contract',
+  internship: 'internship',
+  volunteer: 'volunteer',
+} as const;
+export type TJobPreferenceEmploymentType =
+  (typeof JOB_PREFERENCE_EMPLOYMENT_TYPE)[keyof typeof JOB_PREFERENCE_EMPLOYMENT_TYPE];
+
 export const JOB_SALARY_PERIOD = {
   yearly: 'yearly',
   monthly: 'monthly',
@@ -91,7 +120,12 @@ export interface TJobSalary {
   period: TJobSalaryPeriod | null;
 }
 
+/**
+ * Filtering criteria for the classic LinkedIn jobs search. Every specified field is applied, or the
+ * action fails.
+ */
 export interface TJobFilter {
+  /** @deprecated Use the top-level `location` of {@link TSearchJobsParams} instead. */
   location?: string;
   datePosted?: TJobDatePosted;
   experienceLevels?: TJobExperienceLevel[];
@@ -107,10 +141,32 @@ export interface TJobFilter {
   fairChanceEmployer?: boolean;
 }
 
+/**
+ * Filtering criteria for LinkedIn's AI-powered jobs search. LinkedIn decides which of them it
+ * offers for a given search, and the ones it does not offer are skipped instead of failing the
+ * action.
+ */
+export interface TJobPreferences {
+  datePosted?: TJobDatePosted;
+  experienceLevels?: TJobPreferenceExperienceLevel[];
+  employmentTypes?: TJobPreferenceEmploymentType[];
+  companies?: string[];
+  remote?: boolean;
+  easyApply?: boolean;
+  under10Applicants?: boolean;
+  inYourNetwork?: boolean;
+  keywords?: string[];
+}
+
 export interface TSearchJobsParams extends TBaseActionParams {
   term?: string;
   limit?: number;
+  location?: string;
+  allowSimilarResults?: boolean;
+  /** Mutually exclusive with {@link TSearchJobsParams.preferences}. */
   filter?: TJobFilter;
+  /** Mutually exclusive with {@link TSearchJobsParams.filter}. */
+  preferences?: TJobPreferences;
   customSearchUrl?: string;
 }
 
@@ -125,6 +181,7 @@ export interface TSearchJobResult {
   salary: TJobSalary | null;
   easyApply: boolean;
   isPromoted: boolean;
+  isSimilarMatch: boolean;
 }
 
 export interface TBaseFetchJobParams extends TBaseActionParams {
@@ -139,7 +196,6 @@ export interface TJob {
   jobUrl: string;
   title: string;
   companyName: string | null;
-  companyUrn: string | null;
   companyUrl: string | null;
   location: string | null;
   postedDate: string | null;

src/types/errors.ts

@@ -18,6 +18,7 @@ import { TOperationName } from '../core';
  * - retrievingNotAllowed (retrieveConnections, fetchCompany, nvFetchCompany)
  * - connectionNotFound (removeConnection)
  * - searchingNotAllowed (searchCompanies, searchPeople, searchJobs, nvSearchCompanies, nvSearchPeople)
+ * - searchInterfaceMismatch (searchJobs)
  * - companyNotFound (fetchCompany, nvFetchCompany)
  * - postNotFound (fetchPost, reactToPost, commentOnPost)
  * - jobNotFound (fetchJob)
@@ -43,6 +44,7 @@ export const LINKED_API_ACTION_ERROR = {
   retrievingNotAllowed: 'retrievingNotAllowed',
   connectionNotFound: 'connectionNotFound',
   searchingNotAllowed: 'searchingNotAllowed',
+  searchInterfaceMismatch: 'searchInterfaceMismatch',
   companyNotFound: 'companyNotFound',
   postNotFound: 'postNotFound',
   jobNotFound: 'jobNotFound',