@dench.com/cli 0.4.8 → 0.4.9

package/lib/enrichment-gateway.ts

@@ -36,10 +36,16 @@ export type EnrichPersonBody = {
 };
 
 export type EnrichCompanyBody = {
-  domain: string;
+  domain?: string;
+  companyName?: string;
+  linkedinUrl?: string;
   requiredFields?: string[];
 };
 
+export type ReverseEmailBody = {
+  email: string;
+};
+
 export type SearchPeopleBody = {
   personTitles?: string[];
   personLocations?: string[];
@@ -56,8 +62,21 @@ export type EnrichmentGatewayOptions = {
   baseUrl?: string;
   env?: EnrichmentGatewayEnv;
   fetchImpl?: FetchLike;
+  /** Override the poll interval (ms) for testing. Default: 2000. */
+  pollIntervalMs?: number;
+  /** Override the poll timeout (ms) for testing. Default: 30000. */
+  pollTimeoutMs?: number;
+  /**
+   * Optional abort signal — propagated to fetch and short-circuits the polling
+   * loop so callers (e.g. SSE clients that disconnect) can stop in-flight work.
+   */
+  signal?: AbortSignal;
 };
 
+// ---------------------------------------------------------------------------
+// URL / key resolution (unchanged for backward compat)
+// ---------------------------------------------------------------------------
+
 export function resolveEnrichmentGatewayBaseUrl(
   env: EnrichmentGatewayEnv = process.env,
 ): string {
@@ -108,33 +127,308 @@ export function buildPersonBodyFromIdentifier(
   );
 }
 
+// ---------------------------------------------------------------------------
+// requiredFields → enrichFields translation
+// ---------------------------------------------------------------------------
+
+type EnrichField = "work_emails" | "personal_emails" | "phones";
+
+function mapRequiredFieldsToEnrichFields(rf?: string[]): EnrichField[] {
+  const set = new Set<EnrichField>();
+  for (const f of rf ?? []) {
+    if (f === "phone") set.add("phones");
+    else if (f === "email" || f === "work_email") set.add("work_emails");
+    else if (f === "personal_email") set.add("personal_emails");
+    // profile-only fields (fullName, linkedinID, headline, URLs, location, etc.) → ignored
+  }
+  // If no contact-data fields requested, default to work_emails so FE
+  // returns at minimum profile + cheapest contact charge.
+  return set.size > 0 ? [...set] : ["work_emails"];
+}
+
+// ---------------------------------------------------------------------------
+// Apollo-shape envelope (preserves crm-enrichment catalog extraction paths)
+// ---------------------------------------------------------------------------
+
+export type ApolloPersonEnvelope = {
+  person: {
+    name?: string;
+    first_name?: string;
+    last_name?: string;
+    email?: string;
+    work_email?: string;
+    personal_email?: string;
+    linkedin_url?: string;
+    title?: string;
+    headline?: string;
+    contact: {
+      phone_numbers: Array<{
+        sanitized_number: string;
+        raw_number?: string;
+      }>;
+    };
+  };
+};
+
+type EnrichedPersonUpsertLike = {
+  fullName?: string;
+  firstName?: string;
+  lastName?: string;
+  headline?: string;
+  /** Structured title from the person's current role (distinct from headline). */
+  currentTitle?: string;
+  linkedinID?: string;
+  emails?: Array<{ address?: string; normalizedAddress?: string; type?: string }>;
+  phones?: Array<{ number?: string; normalizedNumber?: string }>;
+};
+
+function shapePersonToApolloEnvelope(
+  u: EnrichedPersonUpsertLike,
+): ApolloPersonEnvelope {
+  const workEmail = u.emails?.find((e) => e.type === "work")?.address;
+  const personalEmail = u.emails?.find((e) => e.type === "personal")?.address;
+  const anyEmail = u.emails?.[0]?.address;
+  return {
+    person: {
+      name: u.fullName,
+      first_name: u.firstName,
+      last_name: u.lastName,
+      email: workEmail ?? anyEmail,
+      work_email: workEmail,
+      personal_email: personalEmail,
+      linkedin_url: u.linkedinID
+        ? `https://www.linkedin.com/in/${u.linkedinID}`
+        : undefined,
+      title: u.currentTitle,
+      headline: u.headline,
+      contact: {
+        phone_numbers: (u.phones ?? []).map((p) => ({
+          sanitized_number: p.normalizedNumber ?? p.number ?? "",
+          raw_number: p.number,
+        })),
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Organization-shape envelope (preserves COMPANY_ENRICHMENT_COLUMNS paths)
+// ---------------------------------------------------------------------------
+
+export type ApolloCompanyEnvelope = {
+  organization: {
+    name?: string;
+    domain?: string;
+    website_url?: string;
+    industry?: string;
+    industry_list?: string[];
+    specialties?: string[];
+    linkedin_url?: string;
+    founded_year?: number;
+    headcount?: number;
+    headcount_range?: string;
+    total_funding?: number;
+    description?: string;
+    hq_city?: string;
+    hq_country?: string;
+    hq_country_code?: string;
+    hq_location?: string;
+  };
+};
+
+type EnrichedCompanyUpsertLike = {
+  name?: string;
+  website?: string;
+  industry?: string;
+  industryList?: string[];
+  specialties?: string[];
+  linkedinUrl?: string;
+  founded?: number;
+  headcount?: number;
+  headcountRange?: string;
+  totalFunding?: number;
+  description?: string;
+  hqAddress?: {
+    city?: string;
+    region?: string;
+    country?: string;
+    countryCode?: string;
+  };
+};
+
+function shapeCompanyToApolloEnvelope(
+  c: EnrichedCompanyUpsertLike,
+): ApolloCompanyEnvelope {
+  const hq = c.hqAddress;
+  const city = hq?.city;
+  const country = hq?.country ?? hq?.countryCode;
+  const hqLocationParts = [city, country].filter(
+    (v): v is string => typeof v === "string" && v.length > 0,
+  );
+  return {
+    organization: {
+      name: c.name,
+      domain: c.website,
+      website_url: c.website,
+      industry: c.industry,
+      industry_list: c.industryList,
+      specialties: c.specialties,
+      linkedin_url: c.linkedinUrl,
+      founded_year: c.founded,
+      headcount: c.headcount,
+      headcount_range: c.headcountRange,
+      total_funding: c.totalFunding,
+      description: c.description,
+      hq_city: city,
+      hq_country: hq?.country,
+      hq_country_code: hq?.countryCode,
+      hq_location:
+        hqLocationParts.length > 0 ? hqLocationParts.join(", ") : undefined,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// enrichPerson — calls POST /v1/enrichment/person/contact with block-and-poll
+// ---------------------------------------------------------------------------
+
 export async function enrichPerson(
   body: EnrichPersonBody,
   options: EnrichmentGatewayOptions = {},
 ): Promise<Record<string, unknown>> {
-  const payload: Record<string, unknown> = {};
-  if (body.email) payload.email = body.email;
-  if (body.linkedinUrl) payload.linkedin_url = body.linkedinUrl;
-  if (body.firstName) payload.first_name = body.firstName;
-  if (body.lastName) payload.last_name = body.lastName;
-  if (body.domain) payload.domain = body.domain;
-  if (body.organizationName) payload.organization_name = body.organizationName;
-  if (body.requiredFields && body.requiredFields.length > 0) {
-    payload.requiredFields = body.requiredFields;
-  }
-
-  if (Object.keys(payload).length === 0) {
+  const enrichFields = mapRequiredFieldsToEnrichFields(body.requiredFields);
+
+  // Build the contact payload for the new endpoint.
+  const contactPayload: Record<string, unknown> = {};
+  if (body.linkedinUrl) contactPayload.linkedinUrl = body.linkedinUrl;
+  if (body.firstName) contactPayload.firstName = body.firstName;
+  if (body.lastName) contactPayload.lastName = body.lastName;
+  if (body.domain) {
+    contactPayload.domain = extractDomain(body.domain) ?? body.domain;
+  } else if (body.email) {
+    // Derive domain from email as a fallback input for person/contact.
+    const emailDomain = body.email.split("@")[1]?.trim();
+    if (emailDomain) contactPayload.domain = emailDomain;
+  }
+  if (body.organizationName) contactPayload.companyName = body.organizationName;
+  contactPayload.enrichFields = enrichFields;
+
+  // Validate we have enough to call person/contact.
+  const hasLinkedin = Boolean(contactPayload.linkedinUrl);
+  const hasNameAndCompany =
+    Boolean(contactPayload.firstName) &&
+    Boolean(contactPayload.lastName) &&
+    Boolean(contactPayload.domain || contactPayload.companyName);
+  if (!hasLinkedin && !hasNameAndCompany) {
     throw new EnrichmentGatewayError(
-      "People enrichment requires at least one identifier.",
+      "People enrichment requires linkedinUrl OR firstName+lastName+domain.",
       { code: "missing_people_identifier" },
     );
   }
 
-  return callGatewayJson("/v1/enrichment/people", {
+  const requestBody = {
+    contacts: [contactPayload],
+    preferCache: true,
+  };
+
+  const raw = await callGatewayJson("/v1/enrichment/person/contact", {
     method: "POST",
-    body: payload,
+    body: requestBody,
     options,
+    expectedStatus: [200, 202],
   });
+
+  const personContactResp = raw as {
+    enrichmentId?: string | null;
+    status?: string;
+    cachedResults?: unknown[];
+    queuedCount?: number;
+  };
+
+  // Cache hit: shape and return immediately.
+  const cachedResults = personContactResp.cachedResults ?? [];
+  if (cachedResults.length > 0) {
+    const hit = cachedResults[0] as EnrichedPersonUpsertLike;
+    return {
+      _meta: { cacheHit: true },
+      ...shapePersonToApolloEnvelope(hit),
+    } as Record<string, unknown>;
+  }
+
+  // Queued: poll for the result.
+  const enrichmentId = personContactResp.enrichmentId;
+  if (!enrichmentId) {
+    throw new EnrichmentGatewayError("No data returned", {
+      code: "not_found",
+    });
+  }
+
+  return pollForPersonResult(enrichmentId, options);
+}
+
+async function pollForPersonResult(
+  enrichmentId: string,
+  options: EnrichmentGatewayOptions,
+): Promise<Record<string, unknown>> {
+  const pollIntervalMs = options.pollIntervalMs ?? 2000;
+  // Default 90s: FullEnrich jobs for hard-to-find contacts can take 40–120s.
+  // 30s was too short and caused spurious "No data returned" FatalErrors.
+  const pollTimeoutMs = options.pollTimeoutMs ?? 90000;
+  const deadline = Date.now() + pollTimeoutMs;
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs, options.signal);
+
+    let raw: Record<string, unknown>;
+    try {
+      raw = await callGatewayJson(
+        `/v1/enrichment/jobs/${encodeURIComponent(enrichmentId)}`,
+        { method: "GET", options },
+      );
+    } catch (err) {
+      // 404 means the webhook hasn't arrived and been persisted yet — treat as
+      // "still pending" and keep polling until the deadline.
+      // 503 means the gateway is temporarily unavailable — same treatment.
+      // Any other error (auth failure, malformed request, etc.) is fatal.
+      if (
+        err instanceof EnrichmentGatewayError &&
+        (err.status === 404 || err.status === 503)
+      ) {
+        continue;
+      }
+      throw err;
+    }
+
+    const jobResp = raw as {
+      status?: string;
+      people?: EnrichedPersonUpsertLike[];
+    };
+
+    if (jobResp.status === "succeeded") {
+      const people = jobResp.people ?? [];
+      if (people.length === 0) {
+        throw new EnrichmentGatewayError("No data returned", {
+          code: "not_found",
+        });
+      }
+      const person = people[0] as EnrichedPersonUpsertLike;
+      return {
+        _meta: { cacheHit: false, enrichmentId },
+        ...shapePersonToApolloEnvelope(person),
+      } as Record<string, unknown>;
+    }
+
+    if (jobResp.status === "failed") {
+      throw new EnrichmentGatewayError("No data returned", {
+        code: "not_found",
+      });
+    }
+
+    // status === "pending" — keep polling
+  }
+
+  // Timed out.
+  throw new EnrichmentGatewayError("No data returned", { code: "not_found" });
 }
 
 export async function enrichPersonByIdentifier(
@@ -142,51 +436,748 @@ export async function enrichPersonByIdentifier(
   requiredFields?: string[],
   options: EnrichmentGatewayOptions = {},
 ): Promise<Record<string, unknown>> {
-  return enrichPerson(buildPersonBodyFromIdentifier(identifier, requiredFields), options);
+  return enrichPerson(
+    buildPersonBodyFromIdentifier(identifier, requiredFields),
+    options,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Bulk helpers — submit one gateway request per chunk, poll once per job,
+// and return a per-input-index result map. Used by the streaming enrich
+// route to avoid waiting 30–90s per row.
+// ---------------------------------------------------------------------------
+
+/** FullEnrich's hard cap on contacts per bulk request. */
+const FULLENRICH_BULK_CHUNK_SIZE = 100;
+
+export type BulkPersonResultEntry =
+  | { ok: true; data: Record<string, unknown> }
+  | { ok: false; error: EnrichmentGatewayError };
+
+/**
+ * Build a contact payload identical to what `enrichPerson` sends, but without
+ * actually firing the request. Used by the bulk path so the route can validate
+ * inputs row-by-row before submitting a single bulk request.
+ */
+export function buildContactPayload(
+  body: EnrichPersonBody,
+): Record<string, unknown> {
+  const enrichFields = mapRequiredFieldsToEnrichFields(body.requiredFields);
+  const contact: Record<string, unknown> = { enrichFields };
+  if (body.linkedinUrl) contact.linkedinUrl = body.linkedinUrl;
+  if (body.firstName) contact.firstName = body.firstName;
+  if (body.lastName) contact.lastName = body.lastName;
+  if (body.domain) {
+    contact.domain = extractDomain(body.domain) ?? body.domain;
+  } else if (body.email) {
+    const emailDomain = body.email.split("@")[1]?.trim();
+    if (emailDomain) contact.domain = emailDomain;
+  }
+  if (body.organizationName) contact.companyName = body.organizationName;
+
+  const hasLinkedin = Boolean(contact.linkedinUrl);
+  const hasNameAndCompany =
+    Boolean(contact.firstName) &&
+    Boolean(contact.lastName) &&
+    Boolean(contact.domain || contact.companyName);
+  if (!hasLinkedin && !hasNameAndCompany) {
+    throw new EnrichmentGatewayError(
+      "People enrichment requires linkedinUrl OR firstName+lastName+domain.",
+      { code: "missing_people_identifier" },
+    );
+  }
+  return contact;
+}
+
+async function submitContactBulkChunk(
+  contacts: Array<{ inputIndex: number; payload: Record<string, unknown> }>,
+  options: EnrichmentGatewayOptions,
+  results: Map<number, BulkPersonResultEntry>,
+): Promise<void> {
+  if (contacts.length === 0) return;
+
+  // Tag each contact with its original input index so cache hits and
+  // webhook results can be mapped back to the caller's row.
+  const requestContacts = contacts.map(({ inputIndex, payload }) => ({
+    ...payload,
+    custom: { contactIndex: String(inputIndex) },
+  }));
+
+  const raw = await callGatewayJson("/v1/enrichment/person/contact", {
+    method: "POST",
+    body: { contacts: requestContacts, preferCache: true },
+    options,
+    expectedStatus: [200, 202],
+  });
+
+  const resp = raw as {
+    enrichmentId?: string | null;
+    status?: string;
+    cachedResults?: Array<EnrichedPersonUpsertLike & { inputIndex?: number }>;
+    queuedCount?: number;
+  };
+
+  // Cache hits resolve immediately. The gateway tags each cached entry with
+  // `inputIndex` so we can place it in the right slot.
+  const cached = resp.cachedResults ?? [];
+  const seenIndexes = new Set<number>();
+  for (const hit of cached) {
+    const idx =
+      typeof hit.inputIndex === "number" ? hit.inputIndex : undefined;
+    if (idx === undefined) continue;
+    seenIndexes.add(idx);
+    results.set(idx, {
+      ok: true,
+      data: {
+        _meta: { cacheHit: true },
+        ...shapePersonToApolloEnvelope(hit),
+      },
+    });
+  }
+
+  // No queued misses → done.
+  const enrichmentId = resp.enrichmentId;
+  if (!enrichmentId) {
+    // Any remaining contacts in this chunk that didn't appear in cachedResults
+    // are unexpected — surface as not_found rather than hanging.
+    for (const { inputIndex } of contacts) {
+      if (seenIndexes.has(inputIndex) || results.has(inputIndex)) continue;
+      results.set(inputIndex, {
+        ok: false,
+        error: new EnrichmentGatewayError("No data returned", {
+          code: "not_found",
+        }),
+      });
+    }
+    return;
+  }
+
+  // Poll the job and demux results back to per-input-index slots.
+  await pollForBulkPersonResults(enrichmentId, contacts, results, options);
+}
+
+async function pollForBulkPersonResults(
+  enrichmentId: string,
+  contacts: Array<{ inputIndex: number; payload: Record<string, unknown> }>,
+  results: Map<number, BulkPersonResultEntry>,
+  options: EnrichmentGatewayOptions,
+): Promise<void> {
+  const pollIntervalMs = options.pollIntervalMs ?? 2000;
+  const pollTimeoutMs = options.pollTimeoutMs ?? 90000;
+  const deadline = Date.now() + pollTimeoutMs;
+
+  // Slots that this chunk is responsible for — anything still missing after
+  // the bulk job resolves is reported as `not_found` to the caller.
+  const ownedIndexes = contacts
+    .map(({ inputIndex }) => inputIndex)
+    .filter((idx) => !results.has(idx));
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs, options.signal);
+
+    let raw: Record<string, unknown>;
+    try {
+      raw = await callGatewayJson(
+        `/v1/enrichment/jobs/${encodeURIComponent(enrichmentId)}`,
+        { method: "GET", options },
+      );
+    } catch (err) {
+      if (
+        err instanceof EnrichmentGatewayError &&
+        (err.status === 404 || err.status === 503)
+      ) {
+        continue;
+      }
+      throw err;
+    }
+
+    const jobResp = raw as {
+      status?: string;
+      people?: Array<EnrichedPersonUpsertLike & { contactIndex?: number }>;
+    };
+
+    if (jobResp.status === "succeeded") {
+      const people = jobResp.people ?? [];
+      for (const person of people) {
+        const idx =
+          typeof person.contactIndex === "number"
+            ? person.contactIndex
+            : undefined;
+        if (idx === undefined) continue;
+        if (results.has(idx)) continue;
+        results.set(idx, {
+          ok: true,
+          data: {
+            _meta: { cacheHit: false, enrichmentId },
+            ...shapePersonToApolloEnvelope(person),
+          },
+        });
+      }
+
+      // Anything FullEnrich didn't resolve is reported as not_found.
+      for (const idx of ownedIndexes) {
+        if (results.has(idx)) continue;
+        results.set(idx, {
+          ok: false,
+          error: new EnrichmentGatewayError("No data returned", {
+            code: "not_found",
+          }),
+        });
+      }
+      return;
+    }
+
+    if (jobResp.status === "failed") {
+      for (const idx of ownedIndexes) {
+        if (results.has(idx)) continue;
+        results.set(idx, {
+          ok: false,
+          error: new EnrichmentGatewayError("No data returned", {
+            code: "not_found",
+          }),
+        });
+      }
+      return;
+    }
+    // pending — keep polling
+  }
+
+  // Timed out.
+  for (const idx of ownedIndexes) {
+    if (results.has(idx)) continue;
+    results.set(idx, {
+      ok: false,
+      error: new EnrichmentGatewayError("No data returned", {
+        code: "not_found",
+      }),
+    });
+  }
+}
+
+/**
+ * Bulk people enrichment via FullEnrich `/v1/enrichment/person/contact`.
+ *
+ * Submits a single request per chunk of up to 100 contacts and returns a map
+ * keyed by the caller's input index. Inputs that fail validation are recorded
+ * as per-row errors instead of throwing — callers can still emit results for
+ * the rows that did go through.
+ */
+export async function enrichPersonBulk(
+  inputs: Array<EnrichPersonBody | null | undefined>,
+  options: EnrichmentGatewayOptions = {},
+): Promise<Map<number, BulkPersonResultEntry>> {
+  const results = new Map<number, BulkPersonResultEntry>();
+  const validContacts: Array<{
+    inputIndex: number;
+    payload: Record<string, unknown>;
+  }> = [];
+
+  inputs.forEach((body, index) => {
+    if (!body) {
+      results.set(index, {
+        ok: false,
+        error: new EnrichmentGatewayError("People enrichment input is empty.", {
+          code: "empty_identifier",
+        }),
+      });
+      return;
+    }
+    try {
+      validContacts.push({ inputIndex: index, payload: buildContactPayload(body) });
+    } catch (err) {
+      results.set(index, {
+        ok: false,
+        error:
+          err instanceof EnrichmentGatewayError
+            ? err
+            : new EnrichmentGatewayError(
+                err instanceof Error ? err.message : "Invalid input",
+                { code: "invalid_input" },
+              ),
+      });
+    }
+  });
+
+  if (validContacts.length === 0) return results;
+
+  // Chunk and submit in parallel.
+  const chunks: Array<typeof validContacts> = [];
+  for (let i = 0; i < validContacts.length; i += FULLENRICH_BULK_CHUNK_SIZE) {
+    chunks.push(validContacts.slice(i, i + FULLENRICH_BULK_CHUNK_SIZE));
+  }
+
+  await Promise.all(
+    chunks.map((chunk) => submitContactBulkChunk(chunk, options, results)),
+  );
+
+  return results;
+}
+
+async function submitReverseEmailBulkChunk(
+  emails: Array<{ inputIndex: number; email: string }>,
+  options: EnrichmentGatewayOptions,
+  results: Map<number, BulkPersonResultEntry>,
+): Promise<void> {
+  if (emails.length === 0) return;
+
+  // The gateway's reverse-email endpoint dedupes emails before calling
+  // FullEnrich, so multiple inputs with the same address end up sharing the
+  // same FullEnrich row. We still need to map each input index back to a
+  // result, so we keep an email→indexes map for fan-out.
+  const indexesByEmail = new Map<string, number[]>();
+  for (const { inputIndex, email } of emails) {
+    const arr = indexesByEmail.get(email) ?? [];
+    arr.push(inputIndex);
+    indexesByEmail.set(email, arr);
+  }
+
+  const raw = await callGatewayJson("/v1/enrichment/reverse/email", {
+    method: "POST",
+    body: {
+      emails: emails.map((e) => e.email),
+      preferCache: true,
+    },
+    options,
+    expectedStatus: [200, 202],
+  });
+
+  const resp = raw as {
+    enrichmentId?: string | null;
+    status?: string;
+    cachedResults?: Array<EnrichedPersonUpsertLike & { inputIndex?: number }>;
+    queuedCount?: number;
+  };
+
+  const cached = resp.cachedResults ?? [];
+  for (const hit of cached) {
+    const idx =
+      typeof hit.inputIndex === "number" ? hit.inputIndex : undefined;
+    if (idx === undefined) continue;
+    // The gateway dedupes emails, so a cache hit at index i corresponds to
+    // the deduped email at that position in the request — we then fan out to
+    // every original input index that requested that email.
+    const requestEmail = emails[idx]?.email;
+    if (!requestEmail) continue;
+    const targets = indexesByEmail.get(requestEmail) ?? [idx];
+    for (const target of targets) {
+      results.set(target, {
+        ok: true,
+        data: {
+          _meta: { cacheHit: true },
+          ...shapePersonToApolloEnvelope(hit),
+        },
+      });
+    }
+  }
+
+  const enrichmentId = resp.enrichmentId;
+  if (!enrichmentId) {
+    for (const { inputIndex } of emails) {
+      if (results.has(inputIndex)) continue;
+      results.set(inputIndex, {
+        ok: false,
+        error: new EnrichmentGatewayError("No data returned", {
+          code: "not_found",
+        }),
+      });
+    }
+    return;
+  }
+
+  // Poll job and demux by `contactIndex` (gateway position, which maps to
+  // the deduped email list). Then fan out to every original input.
+  await pollForReverseEmailResults(
+    enrichmentId,
+    emails,
+    indexesByEmail,
+    results,
+    options,
+  );
+}
+
+async function pollForReverseEmailResults(
+  enrichmentId: string,
+  emails: Array<{ inputIndex: number; email: string }>,
+  indexesByEmail: Map<string, number[]>,
+  results: Map<number, BulkPersonResultEntry>,
+  options: EnrichmentGatewayOptions,
+): Promise<void> {
+  const pollIntervalMs = options.pollIntervalMs ?? 2000;
+  const pollTimeoutMs = options.pollTimeoutMs ?? 90000;
+  const deadline = Date.now() + pollTimeoutMs;
+
+  const ownedIndexes = emails
+    .map(({ inputIndex }) => inputIndex)
+    .filter((idx) => !results.has(idx));
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs, options.signal);
+
+    let raw: Record<string, unknown>;
+    try {
+      raw = await callGatewayJson(
+        `/v1/enrichment/jobs/${encodeURIComponent(enrichmentId)}`,
+        { method: "GET", options },
+      );
+    } catch (err) {
+      if (
+        err instanceof EnrichmentGatewayError &&
+        (err.status === 404 || err.status === 503)
+      ) {
+        continue;
+      }
+      throw err;
+    }
+
+    const jobResp = raw as {
+      status?: string;
+      people?: Array<EnrichedPersonUpsertLike & { contactIndex?: number }>;
+    };
+
+    if (jobResp.status === "succeeded") {
+      for (const person of jobResp.people ?? []) {
+        const idx =
+          typeof person.contactIndex === "number"
+            ? person.contactIndex
+            : undefined;
+        if (idx === undefined) continue;
+        const requestEmail = emails[idx]?.email;
+        if (!requestEmail) continue;
+        const targets = indexesByEmail.get(requestEmail) ?? [];
+        for (const target of targets) {
+          if (results.has(target)) continue;
+          results.set(target, {
+            ok: true,
+            data: {
+              _meta: { cacheHit: false, enrichmentId },
+              ...shapePersonToApolloEnvelope(person),
+            },
+          });
+        }
+      }
+      for (const idx of ownedIndexes) {
+        if (results.has(idx)) continue;
+        results.set(idx, {
+          ok: false,
+          error: new EnrichmentGatewayError("No data returned", {
+            code: "not_found",
+          }),
+        });
+      }
+      return;
+    }
+
+    if (jobResp.status === "failed") {
+      for (const idx of ownedIndexes) {
+        if (results.has(idx)) continue;
+        results.set(idx, {
+          ok: false,
+          error: new EnrichmentGatewayError("No data returned", {
+            code: "not_found",
+          }),
+        });
+      }
+      return;
+    }
+  }
+
+  for (const idx of ownedIndexes) {
+    if (results.has(idx)) continue;
+    results.set(idx, {
+      ok: false,
+      error: new EnrichmentGatewayError("No data returned", {
+        code: "not_found",
+      }),
+    });
+  }
+}
+
+/**
+ * Bulk reverse-email lookup via FullEnrich `/v1/enrichment/reverse/email`.
+ *
+ * Submits a single request per chunk of up to 100 emails and returns a map
+ * keyed by the caller's input index.
+ */
+export async function reverseEmailLookupBulk(
+  inputs: Array<string | null | undefined>,
+  options: EnrichmentGatewayOptions = {},
+): Promise<Map<number, BulkPersonResultEntry>> {
+  const results = new Map<number, BulkPersonResultEntry>();
+  const validEmails: Array<{ inputIndex: number; email: string }> = [];
+
+  inputs.forEach((rawEmail, index) => {
+    const email = rawEmail?.trim().toLowerCase();
+    if (!email || !email.includes("@")) {
+      results.set(index, {
+        ok: false,
+        error: new EnrichmentGatewayError("Reverse email input is empty.", {
+          code: "empty_email",
+        }),
+      });
+      return;
+    }
+    validEmails.push({ inputIndex: index, email });
+  });
+
+  if (validEmails.length === 0) return results;
+
+  const chunks: Array<typeof validEmails> = [];
+  for (let i = 0; i < validEmails.length; i += FULLENRICH_BULK_CHUNK_SIZE) {
+    chunks.push(validEmails.slice(i, i + FULLENRICH_BULK_CHUNK_SIZE));
+  }
+
+  await Promise.all(
+    chunks.map((chunk) => submitReverseEmailBulkChunk(chunk, options, results)),
+  );
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// reverseEmailLookup — calls POST /v1/enrichment/reverse/email with poll
+// ---------------------------------------------------------------------------
+
+export async function reverseEmailLookup(
+  body: ReverseEmailBody,
+  options: EnrichmentGatewayOptions = {},
+): Promise<Record<string, unknown>> {
+  const email = body.email.trim().toLowerCase();
+  if (!email || !email.includes("@")) {
+    throw new EnrichmentGatewayError("Reverse email input is empty.", {
+      code: "empty_email",
+    });
+  }
+
+  const raw = await callGatewayJson("/v1/enrichment/reverse/email", {
+    method: "POST",
+    body: { emails: [email], preferCache: true },
+    options,
+    expectedStatus: [200, 202],
+  });
+
+  const resp = raw as {
+    enrichmentId?: string | null;
+    status?: string;
+    cachedResults?: unknown[];
+    queuedCount?: number;
+  };
+
+  const cachedResults = resp.cachedResults ?? [];
+  if (cachedResults.length > 0) {
+    const hit = cachedResults[0] as EnrichedPersonUpsertLike;
+    return {
+      _meta: { cacheHit: true },
+      ...shapePersonToApolloEnvelope(hit),
+    } as Record<string, unknown>;
+  }
+
+  const enrichmentId = resp.enrichmentId;
+  if (!enrichmentId) {
+    throw new EnrichmentGatewayError("No data returned", { code: "not_found" });
+  }
+
+  return pollForPersonResult(enrichmentId, options);
 }
 
+// ---------------------------------------------------------------------------
+// enrichCompany — calls POST /v1/enrichment/company/search (synchronous)
+// ---------------------------------------------------------------------------
+
 export async function enrichCompany(
   body: EnrichCompanyBody,
   options: EnrichmentGatewayOptions = {},
 ): Promise<Record<string, unknown>> {
-  const domain = extractDomain(body.domain);
-  if (!domain) {
+  const domain = body.domain ? extractDomain(body.domain) ?? body.domain : undefined;
+  const companyName = body.companyName?.trim();
+  const linkedinUrl = body.linkedinUrl?.trim();
+
+  if (!domain && !companyName && !linkedinUrl) {
     throw new EnrichmentGatewayError("Company enrichment input is empty.", {
       code: "empty_domain",
     });
   }
 
-  const url = new URL(
-    `${resolveBaseUrl(options)}/v1/enrichment/company`,
-  );
-  url.searchParams.set("domain", domain);
-  if (body.requiredFields && body.requiredFields.length > 0) {
-    url.searchParams.set("requiredFields", body.requiredFields.join(","));
+  const requestBody: Record<string, unknown> = { limit: 1, preferCache: true };
+  if (domain) requestBody.domain = domain;
+  if (companyName) requestBody.name = companyName;
+  if (linkedinUrl) requestBody.linkedinUrl = linkedinUrl;
+
+  const raw = await callGatewayJson("/v1/enrichment/company/search", {
+    method: "POST",
+    body: requestBody,
+    options,
+  });
+
+  const resp = raw as { companies?: EnrichedCompanyUpsertLike[] };
+  const companies = resp.companies ?? [];
+  if (companies.length === 0) {
+    throw new EnrichmentGatewayError("No data returned", { code: "not_found" });
+  }
+
+  return shapeCompanyToApolloEnvelope(
+    companies[0] as EnrichedCompanyUpsertLike,
+  ) as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// aviatoEnrichPerson — calls POST /v1/enrichment/aviato/person (synchronous)
+// ---------------------------------------------------------------------------
+
+export type AviatoEnrichPersonBody = {
+  linkedinUrl?: string;
+  linkedinID?: string;
+  linkedinNumID?: string;
+  linkedinEntityId?: string;
+  email?: string;
+  preview?: boolean;
+};
+
+export type AviatoEnrichCompanyBody = {
+  website?: string;
+  linkedinUrl?: string;
+  linkedinID?: string;
+  linkedinNumID?: string;
+  preview?: boolean;
+};
+
+export async function aviatoEnrichPerson(
+  body: AviatoEnrichPersonBody,
+  options: EnrichmentGatewayOptions = {},
+): Promise<Record<string, unknown>> {
+  const hasIdentifier =
+    body.linkedinUrl ||
+    body.linkedinID ||
+    body.linkedinNumID ||
+    body.linkedinEntityId ||
+    body.email;
+  if (!hasIdentifier) {
+    throw new EnrichmentGatewayError(
+      "Aviato person enrichment requires at least one identifier: linkedinUrl, linkedinID, linkedinNumID, linkedinEntityId, or email.",
+      { code: "empty_identifier" },
+    );
+  }
+
+  const requestBody: Record<string, unknown> = {};
+  if (body.linkedinUrl) requestBody.linkedinURL = body.linkedinUrl.trim();
+  if (body.linkedinID) requestBody.linkedinID = body.linkedinID.trim();
+  if (body.linkedinNumID) requestBody.linkedinNumID = body.linkedinNumID.trim();
+  if (body.linkedinEntityId)
+    requestBody.linkedinEntityId = body.linkedinEntityId.trim();
+  if (body.email) requestBody.email = body.email.trim();
+  if (body.preview !== undefined) requestBody.preview = body.preview;
+
+  const raw = await callGatewayJson("/v1/enrichment/aviato/person", {
+    method: "POST",
+    body: requestBody,
+    options,
+  });
+
+  const resp = raw as {
+    data?: EnrichedPersonUpsertLike | null;
+    billing?: { charged_cents?: number; cache_hit?: boolean; preview?: boolean };
+    provider?: { name?: string; aviato_id?: string };
+  };
+
+  if (!resp.data) {
+    throw new EnrichmentGatewayError("No data returned", { code: "not_found" });
+  }
+
+  return {
+    _meta: {
+      provider: "aviato",
+      cacheHit: resp.billing?.cache_hit ?? false,
+      chargedCents: resp.billing?.charged_cents ?? 0,
+    },
+    ...shapePersonToApolloEnvelope(resp.data),
+  } as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// aviatoEnrichCompany — calls POST /v1/enrichment/aviato/company (synchronous)
+// ---------------------------------------------------------------------------
+
+export async function aviatoEnrichCompany(
+  body: AviatoEnrichCompanyBody,
+  options: EnrichmentGatewayOptions = {},
+): Promise<Record<string, unknown>> {
+  const hasIdentifier =
+    body.website || body.linkedinUrl || body.linkedinID || body.linkedinNumID;
+  if (!hasIdentifier) {
+    throw new EnrichmentGatewayError(
+      "Aviato company enrichment requires at least one identifier: website, linkedinUrl, linkedinID, or linkedinNumID.",
+      { code: "empty_identifier" },
+    );
+  }
+
+  const requestBody: Record<string, unknown> = {};
+  if (body.website) requestBody.website = body.website.trim();
+  if (body.linkedinUrl) requestBody.linkedinURL = body.linkedinUrl.trim();
+  if (body.linkedinID) requestBody.linkedinID = body.linkedinID.trim();
+  if (body.linkedinNumID) requestBody.linkedinNumID = body.linkedinNumID.trim();
+  if (body.preview !== undefined) requestBody.preview = body.preview;
+
+  const raw = await callGatewayJson("/v1/enrichment/aviato/company", {
+    method: "POST",
+    body: requestBody,
+    options,
+  });
+
+  const resp = raw as {
+    data?: EnrichedCompanyUpsertLike | null;
+    billing?: { charged_cents?: number; cache_hit?: boolean; preview?: boolean };
+    provider?: { name?: string; aviato_id?: string };
+  };
+
+  if (!resp.data) {
+    throw new EnrichmentGatewayError("No data returned", { code: "not_found" });
   }
 
-  return callGatewayJson(url, { method: "GET", options });
+  return {
+    _meta: {
+      provider: "aviato",
+      cacheHit: resp.billing?.cache_hit ?? false,
+      chargedCents: resp.billing?.charged_cents ?? 0,
+    },
+    ...shapeCompanyToApolloEnvelope(resp.data),
+  } as Record<string, unknown>;
 }
 
+// ---------------------------------------------------------------------------
+// searchPeople — calls POST /v1/enrichment/people/search (synchronous)
+// ---------------------------------------------------------------------------
+
 export async function searchPeople(
   body: SearchPeopleBody,
   options: EnrichmentGatewayOptions = {},
 ): Promise<Record<string, unknown>> {
-  const payload: Record<string, unknown> = {};
-  if (body.personTitles) payload.person_titles = body.personTitles;
-  if (body.personLocations) payload.person_locations = body.personLocations;
-  if (body.organizationDomains) {
-    payload.organization_domains = body.organizationDomains;
-  }
-  if (body.organizationLocations) {
-    payload.organization_locations = body.organizationLocations;
+  // Request body matches gateway `peopleSearchRequestSchema`:
+  // `locations`, `headcountRanges`, `titles`, `companyDomain`, etc.
+  const payload: Record<string, unknown> = { preferCache: true };
+
+  if (body.personTitles?.length) payload.titles = body.personTitles;
+
+  const locations = [
+    ...(body.personLocations ?? []),
+    ...(body.organizationLocations ?? []),
+  ]
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (locations.length > 0) payload.locations = locations;
+
+  if (body.organizationDomains && body.organizationDomains.length > 0) {
+    payload.companyDomain = body.organizationDomains[0];
   }
-  if (body.organizationNumEmployeesRanges) {
-    payload.organization_num_employees_ranges =
-      body.organizationNumEmployeesRanges;
+
+  const headcountRanges = (body.organizationNumEmployeesRanges ?? [])
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (headcountRanges.length > 0) {
+    payload.headcountRanges = headcountRanges;
   }
-  if (body.qKeywords) payload.q_keywords = body.qKeywords;
-  if (body.page !== undefined) payload.page = body.page;
-  if (body.perPage !== undefined) payload.per_page = body.perPage;
+
+  if (body.qKeywords) payload.keywords = body.qKeywords;
+  if (body.perPage !== undefined) payload.limit = body.perPage;
 
   return callGatewayJson("/v1/enrichment/people/search", {
     method: "POST",
@@ -195,16 +1186,23 @@ export async function searchPeople(
   });
 }
 
+// ---------------------------------------------------------------------------
+// Shared HTTP helpers
+// ---------------------------------------------------------------------------
+
 async function callGatewayJson(
   pathOrUrl: string | URL,
   args: {
     method: "GET" | "POST";
     body?: Record<string, unknown>;
     options: EnrichmentGatewayOptions;
+    /** HTTP statuses considered "ok" beyond the default 2xx check. */
+    expectedStatus?: number[];
   },
 ): Promise<Record<string, unknown>> {
   const fetchImpl = args.options.fetchImpl ?? fetch;
-  const apiKey = args.options.apiKey ?? requireEnrichmentApiKey(args.options.env);
+  const apiKey =
+    args.options.apiKey ?? requireEnrichmentApiKey(args.options.env);
   const url =
     typeof pathOrUrl === "string"
       ? `${resolveBaseUrl(args.options)}${pathOrUrl}`
@@ -217,9 +1215,14 @@ async function callGatewayJson(
       Authorization: `Bearer ${apiKey}`,
     },
     ...(args.body ? { body: JSON.stringify(args.body) } : {}),
+    ...(args.options.signal ? { signal: args.options.signal } : {}),
   });
 
-  if (!response.ok) {
+  const isOk =
+    response.ok ||
+    (args.expectedStatus?.includes(response.status) ?? false);
+
+  if (!isOk) {
     throw await buildGatewayError(response, pathOrUrl.toString());
   }
 
@@ -280,3 +1283,21 @@ async function buildGatewayError(
     { status: response.status, code },
   );
 }
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new EnrichmentGatewayError("aborted", { code: "aborted" }));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new EnrichmentGatewayError("aborted", { code: "aborted" }));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}