lumnisai 0.5.51 → 0.5.53

package/dist/index.cjs

@@ -970,6 +970,7 @@ class ContactRelationshipsResource {
   }
 }
 
+const COMPANY_SEARCH_PASSTHROUGH_KEYS = ["filters", "properties", "owners"];
 class CrmResource {
   constructor(http) {
     this.http = http;
@@ -1069,6 +1070,134 @@ class CrmResource {
       data
     );
   }
+  /**
+   * List the company fields the connected CRM exposes, with the operators each
+   * one accepts — what a filter builder needs before calling
+   * {@link searchCompanies}. A live, read-only provider call: nothing is
+   * written to the CRM and nothing is served from the `crm_contacts` ledger.
+   *
+   * Pass `propertyName` to narrow to a single field. Attio returns
+   * `select`/`status` choices only that way; HubSpot already includes
+   * enumeration choices in the full listing, except for externally-sourced
+   * ones, which come back as `options: null, optionsComplete: false`.
+   *
+   * Field metadata is provider-shaped, so the return type narrows on the
+   * `provider` you pass.
+   *
+   * A definition with `references: 'owner'` holds a CRM user id; request it
+   * in {@link searchCompanies} to have each company's `owners` map resolve
+   * it to a name and email. HubSpot's is `hubspot_owner_id`; Attio has no
+   * standard one, so take the actor-reference slug this listing flags.
+   *
+   * Failure modes: `403 crm_access_denied` and `503 crm_access_unavailable`
+   * (the `crmUserId` grant), `409 crm_not_connected` (no single active
+   * connection for the owner), `404 crm_property_not_found`,
+   * `429 crm_rate_limited`, `504 crm_read_timeout`, `502 crm_read_failed`.
+   *
+   * @example
+   * ```typescript
+   * const { properties } = await client.crm.getCompanyProperties({
+   *   userId: 'user@example.com',
+   *   provider: 'hubspot',
+   * })
+   * const filterable = properties.filter(p => p.operators.length > 0)
+   *
+   * // Attio choices need the field named explicitly.
+   * const tier = await client.crm.getCompanyProperties({
+   *   userId: 'user@example.com',
+   *   provider: 'attio',
+   *   propertyName: 'employee_range',
+   * })
+   * console.log(tier.properties[0].options)
+   *
+   * // The field that can fill an owner column.
+   * const ownerField = properties.find(p => p.references === 'owner')
+   * ```
+   */
+  async getCompanyProperties(params) {
+    const response = await this.http.get(
+      "/crm/companies/properties",
+      {
+        // Backend requires snake_case query params (see getContactsSyncStatus).
+        params: {
+          user_id: params.userId,
+          provider: params.provider,
+          property_name: params.propertyName,
+          crm_user_id: params.crmUserId
+        }
+      }
+    );
+    return response;
+  }
+  /**
+   * Read one page of companies from the connected CRM using that provider's
+   * own filter syntax. Read-only: no CRM writes, no local persistence, so the
+   * same request can be replayed to refresh a preview.
+   *
+   * Filters are never translated. HubSpot takes `filterGroups` (AND within a
+   * group, OR between groups) with string comparison values; Attio takes its
+   * record-query object with `$`-prefixed operators. Both cross the wire
+   * verbatim — the SDK's camelCase ↔ snake_case conversion is switched off for
+   * `filters` and for each company's `properties` and `owners` maps, whose
+   * keys are CRM property names. Discover valid names and operators with
+   * {@link getCompanyProperties}.
+   *
+   * Requesting an owner-typed field (`references: 'owner'` in its definition)
+   * also resolves it: `owners[field]` is the CRM user's `{ id, name, email }`,
+   * null when the company has none, with `name`/`email` null when the id is
+   * not in the user directory. Resolution is part of the page — if the
+   * directory read fails the whole request fails with the codes below rather
+   * than returning half-resolved owners. Cost: any requested field adds one
+   * definitions read per page; an owner field adds one directory read on top.
+   *
+   * Paging is cursor-based: pass the previous page's `nextCursor` back as
+   * `cursor` and keep every other field identical, because HubSpot pages by
+   * record id inside the original query. `nextCursor: null` is the last page.
+   * `total` is reported on the first HubSpot page only, and is always null for
+   * Attio.
+   *
+   * An empty `companies` array is a real "no matches" result — provider
+   * failures raise instead. Failure modes: `403 crm_access_denied` and
+   * `503 crm_access_unavailable` (the `crmUserId` grant),
+   * `409 crm_not_connected`, `400 invalid_crm_filter` (the provider rejected
+   * the query), `422 invalid_crm_request` (filter/limit/cursor budgets,
+   * checked before the provider call), `429 crm_rate_limited`,
+   * `504 crm_read_timeout`, `502 crm_read_failed`.
+   *
+   * @example
+   * ```typescript
+   * const request: CrmHubspotCompanySearchRequest = {
+   *   userId: 'user@example.com',
+   *   provider: 'hubspot',
+   *   filters: {
+   *     filterGroups: [{
+   *       filters: [
+   *         { propertyName: 'domain', operator: 'CONTAINS_TOKEN', value: 'acme' },
+   *         { propertyName: 'numberofemployees', operator: 'GT', value: '50' },
+   *       ],
+   *     }],
+   *   },
+   *   properties: ['numberofemployees', 'industry', 'hubspot_owner_id'],
+   *   limit: 50,
+   * }
+   *
+   * const page = await client.crm.searchCompanies(request)
+   * for (const company of page.companies)
+   *   console.log(company.name, company.properties.industry, company.owners?.hubspot_owner_id?.name)
+   *
+   * // Same query, next page.
+   * if (page.nextCursor)
+   *   await client.crm.searchCompanies({ ...request, cursor: page.nextCursor })
+   * ```
+   */
+  async searchCompanies(data) {
+    const response = await this.http.post(
+      "/crm/companies/search",
+      data,
+      { passthroughKeys: COMPANY_SEARCH_PASSTHROUGH_KEYS }
+    );
+    return response;
+  }
   /**
    * Trigger a full mirror of the owner's CRM contact book into the local
    * `crm_contacts` ledger. Returns immediately (`202`); poll
@@ -1950,23 +2079,28 @@ const PASSTHROUGH_VALUE_KEYS = /* @__PURE__ */ new Set([
   // those would rename the customer's own groups.
   "committee"
 ]);
-function convertCase(obj, converter) {
+function convertCase(obj, converter, passthroughKeys) {
   if (Array.isArray(obj)) {
-    return obj.map((v) => convertCase(v, converter));
+    return obj.map((v) => convertCase(v, converter, passthroughKeys));
   } else if (obj !== null && typeof obj === "object") {
     return Object.keys(obj).reduce((acc, key) => {
-      const value = PASSTHROUGH_VALUE_KEYS.has(key) ? obj[key] : convertCase(obj[key], converter);
+      const value = passthroughKeys.has(key) ? obj[key] : convertCase(obj[key], converter, passthroughKeys);
       acc[converter(key)] = value;
       return acc;
     }, {});
   }
   return obj;
 }
-function toCamelCase(obj) {
-  return convertCase(obj, toCamel);
+function passthroughSet(extraKeys) {
+  if (!extraKeys || extraKeys.length === 0)
+    return PASSTHROUGH_VALUE_KEYS;
+  return /* @__PURE__ */ new Set([...PASSTHROUGH_VALUE_KEYS, ...extraKeys]);
 }
-function toSnakeCase(obj) {
-  return convertCase(obj, toSnake);
+function toCamelCase(obj, extraPassthroughKeys) {
+  return convertCase(obj, toCamel, passthroughSet(extraPassthroughKeys));
+}
+function toSnakeCase(obj, extraPassthroughKeys) {
+  return convertCase(obj, toSnake, passthroughSet(extraPassthroughKeys));
 }
 
 class MessagingResource {
@@ -5990,7 +6124,7 @@ class Http {
       backoffFactor: options.backoffFactor || DEFAULT_BACKOFF_FACTOR
     };
   }
-  async _handleResponse(response) {
+  async _handleResponse(response, passthroughKeys) {
     const requestId = response.headers.get("x-request-id");
     if (response.ok) {
       if (response.status === 204)
@@ -5998,7 +6132,7 @@ class Http {
       const contentType = response.headers.get("content-type") || "";
       if (contentType.includes("application/json")) {
         const json = await response.json();
-        return toCamelCase(json);
+        return toCamelCase(json, passthroughKeys);
       }
       return await response.text();
     }
@@ -6028,7 +6162,13 @@ class Http {
     }
   }
   async request(path, init = {}) {
-    const { body, params, idempotencyKey: idempotencyKeyOption, ...fetchOptions } = init;
+    const {
+      body,
+      params,
+      idempotencyKey: idempotencyKeyOption,
+      passthroughKeys,
+      ...fetchOptions
+    } = init;
     const method = fetchOptions.method || "GET";
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
     const fullPath = this.options.apiPrefix ? `${this.options.apiPrefix}${normalizedPath}` : normalizedPath;
@@ -6057,10 +6197,10 @@ class Http {
           ...fetchOptions,
           method,
           headers,
-          body: body ? JSON.stringify(toSnakeCase(body)) : void 0,
+          body: body ? JSON.stringify(toSnakeCase(body, passthroughKeys)) : void 0,
           signal: controller.signal
         });
-        return await this._handleResponse(response);
+        return await this._handleResponse(response, passthroughKeys);
       } catch (error) {
         lastError = error;
         if (error instanceof RateLimitError) {