Add endorsePersonSkill and endorsePersonSkills operations

- endorsePersonSkill: endorse one skill on a 1st-degree connection's
  profile by its exact name.
- endorsePersonSkills: endorse every skill whose name matches any of the
  given case-insensitive RE2 patterns (all skills when omitted); returns
  the selected skills in profile order, each with its own success/error.
- Add stEndorsements limit category and the skillNotFound,
  endorsementUnavailable and limitExceeded action error types.
- Bump version to 2.4.0.

Author: KirillSergeevich

README.md

@@ -9,5 +9,29 @@ To get started with Linked API Node.js SDK, read these essential guides first. S
 4. [Handling results and errors](https://linkedapi.io/sdks/handling-results-and-errors/) – see how to process successful results and errors.
 5. [Persisting and cancelling workflows](https://linkedapi.io/sdks/persisting-and-cancelling-workflows/) – learn how to save, resume, and cancel workflows.
 
+## Skill endorsements in 2.4.0
+
+Use `endorsePersonSkill` to endorse one skill by its exact name, or `endorsePersonSkills` to select skills by case-insensitive RE2 patterns. Omit `skillNamePatterns` to endorse every skill. Endorsements require a 1st-degree connection and preserve any existing endorsement.
+
+```typescript
+const workflow = await linkedApi.endorsePersonSkill.execute({
+  personUrl: 'https://www.linkedin.com/in/example-person',
+  skillName: 'Project Management',
+});
+const result = await linkedApi.endorsePersonSkill.result(workflow.workflowId);
+console.log(result.errors);
+
+const skillsWorkflow = await linkedApi.endorsePersonSkills.execute({
+  personUrl: 'https://www.linkedin.com/in/example-person',
+  skillNamePatterns: ['business', 'project\\s*manage'],
+});
+const skillsResult = await linkedApi.endorsePersonSkills.result(skillsWorkflow.workflowId);
+console.log(skillsResult.data, skillsResult.errors);
+```
+
+The single-skill operation returns no data. The multi-skill operation returns only selected skills in profile order, as `{ skillName, success, error? }`. Per-skill failures stay on their items; a failure opening the profile or reading skills returns no data and a top-level error. Each successful endorsement counts toward the `stEndorsements` limit category.
+
+See [examples/endorse-skills.ts](examples/endorse-skills.ts) for both operations and error handling.
+
 ## License
 This project is licensed under the MIT – see the [LICENSE](https://github.com/Linked-API/linkedapi-node/blob/main/LICENSE) file for details.

examples/endorse-skills.ts

@@ -0,0 +1,48 @@
+import LinkedApi, { LinkedApiError } from '@linkedapi/node';
+
+async function endorseSkillsExample(): Promise<void> {
+  const linkedApi = new LinkedApi({
+    linkedApiToken: process.env.LINKED_API_TOKEN!,
+    identificationToken: process.env.IDENTIFICATION_TOKEN!,
+  });
+  const personUrl = 'https://www.linkedin.com/in/example-person';
+
+  try {
+    const workflow = await linkedApi.endorsePersonSkill.execute({
+      personUrl,
+      skillName: 'Project Management',
+    });
+    const result = await linkedApi.endorsePersonSkill.result(workflow.workflowId);
+    if (result.errors.length > 0) {
+      console.error('Skill endorsement failed:', result.errors);
+    } else {
+      console.log('Skill endorsed successfully');
+    }
+
+    const skillsWorkflow = await linkedApi.endorsePersonSkills.execute({
+      personUrl,
+      skillNamePatterns: ['business', 'project\\s*manage'],
+    });
+    const skillsResult = await linkedApi.endorsePersonSkills.result(skillsWorkflow.workflowId);
+    if (skillsResult.errors.length > 0) {
+      console.error('Unable to read the profile skills:', skillsResult.errors);
+    }
+    for (const { skillName, success, error } of skillsResult.data ?? []) {
+      if (success) {
+        console.log('Endorsed:', skillName);
+      } else {
+        console.error('Endorsement failed:', skillName, error);
+      }
+    }
+  } catch (error) {
+    if (error instanceof LinkedApiError) {
+      console.error('Linked API error:', error.type, error.message);
+    } else {
+      console.error('Unknown error:', error);
+    }
+  }
+}
+
+if (require.main === module) {
+  void endorseSkillsExample();
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedapi/node",
-  "version": "2.3.17",
+  "version": "2.4.0",
   "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/core/operation.ts

@@ -30,6 +30,8 @@ export const OPERATION_NAME = {
   ignoreInvitation: 'ignoreInvitation',
   retrieveConnections: 'retrieveConnections',
   removeConnection: 'removeConnection',
+  endorsePersonSkill: 'endorsePersonSkill',
+  endorsePersonSkills: 'endorsePersonSkills',
   searchCompanies: 'searchCompanies',
   searchPeople: 'searchPeople',
   searchJobs: 'searchJobs',

src/index.ts

@@ -8,6 +8,8 @@ import {
   CreatePost,
   CreateRepost,
   CustomWorkflow,
+  EndorsePersonSkill,
+  EndorsePersonSkills,
   FetchCompany,
   FetchJob,
   FetchPerson,
@@ -125,6 +127,8 @@ class LinkedApi {
     this.ignoreInvitation = new IgnoreInvitation(this.httpClient);
     this.retrieveConnections = new RetrieveConnections(this.httpClient);
     this.removeConnection = new RemoveConnection(this.httpClient);
+    this.endorsePersonSkill = new EndorsePersonSkill(this.httpClient);
+    this.endorsePersonSkills = new EndorsePersonSkills(this.httpClient);
     this.searchCompanies = new SearchCompanies(this.httpClient);
     this.searchPeople = new SearchPeople(this.httpClient);
     this.searchJobs = new SearchJobs(this.httpClient);
@@ -168,6 +172,8 @@ class LinkedApi {
       this.ignoreInvitation,
       this.retrieveConnections,
       this.removeConnection,
+      this.endorsePersonSkill,
+      this.endorsePersonSkills,
       this.searchCompanies,
       this.searchPeople,
       this.searchJobs,
@@ -1390,6 +1396,19 @@ class LinkedApi {
    */
   public removeConnection: RemoveConnection;
 
+  /**
+   * Endorse a skill by its exact name on a 1st-degree connection's profile.
+   * Letter case and extra spaces are ignored. An existing endorsement is preserved.
+   */
+  public endorsePersonSkill: EndorsePersonSkill;
+
+  /**
+   * Endorse skills matching any RE2 pattern, or every skill when patterns are omitted.
+   * Results contain only selected skills in profile order, with per-skill errors on each item.
+   * Failures opening the profile or reading skills appear in the top-level errors with no data.
+   */
+  public endorsePersonSkills: EndorsePersonSkills;
+
   /**
    * React to a LinkedIn post with an emoji reaction.
    *

src/mappers/endorse-person-skills-mapper.ts

@@ -0,0 +1,88 @@
+import type {
+  TEndorsePersonSkillsParams,
+  TPersonSkill,
+  TPersonSkillEndorsement,
+} from '../types/actions';
+import { LinkedApiError } from '../types/errors';
+import type {
+  TWorkflowCompletion,
+  TWorkflowDefinition,
+  TWorkflowSingleData,
+} from '../types/workflows';
+
+import { BaseMapper, TMappedResponse } from './base-mapper.abstract';
+
+type TSkillCompletion = TPersonSkill & TWorkflowSingleData;
+
+export class EndorsePersonSkillsMapper extends BaseMapper<
+  TEndorsePersonSkillsParams,
+  Array<TPersonSkillEndorsement>
+> {
+  public override mapRequest(params: TEndorsePersonSkillsParams): TWorkflowDefinition {
+    const { personUrl, skillNamePatterns } = params;
+
+    return {
+      actionType: 'st.openPersonPage',
+      personUrl,
+      basicInfo: false,
+      then: {
+        actionType: 'st.retrievePersonSkills',
+        then: {
+          actionType: 'st.doForSkills',
+          ...(skillNamePatterns !== undefined ? { skillNamePatterns } : {}),
+          then: {
+            actionType: 'st.endorsePersonSkill',
+          },
+        },
+      },
+    };
+  }
+
+  public override mapResponse(
+    completion: TWorkflowCompletion,
+  ): TMappedResponse<Array<TPersonSkillEndorsement>> {
+    const root = Array.isArray(completion) ? completion[0] : completion;
+    if (!root) {
+      throw LinkedApiError.unknownError();
+    }
+    if (root.error) {
+      return { errors: [root.error] };
+    }
+
+    const then = Array.isArray(root.data) ? undefined : root.data?.then;
+    const skillsAction = Array.isArray(then)
+      ? then.find((action) => action.actionType === 'st.retrievePersonSkills')
+      : then;
+    if (!skillsAction || skillsAction.actionType !== 'st.retrievePersonSkills') {
+      throw LinkedApiError.unknownError();
+    }
+    if (skillsAction.error) {
+      return { errors: [skillsAction.error] };
+    }
+    if (!Array.isArray(skillsAction.data)) {
+      throw LinkedApiError.unknownError();
+    }
+
+    const skills = skillsAction.data as Array<TSkillCompletion>;
+    const data: Array<TPersonSkillEndorsement> = [];
+    for (const skill of skills) {
+      const endorsement = Array.isArray(skill.then)
+        ? skill.then.find((action) => action.actionType === 'st.endorsePersonSkill')
+        : skill.then;
+      if (!endorsement || endorsement.actionType !== 'st.endorsePersonSkill') {
+        continue;
+      }
+
+      data.push({
+        skillName: skill.name,
+        success: endorsement.success,
+        ...(endorsement.error ? { error: endorsement.error } : {}),
+      });
+    }
+
+    return {
+      data,
+      errors: [],
+    };
+  }
+}