lumnisai 0.5.48 → 0.5.50

package/dist/index.cjs

@@ -1091,14 +1091,18 @@ class CrmResource {
     });
   }
   /**
-   * Grant a member the right to exclude against an owner's synced CRM ledger
-   * (all providers for that owner). Typically called by the FE on org join.
+   * Grant a member access to an owner's CRM — every provider that owner has
+   * synced. One grant serves both reads that name another owner: ledger
+   * exclusion in search and campaigns, and `account_monitor`'s `crmUserId`.
+   * Both users must be in the authenticated tenant; a self-grant is a no-op.
+   * Typically called by the FE on org join.
    */
   async grantExclusionGrant(data) {
     return this.http.post("/crm/exclusion-grants", data);
   }
   /**
-   * Revoke a member's access to an owner's CRM exclusion ledger.
+   * Revoke a member's access to an owner's CRM. Implicit access to their own
+   * CRM cannot be revoked.
    */
   async revokeExclusionGrant(data) {
     return this.http.delete("/crm/exclusion-grants", {
@@ -1106,7 +1110,8 @@ class CrmResource {
     });
   }
   /**
-   * List CRM owners whose exclusion ledger a member may read (via grants).
+   * List the CRM owners a member may read via grants. The member's own CRM is
+   * implicit and is not listed.
    */
   async listExclusionGrants(memberUserId) {
     return this.http.get("/crm/exclusion-grants", {
@@ -1938,7 +1943,12 @@ const PASSTHROUGH_VALUE_KEYS = /* @__PURE__ */ new Set([
   "customFields",
   "custom_fields",
   "engagementProfile",
-  "engagement_profile"
+  "engagement_profile",
+  // account_monitor's committee: its own fields (`people`, `groups`) are
+  // spelled the same in both cases, while the group labels underneath
+  // `groups` are caller-chosen names such as 'Security team'. Converting
+  // those would rename the customer's own groups.
+  "committee"
 ]);
 function convertCase(obj, converter) {
   if (Array.isArray(obj)) {
@@ -3256,6 +3266,39 @@ const ENGAGEMENT_ACTIVITIES = [
   "comments",
   "authored_posts"
 ];
+const ACCOUNT_MONITOR_SIGNALS = [
+  "company_hiring",
+  "company_news",
+  "company_funding",
+  "company_posts",
+  "company_mention",
+  "company_background",
+  "committee_activity",
+  "committee_to_competitor",
+  "competitor_to_committee",
+  "committee_to_our_company",
+  "account_to_our_company"
+];
+const RETIRED_ACCOUNT_MONITOR_SIGNALS = [
+  "incoming_engagement",
+  "our_company_to_committee",
+  "our_company_to_account"
+];
+const ACCOUNT_MONITOR_FIELDS = [
+  ["account", "account"],
+  ["depth", "depth"],
+  ["committee", "committee"],
+  ["competitors", "competitors"],
+  ["ourCompany", "our_company"],
+  ["days", "days"],
+  ["window", "window"],
+  ["signalDefinitions", "signal_definitions"],
+  ["intentScoringInstructions", "intent_scoring_instructions"],
+  ["history", "history"],
+  ["crmUserId", "crm_user_id"],
+  ["tier", "tier"]
+];
+const ACCOUNT_MONITOR_FIELD_KEYS = new Set(ACCOUNT_MONITOR_FIELDS.flat());
 const MAX_SIGNAL_CONTEXT_CHARS = 4e3;
 const MAX_CONTENT_INTELLIGENCE_COMPETITORS = 5;
 const MAX_CONTENT_INTELLIGENCE_COMPETITOR_CHARS = 200;
@@ -3874,6 +3917,251 @@ class ResponsesResource {
       );
     }
   }
+  /**
+   * Validate one merged `account_monitor` request.
+   *
+   * The monitor's parameters are a CLOSED shape server-side, so unknown keys
+   * are rejected here with the offending name rather than failing after the
+   * request is sent. Everything else mirrors the backend's own rules: an
+   * account that identity resolution can actually resolve, one period (days
+   * OR window, never both), and explicit people/title scopes.
+   */
+  _validateAccountMonitorParams(params) {
+    const account = params.account;
+    if (typeof account !== "string" || !account.trim()) {
+      throw new ValidationError(
+        "`account` is required for account_monitor \u2014 give the monitored company's domain, website, or LinkedIn company URL. A bare company name cannot be resolved."
+      );
+    }
+    const depth = params.depth;
+    if (depth !== void 0 && depth !== "light" && depth !== "deep")
+      throw new ValidationError(`depth must be 'light' or 'deep' for account_monitor`);
+    const days = params.days;
+    if (days !== void 0 && (!Number.isInteger(days) || days < 1))
+      throw new ValidationError("days must be a positive integer for account_monitor");
+    const window = params.window;
+    if (window !== void 0) {
+      if (days !== void 0)
+        throw new ValidationError("Supply days or window for account_monitor, not both");
+      if (!this._isPlainObject(window)) {
+        throw new ValidationError(
+          "window must be an object with startAt and endAt timestamps for account_monitor"
+        );
+      }
+      for (const [camel, snake] of [["startAt", "start_at"], ["endAt", "end_at"]]) {
+        const value = this._getParamValue(window, camel, snake);
+        if (typeof value !== "string" || !value.trim()) {
+          throw new ValidationError(
+            `window.${camel} must be a timezone-aware ISO 8601 timestamp for account_monitor`
+          );
+        }
+      }
+    }
+    this._validateAccountMonitorCommittee(params.committee);
+    const competitors = params.competitors;
+    if (competitors !== void 0) {
+      if (!Array.isArray(competitors))
+        throw new ValidationError("competitors must be an array for account_monitor");
+      competitors.forEach((competitor, index) => this._validateAccountMonitorCompany(competitor, `competitors[${index}]`));
+    }
+    if (params.ourCompany !== void 0)
+      this._validateAccountMonitorCompany(params.ourCompany, "ourCompany");
+    const history = params.history;
+    if (history !== void 0 && typeof history !== "string" && !this._isPlainObject(history)) {
+      throw new ValidationError(
+        "history must be an object or a string for account_monitor \u2014 the run compares against what you supply here, it never looks a previous response up."
+      );
+    }
+    const tier = params.tier;
+    if (tier !== void 0 && typeof tier !== "string")
+      throw new ValidationError("tier must be a string for account_monitor");
+    const instructions = params.intentScoringInstructions;
+    if (instructions !== void 0 && typeof instructions !== "string")
+      throw new ValidationError("intentScoringInstructions must be a string");
+    this._validateAccountMonitorSignalDefinitions(params.signalDefinitions);
+  }
+  /**
+   * `crmUserId` reads one tenant member's CRM, so the request has to name the
+   * requester too: the backend refuses the pair without a top-level `userId`,
+   * and reading anyone else's CRM also needs a CRM access grant
+   * (`client.crm.grantExclusionGrant`). Reading your own is always allowed.
+   */
+  _validateAccountMonitorCrmAccess(params, request) {
+    const crmUserId = params.crmUserId;
+    if (crmUserId === void 0)
+      return;
+    if (typeof crmUserId !== "string" || !crmUserId.trim() || crmUserId.length > 255) {
+      throw new ValidationError(
+        "crmUserId must be the UUID or email of a CRM owner in the authenticated tenant (1-255 characters) for account_monitor"
+      );
+    }
+    if (typeof request.userId !== "string" || !request.userId.trim())
+      throw new ValidationError("userId is required when crmUserId is provided");
+  }
+  /** People are LinkedIn profile URLs; no employee discovery is ever implied. */
+  _validateAccountMonitorProfiles(value, field) {
+    if (!Array.isArray(value) || value.some((url) => typeof url !== "string" || !url.trim())) {
+      throw new ValidationError(
+        `${field} must be an array of LinkedIn profile URLs for account_monitor`
+      );
+    }
+  }
+  /**
+   * The committee accepts the full `{ people, groups }` object, a bare URL
+   * array, or a legacy label-to-URLs map. A map that carries `people` or
+   * `groups` is read as the full object, exactly as the backend reads it.
+   */
+  _validateAccountMonitorCommittee(committee) {
+    if (committee === void 0)
+      return;
+    if (Array.isArray(committee)) {
+      this._validateAccountMonitorProfiles(committee, "committee");
+      return;
+    }
+    if (!this._isPlainObject(committee)) {
+      throw new ValidationError(
+        "committee must be an object with people and/or groups, an array of LinkedIn profile URLs, or a map of group name to URLs"
+      );
+    }
+    const hasPeople = Object.prototype.hasOwnProperty.call(committee, "people");
+    const hasGroups = Object.prototype.hasOwnProperty.call(committee, "groups");
+    if (!hasPeople && !hasGroups) {
+      this._validateAccountMonitorGroups(committee, "committee");
+      return;
+    }
+    if (hasPeople)
+      this._validateAccountMonitorProfiles(committee.people, "committee.people");
+    if (hasGroups) {
+      if (!this._isPlainObject(committee.groups))
+        throw new ValidationError("committee.groups must map each group name to LinkedIn profile URLs");
+      this._validateAccountMonitorGroups(committee.groups, "committee.groups");
+    }
+  }
+  _validateAccountMonitorGroups(groups, field) {
+    for (const [label, people] of Object.entries(groups)) {
+      if (!label.trim())
+        throw new ValidationError(`${field} group names must not be blank`);
+      this._validateAccountMonitorProfiles(people, `${field}['${label}']`);
+    }
+  }
+  /**
+   * A company string means the company page only. People and titles are the
+   * only ways to reach employees — neither is implied by the company itself.
+   */
+  _validateAccountMonitorCompany(value, field) {
+    if (typeof value === "string") {
+      if (!value.trim())
+        throw new ValidationError(`${field} must be a non-empty company domain, URL, or name`);
+      return;
+    }
+    if (!this._isPlainObject(value)) {
+      throw new ValidationError(
+        `${field} must be a company string, or an object with company and an explicit people or employeeTitles scope`
+      );
+    }
+    for (const key of Object.keys(value)) {
+      if (!["company", "people", "employeeTitles", "employee_titles"].includes(key)) {
+        throw new ValidationError(
+          `Unknown ${field} field '${key}'. A company accepts only company, people, and employeeTitles.`
+        );
+      }
+    }
+    const company = this._getParamValue(value, "company", "company");
+    if (typeof company !== "string" || !company.trim())
+      throw new ValidationError(`${field}.company is required and must be a non-empty string`);
+    const people = this._getParamValue(value, "people", "people");
+    if (people !== void 0)
+      this._validateAccountMonitorProfiles(people, `${field}.people`);
+    const employeeTitles = this._getParamValue(value, "employeeTitles", "employee_titles");
+    if (employeeTitles !== void 0 && employeeTitles !== null) {
+      if (!Array.isArray(employeeTitles) || employeeTitles.length === 0 || employeeTitles.some((title) => typeof title !== "string" || !title.trim())) {
+        throw new ValidationError(
+          `${field}.employeeTitles must contain at least one non-blank current-title filter. Omit it to skip employee discovery entirely.`
+        );
+      }
+    }
+  }
+  _validateAccountMonitorSignalDefinitions(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 account_monitor signalDefinitions entry must be an object like { name: 'company_hiring' }`
+        );
+      }
+      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 (RETIRED_ACCOUNT_MONITOR_SIGNALS.includes(name)) {
+        throw new ValidationError(
+          `The '${name}' monitor check was retired and can no longer be requested. Choose from: ${ACCOUNT_MONITOR_SIGNALS.join(", ")}.`
+        );
+      }
+      if (!ACCOUNT_MONITOR_SIGNALS.includes(name)) {
+        throw new ValidationError(
+          `'${name}' is not an account_monitor signal. Choose from: ${ACCOUNT_MONITOR_SIGNALS.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") {
+          throw new ValidationError(
+            `Unknown signalDefinitions field '${key}'. An account_monitor entry accepts only name.`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Merge the monitor request the way the backend does: flat `options` fields
+   * first, then the nested params copy, then the dedicated field. A null never
+   * overwrites a value that an earlier source already supplied.
+   *
+   * Only known monitor fields are read out of flat `options`, because general
+   * platform options live there too. The dedicated and nested parameter
+   * objects are strict, so their unknown fields are reported instead.
+   */
+  _accountMonitorParams(request) {
+    const requestOptions = this._isPlainObject(request.options) ? request.options : {};
+    const nested = this._getParamValue(
+      requestOptions,
+      "specializedAgentParams",
+      "specialized_agent_params"
+    );
+    const strict = [];
+    if (this._isPlainObject(nested))
+      strict.push(nested);
+    if (this._isPlainObject(request.specializedAgentParams))
+      strict.push(request.specializedAgentParams);
+    for (const source of strict) {
+      for (const key of Object.keys(source)) {
+        if (!ACCOUNT_MONITOR_FIELD_KEYS.has(key)) {
+          throw new ValidationError(
+            `Unknown account_monitor parameter '${key}'. This agent accepts only: ${ACCOUNT_MONITOR_FIELDS.map(([camel]) => camel).join(", ")}.`
+          );
+        }
+      }
+    }
+    const merged = {};
+    for (const source of [requestOptions, ...strict]) {
+      for (const [camel, snake] of ACCOUNT_MONITOR_FIELDS) {
+        const value = this._getParamValue(source, camel, snake);
+        if (value !== void 0 && value !== null)
+          merged[camel] = value;
+      }
+    }
+    return merged;
+  }
   /**
    * 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
@@ -4114,6 +4402,12 @@ class ResponsesResource {
       for (const file of request.files)
         this._validateFileReference(file.uri);
     }
+    if (request.specializedAgent === "account_monitor") {
+      const monitorParams = this._accountMonitorParams(request);
+      this._validateAccountMonitorParams(monitorParams);
+      this._validateAccountMonitorCrmAccess(monitorParams, request);
+      return this.http.post("/responses", request);
+    }
     this._validateSalesNavigatorRequest(request);
     for (const params of this._specializedParamSources(request))
       this._validateSignalParams(params);
@@ -4194,7 +4488,7 @@ class ResponsesResource {
    * @param options - Optional search parameters
    * @param options.limit - Maximum number of results (1-100, default: 20)
    * @param options.dataSources - Specific data sources to use: ["PDL", "CORESIGNAL", "CRUST_DATA"]
-   * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true (via request `options`)
+   * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default false (via request `options`)
    * @param options.crmExclusionOwners - Granted owner ledgers to exclude against (user id or email)
    * @param options.crmNameCompanyMatch - Also exclude by exact name+company; @default true
    * @returns Response with structured_response containing:
@@ -4249,7 +4543,7 @@ class ResponsesResource {
    * @param options.excludeProfiles - LinkedIn URLs to exclude from results
    * @param options.excludePreviouslyContacted - Exclude previously contacted people
    * @param options.excludeNames - Names to exclude from results
-   * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default true
+   * @param options.excludeCrmContacts - Exclude people in the acting user's synced CRM ledger; @default false
    * @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
@@ -4400,32 +4694,33 @@ class ResponsesResource {
    *   - criteria: Generated/reused criteria definitions and classification
    */
   async peopleScoring(query, candidateProfiles, options) {
+    const params = {
+      candidateProfiles,
+      deepValidationUseRelevanceReranker: options?.deepValidationUseRelevanceReranker ?? true,
+      deepValidationBackfillBelowCriteria: options?.deepValidationBackfillBelowCriteria ?? true
+    };
     const request = {
       messages: [{ role: "user", content: query }],
       specializedAgent: "people_scoring",
-      specializedAgentParams: {
-        candidateProfiles,
-        deepValidationUseRelevanceReranker: options?.deepValidationUseRelevanceReranker ?? true,
-        deepValidationBackfillBelowCriteria: options?.deepValidationBackfillBelowCriteria ?? true
-      }
+      specializedAgentParams: params
     };
     if (options) {
       if (options.reuseCriteriaFrom)
-        request.specializedAgentParams.reuseCriteriaFrom = options.reuseCriteriaFrom;
+        params.reuseCriteriaFrom = options.reuseCriteriaFrom;
       if (options.criteriaDefinitions)
-        request.specializedAgentParams.criteriaDefinitions = options.criteriaDefinitions;
+        params.criteriaDefinitions = options.criteriaDefinitions;
       if (options.criteriaClassification)
-        request.specializedAgentParams.criteriaClassification = options.criteriaClassification;
+        params.criteriaClassification = options.criteriaClassification;
       if (options.runSingleCriterion)
-        request.specializedAgentParams.runSingleCriterion = options.runSingleCriterion;
+        params.runSingleCriterion = options.runSingleCriterion;
       if (options.addCriterion)
-        request.specializedAgentParams.addCriterion = options.addCriterion;
+        params.addCriterion = options.addCriterion;
       if (options.addAndRunCriterion)
-        request.specializedAgentParams.addAndRunCriterion = options.addAndRunCriterion;
+        params.addAndRunCriterion = options.addAndRunCriterion;
       if (options.deepSearchCriteriaModel)
-        request.specializedAgentParams.deepSearchCriteriaModel = options.deepSearchCriteriaModel;
+        params.deepSearchCriteriaModel = options.deepSearchCriteriaModel;
       if (options.intentScoringInstructions !== void 0)
-        request.specializedAgentParams.intentScoringInstructions = options.intentScoringInstructions;
+        params.intentScoringInstructions = options.intentScoringInstructions;
     }
     return this.create(request);
   }
@@ -4822,6 +5117,86 @@ class ResponsesResource {
       specializedAgentParams: params
     });
   }
+  /**
+   * Report on ONE account for ONE fixed period.
+   *
+   * This runs once, now: there is no backend schedule and no saved cadence, so
+   * call it again when you want the next report. The period defaults to the
+   * last seven days — pass `days` for a different look-back, or `window` for an
+   * exact interval.
+   *
+   * What gets collected is decided ONLY by `signalDefinitions`, or by the
+   * `depth` preset that stands in for it. Nothing is implied: a competitor
+   * string means that company's page, not its employees, and committee work
+   * needs `committee` people plus `depth: 'deep'` or an explicit signal.
+   *
+   * Coverage is always partial and the report says so — a missing record never
+   * proves that nothing happened.
+   *
+   * @param query - What to watch for; it steers the report, not the collection.
+   *   Pass an empty string to run the monitor with no steering prompt — the
+   *   account, the period and `intentScoringInstructions` are what decide the
+   *   report.
+   * @param options - The account, its period, and the explicit scopes to track.
+   * @param options.crmUserId - CRM owner (UUID or email) whose connected CRM is
+   *   read for relationship context; requires `options.userId`, and another
+   *   member's CRM requires a CRM access grant. Omit for no CRM lookup.
+   * @param options.userId - The acting user, sent as the request's top-level
+   *   `userId`. Required with `crmUserId`.
+   * @returns Response; poll with `get()`, read `outputText` for the report and
+   *   `structuredResponse` as {@link AccountMonitorOutput}, whose `crmContext`
+   *   is present only when `crmUserId` was sent.
+   *
+   * @example
+   * ```ts
+   * await client.responses.accountMonitor(
+   *   'Anything suggesting they are re-evaluating their data warehouse',
+   *   {
+   *     account: 'acme.com',
+   *     days: 14,
+   *     depth: 'deep',
+   *     committee: { groups: { 'data platform': ['https://www.linkedin.com/in/some-vp'] } },
+   *     competitors: [{ company: 'rival.com', employeeTitles: ['Account Executive'] }],
+   *   },
+   * )
+   * ```
+   */
+  async accountMonitor(query, options) {
+    if (typeof query !== "string")
+      throw new ValidationError("accountMonitor query must be a string");
+    const params = { account: options.account };
+    if (options.depth !== void 0)
+      params.depth = options.depth;
+    if (options.committee !== void 0)
+      params.committee = options.committee;
+    if (options.competitors !== void 0)
+      params.competitors = options.competitors;
+    if (options.ourCompany !== void 0)
+      params.ourCompany = options.ourCompany;
+    if (options.days !== void 0)
+      params.days = options.days;
+    if (options.window !== void 0)
+      params.window = options.window;
+    if (options.signalDefinitions !== void 0)
+      params.signalDefinitions = options.signalDefinitions;
+    if (options.intentScoringInstructions !== void 0)
+      params.intentScoringInstructions = options.intentScoringInstructions;
+    if (options.history !== void 0)
+      params.history = options.history;
+    if (options.crmUserId !== void 0)
+      params.crmUserId = options.crmUserId;
+    if (options.tier !== void 0)
+      params.tier = options.tier;
+    const prompt = query.trim() || `Account monitor report for ${options.account}`;
+    const request = {
+      messages: [{ role: "user", content: prompt }],
+      specializedAgent: "account_monitor",
+      specializedAgentParams: params
+    };
+    if (options.userId !== void 0)
+      request.userId = options.userId;
+    return this.create(request);
+  }
 }
 
 class SequencesResource {