@absolutejs/engagement-apollo 0.0.12 → 0.0.14

package/README.md

@@ -32,3 +32,21 @@ Company enrichment returns `null` for no match (404), throws `RateLimitError` fo
 ## License
 
 Apache-2.0.
+
+### Company research
+
+`searchCompanies({ domain?, name?, limit?, signal? })` reads one bounded page
+(default 5, maximum 100) without contact reveals or implicit enrichment. Apollo
+charges one credit per page; meter each successful call. Errors are explicit,
+including scope/authentication failures, so an unavailable search is not “no data.”
+`enrichCompany` also accepts `website` and `linkedinUrl`; requests have a 30-second
+timeout and accept cancellation.
+
+Company `intelligence` retains provider-reported ownership, subsidiaries, retail
+locations, industries, technologies, funding, source URL and observation time.
+Missing fields remain null/empty, never inferred. Funding is not revenue, locations
+are not customers, and organization revenue is not necessarily subscription ARR.
+Apollo does not establish a vendor's pricing cadence or comparable business scope.
+Use `companyIdentityMatch` / `selectCompanyIdentity` from the engagement contract
+to require an independently returned exact domain and a compatible brand name;
+ambiguous provider records must not be merged based on revenue size.

package/dist/index.js

@@ -8,7 +8,7 @@ var APOLLO_BASE_URL = "https://api.apollo.io";
 var DEFAULT_ACTIVITY_LIMIT = 50;
 var DEFAULT_SEARCH_LIMIT = 6;
 var LOCKED_EMAIL = /email_not_unlocked/iu;
-var isRecord = (value) => typeof value === "object" && value !== null;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var str = (value) => typeof value === "string" && value.length > 0 ? value : null;
 var num = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
 var companyDomain = (org) => {
@@ -29,6 +29,26 @@ var joinLocation = (parts) => {
   const present = parts.filter((part) => part !== null);
   return present.length > 0 ? present.join(", ") : null;
 };
+var strings = (value) => Array.isArray(value) ? value.flatMap((item) => typeof item === "string" && item.trim() ? [item.trim()] : []) : [];
+var count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+var publicUrl = (value) => {
+  if (typeof value !== "string")
+    return null;
+  try {
+    const url = new URL(value);
+    return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password ? url.href : null;
+  } catch {
+    return null;
+  }
+};
+var reference = (value) => isRecord(value) ? {
+  providerId: str(value.id),
+  name: str(value.name),
+  domain: companyDomain(value),
+  country: str(value.country),
+  employeeCount: count(value.estimated_num_employees),
+  industries: strings(value.industries)
+} : null;
 var apolloSource = (options) => {
   const baseUrl = options.baseUrl ?? APOLLO_BASE_URL;
   const doFetch = options.fetchImpl ?? fetch;
@@ -49,19 +69,6 @@ var apolloSource = (options) => {
     const json = await res.json();
     return isRecord(json) ? json : null;
   };
-  const get = async (path) => {
-    const res = await doFetch(`${baseUrl}${path}`, { headers, method: "GET" });
-    if (res.status === 429)
-      throw new RateLimitError("apollo");
-    if (res.status === 404)
-      return null;
-    if (!res.ok)
-      throw new EngagementProviderError("apollo", res.status, "company enrichment");
-    const json = await res.json();
-    if (!isRecord(json))
-      throw new EngagementProviderError("apollo", 502, "invalid company response");
-    return json;
-  };
   const normalizePerson = (person) => {
     const org = isRecord(person.organization) ? person.organization : null;
     const contact = isRecord(person.contact) ? person.contact : null;
@@ -73,7 +80,7 @@ var apolloSource = (options) => {
     ].filter((value) => value !== null).filter((value) => !LOCKED_EMAIL.test(value))));
     return {
       company: org ? str(org.name) : null,
-      companyDomain: org ? str(org.primary_domain) : null,
+      companyDomain: org ? companyDomain(org) : null,
       emails,
       facebookUrl: str(person.facebook_url),
       firstName: str(person.first_name),
@@ -130,19 +137,37 @@ var apolloSource = (options) => {
       searchRequests
     };
   };
-  const enrichCompany = async (query) => {
-    if (!query.domain)
-      return null;
-    const params = new URLSearchParams({ domain: query.domain });
-    if (query.name?.trim())
-      params.set("name", query.name.trim());
-    const json = await get(`/v1/organizations/enrich?${params.toString()}`);
-    const org = json && isRecord(json.organization) ? json.organization : null;
-    if (!org)
-      return null;
+  const normalizeCompany = (org) => {
     const revenue = num(org.annual_revenue);
     const revenueDisplay = str(org.annual_revenue_printed);
     return {
+      intelligence: {
+        provider: "apollo",
+        observedAt: new Date().toISOString(),
+        sourceUrl: /^[a-f0-9]{24}$/iu.test(str(org.id) ?? "") ? `https://app.apollo.io/#/organizations/${org.id}` : null,
+        websiteUrl: publicUrl(org.website_url),
+        location: joinLocation([
+          str(org.city),
+          str(org.state),
+          str(org.country)
+        ]),
+        industries: strings(org.industries),
+        keywords: strings(org.keywords),
+        technologies: strings(org.technology_names),
+        retailLocationCount: count(org.retail_location_count),
+        activeRetailLocationCount: count(org.num_retail_locations),
+        parent: reference(org.owned_by_organization),
+        ultimateParent: reference(org.ultimate_parent_organization),
+        parentIds: strings(org.owned_by_chain),
+        subsidiaries: Array.isArray(org.suborganizations) ? org.suborganizations.flatMap((value) => {
+          const item = reference(value);
+          return item ? [item] : [];
+        }) : [],
+        subsidiaryCount: count(org.num_suborganizations),
+        totalFunding: count(org.total_funding),
+        latestFundingStage: str(org.latest_funding_stage),
+        latestFundingDate: str(org.latest_funding_round_date)
+      },
       providerId: str(org.id),
       annualRevenue: revenue !== null && revenue > 0 || revenueDisplay ? {
         amount: revenue !== null && revenue > 0 ? revenue : null,
@@ -162,6 +187,64 @@ var apolloSource = (options) => {
       raw: org
     };
   };
+  const companyRequest = async (path, signal, body) => {
+    signal?.throwIfAborted();
+    const res = await doFetch(`${baseUrl}${path}`, {
+      headers,
+      method: body ? "POST" : "GET",
+      ...body ? { body: JSON.stringify(body) } : {},
+      signal: AbortSignal.any([
+        AbortSignal.timeout(30000),
+        ...signal ? [signal] : []
+      ])
+    });
+    if (res.status === 429)
+      throw new RateLimitError("apollo");
+    if (res.status === 404 && !body)
+      return null;
+    if (!res.ok)
+      throw new EngagementProviderError("apollo", res.status, body ? "company search" : "company enrichment");
+    const value = await res.json();
+    if (!isRecord(value))
+      throw new EngagementProviderError("apollo", 502, "invalid company response");
+    return value;
+  };
+  const enrichCompany = async (query) => {
+    if (!query.domain && !query.website && !query.linkedinUrl)
+      return null;
+    const params = new URLSearchParams;
+    if (query.domain)
+      params.set("domain", query.domain);
+    if (query.website)
+      params.set("website", query.website);
+    if (query.linkedinUrl)
+      params.set("linkedin_url", query.linkedinUrl);
+    if (query.name?.trim())
+      params.set("name", query.name.trim());
+    const json = await companyRequest(`/api/v1/organizations/enrich?${params}`, query.signal);
+    if (!json || json.organization === null)
+      return null;
+    if (!isRecord(json.organization))
+      throw new EngagementProviderError("apollo", 502, "invalid company enrichment response");
+    return normalizeCompany(json.organization);
+  };
+  const searchCompanies = async (query) => {
+    if (!query.domain && !query.name?.trim())
+      return { companies: [], searchRequests: 0 };
+    const limit = Number.isFinite(query.limit) ? Math.max(1, Math.min(100, Math.floor(query.limit))) : 5;
+    const json = await companyRequest("/api/v1/mixed_companies/search", query.signal, {
+      page: 1,
+      per_page: limit,
+      ...query.domain ? { q_organization_domains_list: [query.domain] } : {},
+      ...!query.domain && query.name ? { q_organization_name: query.name.trim() } : {}
+    });
+    if (!json || !Array.isArray(json.organizations) || json.organizations.some((value) => !isRecord(value)))
+      throw new EngagementProviderError("apollo", 502, "invalid company search response");
+    return {
+      companies: json.organizations.filter(isRecord).slice(0, limit).map(normalizeCompany),
+      searchRequests: 1
+    };
+  };
   const listActivities = async (query) => {
     const json = await post("/v1/emailer_messages/search", {
       per_page: query.limit ?? DEFAULT_ACTIVITY_LIMIT,
@@ -201,7 +284,8 @@ var apolloSource = (options) => {
     enrichPerson,
     id: "apollo",
     listActivities,
-    searchPeople
+    searchPeople,
+    searchCompanies
   };
 };
 export {

package/dist/manifest.js

@@ -10,6 +10,7 @@ var manifest = defineManifest()({
       "enrich a person with Apollo",
       "enrich a company with Apollo",
       "search people by role",
+      "research company revenue and ownership",
       "read Apollo outreach activity"
     ],
     keywords: ["apollo", "engagement", "enrichment", "outreach", "sales"],
@@ -40,7 +41,7 @@ var manifest = defineManifest()({
         peers: [
           {
             name: "@absolutejs/engagement",
-            range: ">=0.0.7 <0.1",
+            range: ">=0.0.10 <0.1",
             reason: "Shared engagement contracts and rate-limit identity"
           }
         ]

package/dist/manifest.json

@@ -9,6 +9,7 @@
 			"enrich a person with Apollo",
 			"enrich a company with Apollo",
 			"search people by role",
+			"research company revenue and ownership",
 			"read Apollo outreach activity"
 		],
 		"keywords": [
@@ -47,7 +48,7 @@
 				"peers": [
 					{
 						"name": "@absolutejs/engagement",
-						"range": ">=0.0.7 <0.1",
+						"range": ">=0.0.10 <0.1",
 						"reason": "Shared engagement contracts and rate-limit identity"
 					}
 				]

package/package.json

@@ -2,7 +2,7 @@
   "author": "Alex Kahn",
   "description": "Apollo.io EngagementSource adapter for @absolutejs/engagement — person/company enrichment and outreach activity (emails sent/opened/replied) from the Apollo API.",
   "devDependencies": {
-    "@absolutejs/engagement": "0.0.9",
+    "@absolutejs/engagement": "0.0.10",
     "@types/bun": "1.3.14",
     "prettier": "3.8.1",
     "typescript": "5.9.3"
@@ -23,7 +23,7 @@
   "main": "./dist/index.js",
   "name": "@absolutejs/engagement-apollo",
   "peerDependencies": {
-    "@absolutejs/engagement": ">=0.0.9 <0.1"
+    "@absolutejs/engagement": ">=0.0.10 <0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -44,7 +44,7 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",