lumnisai 0.5.44 → 0.5.46

package/dist/index.cjs

@@ -3225,6 +3225,34 @@ class PeopleResource {
   }
 }
 
+const DATE_RANGES = [
+  "past-24h",
+  "past-week",
+  "past-2-weeks",
+  "past-3-weeks",
+  "past-month",
+  "past-quarter",
+  "past-6-months",
+  "past-year",
+  "past-2-years",
+  "past-3-years"
+];
+const SIGNAL_TYPES = [
+  "hiring",
+  "engagement",
+  "recently_joined",
+  "funding",
+  "events"
+];
+const DISABLED_SIGNAL_TYPES = ["competitor_tools", "web_traffic"];
+const ENGAGEMENT_ACTIVITIES = [
+  "reactions",
+  "comments",
+  "authored_posts"
+];
+const MAX_SIGNAL_CONTEXT_CHARS = 4e3;
+const MAX_CONTENT_INTELLIGENCE_COMPETITORS = 5;
+const MAX_CONTENT_INTELLIGENCE_COMPETITOR_CHARS = 200;
 class ResponsesResource {
   constructor(http) {
     this.http = http;
@@ -3372,6 +3400,166 @@ class ResponsesResource {
       throw new ValidationError("maxCommentsPerPost must be between 1 and 100");
     }
   }
+  _validateDateRange(value, field) {
+    if (value === void 0 || value === null)
+      return;
+    if (typeof value !== "string" || !DATE_RANGES.includes(value)) {
+      throw new ValidationError(
+        `Invalid ${field} value: ${String(value)}. Choose from: ${DATE_RANGES.join(", ")}.`
+      );
+    }
+  }
+  /** Company targets are compared the way the backend compares them: trimmed, case-folded, no trailing slash. */
+  _targetCompanyKey(value) {
+    return value.trim().toLowerCase().replace(/\/+$/, "");
+  }
+  _validateEngagementSettings(settings) {
+    const activities = this._getParamValue(settings, "activities", "activities");
+    if (activities !== void 0 && activities !== null) {
+      if (!Array.isArray(activities) || activities.length === 0)
+        throw new ValidationError("engagement settings.activities cannot be empty");
+      for (const activity of activities) {
+        if (typeof activity !== "string" || !ENGAGEMENT_ACTIVITIES.includes(activity)) {
+          throw new ValidationError(
+            `Invalid engagement activity: ${String(activity)}. Choose from: ${ENGAGEMENT_ACTIVITIES.join(", ")}.`
+          );
+        }
+      }
+      if (new Set(activities).size !== activities.length)
+        throw new ValidationError("engagement settings.activities must not contain duplicates");
+    }
+    const targetCompanies = this._getParamValue(
+      settings,
+      "targetCompanies",
+      "target_companies"
+    );
+    if (targetCompanies !== void 0 && targetCompanies !== null) {
+      if (!Array.isArray(targetCompanies) || targetCompanies.length === 0 || targetCompanies.some((company) => typeof company !== "string" || !company.trim())) {
+        throw new ValidationError(
+          "engagement settings.targetCompanies must contain at least one non-empty company name, domain, or LinkedIn company URL"
+        );
+      }
+      const keys = targetCompanies.map((company) => this._targetCompanyKey(company));
+      if (new Set(keys).size !== keys.length)
+        throw new ValidationError("engagement settings.targetCompanies must not contain duplicates");
+    }
+  }
+  _validateSignalSettings(name, settings) {
+    if (settings === void 0 || settings === null)
+      return;
+    if (!this._isPlainObject(settings))
+      throw new ValidationError(`signalDefinitions '${name}' settings must be an object`);
+    const allowed = name === "engagement" ? ["dateRange", "date_range", "activities", "targetCompanies", "target_companies"] : ["dateRange", "date_range"];
+    for (const key of Object.keys(settings)) {
+      if (!allowed.includes(key)) {
+        throw new ValidationError(
+          `Unknown setting '${key}' for the '${name}' signal. Supported settings: ${allowed.filter((setting) => !setting.includes("_")).join(", ")}.`
+        );
+      }
+    }
+    this._validateDateRange(
+      this._getParamValue(settings, "dateRange", "date_range"),
+      `signalDefinitions '${name}' settings.dateRange`
+    );
+    if (name === "engagement")
+      this._validateEngagementSettings(settings);
+  }
+  /**
+   * Validate the one manual signal-enrichment input before anything paid runs.
+   * Mirrors the backend registry: object entries only, known enabled names, no
+   * duplicates, no unknown settings.
+   */
+  _validateSignalDefinitions(value) {
+    if (value === void 0 || value === null)
+      return;
+    if (!Array.isArray(value))
+      throw new ValidationError("signalDefinitions must be an array");
+    const seen = /* @__PURE__ */ new Set();
+    for (const entry of value) {
+      if (!this._isPlainObject(entry)) {
+        throw new ValidationError(
+          `Each signalDefinitions entry must be an object like { name: 'hiring', settings: { dateRange: 'past-month' } }`
+        );
+      }
+      const rawName = this._getParamValue(entry, "name", "name");
+      const name = typeof rawName === "string" ? rawName.trim().toLowerCase() : rawName;
+      if (typeof name !== "string" || !name)
+        throw new ValidationError("Each signalDefinitions entry requires a signal name");
+      if (DISABLED_SIGNAL_TYPES.includes(name)) {
+        throw new ValidationError(
+          `The '${name}' signal is temporarily disabled because of company-record cost. Choose from the enabled signals: ${SIGNAL_TYPES.join(", ")}.`
+        );
+      }
+      if (!SIGNAL_TYPES.includes(name)) {
+        throw new ValidationError(
+          `'${name}' is not a signal we know. Choose from: ${SIGNAL_TYPES.join(", ")}.`
+        );
+      }
+      if (seen.has(name)) {
+        throw new ValidationError(
+          `The '${name}' signal appears more than once in signalDefinitions \u2014 send each signal once.`
+        );
+      }
+      seen.add(name);
+      for (const key of Object.keys(entry)) {
+        if (key !== "name" && key !== "settings" && key !== "context") {
+          throw new ValidationError(
+            `Unknown signalDefinitions field '${key}'. Each entry accepts only name, settings, and context.`
+          );
+        }
+      }
+      this._validateContextBrief(
+        this._getParamValue(entry, "context", "context"),
+        `signalDefinitions '${name}' context`
+      );
+      this._validateSignalSettings(
+        name,
+        this._getParamValue(entry, "settings", "settings")
+      );
+    }
+  }
+  /**
+   * Validate the signal-enrichment, automatic-selection and intent-scoring
+   * params. These apply to every people agent, so they are checked on the
+   * request rather than per agent.
+   */
+  _validateSignalParams(params) {
+    this._validateSignalDefinitions(
+      this._getParamValue(params, "signalDefinitions", "signal_definitions")
+    );
+    for (const [camel, snake] of [
+      ["autoSelectLane", "auto_select_lane"],
+      ["autoSelectSignals", "auto_select_signals"]
+    ]) {
+      const value = this._getParamValue(params, camel, snake);
+      if (value !== void 0 && value !== null && typeof value !== "boolean")
+        throw new ValidationError(`${camel} must be true or false`);
+    }
+    const intentScoringInstructions = this._getParamValue(
+      params,
+      "intentScoringInstructions",
+      "intent_scoring_instructions"
+    );
+    if (intentScoringInstructions !== void 0 && intentScoringInstructions !== null && typeof intentScoringInstructions !== "string") {
+      throw new ValidationError("intentScoringInstructions must be a string");
+    }
+    this._validateDateRange(
+      this._getParamValue(params, "jobSignalDateRange", "job_signal_date_range"),
+      "jobSignalDateRange"
+    );
+    this._validateDateRange(
+      this._getParamValue(params, "postsDateRange", "posts_date_range"),
+      "postsDateRange"
+    );
+  }
+  _validateContextBrief(value, field) {
+    if (value === void 0 || value === null)
+      return;
+    if (typeof value !== "string")
+      throw new ValidationError(`${field} must be plain text`);
+    if ([...value.trim()].length > MAX_SIGNAL_CONTEXT_CHARS)
+      throw new ValidationError(`${field} must be at most ${MAX_SIGNAL_CONTEXT_CHARS} characters`);
+  }
   _validateCompetitorRepEngagementParams(params) {
     const company = this._getParamValue(params, "company", "company");
     const competitors = this._getParamValue(params, "competitors", "competitors");
@@ -3454,6 +3642,91 @@ class ResponsesResource {
         }
       }
     }
+    const rawCompetitors = this._getParamValue(params, "competitors", "competitors");
+    const competitors = this._normalizedContentIntelligenceCompetitors(rawCompetitors);
+    if (competitors.length > MAX_CONTENT_INTELLIGENCE_COMPETITORS) {
+      throw new ValidationError(
+        `competitors must contain at most ${MAX_CONTENT_INTELLIGENCE_COMPETITORS} distinct values`
+      );
+    }
+    const rawCompany = this._getParamValue(params, "company", "company");
+    let company;
+    if (rawCompany !== void 0 && rawCompany !== null) {
+      if (typeof rawCompany !== "string")
+        throw new ValidationError("company must be a string for content_intelligence");
+      company = rawCompany.trim() || void 0;
+      if (company && [...company].length > MAX_CONTENT_INTELLIGENCE_COMPETITOR_CHARS) {
+        throw new ValidationError(
+          `company must be at most ${MAX_CONTENT_INTELLIGENCE_COMPETITOR_CHARS} characters`
+        );
+      }
+    }
+    const normalizedCompany = company?.toLowerCase();
+    if (normalizedCompany && competitors.some((competitor) => competitor.toLowerCase() === normalizedCompany)) {
+      throw new ValidationError(
+        `company '${company}' is also listed in competitors; name it on one side only`
+      );
+    }
+    for (const [camel, snake] of [
+      ["includeCompanyPosts", "include_company_posts"],
+      ["includeExecPosts", "include_exec_posts"]
+    ]) {
+      const value = this._getParamValue(params, camel, snake);
+      if (value !== void 0 && typeof value !== "boolean")
+        throw new ValidationError(`${camel} must be true or false`);
+    }
+    const includeCompanyPosts = this._getParamValue(
+      params,
+      "includeCompanyPosts",
+      "include_company_posts"
+    );
+    const includeExecPosts = this._getParamValue(
+      params,
+      "includeExecPosts",
+      "include_exec_posts"
+    );
+    if (competitors.length > 0 && includeCompanyPosts === false && includeExecPosts === false) {
+      throw new ValidationError(
+        "competitors were provided but includeCompanyPosts and includeExecPosts are both false"
+      );
+    }
+    const execTitles = this._getParamValue(params, "execTitles", "exec_titles");
+    if (execTitles !== void 0 && (!Array.isArray(execTitles) || execTitles.some((title) => typeof title !== "string"))) {
+      throw new ValidationError("execTitles must be an array of strings");
+    }
+    const maxExecsPerTarget = this._getParamValue(
+      params,
+      "maxExecsPerTarget",
+      "max_execs_per_target"
+    );
+    if (maxExecsPerTarget !== void 0 && (!Number.isInteger(maxExecsPerTarget) || maxExecsPerTarget < 1 || maxExecsPerTarget > 20)) {
+      throw new ValidationError("maxExecsPerTarget must be an integer between 1 and 20");
+    }
+  }
+  _normalizedContentIntelligenceCompetitors(value) {
+    if (value === void 0 || value === null)
+      return [];
+    const values = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(values) || values.some((entry) => typeof entry !== "string"))
+      throw new ValidationError("competitors must be an array of strings");
+    const seen = /* @__PURE__ */ new Set();
+    const normalized = [];
+    for (const entry of values) {
+      const competitor = entry.trim();
+      if (!competitor)
+        continue;
+      if ([...competitor].length > MAX_CONTENT_INTELLIGENCE_COMPETITOR_CHARS) {
+        throw new ValidationError(
+          `each competitor must be at most ${MAX_CONTENT_INTELLIGENCE_COMPETITOR_CHARS} characters`
+        );
+      }
+      const key = competitor.toLowerCase();
+      if (!seen.has(key)) {
+        seen.add(key);
+        normalized.push(competitor);
+      }
+    }
+    return normalized;
   }
   _validateEngagementExpansionParams(params) {
     const expandFromResponse = this._getParamValue(
@@ -3505,25 +3778,10 @@ class ResponsesResource {
         }
       }
     }
-    const postsDateRange = this._getParamValue(
-      params,
-      "postsDateRange",
-      "posts_date_range"
-    );
-    if (postsDateRange !== void 0) {
-      const validRanges = [
-        "past-24h",
-        "past-week",
-        "past-month",
-        "past-quarter",
-        "past-6-months",
-        "past-year",
-        "past-2-years",
-        "past-3-years"
-      ];
-      if (!validRanges.includes(postsDateRange))
-        throw new ValidationError(`Invalid postsDateRange value: ${String(postsDateRange)}`);
-    }
+    this._validateDateRange(
+      this._getParamValue(params, "postsDateRange", "posts_date_range"),
+      "postsDateRange"
+    );
     for (const [camel, snake, maximum] of [
       ["limit", "limit", 1e3],
       ["maxReactorsPerPost", "max_reactors_per_post", 5e3],
@@ -3596,6 +3854,25 @@ class ResponsesResource {
       );
     }
   }
+  /**
+   * Every place a caller may put specialized-agent params: the dedicated field
+   * and the legacy nested copy inside `options`. Both are validated so a nested
+   * request cannot smuggle an unknown signal past the SDK.
+   */
+  _specializedParamSources(request) {
+    const sources = [];
+    if (this._isPlainObject(request.specializedAgentParams))
+      sources.push(request.specializedAgentParams);
+    const requestOptions = request.options;
+    const nested = requestOptions ? this._getParamValue(
+      requestOptions,
+      "specializedAgentParams",
+      "specialized_agent_params"
+    ) : void 0;
+    if (this._isPlainObject(nested))
+      sources.push(nested);
+    return sources;
+  }
   _validateSalesNavigatorRequest(request) {
     const directParams = request.specializedAgentParams;
     const directUrl = directParams ? this._getParamValue(directParams, "salesNavigatorUrl", "sales_navigator_url") : void 0;
@@ -3647,6 +3924,11 @@ class ResponsesResource {
         "salesNavigatorUrl must be a Sales Navigator people-search or people-list URL"
       );
     }
+    const autoSelectLane = this._specializedParamSources(request).some(
+      (params) => this._getParamValue(params, "autoSelectLane", "auto_select_lane") === true
+    );
+    if (autoSelectLane)
+      return;
     if (typeof request.userId !== "string" || !request.userId.trim())
       throw new ValidationError("userId is required when salesNavigatorUrl is provided");
   }
@@ -3813,6 +4095,8 @@ class ResponsesResource {
         this._validateFileReference(file.uri);
     }
     this._validateSalesNavigatorRequest(request);
+    for (const params of this._specializedParamSources(request))
+      this._validateSignalParams(params);
     if (request.specializedAgentParams)
       this._validateCriteriaParams(request.specializedAgentParams, request.specializedAgent);
     return this.http.post("/responses", request);
@@ -3956,10 +4240,16 @@ class ResponsesResource {
    * @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')
+   * @param options.jobSignalDateRange - Posting window for the standalone job-signal lane; omit for the planner's 90-365 days
+   * @param options.signalDefinitions - Signal enrichments to run on fast-filter survivors before validation; omit or `[]` for none
+   * @param options.autoSelectLane - Let the backend choose the discovery lane; ignores the manual lane controls; @default false
+   * @param options.autoSelectSignals - Let the backend choose the signals; ignores `signalDefinitions`; @default false
+   * @param options.intentScoringInstructions - Plain-English direction for every intent-scoring stage (never changes fit or filtering)
    * @returns Response with structured_response containing:
-   *   - candidates: Validated and scored candidates
+   *   - candidates: Validated and scored candidates, each with `signalEvidence` for the selected signals
    *   - criteria: Generated/reused criteria definitions and classification
-   *   - searchStats: Search execution statistics
+   *   - searchStats: Search execution statistics, including `enrichment` and `signalFunnel`
+   *   - autoSearchSelection: What automatic selection applied, when either auto flag ran
    */
   async deepPeopleSearch(query, options) {
     const request = {
@@ -4041,7 +4331,17 @@ class ResponsesResource {
         params.enrichEngagementHistory = options.enrichEngagementHistory;
       if (options.deepSearchCriteriaModel)
         params.deepSearchCriteriaModel = options.deepSearchCriteriaModel;
-      if (options.salesNavigatorUrl !== void 0) {
+      if (options.jobSignalDateRange !== void 0)
+        params.jobSignalDateRange = options.jobSignalDateRange;
+      if (options.signalDefinitions !== void 0)
+        params.signalDefinitions = options.signalDefinitions;
+      if (options.autoSelectLane !== void 0)
+        params.autoSelectLane = options.autoSelectLane;
+      if (options.autoSelectSignals !== void 0)
+        params.autoSelectSignals = options.autoSelectSignals;
+      if (options.intentScoringInstructions !== void 0)
+        params.intentScoringInstructions = options.intentScoringInstructions;
+      if (options.salesNavigatorUrl !== void 0 && options.autoSelectLane !== true) {
         params.searchProfiles = false;
         params.searchPosts = false;
         params.searchConnections = false;
@@ -4104,6 +4404,8 @@ class ResponsesResource {
         request.specializedAgentParams.addAndRunCriterion = options.addAndRunCriterion;
       if (options.deepSearchCriteriaModel)
         request.specializedAgentParams.deepSearchCriteriaModel = options.deepSearchCriteriaModel;
+      if (options.intentScoringInstructions !== void 0)
+        request.specializedAgentParams.intentScoringInstructions = options.intentScoringInstructions;
     }
     return this.create(request);
   }
@@ -4115,6 +4417,10 @@ class ResponsesResource {
    * `reusePackageFrom` to re-cook a saved package without collecting again.
    * `companyContext` and `contentDirection` steer post ideas only; collection,
    * curation, and engagement analysis remain an unbiased read of the audience.
+   * Add `competitors` to receive a separate publication report over the same
+   * window; competitor posts never enter the audience package or metrics. Add
+   * `company` to put the caller's own publication activity beside those
+   * competitors in the report.
    *
    * @param query - Natural-language description of the audience. A nonblank
    *   message is required even when reusing a package.
@@ -4141,6 +4447,18 @@ class ResponsesResource {
       params.reusePackageFrom = options.reusePackageFrom;
     if (options.outputs !== void 0)
       params.outputs = options.outputs;
+    if (options.competitors !== void 0)
+      params.competitors = options.competitors;
+    if (options.company !== void 0)
+      params.company = options.company;
+    if (options.includeCompanyPosts !== void 0)
+      params.includeCompanyPosts = options.includeCompanyPosts;
+    if (options.includeExecPosts !== void 0)
+      params.includeExecPosts = options.includeExecPosts;
+    if (options.execTitles !== void 0)
+      params.execTitles = options.execTitles;
+    if (options.maxExecsPerTarget !== void 0)
+      params.maxExecsPerTarget = options.maxExecsPerTarget;
     return this.create({
       messages: [{ role: "user", content: query }],
       specializedAgent: "content_intelligence",
@@ -4183,6 +4501,10 @@ class ResponsesResource {
     if (options?.deepValidationUseRelevanceReranker !== void 0) {
       params.deepValidationUseRelevanceReranker = options.deepValidationUseRelevanceReranker;
     }
+    if (options.signalDefinitions !== void 0)
+      params.signalDefinitions = options.signalDefinitions;
+    if (options.intentScoringInstructions !== void 0)
+      params.intentScoringInstructions = options.intentScoringInstructions;
     return this.create({
       messages: [{ role: "user", content: query }],
       specializedAgent: "engagement_expansion",
@@ -4229,6 +4551,10 @@ class ResponsesResource {
       params.excludeUrls = options.excludeUrls;
     if (options.limit !== void 0)
       params.limit = options.limit;
+    if (options.signalDefinitions !== void 0)
+      params.signalDefinitions = options.signalDefinitions;
+    if (options.intentScoringInstructions !== void 0)
+      params.intentScoringInstructions = options.intentScoringInstructions;
     return this.create({
       messages: [{ role: "user", content: query }],
       specializedAgent: "influencer_engagement",
@@ -4300,6 +4626,10 @@ class ResponsesResource {
       params.maxReactorsPerPost = options.maxReactorsPerPost;
     if (options.maxCommentsPerPost !== void 0)
       params.maxCommentsPerPost = options.maxCommentsPerPost;
+    if (options.signalDefinitions !== void 0)
+      params.signalDefinitions = options.signalDefinitions;
+    if (options.intentScoringInstructions !== void 0)
+      params.intentScoringInstructions = options.intentScoringInstructions;
     request.specializedAgentParams = params;
     return this.create(request);
   }
@@ -4366,6 +4696,10 @@ class ResponsesResource {
       params.maxCompetitors = options.maxCompetitors;
     if (options.thoroughEnrichment !== void 0)
       params.thoroughEnrichment = options.thoroughEnrichment;
+    if (options.signalDefinitions !== void 0)
+      params.signalDefinitions = options.signalDefinitions;
+    if (options.intentScoringInstructions !== void 0)
+      params.intentScoringInstructions = options.intentScoringInstructions;
     request.specializedAgentParams = params;
     return this.create(request);
   }