lumnisai 0.5.40 → 0.5.41

package/dist/index.cjs

@@ -3491,6 +3491,7 @@ class ResponsesResource {
       }
     }
     for (const [camel, snake] of [
+      ["includeReactedPosts", "include_reacted_posts"],
       ["postsEnableFiltering", "posts_enable_filtering"],
       ["thoroughEnrichment", "thorough_enrichment"],
       ["deepValidationUseRelevanceReranker", "deep_validation_use_relevance_reranker"]
@@ -3549,6 +3550,60 @@ class ResponsesResource {
       );
     }
   }
+  _validateSalesNavigatorRequest(request) {
+    const directParams = request.specializedAgentParams;
+    const directUrl = directParams ? this._getParamValue(directParams, "salesNavigatorUrl", "sales_navigator_url") : void 0;
+    const requestOptions = request.options;
+    const nestedParams = requestOptions ? this._getParamValue(
+      requestOptions,
+      "specializedAgentParams",
+      "specialized_agent_params"
+    ) : void 0;
+    const nestedUrl = this._isPlainObject(nestedParams) ? this._getParamValue(nestedParams, "salesNavigatorUrl", "sales_navigator_url") : void 0;
+    const optionsUrl = requestOptions ? this._getParamValue(requestOptions, "salesNavigatorUrl", "sales_navigator_url") : void 0;
+    const salesNavigatorUrl = directUrl ?? nestedUrl ?? optionsUrl;
+    if (salesNavigatorUrl === void 0 || salesNavigatorUrl === null)
+      return;
+    if (typeof salesNavigatorUrl !== "string" || salesNavigatorUrl.length > 8192 || !salesNavigatorUrl.trim()) {
+      throw new ValidationError(
+        "salesNavigatorUrl must be a non-empty string no longer than 8192 characters"
+      );
+    }
+    if ([...salesNavigatorUrl].some((character) => character.charCodeAt(0) < 32) || salesNavigatorUrl.includes("\\")) {
+      throw new ValidationError("salesNavigatorUrl contains unsafe characters");
+    }
+    let parsed;
+    try {
+      parsed = new URL(salesNavigatorUrl);
+    } catch {
+      throw new ValidationError("salesNavigatorUrl is malformed");
+    }
+    const authorityMatch = salesNavigatorUrl.match(/^[a-z][a-z\d+.-]*:\/\/([^/?#]*)/i);
+    const rawAuthority = authorityMatch?.[1];
+    if (parsed.protocol !== "https:")
+      throw new ValidationError("salesNavigatorUrl must use https");
+    if (parsed.hostname !== "www.linkedin.com")
+      throw new ValidationError("salesNavigatorUrl must use www.linkedin.com");
+    if (parsed.username || parsed.password || parsed.port || rawAuthority?.toLowerCase() !== "www.linkedin.com") {
+      throw new ValidationError("salesNavigatorUrl cannot contain credentials or a custom port");
+    }
+    if (parsed.hash)
+      throw new ValidationError("salesNavigatorUrl cannot contain a fragment");
+    const rawSuffix = authorityMatch ? salesNavigatorUrl.slice(authorityMatch[0].length) : "";
+    const rawPath = rawSuffix.split(/[?#]/, 1)[0];
+    if (rawPath === "/sales/search/company") {
+      throw new ValidationError(
+        "Company Sales Navigator searches are not supported yet; use a people search or people list URL"
+      );
+    }
+    if (rawPath !== "/sales/search/people" && !/^\/sales\/lists\/people\/\d+$/.test(rawPath)) {
+      throw new ValidationError(
+        "salesNavigatorUrl must be a Sales Navigator people-search or people-list URL"
+      );
+    }
+    if (typeof request.userId !== "string" || !request.userId.trim())
+      throw new ValidationError("userId is required when salesNavigatorUrl is provided");
+  }
   _validateCriteriaParams(params, specializedAgent) {
     if (!params)
       return;
@@ -3711,6 +3766,7 @@ class ResponsesResource {
       for (const file of request.files)
         this._validateFileReference(file.uri);
     }
+    this._validateSalesNavigatorRequest(request);
     if (request.specializedAgentParams)
       this._validateCriteriaParams(request.specializedAgentParams, request.specializedAgent);
     return this.http.post("/responses", request);
@@ -3846,10 +3902,13 @@ class ResponsesResource {
    * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true
    * @param options.crmExclusionOwners - Granted owner ledgers to exclude against (user id or email)
    * @param options.crmNameCompanyMatch - Also exclude by exact name+company; @default true
+   * @param options.salesNavigatorUrl - Sales Navigator people-search or people-list URL to use as the only discovery source
+   * @param options.userId - Acting user whose owned Sales Navigator connection should be used; required with `salesNavigatorUrl`
    * @param options.searchJobSignal - CrustData job-listing signal search (decision makers at hiring companies); true | false | 'auto'
    * @param options.deepVerify - Web verification for org/location/third-party criteria: 'auto' (default), 'always', or 'off'
    * @param options.deepValidationUseRelevanceReranker - SLM relevance reranker for surfaced candidates (ranking-only); @default true
    * @param options.deepValidationBackfillBelowCriteria - Pad with criteria-failed candidates when under count; @default true
+   * @param options.enrichEngagementHistory - Add recent LinkedIn engagement evidence before validation; forced off for Sales Navigator V1
    * @param options.deepSearchCriteriaModel - Override criteria decomposition model (e.g. 'openai:gpt-5.4')
    * @returns Response with structured_response containing:
    *   - candidates: Validated and scored candidates
@@ -3861,6 +3920,8 @@ class ResponsesResource {
       messages: [{ role: "user", content: query }],
       specializedAgent: "deep_people_search"
     };
+    if (options?.userId !== void 0)
+      request.userId = options.userId;
     const params = {
       deepValidationUseRelevanceReranker: options?.deepValidationUseRelevanceReranker ?? true,
       deepValidationBackfillBelowCriteria: options?.deepValidationBackfillBelowCriteria ?? true
@@ -3894,6 +3955,8 @@ class ResponsesResource {
         params.crmExclusionOwners = options.crmExclusionOwners;
       if (options.crmNameCompanyMatch !== void 0)
         params.crmNameCompanyMatch = options.crmNameCompanyMatch;
+      if (options.salesNavigatorUrl !== void 0)
+        params.salesNavigatorUrl = options.salesNavigatorUrl;
       if (options.searchProfiles !== void 0)
         params.searchProfiles = options.searchProfiles;
       if (options.searchPosts !== void 0)
@@ -3928,8 +3991,22 @@ class ResponsesResource {
         params.searchJobSignal = options.searchJobSignal;
       if (options.deepVerify !== void 0)
         params.deepVerify = options.deepVerify;
+      if (options.enrichEngagementHistory !== void 0)
+        params.enrichEngagementHistory = options.enrichEngagementHistory;
       if (options.deepSearchCriteriaModel)
         params.deepSearchCriteriaModel = options.deepSearchCriteriaModel;
+      if (options.salesNavigatorUrl !== void 0) {
+        params.searchProfiles = false;
+        params.searchPosts = false;
+        params.searchConnections = false;
+        params.searchJobSignal = false;
+        params.includeEngagementInScore = false;
+        params.postsEnableEnrichment = false;
+        params.postsEnableFiltering = false;
+        params.deepValidationUseRelevanceReranker = false;
+        params.deepValidationBackfillBelowCriteria = false;
+        params.enrichEngagementHistory = false;
+      }
     }
     request.specializedAgentParams = params;
     return this.create(request);
@@ -4069,10 +4146,10 @@ class ResponsesResource {
   /**
    * Score people who react to or comment on posts connected to named LinkedIn profiles.
    *
-   * The backend reads posts each seed authored and reacted to within the requested
-   * window, selects posts relevant to the persona prompt, then runs their engagers
-   * through the deep people-search scoring chain. Seed profiles are always excluded
-   * from delivered candidates.
+   * The backend reads posts each seed authored within the requested window and can
+   * optionally include posts they reacted to. It selects posts relevant to the
+   * persona prompt, then runs their engagers through the deep people-search scoring
+   * chain. Seed profiles are always excluded from delivered candidates.
    *
    * @param query - Persona prompt used to select posts and score discovered people.
    * @param options - Seed profiles plus optional window, extraction, and cost controls.
@@ -4085,6 +4162,8 @@ class ResponsesResource {
     const params = {
       seedProfiles: options.seedProfiles
     };
+    if (options.includeReactedPosts !== void 0)
+      params.includeReactedPosts = options.includeReactedPosts;
     if (options.postsDateRange !== void 0)
       params.postsDateRange = options.postsDateRange;
     if (options.engagementTypes !== void 0)

package/dist/index.d.cts

@@ -2005,8 +2005,14 @@ interface EngagementExpansionOutput {
 
 /** Options accepted by {@link ResponsesResource.influencerEngagement}. */
 interface InfluencerEngagementOptions {
-    /** LinkedIn profile URLs whose authored and reacted-to posts seed discovery. */
+    /** LinkedIn profile URLs whose authored posts seed discovery. */
     seedProfiles: string[];
+    /**
+     * Also use posts the seeds reacted to. These posts describe a wider,
+     * third-party audience and are disabled by default.
+     * @default false
+     */
+    includeReactedPosts?: boolean;
     /** How far back to inspect each seed's activity. @default 'past-month' */
     postsDateRange?: PostsDateRange;
     /** Candidate engagement roles to collect. @default ['reactor', 'commenter'] */
@@ -2034,6 +2040,7 @@ interface InfluencerEngagementOptions {
 /** Resolved parameters echoed in `structuredResponse.agentParams`. */
 interface InfluencerEngagementResolvedParams {
     seedProfiles: string[];
+    includeReactedPosts: boolean;
     postsDateRange: PostsDateRange;
     engagementTypes: PostEngagementType[];
     postsEnableFiltering: boolean;
@@ -2497,6 +2504,8 @@ interface ValidatedCandidate {
     name: string;
     /** LinkedIn profile URL */
     linkedinUrl?: string;
+    /** LinkedIn/provider member identifier, including Sales Navigator hidden-profile IDs. */
+    linkedinMemberId?: string | null;
     /**
      * Current job title. When the reranker runs, may reflect the resolved primary
      * operating role (`primaryTitle`); see `enrichedCurrentTitle` for the pre-rerank value.
@@ -2552,8 +2561,9 @@ interface ValidatedCandidate {
     intentSignals?: IntentSignal[];
     /**
      * Holistic relevance score (0-100) from the SLM reranker (on by default).
-     * Ranking-only: absent only when `deepValidationUseRelevanceReranker` was false;
-     * does not change `overallScore` or routing.
+     * Ranking-only: absent when `deepValidationUseRelevanceReranker` was false or
+     * when the fixed Sales Navigator lane was used; does not change `overallScore`
+     * or routing.
      */
     relevanceScore?: number;
     /** Coarse match tier paired with `relevanceScore`. */
@@ -2619,6 +2629,12 @@ interface ValidatedCandidate {
     refoundOnNewPost?: boolean;
     /** Source of candidate data */
     source?: string;
+    /** Candidate-source lanes that found this person, including `sales_navigator`. */
+    discoverySources?: string[];
+    /** LinkedIn relationship distance reported by Sales Navigator. */
+    networkDistance?: 'FIRST_DEGREE' | 'SECOND_DEGREE' | 'THIRD_DEGREE' | 'OUT_OF_NETWORK' | null;
+    /** Number of mutual LinkedIn connections reported by Sales Navigator. */
+    mutualConnectionsCount?: number | null;
     /** When source is job_signal: hiring-company context from CrustData job listings */
     jobSignalMetadata?: {
         companyId?: number | null;
@@ -2774,7 +2790,8 @@ type PostsDateRange = 'past-24h' | 'past-week' | 'past-month' | 'past-quarter' |
 interface SpecializedAgentParams {
     /**
      * Maximum number of results.
-     * Agent-specific ranges: quick_people_search (1-100), competitor_post_engagement (1-1000).
+     * Agent-specific ranges: quick_people_search (1-100), deep_people_search
+     * alias (1-1000), competitor_post_engagement (1-1000).
      */
     limit?: number;
     /**
@@ -2782,6 +2799,17 @@ interface SpecializedAgentParams {
      * Range: 1-1000
      */
     requestedCandidates?: number;
+    /**
+     * LinkedIn Sales Navigator people-search or people-list URL used as the
+     * deterministic candidate source for deep_people_search. Requires `userId`
+     * on the create request so the backend can resolve the acting user's owned
+     * LinkedIn connection. V1 accepts people-search and people-list URLs only,
+     * caps provider extraction at 2,500 rows, and disables all other discovery
+     * lanes, relevance reranking, below-criteria backfill, and engagement-history
+     * enrichment.
+     * @maxLength 8192
+     */
+    salesNavigatorUrl?: string;
     /**
      * Specific data sources to use (agent-specific)
      * For people search agents: ["PDL", "CORESIGNAL", "CRUST_DATA"]
@@ -2855,10 +2883,17 @@ interface SpecializedAgentParams {
      */
     candidateProfiles?: Array<Record<string, any>>;
     /**
-     * LinkedIn profile URLs whose authored and reacted-to posts seed discovery.
+     * LinkedIn profile URLs whose authored posts seed discovery.
      * Required by influencer_engagement. Seeds are always excluded from results.
      */
     seedProfiles?: string[];
+    /**
+     * Whether influencer_engagement should also use posts the seeds reacted to.
+     * These posts describe a wider, third-party audience and may carry no
+     * engagement counts, so they can rank below authored posts.
+     * @default false
+     */
+    includeReactedPosts?: boolean;
     /**
      * Re-cook the content package stored on a prior response without repeating
      * audience search or engagement collection.
@@ -2936,7 +2971,8 @@ interface SpecializedAgentParams {
      * For deep_people_search / competitor_post_engagement it bounds POST recency;
      * for competitor_rep_engagement it bounds how far back each rep's OUTGOING
      * engagement is considered (also bounded by `maxEngagementsPerRep`); for
-     * influencer_engagement it bounds each seed's authored and reacted-to posts;
+     * influencer_engagement it bounds each seed's authored posts and, when
+     * `includeReactedPosts` is true, reacted-to posts;
      * for content_intelligence it bounds each audience member's reaction history.
      *
      * NOTE on keyword post search: Crustdata's keyword-post API only supports up to
@@ -3007,7 +3043,8 @@ interface SpecializedAgentParams {
      * `intentScore` are untouched. Adds `relevanceScore` / `relevanceTier` per candidate.
      * @default true
      * Used by deep_people_search, people_scoring, competitor_post_engagement,
-     * competitor_rep_engagement, and influencer_engagement.
+     * competitor_rep_engagement, and influencer_engagement. Forced off for the
+     * Sales Navigator V1 source lane.
      */
     deepValidationUseRelevanceReranker?: boolean;
     /**
@@ -3015,9 +3052,18 @@ interface SpecializedAgentParams {
      * promoting top-scoring excluded candidates (tagged `backfilled=true`). Set false for
      * quality-over-count (return only passing candidates, even if fewer than requested).
      * @default true
-     * Used by deep_people_search and people_scoring.
+     * Used by deep_people_search and people_scoring. Forced off for the Sales
+     * Navigator V1 source lane.
      */
     deepValidationBackfillBelowCriteria?: boolean;
+    /**
+     * Enrich fast-filter survivors with recent LinkedIn engagement history before
+     * deep validation. This is an optional paid stage and is forced off for the
+     * Sales Navigator V1 source lane.
+     * @default true
+     * Used by deep_people_search.
+     */
+    enrichEngagementHistory?: boolean;
     /**
      * Override the model used for criteria decomposition (e.g. 'openai:gpt-5.4').
      * Defaults to the configured deep-search model. Only changes the criteria generator,
@@ -7176,6 +7222,7 @@ declare class ResponsesResource {
     private _validateSinceDays;
     private _validateCompanyIntelligenceParams;
     private _validatePersonIntelligenceParams;
+    private _validateSalesNavigatorRequest;
     private _validateCriteriaParams;
     private _validateFileReference;
     /**
@@ -7278,10 +7325,13 @@ declare class ResponsesResource {
      * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true
      * @param options.crmExclusionOwners - Granted owner ledgers to exclude against (user id or email)
      * @param options.crmNameCompanyMatch - Also exclude by exact name+company; @default true
+     * @param options.salesNavigatorUrl - Sales Navigator people-search or people-list URL to use as the only discovery source
+     * @param options.userId - Acting user whose owned Sales Navigator connection should be used; required with `salesNavigatorUrl`
      * @param options.searchJobSignal - CrustData job-listing signal search (decision makers at hiring companies); true | false | 'auto'
      * @param options.deepVerify - Web verification for org/location/third-party criteria: 'auto' (default), 'always', or 'off'
      * @param options.deepValidationUseRelevanceReranker - SLM relevance reranker for surfaced candidates (ranking-only); @default true
      * @param options.deepValidationBackfillBelowCriteria - Pad with criteria-failed candidates when under count; @default true
+     * @param options.enrichEngagementHistory - Add recent LinkedIn engagement evidence before validation; forced off for Sales Navigator V1
      * @param options.deepSearchCriteriaModel - Override criteria decomposition model (e.g. 'openai:gpt-5.4')
      * @returns Response with structured_response containing:
      *   - candidates: Validated and scored candidates
@@ -7308,6 +7358,8 @@ declare class ResponsesResource {
         excludeCrmContacts?: boolean;
         crmExclusionOwners?: string[];
         crmNameCompanyMatch?: boolean;
+        salesNavigatorUrl?: string;
+        userId?: string;
         searchProfiles?: boolean | 'auto';
         searchPosts?: boolean | 'auto';
         includeEngagementInScore?: boolean | 'auto';
@@ -7327,6 +7379,7 @@ declare class ResponsesResource {
         deepVerify?: 'off' | 'auto' | 'always';
         deepValidationUseRelevanceReranker?: boolean;
         deepValidationBackfillBelowCriteria?: boolean;
+        enrichEngagementHistory?: boolean;
         deepSearchCriteriaModel?: string;
     }): Promise<CreateResponseResponse>;
     /**
@@ -7403,10 +7456,10 @@ declare class ResponsesResource {
     /**
      * Score people who react to or comment on posts connected to named LinkedIn profiles.
      *
-     * The backend reads posts each seed authored and reacted to within the requested
-     * window, selects posts relevant to the persona prompt, then runs their engagers
-     * through the deep people-search scoring chain. Seed profiles are always excluded
-     * from delivered candidates.
+     * The backend reads posts each seed authored within the requested window and can
+     * optionally include posts they reacted to. It selects posts relevant to the
+     * persona prompt, then runs their engagers through the deep people-search scoring
+     * chain. Seed profiles are always excluded from delivered candidates.
      *
      * @param query - Persona prompt used to select posts and score discovered people.
      * @param options - Seed profiles plus optional window, extraction, and cost controls.

package/dist/index.d.mts

@@ -2005,8 +2005,14 @@ interface EngagementExpansionOutput {
 
 /** Options accepted by {@link ResponsesResource.influencerEngagement}. */
 interface InfluencerEngagementOptions {
-    /** LinkedIn profile URLs whose authored and reacted-to posts seed discovery. */
+    /** LinkedIn profile URLs whose authored posts seed discovery. */
     seedProfiles: string[];
+    /**
+     * Also use posts the seeds reacted to. These posts describe a wider,
+     * third-party audience and are disabled by default.
+     * @default false
+     */
+    includeReactedPosts?: boolean;
     /** How far back to inspect each seed's activity. @default 'past-month' */
     postsDateRange?: PostsDateRange;
     /** Candidate engagement roles to collect. @default ['reactor', 'commenter'] */
@@ -2034,6 +2040,7 @@ interface InfluencerEngagementOptions {
 /** Resolved parameters echoed in `structuredResponse.agentParams`. */
 interface InfluencerEngagementResolvedParams {
     seedProfiles: string[];
+    includeReactedPosts: boolean;
     postsDateRange: PostsDateRange;
     engagementTypes: PostEngagementType[];
     postsEnableFiltering: boolean;
@@ -2497,6 +2504,8 @@ interface ValidatedCandidate {
     name: string;
     /** LinkedIn profile URL */
     linkedinUrl?: string;
+    /** LinkedIn/provider member identifier, including Sales Navigator hidden-profile IDs. */
+    linkedinMemberId?: string | null;
     /**
      * Current job title. When the reranker runs, may reflect the resolved primary
      * operating role (`primaryTitle`); see `enrichedCurrentTitle` for the pre-rerank value.
@@ -2552,8 +2561,9 @@ interface ValidatedCandidate {
     intentSignals?: IntentSignal[];
     /**
      * Holistic relevance score (0-100) from the SLM reranker (on by default).
-     * Ranking-only: absent only when `deepValidationUseRelevanceReranker` was false;
-     * does not change `overallScore` or routing.
+     * Ranking-only: absent when `deepValidationUseRelevanceReranker` was false or
+     * when the fixed Sales Navigator lane was used; does not change `overallScore`
+     * or routing.
      */
     relevanceScore?: number;
     /** Coarse match tier paired with `relevanceScore`. */
@@ -2619,6 +2629,12 @@ interface ValidatedCandidate {
     refoundOnNewPost?: boolean;
     /** Source of candidate data */
     source?: string;
+    /** Candidate-source lanes that found this person, including `sales_navigator`. */
+    discoverySources?: string[];
+    /** LinkedIn relationship distance reported by Sales Navigator. */
+    networkDistance?: 'FIRST_DEGREE' | 'SECOND_DEGREE' | 'THIRD_DEGREE' | 'OUT_OF_NETWORK' | null;
+    /** Number of mutual LinkedIn connections reported by Sales Navigator. */
+    mutualConnectionsCount?: number | null;
     /** When source is job_signal: hiring-company context from CrustData job listings */
     jobSignalMetadata?: {
         companyId?: number | null;
@@ -2774,7 +2790,8 @@ type PostsDateRange = 'past-24h' | 'past-week' | 'past-month' | 'past-quarter' |
 interface SpecializedAgentParams {
     /**
      * Maximum number of results.
-     * Agent-specific ranges: quick_people_search (1-100), competitor_post_engagement (1-1000).
+     * Agent-specific ranges: quick_people_search (1-100), deep_people_search
+     * alias (1-1000), competitor_post_engagement (1-1000).
      */
     limit?: number;
     /**
@@ -2782,6 +2799,17 @@ interface SpecializedAgentParams {
      * Range: 1-1000
      */
     requestedCandidates?: number;
+    /**
+     * LinkedIn Sales Navigator people-search or people-list URL used as the
+     * deterministic candidate source for deep_people_search. Requires `userId`
+     * on the create request so the backend can resolve the acting user's owned
+     * LinkedIn connection. V1 accepts people-search and people-list URLs only,
+     * caps provider extraction at 2,500 rows, and disables all other discovery
+     * lanes, relevance reranking, below-criteria backfill, and engagement-history
+     * enrichment.
+     * @maxLength 8192
+     */
+    salesNavigatorUrl?: string;
     /**
      * Specific data sources to use (agent-specific)
      * For people search agents: ["PDL", "CORESIGNAL", "CRUST_DATA"]
@@ -2855,10 +2883,17 @@ interface SpecializedAgentParams {
      */
     candidateProfiles?: Array<Record<string, any>>;
     /**
-     * LinkedIn profile URLs whose authored and reacted-to posts seed discovery.
+     * LinkedIn profile URLs whose authored posts seed discovery.
      * Required by influencer_engagement. Seeds are always excluded from results.
      */
     seedProfiles?: string[];
+    /**
+     * Whether influencer_engagement should also use posts the seeds reacted to.
+     * These posts describe a wider, third-party audience and may carry no
+     * engagement counts, so they can rank below authored posts.
+     * @default false
+     */
+    includeReactedPosts?: boolean;
     /**
      * Re-cook the content package stored on a prior response without repeating
      * audience search or engagement collection.
@@ -2936,7 +2971,8 @@ interface SpecializedAgentParams {
      * For deep_people_search / competitor_post_engagement it bounds POST recency;
      * for competitor_rep_engagement it bounds how far back each rep's OUTGOING
      * engagement is considered (also bounded by `maxEngagementsPerRep`); for
-     * influencer_engagement it bounds each seed's authored and reacted-to posts;
+     * influencer_engagement it bounds each seed's authored posts and, when
+     * `includeReactedPosts` is true, reacted-to posts;
      * for content_intelligence it bounds each audience member's reaction history.
      *
      * NOTE on keyword post search: Crustdata's keyword-post API only supports up to
@@ -3007,7 +3043,8 @@ interface SpecializedAgentParams {
      * `intentScore` are untouched. Adds `relevanceScore` / `relevanceTier` per candidate.
      * @default true
      * Used by deep_people_search, people_scoring, competitor_post_engagement,
-     * competitor_rep_engagement, and influencer_engagement.
+     * competitor_rep_engagement, and influencer_engagement. Forced off for the
+     * Sales Navigator V1 source lane.
      */
     deepValidationUseRelevanceReranker?: boolean;
     /**
@@ -3015,9 +3052,18 @@ interface SpecializedAgentParams {
      * promoting top-scoring excluded candidates (tagged `backfilled=true`). Set false for
      * quality-over-count (return only passing candidates, even if fewer than requested).
      * @default true
-     * Used by deep_people_search and people_scoring.
+     * Used by deep_people_search and people_scoring. Forced off for the Sales
+     * Navigator V1 source lane.
      */
     deepValidationBackfillBelowCriteria?: boolean;
+    /**
+     * Enrich fast-filter survivors with recent LinkedIn engagement history before
+     * deep validation. This is an optional paid stage and is forced off for the
+     * Sales Navigator V1 source lane.
+     * @default true
+     * Used by deep_people_search.
+     */
+    enrichEngagementHistory?: boolean;
     /**
      * Override the model used for criteria decomposition (e.g. 'openai:gpt-5.4').
      * Defaults to the configured deep-search model. Only changes the criteria generator,
@@ -7176,6 +7222,7 @@ declare class ResponsesResource {
     private _validateSinceDays;
     private _validateCompanyIntelligenceParams;
     private _validatePersonIntelligenceParams;
+    private _validateSalesNavigatorRequest;
     private _validateCriteriaParams;
     private _validateFileReference;
     /**
@@ -7278,10 +7325,13 @@ declare class ResponsesResource {
      * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true
      * @param options.crmExclusionOwners - Granted owner ledgers to exclude against (user id or email)
      * @param options.crmNameCompanyMatch - Also exclude by exact name+company; @default true
+     * @param options.salesNavigatorUrl - Sales Navigator people-search or people-list URL to use as the only discovery source
+     * @param options.userId - Acting user whose owned Sales Navigator connection should be used; required with `salesNavigatorUrl`
      * @param options.searchJobSignal - CrustData job-listing signal search (decision makers at hiring companies); true | false | 'auto'
      * @param options.deepVerify - Web verification for org/location/third-party criteria: 'auto' (default), 'always', or 'off'
      * @param options.deepValidationUseRelevanceReranker - SLM relevance reranker for surfaced candidates (ranking-only); @default true
      * @param options.deepValidationBackfillBelowCriteria - Pad with criteria-failed candidates when under count; @default true
+     * @param options.enrichEngagementHistory - Add recent LinkedIn engagement evidence before validation; forced off for Sales Navigator V1
      * @param options.deepSearchCriteriaModel - Override criteria decomposition model (e.g. 'openai:gpt-5.4')
      * @returns Response with structured_response containing:
      *   - candidates: Validated and scored candidates
@@ -7308,6 +7358,8 @@ declare class ResponsesResource {
         excludeCrmContacts?: boolean;
         crmExclusionOwners?: string[];
         crmNameCompanyMatch?: boolean;
+        salesNavigatorUrl?: string;
+        userId?: string;
         searchProfiles?: boolean | 'auto';
         searchPosts?: boolean | 'auto';
         includeEngagementInScore?: boolean | 'auto';
@@ -7327,6 +7379,7 @@ declare class ResponsesResource {
         deepVerify?: 'off' | 'auto' | 'always';
         deepValidationUseRelevanceReranker?: boolean;
         deepValidationBackfillBelowCriteria?: boolean;
+        enrichEngagementHistory?: boolean;
         deepSearchCriteriaModel?: string;
     }): Promise<CreateResponseResponse>;
     /**
@@ -7403,10 +7456,10 @@ declare class ResponsesResource {
     /**
      * Score people who react to or comment on posts connected to named LinkedIn profiles.
      *
-     * The backend reads posts each seed authored and reacted to within the requested
-     * window, selects posts relevant to the persona prompt, then runs their engagers
-     * through the deep people-search scoring chain. Seed profiles are always excluded
-     * from delivered candidates.
+     * The backend reads posts each seed authored within the requested window and can
+     * optionally include posts they reacted to. It selects posts relevant to the
+     * persona prompt, then runs their engagers through the deep people-search scoring
+     * chain. Seed profiles are always excluded from delivered candidates.
      *
      * @param query - Persona prompt used to select posts and score discovered people.
      * @param options - Seed profiles plus optional window, extraction, and cost controls.

package/dist/index.d.ts

@@ -2005,8 +2005,14 @@ interface EngagementExpansionOutput {
 
 /** Options accepted by {@link ResponsesResource.influencerEngagement}. */
 interface InfluencerEngagementOptions {
-    /** LinkedIn profile URLs whose authored and reacted-to posts seed discovery. */
+    /** LinkedIn profile URLs whose authored posts seed discovery. */
     seedProfiles: string[];
+    /**
+     * Also use posts the seeds reacted to. These posts describe a wider,
+     * third-party audience and are disabled by default.
+     * @default false
+     */
+    includeReactedPosts?: boolean;
     /** How far back to inspect each seed's activity. @default 'past-month' */
     postsDateRange?: PostsDateRange;
     /** Candidate engagement roles to collect. @default ['reactor', 'commenter'] */
@@ -2034,6 +2040,7 @@ interface InfluencerEngagementOptions {
 /** Resolved parameters echoed in `structuredResponse.agentParams`. */
 interface InfluencerEngagementResolvedParams {
     seedProfiles: string[];
+    includeReactedPosts: boolean;
     postsDateRange: PostsDateRange;
     engagementTypes: PostEngagementType[];
     postsEnableFiltering: boolean;
@@ -2497,6 +2504,8 @@ interface ValidatedCandidate {
     name: string;
     /** LinkedIn profile URL */
     linkedinUrl?: string;
+    /** LinkedIn/provider member identifier, including Sales Navigator hidden-profile IDs. */
+    linkedinMemberId?: string | null;
     /**
      * Current job title. When the reranker runs, may reflect the resolved primary
      * operating role (`primaryTitle`); see `enrichedCurrentTitle` for the pre-rerank value.
@@ -2552,8 +2561,9 @@ interface ValidatedCandidate {
     intentSignals?: IntentSignal[];
     /**
      * Holistic relevance score (0-100) from the SLM reranker (on by default).
-     * Ranking-only: absent only when `deepValidationUseRelevanceReranker` was false;
-     * does not change `overallScore` or routing.
+     * Ranking-only: absent when `deepValidationUseRelevanceReranker` was false or
+     * when the fixed Sales Navigator lane was used; does not change `overallScore`
+     * or routing.
      */
     relevanceScore?: number;
     /** Coarse match tier paired with `relevanceScore`. */
@@ -2619,6 +2629,12 @@ interface ValidatedCandidate {
     refoundOnNewPost?: boolean;
     /** Source of candidate data */
     source?: string;
+    /** Candidate-source lanes that found this person, including `sales_navigator`. */
+    discoverySources?: string[];
+    /** LinkedIn relationship distance reported by Sales Navigator. */
+    networkDistance?: 'FIRST_DEGREE' | 'SECOND_DEGREE' | 'THIRD_DEGREE' | 'OUT_OF_NETWORK' | null;
+    /** Number of mutual LinkedIn connections reported by Sales Navigator. */
+    mutualConnectionsCount?: number | null;
     /** When source is job_signal: hiring-company context from CrustData job listings */
     jobSignalMetadata?: {
         companyId?: number | null;
@@ -2774,7 +2790,8 @@ type PostsDateRange = 'past-24h' | 'past-week' | 'past-month' | 'past-quarter' |
 interface SpecializedAgentParams {
     /**
      * Maximum number of results.
-     * Agent-specific ranges: quick_people_search (1-100), competitor_post_engagement (1-1000).
+     * Agent-specific ranges: quick_people_search (1-100), deep_people_search
+     * alias (1-1000), competitor_post_engagement (1-1000).
      */
     limit?: number;
     /**
@@ -2782,6 +2799,17 @@ interface SpecializedAgentParams {
      * Range: 1-1000
      */
     requestedCandidates?: number;
+    /**
+     * LinkedIn Sales Navigator people-search or people-list URL used as the
+     * deterministic candidate source for deep_people_search. Requires `userId`
+     * on the create request so the backend can resolve the acting user's owned
+     * LinkedIn connection. V1 accepts people-search and people-list URLs only,
+     * caps provider extraction at 2,500 rows, and disables all other discovery
+     * lanes, relevance reranking, below-criteria backfill, and engagement-history
+     * enrichment.
+     * @maxLength 8192
+     */
+    salesNavigatorUrl?: string;
     /**
      * Specific data sources to use (agent-specific)
      * For people search agents: ["PDL", "CORESIGNAL", "CRUST_DATA"]
@@ -2855,10 +2883,17 @@ interface SpecializedAgentParams {
      */
     candidateProfiles?: Array<Record<string, any>>;
     /**
-     * LinkedIn profile URLs whose authored and reacted-to posts seed discovery.
+     * LinkedIn profile URLs whose authored posts seed discovery.
      * Required by influencer_engagement. Seeds are always excluded from results.
      */
     seedProfiles?: string[];
+    /**
+     * Whether influencer_engagement should also use posts the seeds reacted to.
+     * These posts describe a wider, third-party audience and may carry no
+     * engagement counts, so they can rank below authored posts.
+     * @default false
+     */
+    includeReactedPosts?: boolean;
     /**
      * Re-cook the content package stored on a prior response without repeating
      * audience search or engagement collection.
@@ -2936,7 +2971,8 @@ interface SpecializedAgentParams {
      * For deep_people_search / competitor_post_engagement it bounds POST recency;
      * for competitor_rep_engagement it bounds how far back each rep's OUTGOING
      * engagement is considered (also bounded by `maxEngagementsPerRep`); for
-     * influencer_engagement it bounds each seed's authored and reacted-to posts;
+     * influencer_engagement it bounds each seed's authored posts and, when
+     * `includeReactedPosts` is true, reacted-to posts;
      * for content_intelligence it bounds each audience member's reaction history.
      *
      * NOTE on keyword post search: Crustdata's keyword-post API only supports up to
@@ -3007,7 +3043,8 @@ interface SpecializedAgentParams {
      * `intentScore` are untouched. Adds `relevanceScore` / `relevanceTier` per candidate.
      * @default true
      * Used by deep_people_search, people_scoring, competitor_post_engagement,
-     * competitor_rep_engagement, and influencer_engagement.
+     * competitor_rep_engagement, and influencer_engagement. Forced off for the
+     * Sales Navigator V1 source lane.
      */
     deepValidationUseRelevanceReranker?: boolean;
     /**
@@ -3015,9 +3052,18 @@ interface SpecializedAgentParams {
      * promoting top-scoring excluded candidates (tagged `backfilled=true`). Set false for
      * quality-over-count (return only passing candidates, even if fewer than requested).
      * @default true
-     * Used by deep_people_search and people_scoring.
+     * Used by deep_people_search and people_scoring. Forced off for the Sales
+     * Navigator V1 source lane.
      */
     deepValidationBackfillBelowCriteria?: boolean;
+    /**
+     * Enrich fast-filter survivors with recent LinkedIn engagement history before
+     * deep validation. This is an optional paid stage and is forced off for the
+     * Sales Navigator V1 source lane.
+     * @default true
+     * Used by deep_people_search.
+     */
+    enrichEngagementHistory?: boolean;
     /**
      * Override the model used for criteria decomposition (e.g. 'openai:gpt-5.4').
      * Defaults to the configured deep-search model. Only changes the criteria generator,
@@ -7176,6 +7222,7 @@ declare class ResponsesResource {
     private _validateSinceDays;
     private _validateCompanyIntelligenceParams;
     private _validatePersonIntelligenceParams;
+    private _validateSalesNavigatorRequest;
     private _validateCriteriaParams;
     private _validateFileReference;
     /**
@@ -7278,10 +7325,13 @@ declare class ResponsesResource {
      * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true
      * @param options.crmExclusionOwners - Granted owner ledgers to exclude against (user id or email)
      * @param options.crmNameCompanyMatch - Also exclude by exact name+company; @default true
+     * @param options.salesNavigatorUrl - Sales Navigator people-search or people-list URL to use as the only discovery source
+     * @param options.userId - Acting user whose owned Sales Navigator connection should be used; required with `salesNavigatorUrl`
      * @param options.searchJobSignal - CrustData job-listing signal search (decision makers at hiring companies); true | false | 'auto'
      * @param options.deepVerify - Web verification for org/location/third-party criteria: 'auto' (default), 'always', or 'off'
      * @param options.deepValidationUseRelevanceReranker - SLM relevance reranker for surfaced candidates (ranking-only); @default true
      * @param options.deepValidationBackfillBelowCriteria - Pad with criteria-failed candidates when under count; @default true
+     * @param options.enrichEngagementHistory - Add recent LinkedIn engagement evidence before validation; forced off for Sales Navigator V1
      * @param options.deepSearchCriteriaModel - Override criteria decomposition model (e.g. 'openai:gpt-5.4')
      * @returns Response with structured_response containing:
      *   - candidates: Validated and scored candidates
@@ -7308,6 +7358,8 @@ declare class ResponsesResource {
         excludeCrmContacts?: boolean;
         crmExclusionOwners?: string[];
         crmNameCompanyMatch?: boolean;
+        salesNavigatorUrl?: string;
+        userId?: string;
         searchProfiles?: boolean | 'auto';
         searchPosts?: boolean | 'auto';
         includeEngagementInScore?: boolean | 'auto';
@@ -7327,6 +7379,7 @@ declare class ResponsesResource {
         deepVerify?: 'off' | 'auto' | 'always';
         deepValidationUseRelevanceReranker?: boolean;
         deepValidationBackfillBelowCriteria?: boolean;
+        enrichEngagementHistory?: boolean;
         deepSearchCriteriaModel?: string;
     }): Promise<CreateResponseResponse>;
     /**
@@ -7403,10 +7456,10 @@ declare class ResponsesResource {
     /**
      * Score people who react to or comment on posts connected to named LinkedIn profiles.
      *
-     * The backend reads posts each seed authored and reacted to within the requested
-     * window, selects posts relevant to the persona prompt, then runs their engagers
-     * through the deep people-search scoring chain. Seed profiles are always excluded
-     * from delivered candidates.
+     * The backend reads posts each seed authored within the requested window and can
+     * optionally include posts they reacted to. It selects posts relevant to the
+     * persona prompt, then runs their engagers through the deep people-search scoring
+     * chain. Seed profiles are always excluded from delivered candidates.
      *
      * @param query - Persona prompt used to select posts and score discovered people.
      * @param options - Seed profiles plus optional window, extraction, and cost controls.

package/dist/index.mjs

@@ -3485,6 +3485,7 @@ class ResponsesResource {
       }
     }
     for (const [camel, snake] of [
+      ["includeReactedPosts", "include_reacted_posts"],
       ["postsEnableFiltering", "posts_enable_filtering"],
       ["thoroughEnrichment", "thorough_enrichment"],
       ["deepValidationUseRelevanceReranker", "deep_validation_use_relevance_reranker"]
@@ -3543,6 +3544,60 @@ class ResponsesResource {
       );
     }
   }
+  _validateSalesNavigatorRequest(request) {
+    const directParams = request.specializedAgentParams;
+    const directUrl = directParams ? this._getParamValue(directParams, "salesNavigatorUrl", "sales_navigator_url") : void 0;
+    const requestOptions = request.options;
+    const nestedParams = requestOptions ? this._getParamValue(
+      requestOptions,
+      "specializedAgentParams",
+      "specialized_agent_params"
+    ) : void 0;
+    const nestedUrl = this._isPlainObject(nestedParams) ? this._getParamValue(nestedParams, "salesNavigatorUrl", "sales_navigator_url") : void 0;
+    const optionsUrl = requestOptions ? this._getParamValue(requestOptions, "salesNavigatorUrl", "sales_navigator_url") : void 0;
+    const salesNavigatorUrl = directUrl ?? nestedUrl ?? optionsUrl;
+    if (salesNavigatorUrl === void 0 || salesNavigatorUrl === null)
+      return;
+    if (typeof salesNavigatorUrl !== "string" || salesNavigatorUrl.length > 8192 || !salesNavigatorUrl.trim()) {
+      throw new ValidationError(
+        "salesNavigatorUrl must be a non-empty string no longer than 8192 characters"
+      );
+    }
+    if ([...salesNavigatorUrl].some((character) => character.charCodeAt(0) < 32) || salesNavigatorUrl.includes("\\")) {
+      throw new ValidationError("salesNavigatorUrl contains unsafe characters");
+    }
+    let parsed;
+    try {
+      parsed = new URL(salesNavigatorUrl);
+    } catch {
+      throw new ValidationError("salesNavigatorUrl is malformed");
+    }
+    const authorityMatch = salesNavigatorUrl.match(/^[a-z][a-z\d+.-]*:\/\/([^/?#]*)/i);
+    const rawAuthority = authorityMatch?.[1];
+    if (parsed.protocol !== "https:")
+      throw new ValidationError("salesNavigatorUrl must use https");
+    if (parsed.hostname !== "www.linkedin.com")
+      throw new ValidationError("salesNavigatorUrl must use www.linkedin.com");
+    if (parsed.username || parsed.password || parsed.port || rawAuthority?.toLowerCase() !== "www.linkedin.com") {
+      throw new ValidationError("salesNavigatorUrl cannot contain credentials or a custom port");
+    }
+    if (parsed.hash)
+      throw new ValidationError("salesNavigatorUrl cannot contain a fragment");
+    const rawSuffix = authorityMatch ? salesNavigatorUrl.slice(authorityMatch[0].length) : "";
+    const rawPath = rawSuffix.split(/[?#]/, 1)[0];
+    if (rawPath === "/sales/search/company") {
+      throw new ValidationError(
+        "Company Sales Navigator searches are not supported yet; use a people search or people list URL"
+      );
+    }
+    if (rawPath !== "/sales/search/people" && !/^\/sales\/lists\/people\/\d+$/.test(rawPath)) {
+      throw new ValidationError(
+        "salesNavigatorUrl must be a Sales Navigator people-search or people-list URL"
+      );
+    }
+    if (typeof request.userId !== "string" || !request.userId.trim())
+      throw new ValidationError("userId is required when salesNavigatorUrl is provided");
+  }
   _validateCriteriaParams(params, specializedAgent) {
     if (!params)
       return;
@@ -3705,6 +3760,7 @@ class ResponsesResource {
       for (const file of request.files)
         this._validateFileReference(file.uri);
     }
+    this._validateSalesNavigatorRequest(request);
     if (request.specializedAgentParams)
       this._validateCriteriaParams(request.specializedAgentParams, request.specializedAgent);
     return this.http.post("/responses", request);
@@ -3840,10 +3896,13 @@ class ResponsesResource {
    * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true
    * @param options.crmExclusionOwners - Granted owner ledgers to exclude against (user id or email)
    * @param options.crmNameCompanyMatch - Also exclude by exact name+company; @default true
+   * @param options.salesNavigatorUrl - Sales Navigator people-search or people-list URL to use as the only discovery source
+   * @param options.userId - Acting user whose owned Sales Navigator connection should be used; required with `salesNavigatorUrl`
    * @param options.searchJobSignal - CrustData job-listing signal search (decision makers at hiring companies); true | false | 'auto'
    * @param options.deepVerify - Web verification for org/location/third-party criteria: 'auto' (default), 'always', or 'off'
    * @param options.deepValidationUseRelevanceReranker - SLM relevance reranker for surfaced candidates (ranking-only); @default true
    * @param options.deepValidationBackfillBelowCriteria - Pad with criteria-failed candidates when under count; @default true
+   * @param options.enrichEngagementHistory - Add recent LinkedIn engagement evidence before validation; forced off for Sales Navigator V1
    * @param options.deepSearchCriteriaModel - Override criteria decomposition model (e.g. 'openai:gpt-5.4')
    * @returns Response with structured_response containing:
    *   - candidates: Validated and scored candidates
@@ -3855,6 +3914,8 @@ class ResponsesResource {
       messages: [{ role: "user", content: query }],
       specializedAgent: "deep_people_search"
     };
+    if (options?.userId !== void 0)
+      request.userId = options.userId;
     const params = {
       deepValidationUseRelevanceReranker: options?.deepValidationUseRelevanceReranker ?? true,
       deepValidationBackfillBelowCriteria: options?.deepValidationBackfillBelowCriteria ?? true
@@ -3888,6 +3949,8 @@ class ResponsesResource {
         params.crmExclusionOwners = options.crmExclusionOwners;
       if (options.crmNameCompanyMatch !== void 0)
         params.crmNameCompanyMatch = options.crmNameCompanyMatch;
+      if (options.salesNavigatorUrl !== void 0)
+        params.salesNavigatorUrl = options.salesNavigatorUrl;
       if (options.searchProfiles !== void 0)
         params.searchProfiles = options.searchProfiles;
       if (options.searchPosts !== void 0)
@@ -3922,8 +3985,22 @@ class ResponsesResource {
         params.searchJobSignal = options.searchJobSignal;
       if (options.deepVerify !== void 0)
         params.deepVerify = options.deepVerify;
+      if (options.enrichEngagementHistory !== void 0)
+        params.enrichEngagementHistory = options.enrichEngagementHistory;
       if (options.deepSearchCriteriaModel)
         params.deepSearchCriteriaModel = options.deepSearchCriteriaModel;
+      if (options.salesNavigatorUrl !== void 0) {
+        params.searchProfiles = false;
+        params.searchPosts = false;
+        params.searchConnections = false;
+        params.searchJobSignal = false;
+        params.includeEngagementInScore = false;
+        params.postsEnableEnrichment = false;
+        params.postsEnableFiltering = false;
+        params.deepValidationUseRelevanceReranker = false;
+        params.deepValidationBackfillBelowCriteria = false;
+        params.enrichEngagementHistory = false;
+      }
     }
     request.specializedAgentParams = params;
     return this.create(request);
@@ -4063,10 +4140,10 @@ class ResponsesResource {
   /**
    * Score people who react to or comment on posts connected to named LinkedIn profiles.
    *
-   * The backend reads posts each seed authored and reacted to within the requested
-   * window, selects posts relevant to the persona prompt, then runs their engagers
-   * through the deep people-search scoring chain. Seed profiles are always excluded
-   * from delivered candidates.
+   * The backend reads posts each seed authored within the requested window and can
+   * optionally include posts they reacted to. It selects posts relevant to the
+   * persona prompt, then runs their engagers through the deep people-search scoring
+   * chain. Seed profiles are always excluded from delivered candidates.
    *
    * @param query - Persona prompt used to select posts and score discovered people.
    * @param options - Seed profiles plus optional window, extraction, and cost controls.
@@ -4079,6 +4156,8 @@ class ResponsesResource {
     const params = {
       seedProfiles: options.seedProfiles
     };
+    if (options.includeReactedPosts !== void 0)
+      params.includeReactedPosts = options.includeReactedPosts;
     if (options.postsDateRange !== void 0)
       params.postsDateRange = options.postsDateRange;
     if (options.engagementTypes !== void 0)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lumnisai",
   "type": "module",
-  "version": "0.5.40",
+  "version": "0.5.41",
   "description": "Official Node.js SDK for the Lumnis AI API",
   "author": "Lumnis AI",
   "license": "MIT",