@absolutejs/engagement-apollo 0.0.11 → 0.0.13

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.d.ts

@@ -1,9 +1,9 @@
 import type { EngagementSource } from "@absolutejs/engagement";
 export type ApolloOptions = {
-    apiKey: string;
-    /** Override for testing or a proxy. Defaults to https://api.apollo.io. */
-    baseUrl?: string;
-    /** Inject a fetch (tests, instrumentation). Defaults to global fetch. */
-    fetchImpl?: typeof fetch;
+  apiKey: string;
+  /** Override for testing or a proxy. Defaults to https://api.apollo.io. */
+  baseUrl?: string;
+  /** Inject a fetch (tests, instrumentation). Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
 };
 export declare const apolloSource: (options: ApolloOptions) => EngagementSource;

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;
@@ -130,16 +137,37 @@ var apolloSource = (options) => {
       searchRequests
     };
   };
-  const enrichCompany = async (query) => {
-    if (!query.domain)
-      return null;
-    const json = await get(`/v1/organizations/enrich?domain=${encodeURIComponent(query.domain)}`);
-    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,
@@ -159,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,
@@ -198,7 +284,8 @@ var apolloSource = (options) => {
     enrichPerson,
     id: "apollo",
     listActivities,
-    searchPeople
+    searchPeople,
+    searchCompanies
   };
 };
 export {

package/dist/manifest.d.ts

@@ -1,10 +1,27 @@
 import type { ApolloOptions } from "./index";
-export declare const manifest: Omit<import("@absolutejs/manifest").PackageManifest<ApolloOptions, never>, "contract" | "settings" | "tools"> & (({
-    contract: 1;
-    tools?: Record<string, import("@absolutejs/manifest").LegacyManifestTool<never>> | undefined;
-} | {
-    contract: 2;
-    tools?: Record<string, import("@absolutejs/manifest").AuthorizedManifestTool<never>> | undefined;
-}) & {
+export declare const manifest: Omit<
+  import("@absolutejs/manifest").PackageManifest<ApolloOptions, never>,
+  "contract" | "settings" | "tools"
+> &
+  ((
+    | {
+        contract: 1;
+        tools?:
+          | Record<
+              string,
+              import("@absolutejs/manifest").LegacyManifestTool<never>
+            >
+          | undefined;
+      }
+    | {
+        contract: 2;
+        tools?:
+          | Record<
+              string,
+              import("@absolutejs/manifest").AuthorizedManifestTool<never>
+            >
+          | undefined;
+      }
+  ) & {
     settings: import("@sinclair/typebox").TObject<{}>;
-});
+  });

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

@@ -1,85 +1,73 @@
 {
-	"contract": 2,
-	"discovery": {
-		"audiences": [
-			"agent-hosts",
-			"application-developers"
-		],
-		"intents": [
-			"enrich a person with Apollo",
-			"enrich a company with Apollo",
-			"search people by role",
-			"read Apollo outreach activity"
-		],
-		"keywords": [
-			"apollo",
-			"engagement",
-			"enrichment",
-			"outreach",
-			"sales"
-		],
-		"protocols": [
-			"HTTPS"
-		]
-	},
-	"identity": {
-		"accent": "#5c4cff",
-		"category": "sales",
-		"description": "Apollo-backed EngagementSource for person and company enrichment, role-based people search, and outreach activity with explicit provider-credit accounting.",
-		"docsUrl": "https://github.com/absolutejs/engagement-adapters/tree/main/apollo",
-		"name": "@absolutejs/engagement-apollo",
-		"tagline": "Connect Apollo enrichment and outreach to your site."
-	},
-	"implements": [
-		{
-			"contract": "engagement/source",
-			"factory": "apolloSource",
-			"from": "@absolutejs/engagement-apollo",
-			"requires": {
-				"env": [
-					{
-						"description": "Apollo API key",
-						"docsUrl": "https://developer.apollo.io/keys/",
-						"key": "APOLLO_API_KEY",
-						"secret": true
-					}
-				],
-				"peers": [
-					{
-						"name": "@absolutejs/engagement",
-						"range": ">=0.0.7 <0.1",
-						"reason": "Shared engagement contracts and rate-limit identity"
-					}
-				]
-			},
-			"settings": {
-				"type": "object",
-				"properties": {
-					"baseUrl": {
-						"description": "Apollo-compatible API origin. Leave empty for the official Apollo API.",
-						"format": "uri",
-						"title": "API origin",
-						"type": "string"
-					}
-				}
-			},
-			"title": "Apollo",
-			"wiring": {
-				"code": "apolloSource({ apiKey: ${env.APOLLO_API_KEY}, ...${settings} })",
-				"imports": [
-					{
-						"from": "@absolutejs/engagement-apollo",
-						"names": [
-							"apolloSource"
-						]
-					}
-				]
-			}
-		}
-	],
-	"settings": {
-		"type": "object",
-		"properties": {}
-	},
-	"wiring": []
+  "contract": 2,
+  "discovery": {
+    "audiences": ["agent-hosts", "application-developers"],
+    "intents": [
+      "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"],
+    "protocols": ["HTTPS"]
+  },
+  "identity": {
+    "accent": "#5c4cff",
+    "category": "sales",
+    "description": "Apollo-backed EngagementSource for person and company enrichment, role-based people search, and outreach activity with explicit provider-credit accounting.",
+    "docsUrl": "https://github.com/absolutejs/engagement-adapters/tree/main/apollo",
+    "name": "@absolutejs/engagement-apollo",
+    "tagline": "Connect Apollo enrichment and outreach to your site."
+  },
+  "implements": [
+    {
+      "contract": "engagement/source",
+      "factory": "apolloSource",
+      "from": "@absolutejs/engagement-apollo",
+      "requires": {
+        "env": [
+          {
+            "description": "Apollo API key",
+            "docsUrl": "https://developer.apollo.io/keys/",
+            "key": "APOLLO_API_KEY",
+            "secret": true
+          }
+        ],
+        "peers": [
+          {
+            "name": "@absolutejs/engagement",
+            "range": ">=0.0.10 <0.1",
+            "reason": "Shared engagement contracts and rate-limit identity"
+          }
+        ]
+      },
+      "settings": {
+        "type": "object",
+        "properties": {
+          "baseUrl": {
+            "description": "Apollo-compatible API origin. Leave empty for the official Apollo API.",
+            "format": "uri",
+            "title": "API origin",
+            "type": "string"
+          }
+        }
+      },
+      "title": "Apollo",
+      "wiring": {
+        "code": "apolloSource({ apiKey: ${env.APOLLO_API_KEY}, ...${settings} })",
+        "imports": [
+          {
+            "from": "@absolutejs/engagement-apollo",
+            "names": ["apolloSource"]
+          }
+        ]
+      }
+    }
+  ],
+  "settings": {
+    "type": "object",
+    "properties": {}
+  },
+  "wiring": []
 }

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.11",
+  "version": "0.0.13",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",