@dench.com/cli 0.4.3 → 0.4.5

package/lib/crm-enrichment.ts

@@ -0,0 +1,431 @@
+// Shared CRM enrichment catalog and helpers.
+//
+// Keep this in the CLI package because CRM enrichment is a CLI-first surface.
+// App/workflow code can import this same catalog so the agent, CLI, and future
+// column UI agree on provider contracts and extraction behavior.
+
+export type EnrichmentCategory = "people" | "company";
+
+export const ENRICHMENT_CATEGORIES: readonly EnrichmentCategory[] = [
+  "people",
+  "company",
+] as const;
+
+export type EnrichmentFieldType =
+  | "text"
+  | "email"
+  | "phone"
+  | "url"
+  | "number"
+  | "boolean"
+  | "date"
+  | "richtext"
+  | "file"
+  | "user"
+  | "enum"
+  | "relation"
+  | "tags"
+  | "action";
+
+export type EnrichmentColumnDef = {
+  label: string;
+  key: string;
+  fieldType: EnrichmentFieldType;
+  /** Dot-path into the gateway response payload to extract the value. */
+  apolloPath: string;
+  /**
+   * Canonical Dench gateway field names sent in the requiredFields contract.
+   * Empty means the gateway should use its default backfill behavior.
+   */
+  requiredFields: string[];
+  /** Additional dot-paths to try when apolloPath does not resolve. */
+  extractionFallbacks?: string[];
+};
+
+export type EnrichmentInputKind = "email" | "linkedin" | "domain";
+
+export type EnrichmentInputDef = {
+  kind: EnrichmentInputKind;
+  label: string;
+};
+
+export type FieldCandidate = {
+  id?: string;
+  name: string;
+  type: string;
+};
+
+const PEOPLE_PATTERNS = /people|person|contact|lead|prospect/i;
+const COMPANY_PATTERNS = /company|companies|organization|account|business/i;
+
+export function detectEnrichmentCategory(
+  objectName: string,
+): EnrichmentCategory | null {
+  if (PEOPLE_PATTERNS.test(objectName)) return "people";
+  if (COMPANY_PATTERNS.test(objectName)) return "company";
+  return null;
+}
+
+export const PEOPLE_ENRICHMENT_COLUMNS: readonly EnrichmentColumnDef[] = [
+  {
+    label: "Full Name",
+    key: "person.name",
+    fieldType: "text",
+    apolloPath: "__computed.fullName",
+    requiredFields: ["fullName"],
+    extractionFallbacks: ["person.name", "fullName", "person.fullName"],
+  },
+  {
+    label: "Email",
+    key: "person.email",
+    fieldType: "email",
+    apolloPath: "person.email",
+    requiredFields: ["email"],
+    extractionFallbacks: ["email"],
+  },
+  {
+    label: "Headline",
+    key: "person.headline",
+    fieldType: "text",
+    apolloPath: "person.headline",
+    requiredFields: ["headline"],
+    extractionFallbacks: ["headline"],
+  },
+  {
+    label: "LinkedIn URL",
+    key: "person.linkedin_url",
+    fieldType: "url",
+    apolloPath: "person.linkedin_url",
+    requiredFields: ["linkedinID"],
+    extractionFallbacks: ["linkedin_url", "URLs.linkedin", "person.URLs.linkedin"],
+  },
+  {
+    label: "Twitter URL",
+    key: "person.twitter_url",
+    fieldType: "url",
+    apolloPath: "person.twitter_url",
+    requiredFields: ["URLs"],
+    extractionFallbacks: ["twitter_url", "URLs.twitter", "person.URLs.twitter"],
+  },
+  {
+    label: "Phone",
+    key: "person.phone",
+    fieldType: "phone",
+    apolloPath: "person.contact.phone_numbers.0.sanitized_number",
+    requiredFields: ["phone"],
+    extractionFallbacks: ["phone", "person.phone"],
+  },
+  {
+    label: "Title",
+    key: "person.title",
+    fieldType: "text",
+    apolloPath: "person.title",
+    requiredFields: [],
+    extractionFallbacks: ["title", "person.headline", "headline"],
+  },
+  {
+    label: "Location",
+    key: "person.location",
+    fieldType: "text",
+    apolloPath: "__computed.location",
+    requiredFields: ["location"],
+    extractionFallbacks: ["location", "person.location"],
+  },
+];
+
+export const COMPANY_ENRICHMENT_COLUMNS: readonly EnrichmentColumnDef[] = [
+  {
+    label: "Company Name",
+    key: "organization.name",
+    fieldType: "text",
+    apolloPath: "organization.name",
+    requiredFields: ["name"],
+    extractionFallbacks: ["name"],
+  },
+  {
+    label: "Website URL",
+    key: "organization.website_url",
+    fieldType: "url",
+    apolloPath: "organization.website_url",
+    requiredFields: ["website"],
+    extractionFallbacks: ["website", "organization.website"],
+  },
+  {
+    label: "Industry",
+    key: "organization.industry",
+    fieldType: "text",
+    apolloPath: "organization.industry",
+    requiredFields: ["industryList"],
+    extractionFallbacks: ["industryList.0", "organization.industryList.0"],
+  },
+  {
+    label: "LinkedIn URL",
+    key: "organization.linkedin_url",
+    fieldType: "url",
+    apolloPath: "organization.linkedin_url",
+    requiredFields: ["linkedinID"],
+    extractionFallbacks: ["URLs.linkedin", "organization.URLs.linkedin"],
+  },
+  {
+    label: "Total Funding",
+    key: "organization.total_funding_printed",
+    fieldType: "text",
+    apolloPath: "organization.total_funding_printed",
+    requiredFields: ["totalFunding"],
+    extractionFallbacks: ["totalFunding", "organization.totalFunding"],
+  },
+  {
+    label: "Founded Year",
+    key: "organization.founded_year",
+    fieldType: "number",
+    apolloPath: "organization.founded_year",
+    requiredFields: ["founded"],
+    extractionFallbacks: ["founded", "organization.founded"],
+  },
+];
+
+export const PEOPLE_INPUTS: readonly EnrichmentInputDef[] = [
+  { kind: "email", label: "Email" },
+  { kind: "linkedin", label: "LinkedIn URL" },
+];
+
+export const COMPANY_INPUTS: readonly EnrichmentInputDef[] = [
+  { kind: "domain", label: "Website / Domain" },
+  { kind: "linkedin", label: "LinkedIn URL" },
+];
+
+export type EnrichmentFieldMeta = {
+  enrichment: {
+    category: EnrichmentCategory;
+    key: string;
+    apolloPath: string;
+    inputFieldName: string;
+  };
+};
+
+export function getEnrichmentColumns(
+  category: EnrichmentCategory,
+): readonly EnrichmentColumnDef[] {
+  return category === "people"
+    ? PEOPLE_ENRICHMENT_COLUMNS
+    : COMPANY_ENRICHMENT_COLUMNS;
+}
+
+export function getInputDefs(
+  category: EnrichmentCategory,
+): readonly EnrichmentInputDef[] {
+  return category === "people" ? PEOPLE_INPUTS : COMPANY_INPUTS;
+}
+
+export function findEnrichmentColumn(args: {
+  category: EnrichmentCategory;
+  key?: string;
+  apolloPath?: string;
+  label?: string;
+}): EnrichmentColumnDef | null {
+  const columns = getEnrichmentColumns(args.category);
+  const normalizedLabel = args.label?.trim().toLowerCase();
+  return (
+    columns.find((column) => {
+      return (
+        (args.key !== undefined && column.key === args.key) ||
+        (args.apolloPath !== undefined && column.apolloPath === args.apolloPath) ||
+        (normalizedLabel !== undefined &&
+          column.label.toLowerCase() === normalizedLabel)
+      );
+    }) ?? null
+  );
+}
+
+export function isEligibleInputField(
+  category: EnrichmentCategory,
+  field: FieldCandidate,
+): boolean {
+  if (category === "people") {
+    return (
+      field.type === "email" ||
+      /^e[-_]?mail/i.test(field.name) ||
+      /linkedin/i.test(field.name)
+    );
+  }
+
+  return (
+    /domain|website/i.test(field.name) ||
+    /linkedin/i.test(field.name) ||
+    (/^url$/i.test(field.name) && field.type === "url")
+  );
+}
+
+export function getEligibleInputFields(
+  category: EnrichmentCategory,
+  fields: readonly FieldCandidate[],
+): FieldCandidate[] {
+  return fields.filter((field) => isEligibleInputField(category, field));
+}
+
+export function getAvailableEnrichmentCategories(
+  objectName: string,
+  fields: readonly FieldCandidate[],
+): EnrichmentCategory[] {
+  const detected = detectEnrichmentCategory(objectName);
+  if (detected) return [detected];
+
+  const categoriesWithInputs = ENRICHMENT_CATEGORIES.filter(
+    (category) => getEligibleInputFields(category, fields).length > 0,
+  );
+  return categoriesWithInputs.length > 0
+    ? [...categoriesWithInputs]
+    : [...ENRICHMENT_CATEGORIES];
+}
+
+export function autoDetectInputField(
+  category: EnrichmentCategory,
+  fields: readonly FieldCandidate[],
+): FieldCandidate | null {
+  const eligibleFields = getEligibleInputFields(category, fields);
+  if (category === "people") {
+    const emailField = eligibleFields.find(
+      (field) => field.type === "email" || /^e[-_]?mail/i.test(field.name),
+    );
+    if (emailField) return emailField;
+    return eligibleFields.find((field) => /linkedin/i.test(field.name)) ?? null;
+  }
+
+  const domainField = eligibleFields.find((field) =>
+    /website|domain|^url$/i.test(field.name),
+  );
+  if (domainField) return domainField;
+  return eligibleFields.find((field) => /linkedin/i.test(field.name)) ?? null;
+}
+
+export function inferInputKind(field: FieldCandidate): EnrichmentInputKind {
+  if (field.type === "email" || /^e[-_]?mail/i.test(field.name)) {
+    return "email";
+  }
+  if (/linkedin/i.test(field.name)) return "linkedin";
+  return "domain";
+}
+
+export function extractEnrichmentValue(
+  payload: Record<string, unknown>,
+  column: Pick<EnrichmentColumnDef, "apolloPath" | "extractionFallbacks">,
+): string | null {
+  const primary = extractApolloValue(payload, column.apolloPath);
+  if (primary !== null) return primary;
+
+  for (const fallback of column.extractionFallbacks ?? []) {
+    const value = extractApolloValue(payload, fallback);
+    if (value !== null) return value;
+  }
+  return null;
+}
+
+export function getRequiredFieldsForApolloPath(
+  category: EnrichmentCategory,
+  apolloPath: string,
+): string[] {
+  const column = getEnrichmentColumns(category).find(
+    (candidate) => candidate.apolloPath === apolloPath,
+  );
+  return column?.requiredFields ?? [];
+}
+
+export function buildEnrichmentMeta(
+  category: EnrichmentCategory,
+  column: EnrichmentColumnDef,
+  inputFieldName: string,
+): EnrichmentFieldMeta {
+  return {
+    enrichment: {
+      category,
+      key: column.key,
+      apolloPath: column.apolloPath,
+      inputFieldName,
+    },
+  };
+}
+
+export function parseEnrichmentMeta(
+  defaultValue: string | null | undefined,
+): EnrichmentFieldMeta | null {
+  if (!defaultValue) return null;
+  try {
+    const parsed = JSON.parse(defaultValue) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const enrichment = (parsed as { enrichment?: unknown }).enrichment;
+    if (!enrichment || typeof enrichment !== "object") return null;
+    const meta = enrichment as Record<string, unknown>;
+    if (
+      (meta.category === "people" || meta.category === "company") &&
+      typeof meta.key === "string" &&
+      typeof meta.apolloPath === "string" &&
+      typeof meta.inputFieldName === "string"
+    ) {
+      return parsed as EnrichmentFieldMeta;
+    }
+  } catch {
+    // Not enrichment metadata.
+  }
+  return null;
+}
+
+export function extractDomain(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return "";
+  try {
+    const url = new URL(
+      trimmed.startsWith("http") ? trimmed : `https://${trimmed}`,
+    );
+    return url.hostname.replace(/^www\./, "");
+  } catch {
+    return trimmed.replace(/^www\./, "");
+  }
+}
+
+function extractApolloValue(
+  payload: Record<string, unknown>,
+  apolloPath: string,
+): string | null {
+  if (apolloPath === "__computed.fullName") {
+    return computeFullName(payload);
+  }
+  if (apolloPath === "__computed.location") {
+    return computeLocation(payload);
+  }
+
+  const parts = apolloPath.split(".");
+  let current: unknown = payload;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return null;
+    const index = Number(part);
+    if (Array.isArray(current) && !Number.isNaN(index)) {
+      current = current[index];
+    } else {
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+  if (current == null) return null;
+  if (typeof current === "object") return JSON.stringify(current);
+  const value = String(current).trim();
+  return value.length > 0 ? value : null;
+}
+
+function computeFullName(payload: Record<string, unknown>): string | null {
+  const person = payload.person as Record<string, unknown> | undefined;
+  if (!person) return null;
+  const explicit = person.name ?? person.fullName;
+  if (typeof explicit === "string" && explicit.trim().length > 0) {
+    return explicit.trim();
+  }
+  const parts = [person.first_name, person.last_name].filter(
+    (part): part is string => typeof part === "string" && part.trim().length > 0,
+  );
+  return parts.length > 0 ? parts.join(" ") : null;
+}
+
+function computeLocation(payload: Record<string, unknown>): string | null {
+  const person = payload.person as Record<string, unknown> | undefined;
+  if (!person) return null;
+  const parts = [person.city, person.state, person.country].filter(Boolean);
+  return parts.length > 0 ? parts.join(", ") : null;
+}

package/lib/enrichment-gateway.ts

@@ -0,0 +1,279 @@
+import { extractDomain } from "./crm-enrichment";
+
+export type FetchLike = (
+  input: string | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type EnrichmentGatewayEnv = Pick<
+  NodeJS.ProcessEnv,
+  "DENCH_API_KEY" | "DENCH_GATEWAY_URL" | "GATEWAY_URL" | "DENCH_HOST"
+>;
+
+export class EnrichmentGatewayError extends Error {
+  readonly status?: number;
+  readonly code?: string;
+
+  constructor(message: string, options?: { status?: number; code?: string }) {
+    super(message);
+    this.name = "EnrichmentGatewayError";
+    this.status = options?.status;
+    this.code = options?.code;
+  }
+}
+
+export type EnrichPersonBody = {
+  email?: string;
+  linkedinUrl?: string;
+  firstName?: string;
+  lastName?: string;
+  domain?: string;
+  organizationName?: string;
+  requiredFields?: string[];
+};
+
+export type EnrichCompanyBody = {
+  domain: string;
+  requiredFields?: string[];
+};
+
+export type SearchPeopleBody = {
+  personTitles?: string[];
+  personLocations?: string[];
+  organizationDomains?: string[];
+  organizationLocations?: string[];
+  organizationNumEmployeesRanges?: string[];
+  qKeywords?: string;
+  page?: number;
+  perPage?: number;
+};
+
+export type EnrichmentGatewayOptions = {
+  apiKey?: string;
+  baseUrl?: string;
+  env?: EnrichmentGatewayEnv;
+  fetchImpl?: FetchLike;
+};
+
+export function resolveEnrichmentGatewayBaseUrl(
+  env: EnrichmentGatewayEnv = process.env,
+): string {
+  const explicit = env.DENCH_GATEWAY_URL?.trim() || env.GATEWAY_URL?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+
+  const host = env.DENCH_HOST?.trim();
+  if (host && /localhost|127\.0\.0\.1/.test(host)) {
+    return "http://localhost:8787";
+  }
+  return "https://gateway.merseoriginals.com";
+}
+
+export function requireEnrichmentApiKey(
+  env: EnrichmentGatewayEnv = process.env,
+): string {
+  const apiKey = env.DENCH_API_KEY?.trim();
+  if (!apiKey) {
+    throw new EnrichmentGatewayError(
+      "DENCH_API_KEY is not set. Inside a Dench sandbox it is baked into " +
+        "the env automatically; outside, export it manually or run " +
+        "`dench login` first.",
+      { code: "missing_api_key" },
+    );
+  }
+  return apiKey;
+}
+
+export function buildPersonBodyFromIdentifier(
+  identifier: string,
+  requiredFields?: string[],
+): EnrichPersonBody {
+  const trimmed = identifier.trim();
+  if (!trimmed) {
+    throw new EnrichmentGatewayError("People enrichment input is empty.", {
+      code: "empty_identifier",
+    });
+  }
+  if (/linkedin\.com/i.test(trimmed)) {
+    return { linkedinUrl: trimmed, requiredFields };
+  }
+  if (trimmed.includes("@")) {
+    return { email: trimmed, requiredFields };
+  }
+  throw new EnrichmentGatewayError(
+    "Unsupported people identifier. Use an email address or LinkedIn URL.",
+    { code: "unsupported_people_identifier" },
+  );
+}
+
+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) {
+    throw new EnrichmentGatewayError(
+      "People enrichment requires at least one identifier.",
+      { code: "missing_people_identifier" },
+    );
+  }
+
+  return callGatewayJson("/v1/enrichment/people", {
+    method: "POST",
+    body: payload,
+    options,
+  });
+}
+
+export async function enrichPersonByIdentifier(
+  identifier: string,
+  requiredFields?: string[],
+  options: EnrichmentGatewayOptions = {},
+): Promise<Record<string, unknown>> {
+  return enrichPerson(buildPersonBodyFromIdentifier(identifier, requiredFields), options);
+}
+
+export async function enrichCompany(
+  body: EnrichCompanyBody,
+  options: EnrichmentGatewayOptions = {},
+): Promise<Record<string, unknown>> {
+  const domain = extractDomain(body.domain);
+  if (!domain) {
+    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(","));
+  }
+
+  return callGatewayJson(url, { method: "GET", options });
+}
+
+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;
+  }
+  if (body.organizationNumEmployeesRanges) {
+    payload.organization_num_employees_ranges =
+      body.organizationNumEmployeesRanges;
+  }
+  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;
+
+  return callGatewayJson("/v1/enrichment/people/search", {
+    method: "POST",
+    body: payload,
+    options,
+  });
+}
+
+async function callGatewayJson(
+  pathOrUrl: string | URL,
+  args: {
+    method: "GET" | "POST";
+    body?: Record<string, unknown>;
+    options: EnrichmentGatewayOptions;
+  },
+): Promise<Record<string, unknown>> {
+  const fetchImpl = args.options.fetchImpl ?? fetch;
+  const apiKey = args.options.apiKey ?? requireEnrichmentApiKey(args.options.env);
+  const url =
+    typeof pathOrUrl === "string"
+      ? `${resolveBaseUrl(args.options)}${pathOrUrl}`
+      : pathOrUrl;
+
+  const response = await fetchImpl(url, {
+    method: args.method,
+    headers: {
+      ...(args.method === "POST" ? { "content-type": "application/json" } : {}),
+      Authorization: `Bearer ${apiKey}`,
+    },
+    ...(args.body ? { body: JSON.stringify(args.body) } : {}),
+  });
+
+  if (!response.ok) {
+    throw await buildGatewayError(response, pathOrUrl.toString());
+  }
+
+  return (await response.json()) as Record<string, unknown>;
+}
+
+function resolveBaseUrl(options: EnrichmentGatewayOptions): string {
+  return (
+    options.baseUrl?.trim().replace(/\/+$/, "") ??
+    resolveEnrichmentGatewayBaseUrl(options.env)
+  );
+}
+
+async function buildGatewayError(
+  response: Response,
+  context: string,
+): Promise<EnrichmentGatewayError> {
+  let body: unknown = null;
+  let rawText = "";
+  try {
+    rawText = await response.text();
+    body = rawText ? JSON.parse(rawText) : null;
+  } catch {
+    // Non-JSON bodies are surfaced below.
+  }
+
+  const error =
+    body && typeof body === "object"
+      ? (body as { error?: { code?: unknown; message?: unknown } }).error
+      : undefined;
+  const code = typeof error?.code === "string" ? error.code : undefined;
+  const upstreamMessage =
+    typeof error?.message === "string" ? error.message : undefined;
+
+  if (response.status === 404 || code === "not_found") {
+    return new EnrichmentGatewayError("No data returned", {
+      status: response.status,
+      code: code ?? "not_found",
+    });
+  }
+  if (response.status === 503 || code === "provider_unavailable") {
+    return new EnrichmentGatewayError("Gateway providers unavailable", {
+      status: response.status,
+      code: code ?? "provider_unavailable",
+    });
+  }
+  if (code === "invalid_required_field") {
+    return new EnrichmentGatewayError(
+      upstreamMessage ?? "Invalid required field",
+      { status: response.status, code },
+    );
+  }
+
+  const detail = upstreamMessage || rawText || response.statusText;
+  const truncated = detail.length > 500 ? `${detail.slice(0, 500)}...` : detail;
+  return new EnrichmentGatewayError(
+    `Gateway ${context} returned ${response.status}: ${truncated}`,
+    { status: response.status, code },
+  );
+}